AGENTS.md 系列总结：五个教训、常见问答与我的复盘
TL;DR —— 五篇文章，一个文件。整条路线：它是什么 → 动手写一个 → 为何会腐化 → 保持真实 → 从事实中自动生成。本篇是收尾篇：系列地图、五个常见问答、以及最重要的教训——事实块 vs 独特文风。
📚 AGENTS.md 系列 · 你正在阅读第 6 篇——系列总结 I · 实战指南 II · 动手写 III · 腐化 IV · 保持真实 V · 从事实生成 VI · 系列总结（就是本篇）
新读者？
AGENTS.md 是仓库根目录下的一个 Markdown 文件，告诉 AI 编程 Agent 如何在这个项目里工作——命令、测试、约定、护栏。它是 AAIF / Linux Foundation 下的开放标准。如果你想了解全貌，从第 I 篇开始看。
我们讲了什么
五个教训，一个目标：让 briefing agent 真正按你定的规则来。
| 篇章 | 角色 | 一句话总结 |
|---|---|---|
| I 实战指南 | AGENTS.md 该放什么、不该放什么 | |
| II 动手写 | 构建一个真实文件，然后让 Agent 去用它 | |
| III 腐化威胁 | 过时的文件依然会被严格执行——而且毫不怀疑 | |
| IV 保持新鲜 | 同 PR 反腐化、用 Agent 验证、让真相跟上代码变化 | |
| V 终极方案 | 从仓库事实自动生成文件，彻底解决跑偏问题 |
如果你只打算在本文之外再读一篇：选第 III 篇（如果你还没体验过腐化）；选第 V 篇（如果你已经有文件，想让文件不再撒谎）。
路线总览：整条弧线如何衔接
把它当作一条完整路径，而不是五个孤岛。
- I 什么是 AGENTS.md？ → 原则、结构、反模式
- II 动手写一个 → 真实文件、真实 Agent 回报
- III 看着它变腐化 → 为什么“存在” ≠ “真实”
- IV 用手保持新鲜 → 代码变动时的人工纪律
- V 停止手动维护事实 → 从仓库已有的信息自动生成
VI 本篇 → 地图 · 常见问题 · 教训
前三篇（I、II）让你得到一个能跑起来的文件。III、IV 让它在变更后依然诚实。V 剔除了那些本就不该手动编写的行。本篇（VI）就是这张地图，以及一个需要人为判断的问题：哪些事依然离不开人。
这个系列并不是在鼓吹把 AGENTS.md 写得更长，而是主张写得更真——先写一个简明的事实块，再配上你的叙事。总长度由你自己决定。
五个常见问题
1. 如果我已经有 README / CONTRIBUTING / CLAUDE.md，还需要 AGENTS.md 吗？
需要——只要你的 repo 里跑着 agent。README 是给人浏览的；CONTRIBUTING 是流程说明；厂商专属文件（如 CLAUDE.md）是给特定工具用的。AGENTS.md 则是通用工具无关的简报，很多 agent 已经在主动寻找它。保持简短，用链接展开深度，不要复述一本小说。
2. 它应该多长？
短到让 agent（以及人类）仍然愿意信任每一行。优先放那些能直接运行的命令、真实存在的路径、以及确实能起作用的护栏。如果某个段落无法通过目录树或一条规则验证，就删掉它，或者移走它。
3. 最常见的失败模式是什么？
看起来依然官方，但内容已经过时。重命名的脚本、废弃的测试命令、滞后于目录结构的映射——agent 会十分信任地照着它们执行。第三篇才是整个系列的核心。新鲜度不是锦上添花，它就是产品本身。
4. 应该每一行都自动生成吗？
不。生成（或检查）那些仓库能证明的东西：包名、脚本、项目布局、CI 命令。保留只有人类才能拥有的内容：判断力、产品的「为什么」、不在目录树中的团队规范、以及尚未写成 linter 规则的「永远不要做 X」。第五篇是事实块部分的终局——不是对判断力的替代。
5. 我什么都没有，从哪里开始？
第一篇 —— 形状与反模式
第二篇 —— 写一个并用 agent 验证
当它开始撒谎时，去读第四篇，然后是第五篇
不要永远跳过第三篇——你迟早会通过痛苦的方式遇到它。
我的教训：事实块 vs 独特叙事
如果说这个系列只留下一个观点，那就是这句。
事实块（Facts block）—— 核心原则
| 项目 | 含义 |
|---|---|
| 独特描述（Unique prose） | 仓库已经知道或能证明的内容 |
| 只有人类才该断言的事情 | 构建/测试命令、包布局、入口点、CI检查等 |
| 产品为何存在、团队偏好、软性规范、尚未编码的硬性“绝对不做” | 失败模式：漂移（如目录移动但文件没跟着动）、模糊或说教（AI无法操作） |
| 修复方法 | 从目录树出发检查，漂移时CI失败（✓）；写短小、可执行、由人类负责的内容，当规范变化时与变更提同一PR（✓） |
更好的 AGENTS.md = 与树结构匹配的事实 + 值得占据字符的描述文字。
以前我总把整个文件当成“我该维护的文档”。这个系列教会我把任务拆分开：用自动化保证地图（目录结构）的真实性；把人类精力留给判断。这就是“文件存在”和“文件值得被信任”之间的区别。
实践中的“好”与“更好”对比
| 维度 | 好 (Good) | 更好 (BETTER) |
|---|---|---|
| 文件存在于仓库根目录 | ✓ | ✓ |
| AI能遵循设置/测试命令 | 常常可以 | 命令与 package.json / just / CI 当前状态匹配 |
| 结构/地图 | 含糊或不全 | 与实时目录树匹配（或特意指向它） |
| 过时行 | “我们以后修” | 与变更同PR，或重新生成事实 |
| 长度 | 又长又炫 | 短而真 |
Goose、Cursor、Claude Code、Copilot、Codex —— 它们都不需要你的回忆录。它们需要一份简报，让它们不会满自信地冲进一个已被重命名的脚本。
问答与反馈
这篇文章是 AAIF（AI Agent 交互框架）大使计划系列收尾 —— 一份实用、无厂商偏见的 AGENTS.md 指南。
我想听听你的声音：
- 你的 AGENTS.md 最先在哪个部分腐烂（命令、结构、围栏、还是其他）？
- 你尝试过从事实出发编写（Part V）吗？什么环节出了问题？
- 这五篇文章还没触及到哪些 AGENTS.md 讨论中的空白？
欢迎在本文下方评论，或在你关心的项目上发起讨论（例如：确保那个仓库的 Structure 部分与 crates/ / src/ 保持一致）。当真实的目录结构开始挑战漂亮的文档时，标准才会变得更好。
系列索引（请收藏）
- AGENTS.md：让 AI 编程 Agent 真正有用的一份文件 — 实践指南
- AGENTS.md 动手实操：一步步构建 — 教程
- 你的 AGENTS.md 已经过期（而你的 Agent 却完全信任它）— 威胁
- AGENTS.md 保持真实：逐步阻止腐化 — 纪律
- AGENTS.md 基于事实：撰写一份不会偏移的文件 — 终极工具路径
- 本文 — 总结 · 常见问题 · 事实 vs 叙述
延伸阅读：标准本身请见 agents.md，以及按章节划分的实践指南 — 什么值得写一行、排序、长度、反模式 — 在 faf.one/agents。感谢你阅读本系列。发布一份简短真实的文件，然后保持它真实。👍