📌 核心问题：AGENTS.md 真的有用吗？

2026 年，AGENTS.md（以及 CLAUDE.md、COPILOT.md 等变体）已成为 AI Coding Agent 的标配实践。几乎所有主流 Agent（Claude Code、Codex、Cursor、Windsurf）都推荐在代码仓库根目录放置一个上下文文件，告诉 Agent 项目的技术栈、编码规范、构建工具等关键信息。这被称为「Context Engineering」——通过精心设计的上下文来引导 AI 行为。

但一个根本性问题从未被严肃回答：这些上下文文件真的能提升 Coding Agent 的任务完成率吗？还是只是让我们自我感觉良好的「安全毯」？

ETH Zurich SRI Lab 的研究团队（Thibaud Gloaguen、Niels Mündler 等）在 ICLR 2026 上发表了一篇 Oral 论文，首次用严格的实验方法给出了答案——结果出乎所有人的预料。

📊 关键数据：更多 Token，更差表现

自动生成的 AGENTS.md 文件平均降低任务成功率约 3%，同时推理成本增加超过 20%

研究团队在两个互补场景中测试：SWE-bench 标准任务（热门开源仓库）+ 自建的 AGENTBENCH（包含开发者自行编写 AGENTS.md 的真实仓库）。测试覆盖 Sonnet-4.5、GPT-5.2、Qwen3-30B 等多个模型和多个 Coding Agent。

  • 自动生成的上下文文件：任务成功率下降约 3%（相比不提供任何仓库上下文）
  • 推理成本增加 20%+，Agent 需要更多推理步骤才能完成同样的任务
  • 人类编写的上下文文件仅带来约 4% 的性能提升——聊胜于无
  • 用更强模型（如 GPT-5.2）生成上下文文件并不会带来更好结果——强模型有足够的「参数化知识」理解常见库，额外上下文反而成了噪声

🔧 研究设计与方法论

  • 双场景评估：SWE-bench（LLM 生成上下文文件）+ AGENTBENCH（开发者手写上下文文件），覆盖「自动生成」和「人工编写」两种实践
  • 多模型测试：Sonnet-4.5、GPT-5.2、Qwen3-30B，验证结论的跨模型泛化性
  • 消融实验：分别测试「指令类内容」vs「仓库概览类内容」的效果，发现后者完全无用
  • 行为分析：发现 Agent 过于「听话」——上下文文件中的不必要指令会让任务变得更难
  • 工具使用统计：当工具被显式提及时，使用频率提升 160 倍（如 uv 从 0.01 次/实例 → 1.6 次/实例）

🧠 关键洞察

🔑 洞察一：Agent 不需要地图，它们自己会探索

目录树、文件结构概览——这些是大多数 AGENTS.md 的核心内容，也是模型厂商强烈推荐的。但研究发现，Agent 比你想象的更擅长自己发现文件结构。读一份目录手册不仅不能帮它们更快找到文件，反而消耗了推理 Token，增加了「认知负担」。就像给一个有 GPS 的人一本纸质地图——不仅没用，还分散注意力。

🔑 洞察二：Agent 太「听话」了，这反而是问题

研究发现了一个有趣的行为陷阱：Agent 会严格遵守上下文文件中的指令。但如果这些指令对当前任务来说是不必要的，遵守它们反而让解题变得更困难。这就像一个实习生严格遵守了过时的操作手册——不是帮他，是害他。过度的「听话」变成了机械执行，而非智能判断。

🔑 洞察三：Context Engineering 应该从「全面文档」转向「精准干预」

论文的核心启示不是「AGENTS.md 无用」，而是「大多数 AGENTS.md 写错了」。应该包含的是：非标准的构建/测试工具（如用 uv 代替 pip）、项目的「为什么」（设计意图）、monorepo 等特殊架构说明。应该删除的是：详细目录树、代码风格指南（用 linter 代替）、只适用于少数任务的特定指令。

🔑 洞察四：渐进式披露优于一次性灌入

论文推荐的做法：主 AGENTS.md 控制在 300 行以内（专业团队甚至 60 行以内），用指向性链接引导 Agent 按需读取更详细的子文档。这和软件工程中的「关注点分离」原则一脉相承——不要把所有信息塞进一个文件，而是让 Agent 在需要时才获取。

💭 引发思考

这篇论文对整个 AI Coding 生态有深远影响。几乎所有主流 Agent 厂商（Anthropic、OpenAI、Google）都在推广 AGENTS.md 实践，但这篇研究用数据证明：「最佳实践」不等于「有效实践」。没有经过严格验证的「最佳实践」，可能只是一种集体错觉。

更深层的问题是：随着 AI Agent 能力的增强，我们提供的上下文从「帮助」变成了「干扰」。这和人类学习的规律惊人相似——初级学习者需要详细指导，但专家会被过度指导拖累。AI Agent 正在经历同样的转变：它们已经足够强大，能够自己探索代码仓库，过多的上下文反而成了束缚。未来的 Context Engineering 可能需要根据 Agent 的能力水平动态调整上下文的详细程度。

对实际工程的启示：如果你正在使用 AGENTS.md，现在是一个好时机回头审视它的内容——删除那些冗余的目录树、风格指南和过度详细的说明，只保留真正非标准的、Agent 无法自行发现的信息。少即是多。

📚 相关阅读

逍遥云初 | 2026.06.30