AGENTS.md 真的对 AI Coding 有用吗？或许在此之前你没用对？

AGENTS.md 相信大家应该不陌生，它们一般都是被放在根目录的典型 Context Files ，这些文件被默认作为 Coding Agnet 的 「README」，一般是用来提供仓库概览、工具链指令、编码规范或者设计模式等，不少 Agent 还提供 /init 之类命令自动生成这些文件。

可以说 AGENTS.md 就像是一个大家都默认的必需品，根据统计，根据 2026 年的统计数据，已经有超过 60,000 个开源项目在 root 目录下包含了 AGENTS.md 文件，但问题是，这些“ Context Files 到底能不能让 Coding Agnet 更容易把 issue/任务做对？还是只会增加 token 成本？

测试条件

论文 《Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?》 针对这个问题做了测试，他们采用了两套互补数据集 + 对照设置：

• 两个数据集

  • SWE-Bench Lite：经典的 300 个 Python repo-level 任务（热门仓库），这些仓库本来没有开发者写的 context file，论文在这里评测“自动生成 context file”的效果。
  • AGENTBENCH：他们专门去挖了 12 个带开发者自带 context file 的 Python 仓库，从真实 PR/issue 里构造出 138 个实例（bugfix + feature）

• 三种对照设置（同一任务跑三遍）

  • NONE：完全不提供 context file
  • LLM：按 agent 开发者推荐流程，用对应 agent 的推荐 init/提示词自动生成 context file
  • HUMAN：使用仓库里开发者自己提交的 context file（仅 AGENTBENCH 有）

然后就是被测 agents / models，这里采用了四套组合：

结论

而得到的结论很有意思，和之前在 《你现在给 AI 用的 Agent Skills 可能毫无作用，甚至还拖后腿？》 聊过的一结论类似：LLM 自动生成总体的效果“负收益”，人写的“微弱正收益但不稳定”，并且成本都更高 。

对于这个结论，这篇论文说的很直观：

• LLM 生成的 context files 往往让成功率更低（平均下降了 3%），同时推高推理成本 20%+
• 开发者写的 context files 相比 NONE 平均带来小幅提升（平均 +4% 左右），但也会让步骤/成本上涨

最有意思的是，他们在实验里量化了“更贵”这件事：

• LLM context file 会让平均 steps 增加
• 成本增加（SWE-Bench Lite 平均约 +20%，AGENTBENCH 平均约 +23% 的量级）
• 开发者文件同样增加成本

你是不是觉得这个成本也没什么？但是从数据可以直观体现：

0. 输入 Token 增加：例如 Claude Opus 4.6，输入超过 200K Token 时，计费单价会直接翻倍
1. 执行步骤增多：在有上下文文件引导时，智能体倾向于进行更广泛的探索，平均每项任务多执行 2.45 到 3.92 个步骤

为什么

那 “为什么会这样”？论文的 trace 证据主要体现在：context file 让 agent 更“谨慎/折腾”，但不更“聪明/精准” ，主要可以体现在三个范畴：

1、 context file 会显著改变 Agent 行为：产生更多探索、更多测试、更多工具调用，当 context file 存在时：

• agent 更频繁地跑测试
• grep / read / write 更多（更广泛地翻仓库、改文件）
• 更多使用 repo 特定工具（如 uv / repo_tool 等）

而且他们发现：context file 里写了某个工具的时候，agent 真的会更常用它，这说明“没提升”不是因为 agent 不听话，而更像是“听话但被加了不必要的工作” 。

2、“仓库 overview” 并没有让 agent 更快找到关键文件，很多推荐写法会要求 context file 提供代码结构概览，但他们用一个很直观的指标测「是否更快碰到 PR 真正修改过的文件」：

3、推理 token 明显上涨，他们用 GPT-5.2 / GPT-5.1 Mini 的「自适应推理 token」现象来佐证「任务变难了」: context file 会让推理 token 平均上涨一截：

因为 context file（尤其自动生成的）往往加入了“额外流程/要求/检查点”，agent 又会遵守，于是探索/测试/步骤/推理都上去了，但这些动作并不等价于更高的任务命中率，反而让任务更容易超时、跑偏或把精力花在无关紧要的规范上。

例外

当然，这里有一点例外的是：当仓库文档删掉，LLM 生成的 context file 反而有用。

