当前位置：首页 > news >正文

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

news 2026/5/12 23:14:41

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

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

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

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

本文提纲

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

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

研究中最让我意外的发现是：同一个 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 到底怎么发现你的文档

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

文档类型	发现率
AGENTS.md	100% 自动发现
AGENTS.md 中引用的文档	90%+ 按需加载
当前目录的 README.md	80%+ 会读取
子目录的 README.md	~40%
`_docs/` 中的孤立文档	<10%