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

- 来源：meng shao (@shao__meng)
- 发布时间：2026-06-08 09:07
- AIHOT 分数：64
- AIHOT 链接：https://aihot.virxact.com/items/cmq4jk52b01lgslotqous9ah6
- 原文链接：https://x.com/shao__meng/status/2063790077021753383

## AI 摘要

论文大规模实证检验 AGENTS.md 等仓库级上下文文件对编码 Agent 的影响。在 SWE-bench Lite（300 任务）和新建 AGENTBENCH（138 任务）上测试 Claude Code、Codex、Qwen Code 等组合。核心发现：LLM 自动生成的 context file 在 8 组设置中 5 组成功率下降，平均 -0.5%（SWE-bench）/-2%（AGENTBENCH），成本增加 +20%+；开发者手写仅平均 +4%。冗余假说：移除其他文档后，自动生成反而 +2.7%。建议避免自动生成，精简测试/lint 命令，优先写入仓库专用工具。

## 正文

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 的冷门仓库）
· 三种条件：1 无 context file 2 LLM 生成（各 Agent 官方 /init 流程）3 开发者手写（仅 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，否则忽略」减少无关负担

### 引用推文

> Sebastian Raschka：http://x.com/i/article/2063647807437705216