AGENTS.md 文件的真实效能差距：为什么 80% 的写法反而拖累 AI 编码 Agent？Augment 内部基准拆解路径
在 Augment Code 的 monorepo 里，我们把几十份 AGENTS.md 文件拉出来，系统测了它们对编码 Agent 的真实影响。结果最优的几份文件，让 Agent 的代码生成质量直接从 Haiku 级跃升到 Opus 级；而最差的几份，反而让输出比完全没有 AGENTS.md 时还糟糕。这个差距大到我们不得不专门做了一轮 AuggieBench 基准研究。
我起初以为 AGENTS.md 只要写得够详细、覆盖够全，就能成为 Agent 的“知识地图”，结果真实评测数据把我彻底打醒：同一份文件在不同任务上效果完全相反，最多能让某个指标提升 25%，同时让另一个指标下降 30%。Agent 不是人类，它对文档的消费方式极其机械——多一页无关内容，就可能触发指数级过探索，最终把简单任务做成一团乱麻。
为什么大多数 AGENTS.md 正在悄悄拖后腿
问题不在内容本身，而在于我们默认把 AGENTS.md 当成“人类可读的知识库”。Agent 读取文档的方式是“全量上下文注入 + 贪婪搜索”，一旦文件超过 150 行，或者周边散落着几十万字符的配套文档，Agent 就会陷入“先理解整个架构再写代码”的死循环，把 token 全部浪费在无关验证上，最终输出保守、残缺、甚至引入多余抽象。
这就像给新手厨师塞一本 500 页的菜谱大全，让他做一盘炒饭：厨师不是偷懒，而是真的被淹没在“别用隔夜米”“别用普通酱油”这类警告里，最后连基本步骤都忘了。
真正有效的七种模式（基准验证过的最优实践）
渐进式披露优于全面覆盖
主文件控制在 100–150 行，只放高频场景和核心工作流，细节推到按需加载的参考文件中。我们的中型模块（约 100 个核心文件）里，这套做法让所有指标平均提升 10–15%。文件一旦变长，收益立刻反转。程序化工作流把“做不完”变成“一步到位”
用编号的多步流程描述任务，是我们测到提升最显著的模式。一份六步集成部署工作流，把缺失布线文件的比例从 40% 降到 10%，正确性和完整性分别提升 25% 和 20%。复杂分支依然推到参考文件，避免主文件膨胀。决策表在写代码前就解决歧义
当 codebase 存在两种合理实现方式时，决策表能让 Agent 在动笔前就锁定正确路径。我们在 React Query vs Zustand 的场景里看到 best_practices 指标直接提升 25%。# 状态管理选择决策表 ## 场景：需要跨组件共享状态 + 服务端数据同步 | 条件 | 推荐方案 | 理由 | |-----------------------|--------------|-----------------------------------| | 需要服务端缓存 & 自动 refetch | React Query | 内置 devtools + 缓存一致性 | | 纯客户端 UI 状态 | Zustand | 轻量 + 极简 API | | 两者都需要 | React Query + Zustand 组合 | 各司其职，避免上下文污染 |真实 codebase 里的短代码片段提升复用率
3–10 行的生产代码示例效果最好。数量控制在少数最相关、非重复的几个，避免 Agent 错误 pattern-match。领域特定规则依然有效，但必须“具体可执行”
语言或组织级坑点写得越精准越好。一旦堆叠到几十条，Agent 就会开始逐条验证，陷入过探索。每一条“Don’t” 必须配一条“Do”
纯警告文档让 Agent 变得过度谨慎。配上具体替代方案后，Agent 立刻知道下一步该做什么，而不是停下来思考“这个规则是否适用”。保持模块化——AGENTS.md 也要模块化
跨仓库根目录的巨型 AGENTS.md 表现远不如模块级（100 个文件左右）的小而美文件。文档环境同样关键：如果模块周边堆着 500K 字符的规范文档，Agent 根本不会只看你的 AGENTS.md。
过探索陷阱：Agent 最大的隐形杀手
我们观察到的最常见失败模式是上下文腐烂（context rot）。两种典型诱因：
- 过长的架构概览，把 Agent 拉进几十个文档的兔子洞。
- 过多纯“Don’t”警告，迫使 Agent 为每个警告去验证迁移脚本、API 版本、鉴权中间件——哪怕当前任务完全无关。
新引入的模式如果与现有文档冲突，也会让 Agent 彻底迷失方向。
Agent 实际如何发现文档（真实追踪数据）
我们追踪了数百次会话，发现规律极其极端：
- AGENTS.md 在工作目录层级内 100% 被自动发现。
- 从 AGENTS.md 引用的参考文件，在 Agent 有理由时 90%+ 被读取。
- 目录级 README.md 在当前目录下 80%+ 被读取。
- 嵌套子目录 README 或 _docs/ 里的孤立文档，发现率暴跌到 40% 甚至 10% 以下。
结论简单粗暴：真正需要被看到的内容，要么直接写进 AGENTS.md，要么被它显式引用。其他位置的文档基本是“写给人类看”的存档。
迁移现有文档的务实路径
不需要把所有 README 都改名 AGENTS.md。Agent 现在已经足够聪明，能把人类文档做总结。但正确做法是：
- 保留高质量、有示例、结构清晰的文档，从 AGENTS.md 里引用（单文件不超过 10–15 个）。
- 激进精简：砍掉所有“供人类快速浏览”的段落，只保留 Agent 执行时真正需要的部分。
- 如果模块周边文档环境已经爆炸，先治理文档 sprawl，再优化 AGENTS.md。
AGENTS.md 不是唯一路径，但它是最高杠杆的入口
Agent 还会通过 grep 和语义搜索发现代码里的注释和文档，大约一半的搜索命中来自这些。但 AGENTS.md 是唯一能 100% 可靠注入上下文的入口——它给了你对上下文窗口的主动控制权。
为了帮助团队快速对齐，我把核心模式做成了决策矩阵：
| 模式 | 对常规 Bug Fix 的影响 | 对复杂特性任务的影响 | 适用场景 | 推荐长度/数量 |
|---|---|---|---|---|
| 渐进式披露 + 参考文件 | +12% | +15% | 中型模块 | 主文件 100-150 行 |
| 程序化工作流 | +25% 正确性 | +20% 完整性 | 多步骤集成/部署 | 6-8 步 |
| 决策表 | +25% best_practices | +18% | 存在多种合理实现方式 | 3-5 种选择 |
| 纯“Don’t”警告 | -15%（过探索） | -30% | 任何场景（强烈不推荐） | 0 条 |
| 巨型跨仓库文档 | -8% | -22% | 避免使用 | - |
为什么模块化 + 流程驱动的 AGENTS.md 才是当前最务实的 Agent 编码基础设施
这份研究最颠覆的认知是：AGENTS.md 不是“越多越好”的文档，而是一把双刃剑。它真正的高杠杆在于把“人类隐性知识”转化成 Agent 运行时的确定性约束，而不是堆砌信息。把大部分智慧前置到结构化模式里，Agent 就能把注意力真正放在写代码上，而不是读文档上。
当然，这套方法也有边界：它对单次任务（one-shot）最有效，长期维护 AGENTS.md 的最佳实践我们还在探索；操作型、交互型任务的模式也需要后续验证。但相比继续让 Agent 在文档海洋里盲目搜索，这已经是生产力上一个数量级的提升。
在生产环境落地 AGENTS.md 前你必须验证的三件事
- 每份 AGENTS.md 主文件严格控制在 150 行以内，所有细节推到显式引用的参考文件。
- 每一条规则都必须配上“Do”的替代方案，并经过至少一轮真实任务的 A/B 测试。
- 模块周边文档环境必须先做审计——如果总字符数超过 500K，先治理 sprawl 再写 AGENTS.md。
当你真正把 AGENTS.md 从“知识库”升级成“Agent 的技能手册”时，会突然发现：编码 Agent 不再是“偶尔能帮上忙的工具”，而是能严格遵守你 codebase 所有隐性共识、稳定输出高质量 PR 的“资深同事”。
你团队当前的 AGENTS.md 里，决策表和工作流的比例大概是多少？在实际让 Agent 基于它们生成代码时，你观察到的最大收益或最严重的过探索场景是什么？欢迎在评论区分享你的真实数据，我们一起把 AI 辅助编码的确定性再推高一个量级。
我是紫微AI，在做一个「人格操作系统（ZPF）」。后面会持续分享AI Agent和系统实验。感兴趣可以关注，我们下期见。