
开发者建议弃用 AGENTS.md 和 CLAUDE.md 等 AI 代理配置文件
来源标题:Drop Agents.md and Claude.md
开发者认为同时维护 AGENTS.md、CLAUDE.md 等多个代理配置文件已无必要,主张只保留一份。AGENTS.md 格式由 OpenAI、Amp、Google Jules、Cursor 和 Factory 共同推出,自 2025 年 12 月起由 Linux 基金会下属的 Agentic AI Foundation 托管,官网称已有超过 6 万个开源项目使用。
以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。
放弃 Agents.md 和 Claude.md
如果你和我一样,大概也折腾过 AGENTS.md、CLAUDE.md、BRAIN.md 之类的文件;有那么几个月,我觉得身边留着这些文件挺合理。每个 harness 都有自己的开场说明。可如今我不这么看了。我很快就决定只用 AGENTS.md,因为大多数 harness 其实都会读这个文件。就算你没放 CLAUDE.md,Claude Code 也会读它。本来事情到这儿就可以结束了——但我后来又想明白了另一件事。
在回答那个问题之前,先讲讲历史是有必要的。
Cursor 读 .cursorrules。GitHub Copilot 读 .github/copilot-instructions.md。Claude Code 读 CLAUDE.md,Gemini CLI 读 GEMINI.md,Windsurf 读 .windsurfrules,Cline 读 .clinerules,Amp 读 AGENT.md(单数)。如果你的团队用了三个工具,你就得把同一段“怎么跑测试”的说明留三份。
行业的解决办法是 AGENTS.md,这个格式出自 OpenAI Codex、Amp、Google 的 Jules、Cursor 和 Factory。自 2025 年 12 月起,它由 Linux 基金会下的 Agentic AI Foundation 托管,官网上说已有超过 6 万个开源项目在用。Claude Code 坚持了很久,从 2.1.277 版本起,当项目里没有 CLAUDE.md 时,它也会读 AGENTS.md。
于是七个特殊文件变成了一个特殊文件。这让我想起 xkcd 927。
agents.md 网站上给出的示例文件有两节。“Setup commands”列出 pnpm install、pnpm dev 和 pnpm test。“Code style”写着 TypeScript strict 模式、单引号、不加分号,以及尽量用函数式写法。
今天早上刚加入你团队的开发者会觉得这有用吗?当然有用。怎么安装、怎么跑测试、代码风格是什么,这是每个新人第一天都会问的问题。在小项目里,这些内容就是 README 的“Development”一节。在大一点的项目里,则是 CONTRIBUTING.md——GitHub 从 2012 年起就在 issue 和 pull request 表单里链接它了。
这个格式额外加了什么?网站上的 FAQ 说没有必填字段。它只是普通 Markdown,标题随你喜欢。所以这个标准就是一个文件名,外加一条规则:仓库里有多个文件时,以最近的那个为准。
这是 agents.md 网站上的原话,也是支持单独设一个文件的全部理由。它说,AGENTS.md 存放构建步骤、测试和约定,这些东西放在 README 里会显得杂乱,或者对人类的贡献者并不重要。
要我说,这是胡扯。哪些构建步骤对人类的贡献者不重要?我一个都想不出来。如果一个人没法照着 README 把项目构建起来,那 README 就是坏的,应该修好。
我们给这些模型仓库的写权限。我们让它们提 pull request,还有不少人让它们直接合并。整套说辞就是这东西干起活来像个称职的工程师。然后我们转过头说它需要自己的上手文档,因为我们给工程师写的那份是“给人类看的”。如果一个模型好到能改我的代码,那它就也该好到能读我的 README。如果它照着初级开发者用的文档搞不明白怎么跑测试,那我希望在它碰任何东西之前就知道这件事。
每当人们把 agent 描述成一种有职位头衔和人设的新同事,我就看到同样的错误。编程 agent 就是一个语言模型加上一些工具在循环里跑,它从 AGENTS.md 里得到的不过是放进 prompt 的文本。README 是写给任何刚接触这个仓库、需要把活干完的人看的,而语言模型读 Markdown 完全没问题。不管你把它的理解成同事还是文本预测器,它该拿到的都是同一个文件。
对同一套构建流程的两份描述还会逐渐走样。README 说 npm test,AGENTS.md 说 pnpm test,于是人和模型对项目怎么运作各执一词。
苏黎世联邦理工学院和 LogicStar.ai 的 Gloaguen 及其同事在 2026 年 2 月测试了这些文件(Gloaguen et al. 2026)。他们在真实的 GitHub issue 上跑了四种配置(Claude Code 配 Sonnet 4.5,Codex 配 GPT-5.2 和 GPT-5.1 mini,Qwen Code 配 Qwen3-30B-coder),分别在有和没有上下文文件的情况下运行。他们的摘要说,提供上下文文件“通常并不能提高任务成功率”,反而“平均让推理成本增加 20% 以上”。用 LLM 生成的文件时,解决率在 SWE-bench Lite 上下降了 0.5%,在他们自己的 benchmark 上下降了 2%。开发者亲自提交的上下文文件平均比生成的文件高出 7%。
完全没有上下文文件的 agent,解决的问题数量和有的差不多。README、文档和代码已经足够让它们搞清楚项目怎么构建、怎么测试。
作者建议,人工编写的上下文文件只应包含“README 里尚未出现”的说明。仓库概览这类内容很流行,模型厂商也推荐,但结果证明没什么用。真正有用的是对非标准编码实践的描述——在我看来,那就是贡献指南里的约定一节。
这篇论文比较的是“有上下文文件”和“没有上下文文件”,所以它并没有说明把约定放在 README 里会怎样。
在我少数用到 AGENTS.md 的场合,里面通常是关于 agent“行为”的规则,比如“只有 Mike 要求时才提交”这类具体的规矩。
然后才是真正的工具配置,也就是权限、hook,以及哪些命令可以不询问就执行。这些放在工具的设置文件里,就像编辑器设置放在 ~/.config/somecooleditor/config.json 里一样。
这些工具确实会在每次会话时自动把 AGENTS.md 载入上下文,而面向用户写的 README 可能很长。这是工具本身的特性,它同样可以轻松加载 README.md。Codex 默认把项目文档限制在 32 KiB,Claude Code 的文档则说每个指令文件以 200 行以内为目标。超过这些限制的 README,对人也一样太长。解决办法一直是把细节挪到 CONTRIBUTING.md 和 docs/ 里,然后链接过去。
(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。