给 agent 写文档

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

唯一检验

每句话都要回答：删掉它，当前模型的行为会不会变差？不会就是无操作，整句删掉，不只删几个字。有分歧时跑一次文档看结果，不靠争论。

常见的无操作：

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

写什么

• 环境是事实源：脚本、配置、目录结构、--help 查得到的不重述。文档只缓存查不到的：未写明的约定、某个选择的理由、配置没承认的坑。
• 单一事实源：同一含义只有一个权威位置；发现第二份就合并，不维护两处同步。
• 越短越正确：每次改动顺手删掉失效、过时或已被别处覆盖的内容。不删的结局是层层沉积，有效内容被埋在过时内容下面。

指针

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

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

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

结构

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

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

措辞

• 写目标行为（"写单行注释"），不写笼统禁令（"别啰嗦"）：禁令会把被禁的东西带进上下文。硬性护栏才直接禁止。
• 观察到具体失败模式时逐项点名（"奶油色背景、标题里的斜体强调词、01/02/03 编号标签"），同时写出要什么。
• 用模型预训练里已有的常用词（tracer bullet、expand–contract），不自造术语。自造词要花字定义，还会被 agent 带进给用户的回复，变成用户看不懂的黑话。

术语表 WORDS.md

项目术语表只收代码看不出的约束，一条一行：

- **桌仔**（Guide）→ `guide`；避免：主持

• 只收两种：带「避免」的（这个概念在本项目叫什么、不能叫什么，含改名后退役的旧名），和易混概念的一句区分（会话 vs 分段）。只有「词 → 模块」映射的不收：搜代码就能找到。
• 业务规则写进所属模块的头注释，不进术语表。
• "避免"项能做成禁词检查的，做成 lint 后从表里删掉。

Skill

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