Linux 内核在给 AI Agent 写说明书：为什么你的 AGENTS.md 正在倒贴 20% 成本

lipengfei634626165@163.com (lpflpf) — Sat, 26 Sep 2026 07:30:00 +0800

9 月 24 日，Linux 内核邮件列表出现一份补丁：提议在内核源码树里加入 AGENTS.md。理由很实在——没有它，AI agent 乱签 Signed-off-by；有了它，违规消失。但反对意见同样实在：你在补丁里链接了整个 README，agent 解析这些文档要白烧 token。

两边都对。今年发表的三项独立实证研究给出了同一把尺子：这份文件不是文档，是每次请求全量加载的运行时配置。写对了，任务时间降 28.64%；写错了（尤其是让 LLM 自己生成），成功率反降 3%、推理成本多付 20%。每个在用 Codex / Cursor / Claude Code 的人，都该重审仓库里那份文件。

内核为什么需要一份给机器读的说明书

先交代背景，不然会觉得这是大项目闲得慌。

内核从 2025 年起允许 AI 参与写代码，但官方流程文档（Documentation/process/coding-assistants.rst）划了一条硬线：AI agent 不得添加 Signed-off-by。这条标签是开发者对代码来源和授权的法律认证（DCO 协议），只有人类能签；AI 参与必须用 Assisted-by 标签披露。

问题在于，你不告诉 agent 这条规则，它就会凭训练数据里的"通用礼貌"自作主张——给补丁加上自己签的 Signed-off-by。这在普通公司仓库顶多算格式瑕疵，在内核是法律层面的错误：一个不具人格的 AI 签名，会让整份补丁的授权链失效。

提交补丁的是 Sasha Levin——stable/LTS 分支的共同维护者，NVIDIA 出身。有意思的是时间线：这不是他第一次干这事。早在 2025 年 7、8 月他就向 LKML 提交过"为 coding agent 建立统一配置"的补丁集，被搁置；这次 9 月 24 日的 AGENTS.md 补丁已经是第三轮尝试。在最保守、最严苛的开源社区里，一个维护者为机器说明书屡败屡战三轮——说明 agent 已经真实地渗进了内核的日常提交流程，规则缺口造成的返工是维护者每天在承受的痛。

而 AGENTS.md 这个格式本身也早已不是小众实验：它现在由 Linux 基金会旗下的 Agentic AI Foundation 托管，超过 6 万个开源项目采用，20 多种 agent 工具原生支持。内核讨论的不是"要不要引入新发明"，而是"事实标准要不要进我的树"。

连把"没用的东西挡在源码树外"当作核心信仰的内核，都在认真考虑给 AI 写说明书。这个信号本身，比补丁内容更值得注意。

补丁修好了署名，却引爆了另一个问题

Levin 团队随补丁给出的测试结果显示：在没有 AGENTS.md 时，一个 agent 违规添加了 Signed-off-by 并使用非标准署名标签（而不是内核规定的 Assisted-by），另一个干脆什么署名都不加；加入 AGENTS.md 后，两类问题都消失了。

不过要把话说在前面：这是小样本的演示性测试，不是受控实验，未见公开的实验细节。它能证明"规则写进去，agent 听"，不能证明"写多少听多少"。

因为补丁同时点了另一根引线。提议的 AGENTS.md 内容是什么？链接 README 及相关文档——意思是让 agent 顺藤摸瓜去读内核那套几千页的开发流程文档。邮件列表立刻有人反对：这会给 agent 增加巨大的 token 消耗。与其让机器啃完整手册，不如专门写一份针对性的 AI 文档。

争论的本质是一个所有 AGENTS.md 作者都遇到过的张力：

说明书越全越好？——agent 确实不再犯低级错误，但每次会话都要为全文付上下文成本；
说明书越短越好？——省钱，但 agent 又开始自由发挥。

内核维护者的分歧不是抬杠。他们恰好按住了天平的两端，而今年发表的三项研究，正好为这场争论提供了裁决证据。

三项研究给内核争论判了个案

第一项，来自 arXiv:2601.20404（Lulla et al.）。研究者在 10 个真实仓库上跑了 124 个 PR 任务，对比"有结构良好的 AGENTS.md"和"没有"：中位运行时间下降 28.64%（98.57 秒到 70.34 秒），输出 token 下降 16.58%，任务完成率持平。写得好的说明书不仅不拖慢 agent，反而让它更快更省——因为 agent 不用再花十几轮试错去猜构建命令和项目惯例。局限：只测了 OpenAI Codex 一种工具。

第二项，苏黎世联邦理工（ETH Zurich）的 arXiv:2602.11988（Gloaguen et al.），泼冷水的那篇：让 LLM 自动生成 context 文件，平均降低约 3% 任务成功率、推理成本增加 20% 以上、执行步骤变多；而人类手写的文件也只带来约 4% 的提升。基准是 SWE-bench Lite 和 AgentBench。也就是说，“顺手让 agent 给自己写份说明书"这个最流行的用法，实测是负收益。

