新建一个仓库，第一件事是让 Codex 生成 AGENTS.md。它交出来的东西看着挺专业：一段项目简介，一棵目录树，技术栈清单，编码规范，构建和测试命令。六百多字，读起来像那么回事。

之后每个任务，这几百字都会被塞进上下文。你大概从没算过这笔账：它到底帮你省了什么。

苏黎世联邦理工和 LogicStar 的几个研究者把这个动作拆开量了一遍。结论不太体面。自动生成的 AGENTS.md 对成功率没有可测量的影响，推理成本平均涨了 20%。人写的版本好一点，但也没有社区里说的那种效果。

论文叫 Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?，arXiv 编号 2602.11988，九月底更新到第三版。看完这篇，我对仓库里那份文件的态度变了。

他们是怎么量的#

这件事之前没人认真做过，原因很简单：AGENTS.md 是 2025 年 8 月才定下来的格式，老基准里的仓库根本没有这文件。现在有 6 万多个开源仓库带它，样本够了。

研究者自己造了一个基准，叫 CTXBENCH。从 12 个带上下文文件（AGENTS.md 或 CLAUDE.md）的 Python 仓库里，筛出 138 个任务实例，每个都对应一个真实的 issue 和已合并的 PR。仓库包括 tinygrad、pdm、ansible、wagtail、transformers、smolagents、ragas 这些，都不算大热门，正好是普通项目的真实样子。这批文件平均 641 个词，分 9.7 节，最长的一份 2003 个词。

配套还用了 SWE-bench Lite 的 300 个任务，那 11 个仓库原本都没有上下文文件，用来测自动生成的那一种。

四套组合：Claude Code 配 Sonnet 4.5，Codex 配 GPT-5.2，Codex 配 GPT-5.1 mini，Qwen Code 配 Qwen3-30B-Coder。三种设置：

  • 不给上下文文件
  • 用各家的初始化命令让 agent 自己生成一份，按官方推荐的做法
  • 用仓库里开发者提交的那份原文

同一个任务跑一次，看补丁能不能让测试全绿，同时记录步数和推理花费。

自动生成的那份，基本是纯支出#

先看成功率。LLM 生成的上下文文件，在 SWE-bench 上平均拉低 0.5 个百分点，在 CTXBENCH 上拉低 2 个百分点。p 值分别是 0.87 和 0.37，意思是这个变化跟噪声分不开。八个设置里有五个是往下走的，剩下三个微涨。

步数每一项都变多，平均多 2.45 步和 3.92 步。成本涨 20% 和 23%，p 值小于 0.001%。

花更多钱，走更多步，结果一样。这是最差的一种组合。

按模型拆开看，损失最明显的是 Claude Code 配 Sonnet 4.5，CTXBENCH 上从 73.5% 掉到 65%，掉了 8.5 个百分点。GPT-5.2 反而从 64.5% 提到 68%。GPT-5.1 mini 从 54.5% 掉到 50.5%。Qwen3 从 45% 到 47%。

方差摆在这，所以作者没敢说"上下文文件有害"，只说"没有普遍收益"。但对写文件的人来说，这句话的实际含义是：你按官方教程做的那一步，期望收益是零。

人写的确实好一点，但别高兴太早#

开发者提交的那批文件，比不提供文件平均高 2.4 个百分点。p 值 0.21，统计上不显著。它确实显著优于 LLM 生成的那份，平均高 7 个百分点，p 值 0.038。这是全篇唯一一个让人舒服的数字。

代价也还在：平均多 3.34 步，成本最多涨 19%。四个模型里只有 Claude Code 配 Sonnet 没吃到好处，从 73.5% 到 70.3%，还是掉了。

所以"人写的比机器写的好"成立，“人写的能提升 agent 能力"不成立。它更像是把一个本来能跑的任务，绕了几步再跑一遍，顺便多花点钱。

顺带说一个反面案例：Qwen3-30B 从 45% 涨到 53.5%，是四个模型里唯一因为人写的文件涨了 8.5 个点的。小模型对明确指令的依赖确实更重，这件事值得单独研究，但这篇论文没深挖。

指令被认真执行了，这才是坏消息#

论文最有价值的部分不是成功率，是对 trace 的分析。他们把 agent 的每次工具调用都分了类，看上下文文件到底改变了什么行为。

结论：文件里的指令，agent 基本都照做了。有测试相关的句子，就多跑测试；有 grep 的建议，就多搜文件；提到 uv，就真的开始用 uv 而不是 python -m pytest。读文件、写文件、遍历目录，各项都变多。

问题是这些多做出来的动作，对解决眼前这个 issue 没有帮助。

