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

> Augment Code 实测数十份 AGENTS.md 后总结：写好了相当于把模型从 Haiku 升级到 Opus，写烂了让 AI 比裸跑更差。7 个有效模式 + 2 个失败陷阱 + 文档发现率梯度，外加几条不能假装不存在的工程边界。

- 原文链接: https://laojin.blog/blog/20260509_agents_md_engineering
- 作者: 老金
- 发布日期: 2026-05-09
- 标签: AGENTS.md, AI编程, 工程实践, 上下文工程

---

![好的 AGENTS.md 等于免费换模型，写错了比没文档更糟](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260509/00_cover.png)

一份文件，让 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 个有效模式

![AGENTS.md 是一个聚焦的入口，细节按需外推](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260509/01_progressive_disclosure.png)

### 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 描述现状，不是愿景。**

---

## 文档发现率

![文档发现率梯度：从 100% 到 小于10%](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260509/02_discovery_ladder.png)

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 工程里，**"少即是多"这句话，从未像现在这样字面成立过。**