本文翻译自 Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?，原载于 Hacker News。
背景：上下文文件的崛起
Coding Agent（编程智能体）正在软件工程领域快速普及。为了让 Agent 更好地理解特定代码库，业界形成了一种普遍实践：在仓库根目录添加上下文文件（Context Files），如 AGENTS.md 或 CLAUDE.md。
这些文件通常包含：
- 仓库概览和架构说明
- 构建和测试命令
- 代码风格指南
- 设计模式和最佳实践
主流 AI 厂商纷纷推荐这种做法。Anthropic 官方博客专门发文指导如何编写 CLAUDE.md，OpenAI 的 Codex 和阿里的 QwenCoder 也都内置了 /init 命令自动生成这些文件。
截至本文写作时，AGENTS.md 官网报告已有 超过 60,000 个公开 GitHub 仓库 包含上下文文件。
然而，一个关键问题从未被严谨研究过：这些文件真的有效吗？
研究方法：构建 AGENTBENCH
ETH Zurich 和 LogicStar.ai 的研究团队进行了首次大规模实证研究。他们面临两个挑战：
- 现有基准测试（如 SWE-bench）的实例发生时，上下文文件尚未普及
- 流行的知名仓库不具代表性——大多数代码库是小众项目
为解决这个问题，研究者构建了 AGENTBENCH——一个全新的基准测试数据集：
- 138 个真实任务实例
- 12 个包含开发者手写上下文文件的仓库
- 覆盖 bug 修复和功能添加两类任务
- 所有任务都来自真实的 GitHub Issues 和 PR
对比 SWE-BENCH LITE（300 个任务，来自 11 个流行 Python 仓库，没有任何上下文文件），AGENTBENCH 提供了评估开发者手写上下文文件的独特机会。
核心发现：出乎意料的结果
发现一：LLM 生成的上下文文件降低性能
在 SWE-BENCH LITE 上，使用 Agent 推荐的 /init 命令生成的上下文文件：
- 平均成功率降低 0.5%
- 在 AGENTBENCH 上，平均成功率降低 2%
发现二：开发者手写的文件仅有边际改善
在 AGENTBENCH 上，使用开发者实际提交的上下文文件：
- 4 个 Agent 中有 3 个获得提升
- 平均成功率仅提升 4%
- 但同时增加了推理成本
发现三：上下文文件增加超过 20% 的成本
无论哪种类型的上下文文件，都会导致：
- 步骤数增加 2-4 步
- 推理 token 数量增加 14-22%
- 总成本增加超过 20%
以下是主要数据：
| 设置 | Sonnet-4.5 | GPT-5.2 | GPT-5.1 Mini | Qwen3-30B |
|---|---|---|---|---|
| SWE-BENCH LITE | ||||
| 无上下文 | 54.4 步, $1.30 | 12.5 步, $0.32 | 40.9 步, $0.18 | 29.7 步, $0.12 |
| LLM 生成 | 57.2 步, $1.51 | 12.7 步, $0.43 | 45.2 步, $0.22 | 32.2 步, $0.13 |
| AGENTBENCH | ||||
| 无上下文 | 40.7 步, $1.15 | 12.1 步, $0.38 | 40.6 步, $0.18 | 31.5 步, $0.13 |
| LLM 生成 | 46.5 步, $1.33 | 13.1 步, $0.57 | 46.9 步, $0.20 | 34.2 步, $0.15 |
| 开发者手写 | 45.3 步, $1.30 | 13.6 步, $0.54 | 46.6 步, $0.19 | 32.8 步, $0.15 |
为什么上下文文件没有帮助？
行为分析：更多测试，更多探索
研究团队通过详细的 trace 分析发现，上下文文件改变了 Agent 的行为：
- 更多测试：Agent 运行了更多的测试用例
- 更多探索：更多的 grep、read、write 操作
- 使用特定工具：如果上下文文件提到了
uv或pytest，Agent 会更频繁地使用它们
指令被执行，但增加了负担
关键发现：Agent 确实会遵循上下文文件中的指令。
例如：
- 当上下文文件提到
uv时，Agent 平均每个任务使用 1.6 次 - 当没有提到时，使用次数少于 0.01 次
但这恰恰是问题所在——额外的指令让任务变得更难。GPT-5.2 的推理 token 数量增加了 22%，说明模型认为任务更复杂了。
上下文文件没有提供有效的仓库概览
一个假设是：上下文文件可以帮助 Agent 快速定位相关代码。研究者测量了 Agent 第一次接触 PR 修改的文件所需的步数。
结果：上下文文件并没有显著减少发现相关文件的时间。LLM 生成的概览和开发者手写的概览都没有效果。
上下文文件是冗余的文档
研究者做了一个有趣的实验：移除所有文档文件（.md 文件、示例代码、docs/ 目录）后，LLM 生成的上下文文件反而开始有帮助了——成功率提升 2.7%。
这说明：
- LLM 生成的上下文文件主要是对现有文档的总结
- 当文档缺失时，这些总结才有价值
- 开发者手写的文件往往包含额外信息，但这些信息可能不是解决任务所需的
实践建议
1. 暂时不要使用 LLM 生成的上下文文件
与厂商推荐相反，研究数据表明 LLM 生成的上下文文件弊大于利。
2. 如果手写，保持最小化
开发者手写的上下文文件应只包含最小必要信息：
- 必须使用的特定工具
- 关键的构建/测试命令
- 与众不同的项目约束
避免：
- 仓库结构概览（Agent 可以自己探索）
- 通用编程建议
- 可从代码推断的信息
3. 关注未来改进方向
研究者指出几个有潜力的方向：
- 小众语言：对于训练数据少的语言，上下文文件可能更有价值
- 安全性：明确的安全约束可能改善代码安全性
- 更好的生成方法：当前的 LLM 生成方法可能不是最优的
我的思考
这篇论文的结论与直觉相悖。我们倾向于认为”更多信息总是好的”，但实际上：
- 信息过载：Agent 在解决问题时需要过滤大量无关信息，上下文文件增加了认知负担
- 指令冲突：上下文文件中的指令可能与任务要求产生冲突
- 覆盖问题：LLM 已经在大量代码上训练，对常见模式有充分的”参数知识”
这也让我想起之前的 Harness 问题——AI 编程工具的瓶颈往往不是模型本身，而是我们如何与之交互。上下文文件是另一个例子：好的初衷，但目前的效果有限。
总结
- LLM 生成的上下文文件降低成功率：平均降低 2%，同时增加 20%+ 成本
- 开发者手写文件仅有边际改善：平均提升 4%，但不稳定
- Agent 确实遵循指令：问题不在执行能力，而是指令本身增加了任务复杂度
- 建议：最小化上下文文件：只包含必要的工具和命令信息
这项研究为 AI 编程工具的发展提供了重要参考。也许未来的方向不是让 Agent 阅读更多文档，而是让 Agent 更擅长自己探索和理解代码。