我现在运行的每个重要编码项目，根目录下都有一个 CLAUDE.md 或 AgentS.md 文件。它告诉智能体应该运行哪些命令、遵循哪些规范、以及哪些文件需要避开。和许多 AI 工程师一样，我一直认为这能让智能体表现更好。大多数使用编码智能体进行构建的人都持有同样的假设。
苏黎世联邦理工学院（ETH Zurich）SRI 实验室的一篇新论文对这一假设进行了严格检验。简短的答案是：情况比较复杂，如果你经常与编码智能体打交道，这些细节很值得深入了解。
这篇论文题为《评估 AGENTS.md：仓库级上下文文件对编码智能体是否有帮助？》，让 Claude Code、Codex 和 Qwen Code 处理了数百个真实的 GitHub issue，对比了智能体在有无上下文文件情况下的表现差异。结果出乎大多数人的预料。
那么，当你给智能体提供一个 CLAUDE.md 或 AGENTS.md 时，究竟会发生什么？我们来逐一拆解。
问题所在
上下文文件（AGENTS.md、CLAUDE.md、CONTRIBUTING.md 等变体）随着编码智能体的普及而大量涌现。背后的逻辑很直观：如果你告诉智能体这个仓库是如何运作的——需要运行哪些命令、使用哪些 lint 工具、测试环境是什么样的——它应该表现得更好。
问题在于，没有人真正验证过这种直觉是否成立。实践超前于评估。开发者写了这些文件，智能体读了这些文件，而我们一直靠"信念"维系着这段关系，默认它是正向的。
更深层的问题在于：要正确衡量这一点，需要一个包含开发者实际编写的上下文文件的基准测试集。而 SWE-bench 这一标准编码智能体基准测试，主要覆盖的是热门仓库。热门仓库往往没有上下文文件，因为它们的文档以其他形式积累。典型的基准测试环境并不能真实反映上下文文件的实际使用场景。
围绕上下文文件构建的新基准测试
这篇论文在与 SWE-bench Lite 对比的同时，还引入了 AGENTbench。AGENTbench 包含来自 12 个相对冷门的 Python 仓库的 138 个实例，这些仓库都已预置了开发者编写的上下文文件。这些是真实的开源项目，维护者主动为自动化智能体编写了使用指引。
AGENTbench 中的上下文文件内容相当丰富，平均长度为 641 个词，分布在 9.7 个章节中。这些不是简单的"使用 pytest"之类的一行说明，而是详细涵盖项目结构、工具偏好、工作流规范和测试要求的完整指南。
测试涉及三个智能体，分别在两个基准上进行评估：
- Claude Code（Sonnet-4.5）
- Codex（GPT-5.2 和 GPT-5.1 mini）
- Qwen Code（Qwen3-30b-coder）
每个智能体分别在三种条件下运行：无上下文文件、有 LLM 生成的上下文文件、有开发者编写的上下文文件。
数据说明了什么
核心发现是：与不提供任何仓库上下文相比，LLM 生成的上下文文件会降低任务成功率，同时将推理成本提高超过 20%。
在 SWE-bench Lite 上，LLM 生成的文件平均使性能下降 0.5%；在 AGENTbench 上，下降幅度为 2%。虽然都不是灾难性的，但方向是错的。
成本的变化在所有条件下保持一致。无论上下文文件是人工编写还是自动生成，智能体都会多消耗 14%–22% 的推理 token，并多出 2–4 个额外步骤才能完成任务。遵循指令是有算力代价的，不管那些指令是否真的有帮助。
人工编写的上下文文件呈现出截然不同的情况：在两个基准测试中，平均比无上下文情况提升了 4%。这是一个有意义的收益，也解释了为什么上下文文件依然被广泛使用。在合适的基准测试、配合合适的文件，它们确实有效。
但这里有一个值得深究的问题。
探索悖论
智能体会忠实地遵循上下文文件中的指令——这一点毋庸置疑。当上下文文件提到使用 uv 作为包管理器时， uv 的使用频率会跃升至每个实例平均 1.6 次，而没有上下文文件时不足 0.01 次。当文件指定了测试框架，智能体就会切换过去。指令遵循机制是有效的。
但问题在于，指令遵循并不等于任务成功。获得上下文文件的智能体会运行更多测试、搜索更多文件、遍历更多仓库结构、生成更多推理输出——它们确实探索得更彻底。但"更彻底的探索"并不等于"更正确的探索"。
论文对执行轨迹的分析显示：100% 的 LLM 生成上下文文件都包含详尽的目录枚举和代码库概述，但这些内容并不能有效减少智能体到达目标文件所需的步骤数。智能体依然需要自己找到代码中的正确位置。整座城市的地图，并不会告诉你该走进哪栋楼。
这就是核心矛盾所在：智能体是遵循指令的系统。给它更多指令，它就会执行更多指令。但更多的动作并不等于更好的结果。
为什么人工编写的文件在本地更胜一筹
人工编写与自动生成的上下文文件之间的差距，归根结底在于信息冗余。
LLM 生成的文件往往会重复仓库中其他地方已有的信息，比如 README、文档目录、现有的 CONTRIBUTING.md 文件。论文直接对此进行了测试：当从仓库中移除文档文件（.md 文件、docs/ 目录）再生成上下文文件时，LLM 生成的文件性能提升了 2.7%，甚至超过了人工编写的文件。让自动生成文件适得其反的，正是那些冗余内容。
相比之下，人工编写的上下文文件往往包含仓库其他地方找不到的信息。维护者编写这些文件，是为了记录那些无法从代码中直接看出的内容：他们做出的特定工具选择、CI 配置的独特之处、他们采用的非默认规范。这是增量信息。
实际含义是：上下文文件的价值，在于它能告诉智能体那些从仓库本身无法推断出的信息。代码库概述和工作流摘要通常达不到这个标准，而具体的工具要求往往能做到。
当前的局限性
此次评估仅限于 Python 仓库。这些规律是否适用于 TypeScript、Rust 或多语言代码库，仍是未解之问。
基准测试也只衡量了 issue 解决率。上下文文件可能还有其他影响未被纳入考量，例如安全性、一致性，以及对项目特定规范的遵循程度——这些并不一定体现在 PR 是否被合并上。一个能减少幻觉库调用的上下文文件，即便不能提升成功率数字，也可能具有很大价值。
纵向视角的缺失是客观限制。上下文文件的出现时间尚短，无法研究其质量随时间的演变，也无法评估随着训练数据跟上实践步伐，智能体使用它们的能力是否会有所提升。
对未来的启示
几个值得思考的方向：
写"缺口"，而非"概述"。 最清晰的实践建议是：上下文文件应该编码仓库本身尚未说明的内容——偏离默认设置的工具选择、非显而易见的测试配置、从代码中看不出的约束条件。一个只是重申 README 的 CLAUDE.md，很可能弊大于利。
评估方法论影响上下文文件设计。 论文发现，自动生成的文件在标准仓库上有害，而人工文件在小众仓库上有益，这表明效果高度依赖于信息环境。已有完善文档的团队，可能会发现上下文文件默认是多余的；而文档稀少或使用非常规工具栈的团队，则有更多收益空间。
成本底线是真实存在的。 每个上下文文件都会使推理成本增加约 20%，不论其质量如何。对于高吞吐量的智能体流水线，这不是小数目。性能收益是否值得这个代价，取决于文件质量和任务性质。
LLM 生成的上下文文件需要一种不同的方法。 自动生成文件中的冗余问题是可以修复的。一个明确避免重述现有文档、专注于提取非显而易见的工具决策和规范的生成器，很可能会表现明显更好。这是一个显而易见的工程改进，但当前这一代生成器还没有做到。
论文提出的更深层问题，是关于指令遵循对于那些致力于完成任务（而非仅仅执行指令）的智能体究竟意味着什么。一个花费额外步骤认真遵循上下文文件中测试规范的智能体，最终却没能修复 bug——它把流程置于结果之上了。如何找到这种平衡，既是训练问题，也是上下文文件设计问题。
总结与资源
上下文文件不是魔法，但也并非毫无用处。论文的结论落在了一个切实有用的位置：包含具体、非冗余信息的人工编写文件能提升性能；而重复现有文档的自动生成文件则会损害性能。两种情况背后的机制是一样的——智能体遵循指令，而结果的好坏完全取决于指令的质量。
对于任何经常编写 AGENTS.md 文件的人，实践建议是：保持简洁具体。描述那些从代码中看不出的工具和规范。把 README 里已有的内容留在那里就好。
