--- id: write-agent-instruction type: sop group: C status: published version: 1 updated: 2026-11-06 token_estimate: 2086 --- # 如何写一份 Agent 能照着执行的指令文件 > **用途**：把「我希望它怎么做」写成「它能照着判的条件」。这两者的差距，就是规则写了却不生效的全部原因。 > > **覆盖**：AGENTS.md、系统提示、自定义指令、链头文件、技能包说明书。 > > **产出**：一份能被判断、能被执行的指令文件。 > > 拿到就能跑：**先写「什么时候不适用」，再写「怎么做」。** 顺序反了，规则会被套用到所有场景。 --- ## 触发的变异问法 - 「AGENTS.md 该怎么写」 - 「怎么让 AI 记住我的规则」 - 「规则写了它不照做」 - 「指令文件越写越长怎么办」 - 「怎么给 AI 定规矩」 - 「系统提示词怎么写才有效」 - 「每次都要重新交代一遍」 - 「怎么让它在所有对话里都按同一套来」 --- ## 什么时候不要用这份文件 - **只有一两句偏好要交代**（称呼、语气、禁用词）—— 直接说，不需要指令文件。 - **规则本身还在变** —— 先稳定一周再写。写成文件的那一刻，它就开始落后了。 - **对方读不到文件** —— 没有固定加载位时，指令文件等于没有。先解决位置。 - **要的是「让它更聪明」** —— 指令文件管边界，不管能力。 --- ## 执行步骤 ### 第一步 · 先分清三样东西 大多数人写不好指令文件，是因为把三类东西混在一份里： | 类型 | 例子 | 写法 | |---|---|---| | **偏好** | 称呼、语气、不要用感叹号 | 一句话，不加解释 | | **规则** | 什么可以做、什么绝对不行 | 每条带判据 | | **流程** | 某类事按什么顺序做 | 单独的流程文件，用指针连 | 混写的典型后果：**偏好被当成规则执行**（「不喜欢啰嗦」被理解成「删掉所有解释」），**流程被写成规则**（「每次都要先备份」变成了绝对命令，连临时文件也要备份）。 **输出**：三类各自分到哪个文件。 ### 第二步 · 每条规则写成能判真假的句子 判据只有一句：**这句话能不能回答「做到了没有」**。 - ⛔「注意代码质量」—— 做不到，也没法验 - ⛔「尽量简洁」—— 「尽量」等于没要求 - ✅「提交前跑一次测试，失败不提交」 - ✅「回复不超过三段」 同一个意思，能不能写成可判的形式，决定了它会不会被执行。 **输出**：每条规则后面能打勾或打叉。 ### 第三步 · 每条规则后面写「什么时候不适用」 没有例外条款的规则，会被套用到所有场景——包括你说这句话时根本没想到的场景。 ``` 规则：删文件前先备份 不适用：临时文件、构建产物、可再生的缓存 ``` 这一段不是补充说明，是**规则的一部分**。省略它，Agent 要么机械执行（备份一堆垃圾），要么自行判断（判断往往和你不一样）。 **输出**：每条规则至少一个不适用场景。 ### 第四步 · 给每条规则一个出口 做不到的时候怎么办？三种出口，选一个写清楚： - **停住**：不具备条件就不做，等指示 - **降级**：按次优方式做，并说明降级了 - **报错**：明确说做不了，给出原因 ⛔ 不写出口，Agent 会自己编一个——通常是「默默按最省事的方式做」。 **输出**：每条规则的失败动作。 ### 第五步 · 控制总量，细节用指针 指令文件超过一屏（约 800 字），执行率就会下降。不是模型读不懂，是**重点被稀释了**。 拆法： - **常驻的只放规则**（不写背景、不写为什么） - **细节放单独文件**，用一句指针连：「部署注意事项 → `部署.md`」 - **为什么** 放到别处 —— 需要理解时才读，平时不用带 **输出**：一屏以内，其余靠指针。 --- ## 出问题怎么办 | 现象 | 最可能的原因 | 处理 | |---|---|---| | 规则写了但不照做 | 太抽象，无法判断做到没有 | 改成可判句 | | 越写越长，还是不管用 | 背景、规则、流程混在一起 | 拆成三类，各归其位 | | 每条都遵守，结果却不对 | 缺优先级——两条规则冲突时听谁的 | 写明「冲突时以 X 为准」 | | 换个模型就不灵 | 规则里用了模型不懂的行话 | 换成具体动作，不用行业词 | | 它自己决定跳过了某条 | 没有出口，它替你选了 | 补上失败动作 | | 遵守得过死，什么都要问 | 出口写成了「停住」，且没给判断条件 | 给「什么情况下可以自行处理」 | | 加了新规则，旧行为变了 | 规则之间有隐含冲突 | 逐条过一遍，找矛盾 | 倒数第三条是常见误区：**出口写「停住」不等于安全**——如果每条都写停住，Agent 会变成一个什么都不敢做的执行器。 --- ## 输出规范 ### 人读 ``` 指令文件：<文件名> · 长度 字 分三类：偏好 条 / 规则 条 / 流程指针 条 每条规则：可判句 ☑ / 不适用场景 ☑ / 出口 ☑ 优先级：冲突时以 <哪条> 为准 未覆盖：<这份文件不管什么> ``` ### 机器读 ``` file: size_words: n sections: {preference: n, rule: n, flow_pointer: n} rules: [{text, checkable: bool, not_for: [...], on_fail: stop|degrade|error}] priority: <文本> out_of_scope: <文本> ``` `checkable` 为 false 的规则，会在第一次执行时被跳过——**写的时候就要拦住，不要等它不生效再回头找**。 ### 一句话版 `N 条规则，全部可判、都带不适用与出口；超出的细节用 3 条指针连出去。` --- ## 常见错误 - **先写怎么做，不写什么时候不做** —— 规则会被套到不该用的地方。 - **用形容词写规则** —— 「注意」「尽量」「适当」全部不可判。 - **把背景写进指令文件** —— 每次会话都要读一遍背景，重点被稀释。 - **没有优先级** —— 两条规则冲突时，它选哪条看运气。 - **没写出口** —— 它会自己编一个，通常是最省事的那个。 - **一次写太长** —— 超过一屏执行率就掉，不是内容不对，是重点被埋了。 - **写完就不管** —— 规则会随着环境变化逐渐失真，需要定期核对。 --- ## 最后核对 2026-11-06。指令文件的形式随产品不同（AGENTS.md / 系统提示 / 自定义指令），但「可判 + 不适用 + 出口」这三条判据与平台无关。与所执行系统的既定标准冲突时，以那个系统的标准为准。