一条"提交前跑完整测试套件"的指令，对每次任务都要收一次费。它防的是你将来可能出的错，不是当前这道题。agent 不会判断这条指令跟今天这个 bug 有没有关系，它只会执行。

论文附录里有一个更直白的消融实验。他们把上下文文件按节拆开，逐节删掉再跑。在 SWE-bench 上，删掉"测试"那一节之后，成本从 0.327 美元降到 0.276 美元，降了 16%，p 值 0.0035。成功率从 54.4% 升到 57.7%，虽然不显著，但方向是往上。

删掉要求跑测试的那段话，agent 变便宜了，也没变笨。

在 CTXBENCH 上，删掉"项目简介"那一节，成本从 0.47 美元降到 0.40 美元，准确率从 68.1% 掉到 62.3%，p 值 0.15，还是不显著。

这些数字指向同一件事：文件里的每一句话都在收税，只有极少数几句能带来回报。

最没用的一节，恰好是大家最爱写的#

关于项目简介，论文说得比摘要更狠：模型厂商都在推荐写一段仓库概览，但这类内容"没有帮助”。

他们量的指标很具体：agent 从开始干活到第一次碰到 PR 真正改过的那个文件，中间要走多少步。如果概览有用，这个数字应该下降。结果在所有 agent、两个基准上都没有实质下降。GPT-5.1 mini 反而显著变多，因为它会先跑几条命令去找上下文文件，找到之后反复读，尽管文件本来就在它的上下文里。这个行为只在有文件的时候出现。

再看生成端。Sonnet 4.5 生成的上下文文件，100% 被判定包含仓库概览；GPT-5.2 是 99%，Qwen3-30B 是 95%。GPT-5.1 mini 只有 36%，它是这批里唯一不怎么写概览的。

至于人写的：12 份里有 8 份带专门的代码库概览，其中 4 份把目录和子目录挨个列了出来。

我自己以前也这么写。列目录看起来是在帮忙，实际上是让 agent 用 token 去读一份它 ls 一下就能拿到的东西，而且这份东西会过期。目录改了，文件不改，agent 拿到的就是一份错误的导航。

我的判断：这是策略文件，不是文档#

把 AGENTS.md 当 README 写，是最常见的错。README 是给人的，讲这个项目是什么、为什么存在。AGENTS.md 是给 agent 的策略，讲在这个仓库里该怎么动手。

两者的区别不在文体，在可验证性。策略能被检查：命令跑不跑得通，测试过不过得了，这条路径允不允许碰。文档不能：一段架构描述是真是假，agent 没法验证，只能照单全收，然后基于它做判断。

所以我删文件时用三个筛子：

能不能执行。 pnpm test:e2e -- --grep auth 是策略。本项目的核心是解耦的事件架构 不是。

能不能验证。 不要改 migrations/ 下的历史文件 可以查。写代码要注意可维护性 查不了。

是不是这个项目独有。 提交前跑测试、遵循 PEP 8、写清晰的注释，这些话对所有项目都成立，等于没说，还占位置。真正值钱的是那些反常识的约定：这个仓库的测试必须先起一个 docker compose，那个目录的代码是生成的不要手改，某个看起来该用的库在这里是被禁的。

按这个标准，多数 AGENTS.md 能砍掉七成。剩下三成是命令、红线、和真正非标准的约定。

还有一个判断标准更粗暴，但很好用：超过 100 行就该怀疑。论文里那些开发者文件平均 641 个词，已经算长了，效果也只是"不比没有差太多"。

怎么在自己的仓库上验证#

不用信我，也不用信论文。你仓库的分布跟他们的样本不一样。

准备两组同样的任务，一组留着文件，一组把文件删到只剩命令。跑十个真实 issue，记三个数：成功率、平均步数、每次任务的成本。Codex 的 session 里能直接看到 token 消耗，换算成钱不难。

如果删完之后步数下降、成功率不掉，你那份文件就是负担。

更省事的做法是先做减法再观察：把概览、目录树、编码规范、“最佳实践"那几节整段删掉，只留构建、测试、代码生成目录和禁用清单，用一周。多数人会发现差别小到感觉不出来，这本身就是答案。

最后#

AGENTS.md 是一个不太常见的工具：写它的成本是一次性的，读它的成本是每次任务都要付的。这种不对称很容易让人写多，反正写的时候不疼。

但 agent 是照做的。你写进去的每一条要求，它都会在每一个不相关的任务上执行一遍。写得越多，它越勤快，也越慢，越贵。

一句话总结这篇论文：少写点。只写那些 agent 猜不到、又必须遵守的东西。

参考来源：