一份 AGENTS.md 能顶一次模型升级？Augment Code 用数据说了算

Augment Code 做了一件大部分公司只说不做的事：他们从自己的 monorepo 里拉了几十份 AGENTS.md，然后用数据测量每份文件对 AI 代码生成质量的影响。

结论很刺激——最好的 AGENTS.md 带来的质量提升，相当于把模型从 Haiku 升级到 Opus。最差的那些，比没有 AGENTS.md 还要糟糕。

同一个文件，在一个 bug 修复任务上把 best_practices 提升了 25%，在同一个模块的一个复杂 feature 任务上却把 completeness 拉低了 30%。同一份文档，不同任务，效果天壤之别。

这篇文章在 Hacker News 上炸了，因为戳中了所有用 Claude Code、Cursor 这些工具的开发者的痛点：AGENTS.md 写得好不好，直接决定 AI 给你写的代码行不行。

本文提纲

  1. 他们怎么测的
  2. 七个有效模式
  3. 两个致命陷阱
  4. 文档发现率的残酷真相
  5. 实战迁移建议

他们怎么测的

用内部评估套件 AuggieBench。流程很硬核：

  1. 从大仓库里挑出高质量的 PR（经过多位高级工程师 review 的"黄金版本"）
  2. 设置环境，让 Agent 执行相同的任务
  3. 把 Agent 的输出和黄金 PR 对比打分
  4. 每个任务跑两遍——有 AGENTS.md 和没有，对比差异

他们加了过滤条件：PR 必须限定在单个模块内，且范围是 AGENTS.md 合理能帮到的场景。

这不是拍脑袋的结论，是控制变量实验。

七个有效模式

1. 渐进式披露，别一口气全写

100–150 行的 AGENTS.md + 几份聚焦的参考文档，是表现最好的组合。在约 100 个核心文件的中等模块中，这种结构带来 10–15% 的全指标提升。

超过这个长度，收益开始反转。

原理：把 AGENTS.md 当成一个 skill 来写——先覆盖常见场景和工作流的高层描述，细节推到参考文件里按需加载。每份参考文件的范围要清晰，让 Agent 知道什么时候该拉进来。

2. 编号工作流：从"做不出来"到"一次做对"

这是他们测量到的最强模式之一。把任务描述成编号的多步骤流程，效果立竿见影。

实测案例：一个部署新集成的六步工作流。Agent 严格按步骤执行，PR 缺失 wiring 文件的比例从 40% 降到 10%。Correctness 提升 25%，Completeness 提升 20%。

复杂工作流可以拆分——主文件保持简洁，分支情况放到参考文件。

3. 决策表：在写代码之前消除歧义

代码库里有两种以上合理做法时，决策表能强制 Agent 在动笔之前就做出正确选择。

实测效果：一个 React Query vs Zustand 的决策表，让 PR 的 best_practices 直接提升 25%。

| 问题                          | React Query | Zustand |
|-------------------------------|-------------|---------|
| 数据源只有服务端？             | ✅          |         |
| 多个代码路径会修改这个状态？   |             | ✅      |
| 需要乐观更新混合本地状态？     |             | ✅      |

Agent 看到这个表，在写第一行代码之前就知道该用什么方案了。

4. 从真实代码库里摘例子

3–10 行的真实生产代码片段，能显著提升代码复用和模式遵循。

实测：粘贴 Redux Toolkit 的 createSlice（带类型初始状态）、createAsyncThunk（带错误处理）、useAppSelector（带类型）的模板。code_reuse 提升 20%。Agent 照着模板写，不会自己发明新花样。

但别贪多。超过几个最相关的例子后，Agent 会开始错误地 pattern-matching。

5. 领域特定规则依然有效

这是大家最熟悉的模式：语言或组织特有的坑。

比如：所有金融计算用 Decimal，不用 float。Agent 就会捕获截断、舍入、精度问题。

有效的前提是：规则必须具体且可执行。堆砌几十条就没用了（后面会讲原因）。

6. 每个"不要"都配一个"要这样做"

只写警告的文档，效果稳定低于"禁令+具体替代方案"的文档。

# ❌ 只说"不要"
Don't instantiate HTTP clients directly.

# ✅ 禁令+替代方案
Don't instantiate HTTP clients directly.
Use the shared apiClient from lib/http with the retry middleware.

