AGENTS.md 在 Coding Agents 中真的有用吗？

这篇论文，大规模实证研究仓库级上下文文件（AGENTS.md、CLAUDE.md 等）对编码 Agent 实际效果的影响，可能有些反直觉！感谢 @rasbt 分享！
论文在这：https://arxiv.org/abs/2602.11988

研究背景：实践先行，证据滞后
AGENTS.md 已成为行业惯例，GitHub 上已有 6 万+ 仓库采用，Claude Code (CLAUDE.md)、Codex、Qwen Code 等 Agent 都内置 /init 自动生成。但此前研究多停留在内容分类与描述性统计，缺少对任务完成率的严格评估。

核心难点在于：主流基准 SWE-bench 来自 Django、Flask 等知名仓库，这些项目本来就没有开发者手写的 context file，无法直接评估该实践的真实价值。

实验设计：双基准、三条件、四 Agent
· 基准：SWE-bench Lite（300 任务，11 个热门 Python 仓库）+ 新建 AGENTBENCH（138 任务，12 个已含开发者 context file 的冷门仓库）
· 三种条件：① 无 context file ② LLM 生成（各 Agent 官方 /init 流程）③ 开发者手写（仅 AGENTBENCH）
· Agent/模型：Claude Code + Sonnet 4.5、Codex + GPT-5.2 / GPT-5.1 mini、Qwen Code + Qwen3-30B
· 指标：任务成功率、步数、推理成本、工具调用轨迹

核心发现：效果微弱，成本显著
1. 成功率：边际效应，甚至为负
· LLM 生成：8 组设置中 5 组下降，平均 -0.5%（SWE-bench）/ -2%（AGENTBENCH）
· 开发者手写：平均 +4%，优于 LLM 生成，但 Claude Code 上甚至不如无文件
· 跨模型、跨 prompt 结论稳健
一句话：自动生成 context file 不仅无益，还可能略有害；手写的提升也很有限。

2. 效率：无文件反而最便宜（步数，成本）
· LLM 生成：+2.45 / +3.92 步，+20% / +23%
· 开发者手写：+3.34 步，最高 +19%

3. 代码库概览几乎无效
Context file 常被推荐用于「帮助 Agent 快速定位代码」。实测显示：有无 context file，Agent 首次接触相关文件所需的步数并无显著差异。95–100% 的 LLM 生成文件都包含代码库概览，但对导航帮助甚微。

轨迹分析：Agent 听话，但听话很贵
论文排除了「Agent 忽略 context file」这一假设。轨迹分析表明：
· 指令遵从度高：context file 提到 uv，使用率从 <0.01 次/任务升至 1.6 次；提到仓库专用工具，从 <0.05 升至 2.5 次
· 行为更「认真」：更多测试、更多文件搜索/阅读、更多 lint/质量检查
· 推理更深：GPT-5.2 推理 token 增加 14–22%

机制链条：
Context file 写入额外要求
→ Agent 更严格遵从（测试、探索、专用工具）
→ 步数与成本上升
→ 成功率未同步提升（甚至更差）

Context file 不是被忽略，而是被过度执行——把「建议性流程」当成了「必做清单」，增加了任务复杂度，却没有换来更高成功率。

一个关键反转：文档冗余假说
当移除仓库中所有其他文档（.md、docs/、示例代码）后，LLM 生成的 context file 反而带来 +2.7% 提升，且优于开发者手写的。

这说明：
· 在文档齐全的仓库里，context file 与 README、docs 高度冗余
· 开发者口述的「加了 AGENTS.md 后 Agent 变强了」，很可能是因为目标仓库本身文档稀缺，context file 填补了信息真空
· 对 Django 这类文档完善的知名项目，额外 context 的价值被稀释

消融实验：生成质量的上限
· 更强模型生成 ≠ 更好 context：GPT-5.2 生成的文件在 SWE-bench 上略好（+2%），在 AGENTBENCH 上反而更差（-3%）
· 不同 prompt 无一致优势：Codex prompt vs Claude prompt 效果因数据集而异，差异很小

自动生成 context file 的改进空间，目前看来很有限。

实践建议
· 依赖 /init 自动生成：谨慎——平均略降成功率，成本 +20%+
· 长篇架构概览、目录枚举：避免——与代码探索冗余，不加速定位
· 测试/lint/构建命令：精简写入——Agent 会严格执行，但过多要求推高成本
· 仓库专用工具（uv、pdm 等）：值得写——指令遵从度高，且代码中不易推断
· 分层/按需引用：方向正确——「做 X 时读 Y.md，否则忽略」减少无关负担