AGENTS.md 有用吗？首次大规模实证说：自动生成的反而有害
挠痒
AGENTS.md（以及 CLAUDE.md、.cursorrules 等）已经成了 AI 辅助编程的标配——超过 6 万个 GitHub 仓库包含上下文文件，所有主流 agent 框架都推荐甚至内置了自动生成命令（/init）。整个行业的默认假设是：给 agent 提供仓库级别的上下文文件 = 更好的任务完成率。
但这个假设从来没有被严格验证过。原因有二：一是上下文文件刚出现不久（2025 年 8 月才正式标准化），SWE-bench 等经典基准里的仓库根本没有上下文文件；二是有上下文文件的仓库大多是小众项目，PR 质量和测试覆盖率与主流基准的大型仓库差异大，没法直接比。已有的研究只做了描述性统计（上下文文件平均多长、包含哪些章节），没有一篇做了 with/without 的对照实验。
假设(业界共识) 实证(本文之前) 本文
| | |
v v v
"上下文文件让 零对照实验, AGENTBENCH(138实例,
agent更好" 仅描述性统计 12仓库,开发者写的
| | 上下文文件) +
| | SWE-BENCH LITE(300实例,
| | 无上下文文件,用LLM生成)
| | |
v v v
被6万仓库 个案证据: 三组对照:
采纳为标配 "加了感觉好些" None vs LLM vs Human翻译
一句话
LLM 自动生成的上下文文件平均降低 agent 成功率 0.5-2%，同时增加推理成本 20-23%；开发者手写的仅提升约 4%。上下文文件的主要效果不是"让 agent 更聪明"，而是"让 agent 做更多事"——更多测试、更多探索、更多工具调用，但这些额外行为并不转化为更高的成功率。
核心机制
实验设计(三组对照)
+----------+ +----------+ +----------+
| NONE | | LLM | | HUMAN |
| 无上下文 | | 自动生成 | | 开发者写 |
| 文件 | | /init命令 | | 仓库自带 |
+----+-----+ +----+-----+ +----+-----+
| | |
+--------+-------+--------+-------+
| |
SWE-BENCH LITE AGENTBENCH
(300实例,11大仓库) (138实例,12小众仓库)
| |
4个agent x 3设置 4个agent x 3设置
= 12组实验 = 12组实验
| |
v v
测成功率 + 步数 + 成本 + trace分析核喻：给新员工发一本过厚的入职手册。 想象你是一家公司的新员工。场景 A：没有手册，你自己摸索（None）。场景 B：HR 用 AI 自动生成了一本 200 页的手册，包含每个部门的职能描述、每条走廊的地图、每个会议室的预订规则（LLM）。场景 C：你的直属 leader 手写了两页纸："我们用 pytest 跑测试，别碰 legacy/ 目录，有问题先看 CONTRIBUTING.md"（Human）。
论文发现：场景 B 的员工确实更勤快了——跑了更多测试、翻了更多文件、用了更多工具。但任务完成率反而比场景 A 更低。为什么？200 页手册里大部分信息是冗余的（与仓库已有文档重复），还有一部分是有害的（不必要的要求让任务变难了）。员工花了 20% 更多的时间"遵循手册"而不是"解决问题"。场景 C 的员工稍微好一点——但也只好了 4%，因为那两页纸虽然精准，但代价是更多的步骤和更高的成本。
关键定量结果：
SWE-BENCH LITE AGENTBENCH
None LLM Human None LLM Human
Sonnet 54.4% 57.2% -- 40.7% 46.5% 45.3%
GPT-5.2 12.5% 12.7% -- 12.1% 13.1% 13.6%
GPT-5.1M 40.9% 45.2% -- 40.6% 46.9% 46.6%
Qwen3 29.7% 32.2% -- 31.5% 34.2% 32.8%
平均成功率变化: -0.5%(LLM) -2%(LLM) / +4%(Human)
平均成本变化: +20%(LLM) +23%(LLM) / +19%(Human)
平均步数变化: +2.45步(LLM) +3.92步(LLM) / +3.34步(Human)等等——上面 SWE-BENCH LITE 的数字看起来 LLM 列都比 None 高？注意：论文原文明确说"LLM-generated context files cause performance drops in 5 out of 8 settings"。上表中 Sonnet 从 54.4% 涨到 57.2%，但这是例外。across all settings 的平均效果是负的。
行为分析（trace 层面的发现）：
- Agent 确实遵循上下文文件的指令：提到
uv的文件使 agent 使用uv的频率从 0.01 次/实例跳到 1.6 次/实例 - 上下文文件导致更多探索：更多 grep、更多 read、更多 ls、更多 pytest
- 推理 token 增加 10-22%：agent 花更多 token "思考"如何遵循指令
- 但上下文文件并不加速定位：首次接触补丁文件的步数无显著下降
文档去除实验（关键消融）： 去掉仓库里所有 .md 文件和 docs/ 目录后，LLM 生成的上下文文件反而提升了 2.7%。这说明：当仓库自带文档丰富时，上下文文件是冗余的；当仓库文档匮乏时，上下文文件才有补位价值。
关键概念
1. AGENTBENCH（本文新基准）
SWE-bench 的问题是：它的 11 个仓库都是知名大项目（Django、scikit-learn、Flask 等），训练数据里见过无数次，且这些仓库没有上下文文件。要测上下文文件的效果，需要一个新基准。AGENTBENCH 的构建过程：先在 GitHub 上搜索根目录有 AGENTS.md 或 CLAUDE.md 的 Python 仓库 -> 筛选有测试套件且 PR 数 > 400 的 -> 从 5694 个 PR 中筛选出 138 个有确定性、可测试行为变化的实例 -> 用 LLM 生成标准化任务描述（6 节：描述、复现步骤、预期行为、实际行为、规格、附加信息）-> 生成配套单元测试（平均覆盖率 75%）。12 个仓库包括 tinygrad、smolagents、openai-agents-python、fastmcp 等。与 SWE-bench 的区别：更均匀分布在不同仓库、包含开发者写的上下文文件、仓库更小众。
2. 上下文文件的冗余悖论
论文揭示了一个悖论：上下文文件的主要推荐内容（仓库概览、目录结构、构建命令、测试命令）与仓库自带的 README、CONTRIBUTING.md、Makefile 高度重复。8/12 个开发者写的上下文文件包含显式的代码库概览，100% 的 Sonnet-4.5 自动生成的上下文文件包含概览。但 agent 已经能通过 ls、cat README.md 自行获取这些信息。上下文文件不是提供了 agent 不知道的信息——它是把 agent 已经能发现的信息提前塞进了上下文窗口，占用了 token 预算但没有增加信息量。论文的文档去除实验证实了这一点：去掉所有文档后，上下文文件才开始有正面效果。
3. 不必要的约束假说
为什么自动生成的上下文文件反而有害？论文提出一个假说：LLM 生成的上下文文件倾向于包含过度具体的要求（"所有函数必须有 docstring"、"使用 ruff 格式化"、"遵循 PEP 8"），这些要求与当前任务无关，但 agent 会忠实遵循——花额外步骤跑格式化、写 docstring、检查风格。这些额外步骤增加了成本但不增加成功率。论文的 trace 分析证实：有上下文文件时，agent 使用 ruff、uv、repo_tool 等工具的频率显著增加，但这些工具调用与任务解决率无相关。开发者手写的上下文文件这个问题较轻——因为人知道什么重要什么不重要，倾向于只写最关键的约束。
Napkin Sketch
业界假设: 实证发现:
上下文文件 上下文文件
| |
v +----+----+
agent 更了解仓库 | |
| LLM生成 人写的
v | |
更高成功率 冗余+过度约束 精简+相关
| |
成功率-0.5~2% 成功率+4%
成本+20~23% 成本+19%
| |
v v
更多探索/测试 更多探索/测试
但不转化为 略转化为
更好结果 更好结果
真正有效的条件:
仓库自带文档丰富 --> 上下文文件冗余 --> 边际效果为零或负
仓库自带文档匮乏 --> 上下文文件补位 --> LLM生成 +2.7%一句话位移：从"上下文文件是最佳实践"到"上下文文件是需要实证检验的假设"——在文档丰富的仓库中，自动生成的上下文文件是付费的噪声。
洞见
哦，原来……给 agent 更多上下文不等于让 agent 更好——自动生成的上下文文件让 agent 更勤快了，但勤快不等于有效，多出来的步骤全是遵循指令的开销，而不是解决问题的进展。
这个结论反直觉的程度超过了大多数人的预期。整个行业的直觉是"上下文越丰富，agent 理解越深，表现越好"——这个直觉驱动了 6 万个仓库建立上下文文件、所有主流 agent 框架内置 /init 命令。但论文发现：LLM 自动生成的上下文文件平均让成功率下降了 0.5-2%，同时成本上升 20-23%。为什么？因为上下文文件主要包含两类信息：一是 agent 已经能自己发现的（README、目录结构、构建命令），把它们放进上下文只是浪费 token 预算；二是不必要的约束（"所有函数必须有 docstring"、"用 ruff 格式化"），agent 忠实遵循这些约束反而增加了解决问题的复杂度。真正有效的上下文文件是开发者手写的——因为人知道什么重要什么不重要，只写最关键的两行：别碰这个目录、用这个命令跑测试。
这揭示了上下文工程的一个根本张力：信息量和信噪比是相互拮抗的。更多信息不等于更高信噪比。当 agent 已经能自主探索仓库时，提前注入的上下文可能不是帮助，而是噪声加约束的组合——它限制了 agent 的探索自由，同时没有提供真正新的、无法自行获取的信息。
博导审稿
选题眼光： 精准且及时。6 万仓库在用、所有主流 agent 都在推荐、但零实证验证——这是一个典型的"皇帝的新衣"选题。ETH Zurich 这帮人做了行业应该在 2025 年就做的事：跑对照实验而不是收集轶事。AGENTBENCH 的构建本身就是贡献——138 个带开发者上下文文件的实例，填补了基准空白。
方法成熟度： 实验设计干净。三组对照（None/LLM/Human）覆盖了所有有意义的组合。四个 agent（Claude Code + Codex + Qwen Code）跨越三个厂商。SWE-bench Lite + AGENTBENCH 互补覆盖了大型知名仓库和小众仓库两个场景。trace 分析（工具使用频率、推理 token 数、首次接触补丁文件的步数）提供了行为层面的解释，不只是报数字。文档去除消融实验是画龙点睛——直接证明了冗余假说。
实验诚意： 数据说服力强但有局限。AGENTBENCH 只有 138 个实例、12 个仓库，全是 Python——能不能推广到 TypeScript、Rust、Go？样本量在某些子组上可能不够支撑显著性检验。每个 agent 只采样一次（temperature=0），没有多次运行的方差估计——SWE-bench 的成功率方差在 2-5% 范围内，这意味着 0.5-4% 的差异可能在噪声范围内。论文没有报告置信区间或统计显著性检验，这对于"上下文文件有害"这么强的声明是一个缺陷。
还有一个隐形假设值得追问：LLM 生成的上下文文件质量代表了当前行业最佳实践吗？论文用的是每个 agent 自带的 /init 命令——但这些命令本身可能还很粗糙。如果用更精心设计的 prompt 生成上下文文件呢？论文确实做了 prompt 消融（Figure 9），结论是"不同 prompt 无显著差异"——但只比较了 Codex prompt vs Claude Code prompt，没有测试真正优化过的 prompt。
写作功力： 结构清晰，Figure 1 的实验流水线图一目了然。行文克制，没有过度解读数据。唯一的遗憾是 Section 4.3 的 trace 分析可以更定量——"agents run more tests"和"agents explore more"可以给出具体的倍数和统计检验。
一句话判决： weak accept — 选题精准、实验设计干净、结论反直觉且有数据支撑，但样本量偏小、缺显著性检验、仅覆盖 Python。
接线
迁移：把"删除所有不能回答'去掉这条 agent 行为会变差吗'的规则"这个原则应用于 PAI 的 CLAUDE.md 审计。论文证明了信息量和效果之间不是正相关。PAI 的 rules/ 目录（coding-style.md、testing.md、patterns.md、git-workflow.md 等）中的每一条约束都需要过这个筛子：如果 agent 不知道这条规则，它的行为会有什么具体的、可观测的变差？能回答"是"的留着，回答含糊或"不一定"的删掉或移到 T2/T3 按需注入。这不是一次性优化，而是一个持续的维护习惯——每次发现 agent 多了一步无效的工具调用，就反查是哪条 rule 触发了它。
反转：我一直把 PAI 的 T1 层（always-on 宪法级上下文）视为越完整越好——覆盖的场景越多、规定越细，agent 的行为就越可预测。但论文说，当 agent 已经能自主探索时，提前注入的上下文更可能是约束而非赋能。这揭示了一个盲区：CLAUDE.md 的价值主要在于"agent 无法自行发现的信息"（身份/角色定义、安全铁律、Fish 的认知风格偏好）和"红线约束"（绝对不能做的事）——这些是人工上下文文件真正有不可替代价值的部分。而编码细节（变量命名、文件结构偏好、测试框架选择）这类 agent 能从代码库本身推断的信息，放进 CLAUDE.md 可能更多是增加干扰而非提供帮助。区分这两类信息，是重构 CLAUDE.md 的关键判据。