第三项，巴西 UFMG 团队的 arXiv:2606.15828，直接解剖生态：抓取 GitHub Top-100 热门仓库的 AGENTS.md/CLAUDE.md 逐一分类，91% 至少含一种"配置异味”。最高频的三种：Lint Leakage（62%，把 lint 能查的规则抄进说明书）、Context Bloat（42%，无差别堆长文）、Skill Leakage（35%，把低频专项知识常驻在每次会话里）。

三项研究测量的指标不同，不可直接横向比较；数值取自各论文原文（arXiv:2601.20404 / 2602.11988 / 2606.15828）

三篇放在一起看，会发现它们根本没有互相矛盾——分歧从来不在"要不要 AGENTS.md"，而在"谁写的、写了什么"。写得好的（第一篇）大幅正收益；LLM 自动生成的（第二篇）负收益；而现实中 91% 的文件属于后者或掺了大量水分（第三篇），所以你体感"这玩意没用"，其实是"你那份没写对"。

内核邮件列表的双方各拿了对自己有利的一半证据：Levin 的署名修复对应第一篇的机制，反对者担心的 README 链接正是第三篇里的 Context Bloat。还有一派声音主张把知识拆进按需加载的 skill 文件，而 Vercel 的评测又说整份 AGENTS.md 优于拆分方案——注意这是厂商自报数据、任务集与 ETH 不同，本文如实呈现，不做裁决。

照抄内核的判据：你的仓库该留哪几行

把三方证据收敛成一条判据：一行规则值不值得常驻上下文，取决于"agent 每次会话是否都需要它、且没有任何确定性工具能拦住违反"。 两个条件缺一个，这行字就是在收推理费。

一条规则该进 AGENTS.md、交给 CI、放进链接文档，还是直接删掉

按这个判据做三分：

进 AGENTS.md：构建/测试命令入口、环境陷阱（“集成测试要先起 docker”）、“绝不要碰 X"级禁令、署名/合规约定。共同点：违反即打回，且只有 agent 自己知道才算数的隐性知识——内核那份补丁选的就是这一类。
交给 CI / lint：代码风格、命名、格式化。这正是 Lint Leakage 占 62% 的原因——你把 golangci-lint 五分钟就能拦下的东西，抄进了每次请求都付费的说明书里。
放按需加载的链接文档：专项流程、低频知识。AGENTS.md 里只留一句"做数据库迁移时先读 docs/migrations.md”，而不是把迁移手册全文粘进去。

一个 Go 后端仓库的 AGENTS.md，密度参考线大概是这样（15 行封顶）：

# 构建与测试
- make build / make test（单测无需外部服务）
- 集成测试需要本地 docker：make test-integration

# 硬性规则（违反即打回）
- 禁止手工编辑 go.sum，只能 go mod tidy 生成
- 新增 migration 必须配 down 脚本（CI 强制校验）
- 不要修改 internal/api/v1/ 下的接口签名，除非任务明确要求
- 提交信息不加任何 AI 署名标签，作者字段只允许人类

# 深入阅读
- 领域模型见 docs/domain.md（改 model/ 前先读）

每一行都满足"违反即打回"。没有一行是"写出清晰可维护的代码"这种给模型添噪音的废话——ETH 研究里自动生成文件的典型形态就是后者。

配套的五分钟审计动作，现在就能做：数一下现有文件的行数占比；grep 出与 linter 规则重复的条目删掉；检查有没有相互矛盾的指令；把裸 URL 引用改成"什么时候需要它"的一句话说明；最后把它纳入 code review 保护范围——防止 agent 在会话里自行改写自己的说明书。

不过账也得算全。这套判据对小个人项目和一次性脚本不适用：agent 误操作的代价低于说明书的维护成本时，空文件就是最优解。内核案例也不能直接照搬条文——它的 DCO、Assisted-by、邮件流都是特化规则，普通团队借走的是那条方法论：说明书是运行时配置，一行即一行钱。

下一次派 agent 干活之前，先打开你仓库里的 AGENTS.md 数一遍行数：凡是被 golangci-lint、prettier 或任何 CI 步骤已经拦得住的规则，全部删掉；删完之后剩下的每一行，应该都能回答"违反了谁会打回这个 PR"。答不上来的那几行，就是你此刻正在为说明书付的那笔推理费。

AGENTS.md on 搬砖程序员带你飞

Linux 内核在给 AI Agent 写说明书：为什么你的 AGENTS.md 正在倒贴 20% 成本

内核为什么需要一份给机器读的说明书

补丁修好了署名，却引爆了另一个问题

三项研究给内核争论判了个案

照抄内核的判据：你的仓库该留哪几行