好的 AGENTS.md 等于免费换模型，写错了比没文档更糟

一份文件，让 AI 编码质量从 Haiku 跳到 Opus——或者让它比裸跑还烂。

下面这套东西，是 Augment Code 团队从一个大型 monorepo 里抽出几十份真实的 AGENTS.md 跑出来的实测结论，外加老金我自己的怀疑视角，把里面的几个坑也补上去。

希望读完这一篇，你不再"凭感觉"写 AGENTS.md。

让工程师惊掉下巴的实验

Augment Code 做了件事：从一个大型 monorepo 里提取了数十个 AGENTS.md，逐一测量它们对 AI 代码生成质量的影响。

结果他们自己都没想到——

最好的 AGENTS.md，带来的质量提升相当于把模型从 Claude Haiku 直接换成 Claude Opus。

最差的 AGENTS.md，让输出比完全不写任何文档还糟。

更夸张的是：同一份 AGENTS.md，在常规 bug 修复任务上把代码质量提升了 25%，在同一模块的复杂功能任务上却让完整性下降了 30%。

一份文件，正负 30% 的波动。

顺带泼一盆冷水："Haiku 跳到 Opus"是个非常抓人的比喻，但严格说不是模型变聪明了。好 AGENTS.md 提升的是"消除歧义"的能力，不是模型自身的推理能力。遇到真正需要多步逻辑推演的架构难题，再好的文档也救不了 Haiku。把它当成"减少 Agent 在你代码库里走错路的概率"更准确。

把这件事讲清楚，是因为后面的所有模式，本质都在做一件事：给 Agent 一份没有歧义的执行手册。

7 个有效模式

1. 渐进式披露，而不是把所有东西塞进一个文件

把 AGENTS.md 想成一个入口，不是百科全书。

• • 主文件控制在 100~150 行，覆盖常见场景与工作流
• • 细节推到几份"按需加载"的参考文件里

实验数据：在一个约 100 个核心文件的中等规模模块里，这个体量的主文件让所有指标提升 10~15%。一旦超过 150 行，收益开始反向。

为什么是 150 行？因为当前 AI 编码助手普遍存在"中间迷失"（Lost in the Middle）现象——即便模型宣称 200K 甚至 1M 上下文，当规则被埋在长文本中段时，遵循率会直线下降。150 行是把注意力机制压在"高度聚焦区"的甜区。

2. 程序性工作流：让 Agent 从"无法完成"到"一次成功"

把任务写成编号的多步骤工作流，是测量到的最强模式之一。

一个真实例子：部署新集成的六步工作流。Agent 照步骤执行后——

• • 缺少连接文件的 PR 比例：40% → 10%
• • 正确性 +25%
• • 完整性 +20%

工作流的本质是消除歧义，让 Agent 不用猜。

3. 决策表：在写第一行代码前就解决"二选一"

代码库里经常有两三种都说得通的做法——React Query 还是 Zustand？REST 还是 GraphQL？

决策表强制提前选好。Agent 读完就知道走哪条路，不用在代码里反复试探。

效果：相关区域的 PR 在"最佳实践遵从度"上 +25%。

4. 真实代码片段，不是伪代码

来自实际生产代码的 3~10 行短片段，改善了代码复用和模式遵从。

关键词是"真实"——伪代码和示意性代码效果远不如直接从生产代码里截取的。但保持在最相关的几个示例以内，超过这个数量，Agent 会开始在错误的地方做模式匹配。

很多人到这里会担心：代码飞速迭代，硬编码的片段下个月就过期了，AI 不就被带偏了吗？
解法：动态引用优于硬编码。如果工具支持，尽量用相对路径或 @引用核心文件，让 Agent 跳去看活的代码；只有在那段逻辑足够稳定时，才直接复制片段。复制进来的片段，必须进 Code Review 的 checklist——API 一变就同步更新，否则它就从资产变成毒药。

5. 每个"不要做"都配上"要做"

只有警告的文档，表现一贯不如"禁令 + 替代方案"配对的文档。

❌ 不要直接实例化 HTTP 客户端

✅ 不要直接实例化 HTTP 客户端。
   使用 lib/http 中带有重试中间件的共享 apiClient。

第一条让 Agent 变得谨慎和探索性——它知道不能做什么，但不知道该做什么，于是开始翻代码库。第二条告诉它该怎么做，直接继续。

有 15 条以上连续"不要做"且没有"要做"的文件，会导致 Agent 过度探索、保守行事、完成更少工作。

6. 代码模块化，文档也要模块化

表现最好的 AGENTS.md，描述的是相对隔离的子模块。仓库根目录的大型跨领域文件，效果不如模块级别的。

更关键的是：AGENTS.md 只是入口，周围环境才是问题所在。

