给 agent 写文档

适用于一切会被 agent 读到的文档。目标是让每次运行走同样的过程，用最少的字。

检验

每句话默认删。留下的要同时满足：

• 有出处：一次观察到的失败（agent 这样错过，或用户这样纠正过；“模型可能会犯”不算），或环境里查不到、重新摸清代价高的事实（未写明的约定、某个选择的理由、只能在第三方控制台上做的步骤）。几分钟能试出来的坑不算：踩到时修成报错、lint 或代码旁的一句注释。脚本、配置、目录结构、--help 查得到的不重述。
• 删掉会变差：当前模型没有它就做错。

不满足的整句删掉，不只删几个字。常见的：

• 模型默认就会做的步骤：理解需求、自查、"要彻底"。
• 为旧模型写的验证与复查指令。当前模型会自行验证，这类指令只造成过度验证；删掉，不改写。
• 全大写和"必须""务必"式强调。新模型对系统提示更敏感，强调会让它过度触发；写成平实的"在……时做……"。

清理

新写、被要求精简或审查时过整份文档；只改一处时过它所在的那一节。每句定一个去向：

1. 过不了检验的，删。
2. 能机器检查的（格式、禁词、命名、依赖方向），做成 lint、hook 或测试，修复指引写进报错信息，然后从文档删掉；这次做不了就留着，在回复里提出。
3. 其他层（全局系统提示、插件提示词、项目 AGENTS.md、skill）已有同义的，合并到一处：各层各写一遍“要验证”，agent 就验证三遍。
4. 只有部分情形用到的，按「结构」移出正文。

要加规则时先找能改写的现有句子；确需新增，同一次改动里找一句可删的。

完成标准：留下的每一句都过了检验，且同一含义只在一处出现。

常驻文档（系统提示、AGENTS.md、skill 的 description）新写或大改后，有子代理工具时派一个新上下文的子代理，只给它文档和本 skill，让它列出过不了检验的句子，属实的删掉。起草者带着整段对话的上下文，看不出哪些句子多余。

指针

AGENTS.md 里指向某份文件的一行、skill 的 description，都是指针：说明材料是什么，以及什么情形去读。

• 触发词放最前；每种情形只留一个触发词，同义改写合并掉。
• 该读的材料没被读到，先加强指针措辞、写清触发情形（"等合并与发布只用 make land"），加强无效才把内容内联。
• 指针每轮都在上下文里，比正文裁剪得更狠；正文已说明的身份信息不在指针里重复。

AGENTS.md 是地图：命令入口、代码看不出的约束、"遇到某种情形去读某份文件"的条件指针。架构概述、目录树、rg 一下就能找到的东西不写。

结构

文档由两种内容组成：agent 按顺序做的步骤，和按需查的参考。

• 每条路径都用到的内容写在正文；只有部分情形用到的移到单独文件，正文留指针。步骤被参考资料埋住时，agent 注意不注意到全看运气。
• 同一概念的定义、规则、注意事项放在同一标题下，不散在各处。
• 只在某个事件或某次工具调用时才用得上的说明，写进那条事件消息或工具说明，不放进每轮常驻的提示词。
• 每个步骤以完成标准结尾：可检查（分得清做完没做完），且要求穷尽（"每个被改的调用点都已核对"，而不是"列出改动"）。标准含糊，agent 会提前收工。

措辞

• 写目标行为（"写单行注释"），不写笼统禁令（"别啰嗦"）：禁令会把被禁的东西带进上下文。硬性护栏才直接禁止。
• 规则有例外就写进同一句（“……时先确认，其余直接开工”），不另起一条去抵消它：两条规则相互拉扯时，哪条占上风没有保证。
• 观察到具体失败模式时逐项点名（"奶油色背景、标题里的斜体强调词、01/02/03 编号标签"），同时写出要什么。
• 用模型预训练里已有的常用词（tracer bullet、expand–contract），不自造术语；一串形容能收成一个这样的词就收（“快、确定、开销低”收成 tight）。自造词要花字定义，还会被 agent 带进给用户的回复，变成用户看不懂的黑话。

Skill

• description 每轮常驻上下文，按「指针」写；模型需要自己发现时才开放自动触发。
• 只靠手动命令或其他 skill 明确指向的，加 disable-model-invocation: true，它就不进自动列表。
• 正文超过 500 行就按情形拆出参考文件，引用只走一层。