都说要给代码库写 AGENTS.md,写了真的有用吗?(易读版)

本文是同名深入版的精简版。所有关键数字经过三轮独立核查(105 票转述保真验证 + 12 份反证搜索与方法学审计判决——审计否决了两组流传甚广的数字,反证搜索找到了互相矛盾的研究),想看完整论证、证据分级和出处,请读深入版。

一个新的技术羞辱,和它缺的东西

这一两年,所有 AI coding 工具的厂商都在说同一件事:给你的代码库写一个"给 AI 看的 README"——OpenAI 叫它 AGENTS.md,Anthropic 叫 CLAUDE.md,Cursor 和 Copilot 各有各的名字。道理听起来无懈可击:AI agent 每次进你的仓库都要从零开始摸索,把构建命令、目录结构、团队规矩提前写好,它就不用瞎逛了。"你的 repo 居然还没有 AGENTS.md?"已经快成一种新的技术羞辱。

这个道理缺的东西叫对照组。我们把能找到的一手证据全部核了一遍,结论比口号有意思得多。

第一个意外:对照研究互相打架,唯一有统计检验的是省时省钱

2026 年上半年出了三个"带文件 vs 不带文件"的对照研究,结论互相矛盾:ETH Zurich 团队说成功率不升、成本涨两成;另一团队的配对实验测得完成同样的任务,时间中位数少 28.64%、输出 token 少 16.58%(这是三项里唯一带统计显著性检验的数字);第三个团队测得 AI 生成的指导文件把成功率提高了 2.8-7.5 个百分点。

我们对三项研究都做了敌意方法学审计,结果:名气最大的那项(ETH)的"成功率涨跌"数字被否决了——它全文没有任何统计检验、每个任务只跑一次、有效样本量其实只有 12 个仓库,±2-4 个百分点的"方向"在这种精度下是读不出来的。

所以诚实的总结是:成功率有没有影响,现在谁也说不准;唯一站得住的收益是省时间省 token——而且这也只测过一次。给老板汇报请用这个口径:值得试、值得自己测,但别承诺能力奇迹。

第二个意外:"怎么写"的讲究,大多讲究错了地方

网上有一整套写法圣经:文件要短、重要的放开头、别拆太多文件、千万别有矛盾指令。有人真的做了随机对照实验(1,650 次真实 agent 会话):文件大小、指令位置、单文件还是嵌套、有没有矛盾——四个变量对 agent 听不听话全都没有可检测的影响。其中"大小"和"矛盾"两项还是统计上确证的"无效应",不是"没测出来"。

真正影响 agent 听话程度的是两样:任务本身是什么,以及会话进行到多深——agent 每多干一个活,遵守你那条指令的概率就往下掉一点。指令写在文件哪一行不重要,agent 干到第几件事才重要。

那"短"就不用讲究了?还是要短,但理由换了:不是"短了更听话"(没证据),而是你写的每一行都在挤占 agent 干活的工作记忆——长上下文的性能退化是实测出来的,而且 OpenAI 的 Codex 会对超过 32 KB 的部分直接静默截断,你写再多它也看不见。

那到底该写什么?抄作业时间

几个大厂生产仓库的文件,我们逐字核对过原文,共性非常一致:

• 命令优先:把带完整参数、亲手跑过的构建/测试命令放最前面。
• 禁令要具体、放最前:Cloudflare 的文件第一条就是"用 pnpm——永远不要用 npm 或 yarn"(不然 agent 会搞坏整个 monorepo 的依赖锁)。
• 只写 AI 猜不到的:Airflow 写的是"所有文章里 Dag 一律首字母大写"和"永远别在宿主机直接跑 pytest"——这种团队私规,AI 读一万行代码也猜不出来。
• 一个文件当老大:Sentry 的文件开头就声明"AGENTS.md 是唯一事实源,不要往 CLAUDE.md 或 Cursor rules 里加内容"——防止三个文件各说各话。
• 别复制 README:上下文文件的价值可能来自"AI 从别处拿不到的信息"——这是目前最有希望的机制假说,两个独立研究的弱信号都指向它;复述 README 大概率是纯负担。

顺带一个反面教材:常和 AGENTS.md 一起被安利的 llms.txt(给网站写的 AI 索引文件),实测 97% 的文件一整个月连一个请求都没收到,Google 官方明确说不用它。写任何"给机器看的文档"之前,先确认那台机器真的会来读。

一个多数人没想过的问题:这文件是攻击面

Agent 把上下文文件当指令执行,不当普通文本读。这意味着:谁能写你的 AGENTS.md,谁就能指挥你的 agent。NVIDIA 红队做过完整演示:一个恶意依赖包在构建时偷偷改写 AGENTS.md,指挥 agent 往代码里埋后门,还附带"不许在 PR 描述里提这件事"的隐身指令。另外,VS Code 现在默认把仓库里的 AGENTS.md 注入每一次对话——打开陌生仓库前,记得这一点。

所以:上下文文件的改动要走 code review,来自机器人和自动化 PR 的改动尤其要盯;打开第三方仓库时,把它们的指令文件当不可信内容。

给你公司代码库的行动清单

1. 先盘点:团队用哪些 agent(决定文件叫什么名字)、哪些仓库文档最烂(文档荒地收益最大,文档完善的仓库预期放低)。
2. 选一个标准:默认 AGENTS.md 当唯一事实源,给 Claude Code 加个软链接;文件开头声明"就我一个,别处别写"。
3. 每个仓库花一两小时写个最小版:跑过的命令、三五行目录地图、always/ask-first/never 三档规矩,200 行以内。AI 全自动生成后直接提交?两个研究一个说有害一个说有益,谁都没赢——稳妥做法是生成初稿、人工修剪、再用第 5 条的度量验收。
4. monorepo 分层:根文件管全局,只给高风险子目录加嵌套文件,每个文件写个负责人。
5. 度量代替信仰:挑一两个试点仓库,准备每类任务一两条测试提示词,改版前后各跑一遍,看完成率、耗时、token。公开研究互相打架,你自己的度量是你唯一能拿到的本地真值;默认预期是省时省钱,成功率算意外之喜。
6. 当代码维护:改动走 PR;模型大版本更新后重新修剪(给旧模型打的补丁会变成新负担);安全团队看一眼编辑器的自动加载开关。

最后记住这个领域的现状:厂商建议很多,对照实验很少,而且刚出现的几个对照实验不但不站厂商,连彼此都说不到一起。把厂商口径当默认值用,把你自己的度量当裁判用。