它解决什么问题
没有说明书时，Agent 会用平均互联网习惯：乱改格式、新增依赖、把文件放到你不用的目录。
有说明书时，它先看到：语言版本、测试命令、生成代码放哪、什么不能提交。
它不是博客，也不是 README 的复制。README 给人看；AGENTS.md 给会跑命令的 Agent 看。
说明书是契约：语言、测试命令、禁止路径。
文件放哪，怎么合并
最常见的是仓库根目录一份 AGENTS.md。子目录也可以再放，客户端常从根走到当前目录拼接。
用户级文件常在 Codex 主目录。全局习惯放用户级，仓库特例放仓库根。官方文档还提到可选的覆盖文件名，以你当天的文档为准。
若根目录和子目录说明书打架，宜补细节，不要反转禁区。
- 仓库根：团队共享的硬约束。
- 子目录：该包自己的测试命令。
- 用户级：你个人的口味，别强迫同事。
第一页写什么
开头写三行：这是什么项目、怎么验证、绝对不要做什么。禁区比形容词有用。
然后写目录地图和常用命令。长流程不要塞这里，请写技能。文件过大时，后面的内容可能被截断，所以关键句放前面。
把最硬的三条禁区写在第一屏。文件很长时后面可能被截断。
- 验证命令。
- 禁提交的路径和密钥。
- 代码风格只写会反复踩的点。
- 生成文件放哪。
一份可以借的起手结构
有用的第一页：这是什么仓库、怎么验证、不要提交密钥、新文件放哪。
不要为了像真就贴真令牌。写环境变量名就够。
- 项目一句话和验证命令。
- 密钥和生成目录写进禁区。
- 新文件应该放哪。
和技能、编辑器规则的分工
AGENTS.md 是始终生效的约束。技能是可点名的剧本。Cursor Rules 是另一客户端的常驻规则，职责类似说明书，文件名不同。
稳定禁区写说明书。开 PR、发版这类步骤写技能。不要两边复制一份会过期的长流程。
若也用 Cursor Rules，把同一套禁区留在两边，或指定一份常驻文件为真源。
- 密钥、生成目录：说明书。
- PR 清单：技能。
- 只对 Cursor 生效的格式：Rules。
人们实际怎么加载说明书
让 Agent 引述 AGENTS.md 的前几行。看不见就是路径或扫描问题。
有的客户端能生成起草。当草稿用，改成这个仓库的事实。
- 先让它引述 AGENTS.md。
- 加技能之前先修路径。
写完怎么维护
Agent 连续踩同一条，再加一句。不要每次对话都扩写。
有的客户端提供初始化命令生成草稿，仍要你改成这个仓库的事实。
当 Agent 重复踩同一个错，在顶部加一句。
- 每季删过期命令。
- 新禁区写在文件顶部。
写说明书时的错
从别的仓库克隆说明书，会写错测试命令，Agent 会很自信地失败。
长篇说明书会把禁区措在后面。第一页要短。
- 克隆别人的说明书。
- 把禁区藏在长文下面。
AGENTS.md 清单
同事不问你也能按禁区做，这一章就结束了。
- 禁区在第一页。
- 一条你能跑的验证命令。
- 文件里没有真密钥。
下一步：把重复任务变成技能
第三次打同一套 PR 步骤，就该写进技能，不是更长的说明书。
写技能时让说明书保持稳定。