Augment Code 系统研究了 AGENTS.md 对 coding agent 输出质量的影响，结论反直觉。
核心发现
最好的 AGENTS.md 效果等同于从 Haiku 升级到 Opus。最差的 AGENTS.md 让输出比没有文档还差。
同一个文件在不同任务上效果截然不同：
- 同一个 AGENTS.md 在常规 bug fix 上让 best_practices 提升 25%，但在复杂 feature 任务上让 completeness 下降 30%。
7 个有效模式
1. 渐进式披露（Progressive Disclosure）
主文件 100-150 行，覆盖常见 case 和工作流的高层描述，细节推入 reference 文件按需加载。最佳表现是 100 个核心文件的中等模块配 100-150 行主文件 + 少量 reference docs。一旦主文件超过这个长度，收益就开始反转。
2. 流程化工作流让 agent 从做不到到一次做对
把任务描述成编号的多步骤工作流，是测量中效果最强的 pattern 之一。六步部署工作流让缺失 wiring 文件的 PR 比例从 40% 降到 10%，正确率提升 25%，完成速度提升 20%。
3. 决策表在 agent 写代码前解决歧义
当 codebase 里有两个合理方案时，决策表把选择提前。React Query vs Zustand 的决策表让相关 PR 的 best_practices 得分提升 25%。
4. 真实代码示例提升复用
3-10 行的真实生产代码片段最有帮助。太多会让 agent 开始 pattern-match 错误的东西。
5. 领域特定规则仍有价值
但只在你写得具体、可执行的时候有效。堆几十条规则反而有害。
6. 每个「不要」都要配一个「要」
只有警告没有替代方案会让 agent 保守、过度探索。只写「不要直接实例化 HTTP client」不如写「用 lib/http 里的共享 apiClient 带 retry middleware」。后者直接告诉 agent 做什么，然后 move on。
15+ 条连续的「不要」没有对应「要」，会导致 agent 过载：读每条指令，判断是否适用于当前任务，然后对照每条 warning 验证自己的方案。30-50 条 warning 的结果是，即使任务根本不需要，agent 也会去读 migration scripts、检查 API 版本兼容性、探索 auth middleware 代码。
7. 模块化文档结构
100 个核心文件的中等模块是 AGENTS.md 效果最好的粒度。repo 根目录的大型跨模块 AGENTS.md 表现反而差。
2 个失败模式
Overexploration Trap（过度探索陷阱）
这是最常见的失败模式，本质上是 context rot：
- 过多架构概述：agent 被拉去读文档文件（有时候几十个），试图「更好地理解架构」，结果 context window 装了十万 token 的内容，输出反而变差。
- 过多警告：每个 warning 让 agent 判断是否适用当前任务，然后去验证。warning 越多，exploration 越多，完成的工作越少。
新模式打破旧文档
当你在 codebase 里引入尚不存在的新 pattern 时，AGENTS.md 会主动把 agent 引向错误方向——因为文档里没有这个新 pattern，agent 读文档反而被误导。
文档发现优先级
Augment 追踪了数百个 session 中 agent 的文档发现路径：
| 文档位置 | 发现率 |
|---|---|
| AGENTS.md（从工作目录向上所有层级自动发现） | 100% |
| AGENTS.md 里引用的 reference 文件（有理由拉取时） | >90% |
| 目录级 README.md（非自动加载，但 80%+ session 会读） | ~80% |
| 嵌套 README（agent 不在那个 subdir 时） | ~40% |
| _docs/ 里没有引用的孤立文档 | <10% |
AGENTS.md 是唯一有可靠发现率的文档位置。 如果某个内容需要被看到，要么放在 AGENTS.md 里，要么从 AGENTS.md 直接引用。
不要把 README.md 改成 AGENTS.md
README 和 AGENTS.md 服务于不同受众。可以复用 README，但要激进裁剪——保留对 agent 有用的部分，删掉给人浏览的内容。
周围文档环境同样重要
一个案例：某个模块有 37 个相关文档共约 500K 字符。删掉 AGENTS.md 几乎没改变 agent 行为——agent 继续找周围的文档 sprawl，那个 sprawl 才是问题。
好的 AGENTS.md 放在有 500K specs 的模块上，agent 还是会去读那些 specs。
修复文档环境比修复入口点优先级更高。