只看到"不要"的 Agent 会变得谨慎且到处探索。看到"用这个"的 Agent 直接动手干活。

实测：15 条以上连续的"不要"且没有"这样做"的 AGENTS.md，Agent 会过度探索、过度保守、产出更少。

7. 保持模块化——代码和文档都一样

表现最好的 Agent 文档，描述的是相对隔离的子模块。

关键发现：表现最差的 AGENTS.md，往往不是文档本身写得差，而是周围的文档环境太烂。一个模块有 37 份相关文档共 50 万字符，另一个有 226 份文档超过 2MB。这种情况下，删掉 AGENTS.md 几乎不影响 Agent 行为——因为它还是在读那些散乱的文档。

如果你的 AGENTS.md 写得很好但模块周围有 500K 的 spec，Agent 读的是那些 spec，不是你的 AGENTS.md。

两个致命陷阱

陷阱一：过度探索（Context Rot）

这是最常见的失败模式。两种触发方式：

太多架构概述。 Agent 被拉去读一堆文档，试图"更好理解架构"，加载了几万到几十万 token 的无关上下文，输出反而变差。

极端案例：AGENTS.md 里包含了完整的服务拓扑（事件总线、消息队列、API 网关路由、中间件层）及每个架构决策的理由。任务是改两行配置。Agent 读了 12 份文档试图理解架构，加载了约 80K token 无关上下文，搞混了哪个服务拥有这个配置，产出了不完整的修复。Completeness 掉了 25%。

太多警告。 30–50 条"不要"规则，Agent 对每条都检查适用性，即使任务完全无关。一个简单 CRUD 端点的任务，Agent 去查数据库迁移、API 版本兼容性、认证中间件。PR 花了两倍时间，完整度低了 20%。

陷阱二：新模式撞上旧文档

AGENTS.md 描述的是现有模式，但任务需要全新架构时，文档会主动把 Agent 带偏。

案例：AGENTS.md 写的是 REST + 轮询模式。任务是构建实时协作编辑（需要 WebSocket）。Agent 照着文档做了个轮询方案，技术上行得通，架构上完全错误。黄金 PR 用的是完全不同的数据流。

这种情况的修复方案不是更好的 AGENTS.md，而是为全新架构提供专门的 spec。

文档发现率的残酷真相

他们追踪了数百个会话中的文档发现路径，数据很扎心：

文档位置 发现率
AGENTS.md 100%（每个层级自动加载）
AGENTS.md 中的参考文件引用 90%+（Agent 有理由时）
当前工作目录的 README.md 80%+
其他子目录的 README.md ~40%
_docs/ 里的孤立文档 <10%

有个服务在 _docs/ 里放了 30K 字符的详细协议设计、限流规则和安全文档。Agent 在几十个会话里几乎从未打开过它们。

AGENTS.md 是唯一有可靠发现率的文档位置。需要被看到的内容，要么放在里面，要么从里面直接引用。

不同目标用不同模式

不是所有模式都解决同一个问题：

你想改善什么 用哪个模式
复用已有代码 真实代码库的几个清晰例子
遵循代码库既定实践 决策表（组件和库的选择）
大型 feature 正确接线 编号式工作流
避开常见坑 "不要"配"这样做"
上下文腐烂 渐进式披露 + 参考文件范围清晰
上下文腐烂 AGENTS.md 只包含和周围代码相关的指导

我的理解

读完这篇文章，最大的感触是：写 AGENTS.md 不是写给人看的文档，是写给机器看的 prompt。

人看文档会抓重点、跳废话、自己判断相关性。Agent 不会。它会忠实地读每一条规则，检查每一条警告，探索每一个引用链接。所以"多写点总比少写好"这个直觉在这里是错的。

100–150 行，聚焦当前模块，细节外推到参考文件，配真实代码示例和决策表。这是目前被数据验证过的最优解。

原文：A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all.

——来自公众号：人生几十年噢耶

作者: itech001
来源: 公众号：AI人工智能时代
主页: https://www.theaiera.cn，每日分享最前沿的AI新闻和技术。

本文首发于 AI人工智能时代，转载请注明出处。

posted @ 2026-04-30 13:34  iTech  阅读(9)  评论(0)    收藏  举报