AGENTS.md真的对编码智能体有帮助吗？— ETH Zürich 论文分析

使用编码智能体时，有时会遇到一些文件，例如 AGENTS.md、CLAUDE.md、CODEX.md 等上下文文件。这些文件类似于“智能体专用 README”，用于向智能体告知代码库的结构、构建方法和编码规范。包括 Anthropic、OpenAI、阿里巴巴在内的所有智能体供应商都积极推荐使用，并且 GitHub 上有超过 6 万个代码库包含这些文件。

但是，它们真的有效吗？

ETH Zürich 的 Thibaud Gloaguen 等人在 ICML 2026 上发表的论文 "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" 首次对这个问题给出了定量答案。总而言之，目前方式的上下文文件并没有预期的那么有效。

实验设计：两个基准，三种条件

研究人员使用了两个基准测试。

• SWE-bench Lite：从 11 个著名的 Python 项目中提取的 300 个 GitHub issue。这些代码库没有上下文文件。
• AGENTbench（新）：研究人员直接构建的基准测试。从开发人员实际提交上下文文件的 12 个小众代码库中收集了 138 个 issue。

在每个基准测试中，研究人员在三种条件下进行了实验。

1. None：没有上下文文件
2. LLM：通过智能体的 /init 命令自动生成的上下文文件
3. Human：开发人员直接编写的上下文文件（仅 AGENTbench）

测试了四种编码智能体：Claude Code(Sonnet 4.5)、Codex(GPT-5.2, GPT-5.1 mini)、Qwen Code(Qwen3-30b-coder)。

核心结果：LLM 生成的文件反而适得其反

结果总结如下：

LLM 自动生成的上下文文件：

• 在 8 个设置中的 5 个中性能下降（平均 -0.5%~-2%）
• 推理成本增加 20~23%
• 步骤数平均增加 2.5~3.9 个

开发人员直接编写的上下文文件：

• 除了 Claude Code 之外的 3 个智能体性能略有提高（平均 +4%）
• 但成本同样增加（高达 19%）

总之，LLM 自动生成的上下文文件只会增加成本，并降低性能。开发人员直接编写的文件有一些改进效果，但性价比不高。

为什么会出现这样的结果？

1. 与现有文档重复

LLM 生成的上下文文件大多重复了 代码库中已有的信息，例如 README、docs/、示例代码等。研究人员从代码库中删除所有文档后进行实验，发现 LLM 生成的上下文文件反而平均提高了 2.7% 的性能。也就是说，在文档充足的代码库中，上下文文件会变成纯粹的噪音。

2. 代码库概述实际上毫无意义

上下文文件的一个典型建议是“放入代码库结构概述”，但实验结果表明，这根本无法帮助更快地找到相关文件。相反，GPT-5.1 mini 在有上下文文件时表现出低效率的行为，反复读取该文件。

3. 不必要的需求使任务变得困难

如果上下文文件中包含“该项目使用 uv”、“请使用 pytest 运行测试”等指令，智能体就会忠实地遵循。问题在于，这会消耗更多的探索、更多的测试和更多的推理令牌。GPT-5.2 的 reasoning 令牌在使用上下文文件时增加了 22%。问题不是智能体忽略指令，而是太过于听话了。

4. 强大的模型也无法创建更好的上下文文件

将 GPT-5.2 生成的上下文文件放入其他智能体中进行测试，尽管 SWE-bench Lite 中略有改进（+2%），但在 AGENTbench 中反而下降了 -3%。即使更改提示，也没有发现一致的差异。

实际意义

现在可以做的事情

不要使用 LLM 自动生成的上下文文件。从目前来看，使用 /init 自动生成只会增加成本，而不会带来性能优势。

如果要手动编写，请尽量精简。论文的结论很明确：不要放入“代码库概述”、“目录描述”、“架构图”等内容。智能体已经可以使用 grep 和 find 探索代码库。相反，只应放入智能体无法自行获取的信息。

有效上下文文件的示例：

• 该项目使用 uv 管理依赖项（不是 pip）
• 运行测试：make test-unit（禁止直接调用 pytest）
• CI 仅支持 Python 3.12
• 不要碰 src/legacy/

无效上下文文件的示例：

• 项目概述和目的说明
• 列出目录结构
• 编码风格指南（lint 会处理）
• 架构描述

在文档不足的代码库中有效

一个有趣的转折是，在文档几乎没有的代码库中，上下文文件实际上是有帮助的。如果在内部项目或文档不完善的代码库中使用智能体，那么记录构建/测试命令和核心依赖项等信息将具有重要意义。

Python 以外的语言呢？

该论文仅涉及 Python。Python 是一种包含在 LLM 学习数据中的丰富语言，因此模型已经很好地了解 pip、pytest、Django、Flask 等约定。对于 Rust、Zig、Elixir 等小众语言，上下文文件的效果可能会有所不同。这是一个有待进一步研究的课题。

在我们的工作流程中的应用

总结该论文的教训：

1. 不要在 AGENTS.md 中冗长地编写代码库结构 — 智能体已经具有探索能力
2. 只编写智能体无法知道的内容 — 构建工具、特殊命令、禁区
3. 避免自动生成（/init） — 如果与现有文档重复，则会造成纯粹的损害
4. 必须监控成本 — 添加上下文文件后，令牌使用量可能会增加 20%+ 以上
5. 仅在没有文档的项目中积极编写

最终，好的上下文文件应该是简短、具体且仅包含智能体无法自行发现的信息。“更多信息 = 更好结果”的直觉至少对于当前的编码智能体是不适用的。

论文：Gloaguen et al., "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?", ICML 2026. arXiv:2602.11988

基准测试代码：github.com/eth-sri/agentbench