我现在跑的每一个严肃的编码项目，都会在仓库根目录放一个 CLAUDE.md 或 AGENTS.md。它会告诉智能体该跑哪些命令、遵循哪些约定、避开哪些文件。我和很多 AI 工程师一样，一直默认这会让智能体“明显更强”。多数在用 coding agents 做开发的人，也都做了同样的默认假设。
ETH Zurich 的 SRI Lab 刚出了一篇新论文，把这个假设拿来做了严格检验。结论的简短版本是：情况很复杂——如果你经常和 coding agents 打交道，里面的细节值得搞懂。
这篇论文《Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?》让 Claude Code、Codex、Qwen Code 在数百个真实 GitHub issue 上跑流程，对比“给 context file”和“不给 context file”两种情况下会发生什么。结果并不是我们大多数人会预期的那样。
所以，当你把一个 CLAUDE.md 或 AGENTS.md 交给智能体时，实际上会发生什么？我们拆开来讲。
The Problem（问题）
随着 coding agents 的普及，上下文文件（AGENTS.md、CLAUDE.md、以及各种 CONTRIBUTING.md 变体）也开始快速增殖。这个想法很直觉：如果你告诉智能体这个 repo 怎么运作，它就应该做得更好——该跑哪些命令、用哪些 lint 工具、测试环境怎么搭。
问题在于：之前没有人真正测量过这个直觉到底成立不成立。采用速度跑在评估前面。开发者写这些文件，智能体读这些文件，然后我们一直“凭信仰”认为这段关系是正向的。
更深一层的问题是：要把这件事测准，需要一个基准测试，里面得包含那些已经有维护者手写 context file 的仓库。而 SWE-bench 作为标准的 coding agent benchmark，主要覆盖的是热门仓库。热门仓库通常不会有这类 context file，因为它们往往通过别的形式长期积累了文档。典型 benchmark 的环境，并不反映 context file 在现实里是怎么被使用的。
A New Benchmark Built Around Context Files（围绕 context files 构建的新基准）
论文引入了 AGENTbench，并和 SWE-bench Lite 做对比。AGENTbench 包含 138 个实例，来自 12 个不那么热门的 Python 仓库——它们都已经有维护者写好的 context file。这些是真实世界的 repo：维护者主动选择写给自动化智能体的指导。
AGENTbench 里的 context file 内容很“厚”：平均 641 词、分布在 9.7 个章节。这不是那种“一句话说用 pytest”的提示，而是覆盖了项目结构、工具偏好、工作流约定、测试要求等更细的指南。
三个智能体在两个 benchmark 上都被评估了：
- Claude Code（Sonnet-4.5）
- Codex（GPT-5.2 和 GPT-5.1 mini）
- Qwen Code（Qwen3-30b-coder）
每个智能体都跑了三种条件：无 context file、LLM 生成的 context file、以及维护者手写的 context file。
Distribution of AGENTbench instances across 12 Python repositories
（AGENTbench 的实例在 12 个 Python 仓库中的分布）
What the Numbers Show（数据告诉我们什么）
最醒目的发现是：LLM 生成的 context files 会降低任务成功率，而且相比“完全不给仓库上下文”，推理成本增加超过 20% 。
在 SWE-bench Lite 上，LLM 生成的文件让表现平均下降 0.5% ；在 AGENTbench 上，下降 2% 。这不是灾难性的下滑，但方向是反的。
Reasoning token usage increases with context files regardless of quality
（无论质量如何，只要有 context file，推理 token 用量就会上升）
成本方面在所有条件下都很一致：不管是人写的还是自动生成的 context file，智能体都会多花 14–22% 的 reasoning tokens，并且平均多走 2–4 个步骤 才完成任务。遵循指令本身就要付出算力，不管这些指令有没有帮上忙。
Success rates on SWE-bench Lite. LLM-generated files consistently underperform the no-context baseline
（SWE-bench Lite 的成功率：LLM 生成的文件稳定地不如“无上下文”的基线）
而人写的 context file 则呈现出另一条曲线：在两个 benchmark 上相对“无上下文”平均提升 4% 。这是一个有意义的增益，也正是 context files 能持续流行的原因：在合适的 benchmark、配上合适的文件，它们确实有效。
但这里有一个值得深挖的“坑”。
The Exploration Paradox（探索悖论）
智能体会很忠实地执行 context file 里的指令，这一点毫无疑问。比如 context file 提到用 uv 做包管理器，那么 uv 的使用频次会提升到平均每个实例 1.6 次；而在没有 context file 的情况下，uv 使用几乎是 < 0.01 次。如果文件指定了测试框架，智能体也会切过去用它。指令遵循是有效的。
How context files change tool usage across agents. Instruction-following is strong but doesn't guarantee success
（context files 如何改变工具使用：指令遵循很强，但并不保证成功）
但接下来并不必然成立的是：遵循指令会转化为成功。拿到 context file 的智能体会跑更多测试、搜索更多文件、遍历更多仓库内容、产出更多推理文本。它们更“彻底”地探索了。可更彻底的探索 ≠ 更正确的探索。
论文对 traces 的分析显示：那些细致的目录枚举和代码库概览（100% 的 LLM 生成 context files 都包含）并不会显著减少智能体在找到相关文件之前需要的步骤数。智能体仍然要自己去定位真正该改的地方。给你一张整座城市的地图，并不会告诉你该走进哪一栋楼。
这就是核心张力：智能体是遵循指令的系统。你给它更多指令，它就会执行更多指令。但更“忙”不等于更“对” 。
Why Human Files Win (On Their Turf)（为什么人写的文件能赢——在它们的主场）
人写和自动生成的差异，本质上落在一个词上：冗余（redundancy） 。
LLM 生成的文件往往会复述仓库里已经存在的信息，比如 README、docs/ 目录、既有的 CONTRIBUTING.md 等。论文做了一个直接测试：在生成 context file 之前，把文档类文件（.md 文件、docs/）从仓库里移除。结果是：LLM 生成文件的表现提升了 2.7% ，甚至超过了人写的文件。也就是说，让自动生成文件“拖后腿”的内容，主要是重复信息。
相反，人写的 context file 往往包含仓库里其他地方并不存在的信息。维护者写它，是为了记录一些从代码里不明显的东西：比如特定的工具选型、CI 的奇怪配置、一些非默认的约定。它提供的是增量信息。
因此，一个非常实际的含义是：context files 的价值取决于它是否告诉智能体一些无法从仓库自身推出来的东西。代码库概览和工作流总结，通常达不到这个门槛；而明确的工具要求，经常可以。
Current Limitations（当前局限）
这项评估只覆盖 Python 仓库。这些模式是否同样适用于 TypeScript、Rust 或多语言代码库，仍是一个开放问题。
基准也只衡量了“issue 能否被解决”。context files 可能还有其他影响维度没有被捕捉到，比如安全性、一致性、是否遵循项目特定约定——这些未必会直接反映到 PR 是否能合并的成功率上。一个 context file 即便不提升成功率，只要它能减少“幻觉式引入库”的情况，也可能很有价值。
另外，长期演化的视角也缺失是必然的：context files 出现得还很新，你很难研究它们质量如何随时间变化，或者随着训练数据逐步覆盖这类实践，智能体会不会越来越会用它们。
What This Means Going Forward（这对未来意味着什么）
有几条值得继续推演的线索。
为“缺口”而写，而不是为“概览”而写。 最明确的可操作结论是：context files 应该编码仓库里没有解释清楚的东西——偏离默认值的工具选择、不明显的测试配置、从代码阅读中看不出的约束。一个只是复述 README 的 CLAUDE.md，可能弊大于利。
评估方法会反过来影响 context file 的设计。 论文发现：在标准热门仓库上，自动生成的文件会伤害表现；而在小众仓库上，人写的文件能提升表现——这说明效果高度依赖“信息环境”。文档已经很完善的团队，context file 更容易天然冗余；文档稀缺或工具栈很非典型的团队，收益空间更大。
成本底线是真实存在的。 每一个 context file 都会把推理成本抬高大约 20% ，不管它好不好。对于高吞吐量的 agentic pipeline，这不是小数字。性能增益是否值得这份成本，取决于文件质量和任务类型。
LLM 生成的 context files 需要换一种打法。 冗余问题是可以修的。如果生成器能明确避免复述已有文档，而是聚焦提取“不显眼但关键”的工具决策和约定，它很可能会明显更好。这是一个非常直接的工程改进点，而当前这一代生成器还没有做到。
论文更深层抛出的，是关于“指令遵循”对任务型智能体到底意味着什么的问题：一个智能体花了额外步骤，认真照着 context file 去跑测试规范，但最终没修掉 bug——它是在把过程优先于结果。这个平衡怎么做好，既是 context file 设计问题，也是训练问题。
Final Words and Resources（结语与资源）
context files 不是魔法，但也不是没用。论文的落点其实非常实用：带有具体、非冗余信息的人写文件会提升表现；复述既有文档的自动生成文件会降低表现。 两者背后的机制是同一个：智能体会跟随指令，而最终效果完全取决于指令质量。
如果你经常写 AGENTS.md，一个实践建议是：保持最小化、保持具体化。写清楚代码里看不出来的工具与约定；把 README 里已经写过的内容删掉。
Resources（资源）
- Full paper: Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
- AGENTbench dataset: github.com/eth-sri/agentbench
