写好 AGENTS.md 相当于白嫖一次模型升级（写错了还不如不写）

最近 Augment Code 团队发了一篇非常扎实的研究文章。他们从自己的 monorepo 中抽取了几十个 AGENTS.md 文件，用内部评测框架 AuggieBench 逐一测量对代码生成质量的影响。

结论很炸裂：最好的 AGENTS.md 让 Agent 输出质量的提升，相当于从 Haiku 升级到 Opus；最差的 AGENTS.md 反而让结果比没有任何文档更糟。

我读完之后觉得这些发现太实用了，不仅适用于 Augment Code 的 Agent，对 Claude Code、Cursor、Copilot 等所有 AI 编码工具都适用。下面把核心要点整理出来。

本文提纲

1. 同一个文件，不同任务效果天差地别
2. 7 个经过验证的有效模式
3. 最大的坑：过度探索导致上下文腐烂
4. Agent 到底怎么发现你的文档
5. 实操：如何迁移现有文档

同一个文件，不同任务效果天差地别

研究中最让我意外的发现是：同一个 AGENTS.md 文件，在不同任务上的效果可以完全相反。

一个案例：某个 AGENTS.md 在修复常规 bug 时，让 best_practices 提升了 25%。但同一个文件在处理复杂 feature 任务时，completeness 下降了 30%。

原因很有意思。这个文件里有一个决策表，帮助 Agent 在两种数据获取方案之间做选择。修 bug 时这个表格很好用，Agent 直接选对了方案。但做 feature 时，Agent 被引导着读了参考文档，打开了十几个 markdown 文件试图验证自己的方案，结果创造了不必要的抽象层，方案反而做不完整。

教训：AGENTS.md 不是越全越好，不同内容块对不同任务有完全不同的影响。

7 个经过验证的有效模式

1. 渐进式披露 > 大而全

把 AGENTS.md 当成一个索引，控制在 100–150 行以内。常见的工作流和规则放在主文件里，详细内容放到被引用的参考文档中。

实测数据：100-150 行的 AGENTS.md + 几个聚焦的参考文档，在约 100 个核心文件的中型模块上，跨指标提升 10-15%。超过这个长度，收益开始反转。

2. 流程式工作流：从做不出来到一次做对

这是测量中效果最强的模式。把复杂任务描述成带编号的多步骤流程。

一个真实案例：6 步部署新集成的流程。Agent 按步骤执行，缺少接线文件的 PR 从 40% 降到 10%。Correctness 提升 25%，Completeness 提升 20%。

## 部署新集成的工作流

1. 在 `integrations/` 目录创建新的配置文件
2. 在 `lib/registry.ts` 注册新集成
3. 添加对应的单元测试到 `tests/integrations/`
4. 更新 `docs/supported-integrations.md`
5. 运行 `npm run validate-integrations` 确认无报错
6. 提交 PR，标题格式：`feat(integration): add <name>`

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

当项目有两种以上合理方案时，决策表能强制 Agent 先做选择，再动手。这是最能提升代码规范遵守度的模式。

## 状态管理选择

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

用了决策表的 PR，best_practices 提升了 25%。

4. 真实代码示例提升代码复用

从生产代码中复制 3-10 行的片段作为模板。别太多，超过几个 Agent 会匹配到错误的模式。

// ✅ 好的示例：Redux Toolkit createSlice 模板
const counterSlice = createSlice({
  name: 'counter',
  initialState: { value: 0 } as CounterState,
  reducers: {
    increment: (state) => { state.value += 1; },
  },
});

实测：code_reuse 提升 20%。

5. 领域规则要具体可执行

# ✅ 好的规则（具体可执行）
所有金额计算使用 Decimal 类型，禁止使用 float。

# ❌ 差的规则（太泛）
注意数值精度问题。

具体且可执行的规则能提升 best_practices，但堆叠几十条就适得其反。

6. 每个「不要」都配一个「要」

只写「不要」的文档效果很差。Agent 会变得过度谨慎、过度探索。

# ❌ 只有禁止
不要直接实例化 HTTP 客户端。

# ✅ 禁止 + 替代方案
不要直接实例化 HTTP 客户端。使用 `lib/http` 中的共享 `apiClient`，
它自带重试中间件。

有 15+ 条连续「不要」但没有「要」的 AGENTS.md，会导致 Agent 过度探索、过于保守、产出更少。

7. 模块化代码配模块化文档

最佳效果的 AGENTS.md 都对应相对独立的子模块。约 100 个核心文件的中型模块 + 100-150 行的 AGENTS.md + 几个参考文档 = 10-15% 跨指标提升。

放在 repo 根目录的大一统 AGENTS.md，效果不如模块级别的。

最大的坑：过度探索导致上下文腐烂

这是研究中最常见的失败模式，本质是上下文腐烂。

坑 1：架构描述太多

一个 AGENTS.md 包含了完整的服务拓扑：事件总线、消息队列、API 网关路由、共享中间件层……而任务只是改两行配置。Agent 读了 12 个文档文件，加载了约 80K token 无关上下文，搞不清哪个服务拥有这个配置，产出了不完整的修复。completeness 下降 25%。

修复方法：架构描述要简洁且隔离。模糊的组件职责描述会把 Agent 推入探索模式。突出边界，关注「是什么」而非「为什么」。

坑 2：警告太多

30+ 条「不要」规则覆盖数据库迁移、API 版本、部署安全、认证边界……而任务只是写个 CRUD 接口。Agent 逐条检查每条警告的相关性，探索了根本不需要碰的代码。PR 耗时翻倍，完整度下降 20%。

修复方法：核心陷阱放主文件，大部分移到参考文档。每条「不要」都配「要」。

坑 3：周围文档太多

一个模块有 37 个相关文档共 50 万字符。另一个有 226 个文档超过 2MB。即使删掉 AGENTS.md，Agent 行为几乎不变——因为它会自己找到并阅读周围那一堆文档。

如果你的 AGENTS.md 写得很好，但模块周围有 50 万字的规范文档，那 Agent 读的正是这些文档。解决文档环境，而不只是入口。

Agent 到底怎么发现你的文档

研究追踪了数百次会话的文档发现行为，数据很有指导意义：

一个服务有 30K 详细的协议设计、限流规则、安全文档放在 _docs/ 目录。Agent 在数十次会话中从未打开过其中大多数文件。

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

实操：如何迁移现有文档

大部分人已经有散落在 repo 各处的 README、架构文档、设计规范。怎么把这些变成 Agent 真正能用的东西？

能不能直接把 README.md 改名为 AGENTS.md？

可以，但要大刀阔斧地删。Agent 现在对代码库摘要的能力已经够强了，很多给人看的铺垫性内容 Agent 不需要。保留短小精悍的结构，按上面的模式组织，砍掉所有「给人扫一眼」的段落。

保持聚焦

• 一个 AGENTS.md 中引用不超过 10-15 个参考文档
• 审计周围环境：如果模块周围有几十个架构文档和规范文件，Agent 会找到并阅读它们，不管你有没有引用
• 一个 150 行的精炼 AGENTS.md 放在 50 万字的规范堆上，救不了 Agent

AGENTS.md 不是唯一路径

Agent 也能通过 grep 和语义搜索找到参考资料。研究中约一半的搜索结果来自这些工具，而非 AGENTS.md 引用。如果你保留旧文档，确保里面包含可搜索的代码示例和描述性文本。

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

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