其实这也很好理解，对于项目原本文档很差/缺失的情况，LLM 生产的 md 反而会能补上大量关键操作信息（怎么装依赖、怎么跑测试、目录大概干嘛），这时候的 AGENTS.md 自然反而体现了作用。

同时，他们还测了更强模型 / 换 meta-prompt ：

• 用更强模型（如 GPT-5.2）来生成 context file，不等于更好：在一个数据集上可能涨，在另一个上可能跌，所以并不是一个稳定收益
• 用 Codex 的生成提示词 vs Claude Code 的生成提示词，也没有稳定的输赢，这体了现在 AI 还是一个概率预测是本质

所以，问题不在“提示词不够好”和“模型不够好”这种浅层因素，更像是“自动生成这件事本身”还缺少可靠方法 。

争议

当然，对于论文的结论：

• 大模型自己维护并生产的 AGENTS.md ，在文档齐全的项目下没有收益，还增加成本，这个大家都还能够接受
• 但是对于开发者写的 context files 相比 NONE 平均带来 +4% 左右收益这个，在 HN 上大家还是觉得很大争议

目前 HN 上主要的核心讨论点有三个：

1、AGENTS.md 最大价值是 domain knowledge，而开源仓库很少有这种东西 ，对于 AI 来说，最有用的是模型无法从 repo 直接推断的业务/历史原因/隐含约束，这在闭源大项目常见，但在很多开源（尤其新做的小项目）里稀缺，所以 benchmark 里看不到收益。

2、有人说自己用 CLAUDE.md 主要是为了避免蠢错、减少后续 cleanup/refactor，而不是为了跑分意义上的“performance”，因为论文指标的边界测的是 exec(test)=PASS 的任务完成率，而不是“代码质量/可维护性/团队规范遵守度/后续返工成本”。

3、页有人直觉认为：仓库越大，越需要 AGENTS.md ，否则 agent 会浪费很多上下文去找命令、找入口，但论文在“是否更快找到关键文件”这个指标上，给出了相反的证据：**overview 并没有显著加速触达关键文件，对此他们认为：

• overview 的写法不对：列目录树/泛泛描述，信息密度低，不能直接指向“任务常改哪里”
• benchmark 任务分布的现实差异：SWE-Bench Lite 的热门仓库本身文档/惯例更成熟，agent 已经有“先验”，而很多人说的“大闭源仓库痛点”在 benchmark 里不充分

4、手工写的 4% 的成功率提升真的是微不足道吗？不少人认为，如果一个 md 文档就可以提高 4% 的成功率，这其实已经是一个非常大的收益，当然，4% 的提升并不具备跨模型的一致性，所以这个数据不能看作是一种普适的工程增量。

最后

实际上这篇论文和之前 Skills 那篇都指向同一个观点：LLM 自动生成总体不稳，常常负收益还更贵 ，所以更现实的做法是：把自动生成当作“草稿”，但必须人来重新审阅并修改为更具体和更具针对性的文档，而 AGENTS.md 最值得写的内容：

例如 AGENTS.md 可以表述：

• 只能跑 uv 而不是 pip ，以及这么做的原因
• 必须用某个脚本启动集成环境，具体哪些 env var
• 关键约束（兼容性矩阵、部署目标、性能红线、安全规则）

另外少写“目录导览”，多写“任务路由” ， 更有效的结构往往是：

• 常见任务 ：对应入口文件/模块（例如“新增 API → 先看 api/routes.py + schemas.py”）
• 常见 bug 类型 ： 排查路径（日志在哪，feature flag 在哪）

更最重要的是，冗长的文档反而会产生副作用，建议只在 AI 犯错后才添加针对性的补丁指令，然后支持在子目录中使用嵌套的 AGENTS.md，实现“按需加载”上下文，避免全局上下文污染，类似于：

另外还有一个小 tip 就是：「不要做 xxx 」的收益其实很一般，在 AI 上更建议使用正面引导或结合 Pre-commit Hooks 进行硬性拦截。

最后，事实上 AI 很多时候是会偷懒和「作弊」的，虽然它会说「我已经读过并理解了需求」，但实际执行时依然没有任何约束，这其实就是它直接忽略了 AGENTS.md ，因为此时它已经进入了 LLM 的炼丹玄学层面。