我们分析了单体仓库中数十个 AGENTS.md 文件，并量化了它们对代码生成质量的影响。结果令人惊讶：一份优秀的 AGENTS.md 能让 AI 助手的表现产生质变，效果相当于从轻量级模型升级到了旗舰级模型（如 Claude Haiku 升级到 Opus）。而一份糟糕的文档，效果反而比完全没有文档还要差。
这种两极分化的现象促使我们进行了一项系统性研究。我们发现，大多数人习惯在 AGENTS.md 中塞入的信息要么毫无用处，要么在起反作用。真正有效的文档模式其实非常具体且易于掌握。
同样的文档：一处蜜糖，一处砒霜
一个 AGENTS.md 文件并不能在所有场景下都表现良好。在我们的测试中，同一个文档在处理常规 Bug 修复时能提升 25% 的最佳实践规范性，但在同一模块的复杂功能开发中，却导致代码完整性下降了 30%。
在 Bug 修复场景下，文档中的“数据获取方案决策表”让 AI 瞬间选对了模式。但在复杂任务中，AI 被文档中的参考资料部分误导，为了验证方案，它翻阅了数十个 Markdown 文件，过度封装了不必要的抽象层，最终交付了一个半成品。
文档中的不同区块，对不同任务的影响截然不同。
评估方法：AuggieBench
我们使用内部评估套件 AuggieBench 来衡量 AI 助手的表现。我们从大型仓库中提取高质量的 PR（这些 PR 代表了日常典型的编程任务），对比 AI 的输出与经过资深工程师审核并最终合入的“黄金代码”。
在本次研究中，我们筛选了局限在单一模块内的任务，并分别在“有 AGENTS.md”和“无 AGENTS.md”两种环境下运行，对比其在准确性、完整性和代码复用率上的得分。
哪些文档模式真正奏效？
1. 渐进式披露优于全量覆盖
不要试图在一个文件中塞入所有细节。要把 AGENTS.md 当作一个索引。高层级地描述通用案例和工作流，将具体细节推送到参考文件中。
研究显示，100-150 行左右的 AGENTS.md 配合几个专注的参考文档表现最好。在包含约 100 个核心文件的中型模块中，这种结构能带来 10-15% 的全方位提升。一旦主文档过长，收益就会开始递减。
2. 过程化工作流：从“无法完成”到“一次过”
将任务描述为带有编号的多步骤工作流，是效果最明显的模式之一。
例如，在我们的代码库中，针对部署新集成的任务提供了一个六步工作流。加入该引导后，PR 中缺失配置文件的情况从 40% 降至 10%，代码正确性提升了 25%，开发速度也明显加快。
3. 用决策表消除歧义
当代码库中存在两三种可行的实现方式时，决策表能强迫 AI 预先做出正确选择。这是提升代码一致性最直接的手段。
示例：React Query 与 Zustand 的选择策略
| 提问 | → 选择 React Query | → 选择 Zustand |
|---|---|---|
| 服务端是唯一数据源吗？ | ✅ | |
| 是否有多个代码路径修改此状态？ | ✅ | |
| 需要在本地状态中混合乐观更新吗？ | ✅ |
通过这种方式，AI 在写第一行代码前就解决了架构分歧。
4. 真实的生产代码片段
提供 3-10 行的真实代码模板可以显著提升复用率。 例如，提供带类型的 Redux Toolkit 模板或特定的 Hook 调用方式。在我们的测试中，这让代码复用率提升了 20%。AI 会倾向于模仿已有的模式，而不是自己发明一套。
5. “不要做”必须搭配“应该做”
单纯的警告（Warning-only）效果很差。如果你只告诉 AI “不要直接实例化 HTTP 客户端”，它会变得畏手畏脚并开始过度探索。
正确的做法是：“不要直接实例化 HTTP 客户端，请使用 lib/http 中带有重试中间件的 apiClient。” 给出明确的替代方案，AI 才能直接推进任务。
为什么有些文档会让 AI 变笨？
过度探索陷阱（Overexploration）
这是最常见的失败模式，本质上是“上下文腐败”。
- 过多的架构概览： 如果文档详细描述了事件总线、消息队列、网关路由的所有原理，AI 可能会为了“理解架构”而去读取几十个关联文件。在处理一个简单的配置修改任务时，AI 可能会加载 8 万个 Token 的无关上下文，最终在冗余信息中迷失，导致产出的修复方案不完整。
- 规则堆砌： 当一个文件包含 30 条以上的“禁止事项”且没有明确优先级时，AI 会强迫自己针对每一条规则去验证方案。这会导致它去读取无关的迁移脚本、鉴权中间件等，浪费了大量的推理能力。
文档滞后导致的误导
如果你正在引入一种代码库中尚不存在的新模式，旧的 AGENTS.md 会成为绊脚石。AI 会固守文档中的旧模式，而忽略了新任务的技术要求。这种情况下，不写文档反而比留着旧文档要好。
AI 是如何发现文档的？
了解 AI 的检索行为有助于我们优化文档分布：
AGENTS.md： 100% 的发现率。几乎所有的 AI 框架都会自动加载当前目录及其父目录下的该文件。AGENTS.md中的引用链接： 超过 90% 的发现率。- 目录级的
README.md： 如果 AI 正在该目录工作，发现率约 80%。 - 孤立的文档（如
_docs/文件夹）： 发现率低于 10%。
结论： AGENTS.md 是唯一具备稳定发现率的入口。如果某些规范极其重要，要么直接写在这里，要么在这里明确引用它。
文档迁移建议
你不需要从头重写所有文档。如果现有的 README.md 质量很高且包含代码示例，可以直接重用。
- 精简： 删掉那些只给人类看、用于快速扫视的修饰性文字。
- 模块化： 根目录下的巨型文档不如模块目录下的精简文档有效。
- 可搜索性： 确保文档中包含相关的关键词和代码范例，这有助于 AI 通过语义搜索精准命中。
总结
编写 AGENTS.md 不是为了写一篇技术博客，而是为了给 AI 提供一套“操作指南”。
- 优化目标： 如果为了复用代码，给示例；如果为了统一风格，给决策表。
- 克制： 保持在 150 行以内，剩下的交给引用文件。
- 务实： 重点说“怎么做”，少说“为什么”。
关于
关注我获取更多资讯