实验里，一个模块有 37 个相关文档总计 50 万字符；另一个有 226 个文档超过 2MB。这两种情况下，仅仅移除 AGENTS.md 几乎不改变 Agent 的行为——因为 Agent 会继续找到并阅读周围的文档蔓延。

一个聚焦的 150 行 AGENTS.md，放在 50 万字符的周围规格之上，救不了你。

修复文档环境，不是只修入口。

7. 特定领域规则要具体、可执行

语言特性、框架约定、安全限制——这些规则有效，前提是具体且可执行。堆几十条模糊规则，效果跟没写一样。

两个最常见的失败模式

1. 过度探索陷阱（上下文腐烂）

最常见的失败，本质是上下文中毒。

两种写法触发它：

太多架构概述
Agent 被拉去阅读数十个文档，试图"更好地理解架构"，加载几万甚至几十万 token 后，输出反而变差。

过多警告堆叠
大量"不要做"且没匹配"要做"，Agent 会对每一条警告都去验证当前方案是否违规。30~50 条警告，意味着它要去翻迁移脚本、检查 API 版本兼容性、探索认证中间件——即使这些跟当前任务完全无关。

2. 文档描述了代码库里还不存在的模式

如果在 AGENTS.md 里写了一个"打算引入但还没落地"的新模式，Agent 会被积极地引向错误方向——它按文档去找根本不存在的代码，然后产生错误的解决方案。

AGENTS.md 描述现状，不是愿景。

文档发现率

Augment Code 在数百个 session 里追踪了 Agent 实际读取了什么：

• • AGENTS.md：100%，自动发现
• • AGENTS.md 中引用的参考文件：>90%，按需加载
• • 当前工作目录的 README.md：>80%
• • 嵌套子目录的 README：~40%
• • _docs/文件夹中无引用的孤立文档：<10%

一个服务在 _docs/里放了 3 万字符的协议设计、限流规则和安全文档，Agent 在数十个 session 里几乎从未打开过其中大多数。

**AGENTS.md 是唯一具有可靠发现性的文档位置。**如果某些内容需要被 Agent 看到，要么在那里，要么从那里直接引用。把内容移到被引用的位置，往往比写更多文档更有杠杆效果。

几个值得讨论的边界

到这里我把 Augment Code 的实验讲完了。但作为一个见过太多"银弹"的工程师，必须把下面这几条也说清楚——否则这套方法落到不同团队、不同工具上，会失效。

1. AGENTS.md 不是 README 的替代品

读到"主文件控制在 150 行 / 不要写架构概述"，很多人会担心：那新人入职怎么办？架构图、历史决策、设计哲学谁来讲？

答案是分受众。

README 是写给人类的
人类需要架构、愿景、来龙去脉，才能在脑子里建立心智模型。

AGENTS.md 是写给机器的执行手册
它只关心规则、工作流、防坑指南。

接受这种分离，是 AI 时代工程实践的第一步。两份文件不是 DRY 的破坏，而是因为受众不同，关心的层级也不同。当然，两份都要维护——这是真实成本，要计入。

2. 维护成本不能假装不存在

"使用真实代码片段"+"描述现状不描述愿景"这两条加起来，意味着 AGENTS.md 是一份高频更新文档。

不接受这一点的团队，AGENTS.md 几个月后就会变成第二种失败模式——描述了代码库里已经不存在的模式，把 Agent 主动引向错误方向。

应对办法：

优先用引用，不用复制
真实代码片段尽量是文件路径 + 函数名而不是粘贴。

复制片段进 Code Review checklist
API 改动时强制 reviewer 检查 AGENTS.md。

定期 prune
每个迭代/季度删一遍过时的警告与工作流，比加新条目更重要。

3. 150 行不是真理，是当前模型的甜区

这条数据来自 Augment Code 自家的 RAG 与上下文管理策略。换一套底层 Agent（Cursor / Claude Code / Devin / Copilot Workspace），检索算法和注意力分布都会不同。

100~150 行真正的含义不是"上限"，而是：把规则压进模型注意力机制最聚焦的那一段。模型一升级，这个数字会往上挪；但"主文件聚焦、细节外推"这个结构原则不会变。

把它当原则用，不要当数字背。

最后

这件事最有价值的地方，不是抛出了什么新奇的结论，而是用数据把一件模糊的事说清楚了：

AGENTS.md 不是越多越好，不是越全越好，不是越详细越好。

它是一个精心设计的上下文入口。写好了，相当于免费升级了一个更强的模型；写烂了，你付出维护成本，换来一个比裸跑更差的 AI。

在 AI 工程里，"少即是多"这句话，从未像现在这样字面成立过。

转自：https://mp.weixin.qq.com/s/3bTDtC5keck37gq4NMAi9Q