Claude Code 开始读 AGENTS.md：编码代理的配置文件之争开始收敛

Claude Code 的 2.1.277 版本（9 月 18 日）加了一条不大但方向明确的更新：项目里没有 CLAUDE.md 时，Claude Code 会去读 AGENTS.md。可以在 /config 的「Project instructions」里改这一行为；目前 Bedrock、Vertex 和 Foundry 上还不支持。

这条更新的意义不在于功能本身，而在于它标志着编码代理（coding agent）的「配置文件」之争开始收敛。

AGENTS.md 是什么

按官方说法，AGENTS.md 是 「给 agent 看的 README」：README 写给人看（快速开始、项目介绍、贡献指南），AGENTS.md 则专门放代理需要的上下文——构建命令、测试命令、代码风格、PR 规范这类「写进 README 会显得啰嗦」的东西。

几个关键事实：

目前有 6 万多个开源项目在用它（GitHub 代码搜索口径）；
它不是某一家公司的私有格式，而是由 OpenAI Codex、Amp、Google 的 Jules、Cursor、Factory 等协作产生的；
现在由 Linux Foundation 下的 Agentic AI Foundation 托管；
格式就是普通 Markdown，没有必填字段，用什么标题都行，代理只是解析你提供的文本。

为什么这件事值得记一笔

编码代理的指令文件长期是分裂的：Claude Code 用 CLAUDE.md，Cursor 有 .cursorrules，Gemini CLI 有 GEMINI.md，GitHub Copilot 有 .github/copilot-instructions.md。同一个仓库要想让多个工具都听话，就得维护好几份内容重复的文件。

AGENTS.md 是第一个真正跨工具的事实标准。而 Claude Code 此前是最主要的「各行其是」者之一——它一如既往地使用自己的 CLAUDE.md。现在它把 AGENTS.md 接成了 fallback，等于承认了这个约定。

对维护者来说，实际收益是：一份文件，多个代理。

规则与边界

就近优先：大型 monorepo 里可以在子包里再放 AGENTS.md，代理会读取目录树上最近的那一份，子项目因此可以有各自定制的指令。官方给的数据是：写作时 OpenAI 主仓库里有 88 个 AGENTS.md。
冲突时：离被编辑文件最近的 AGENTS.md 生效；用户在对话里明确给出的指令覆盖一切。
会执行命令：如果 AGENTS.md 里写了测试命令，代理会尝试执行这些检查并在结束任务前修掉失败（前提是你写了）。
CLAUDE.md 优先级更高：Claude Code 这次加的是 fallback，不是替换。

如果你同时用几个代理

迁移：把现有文件改名成 AGENTS.md，再建一个符号链接保持向后兼容——mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md；CLAUDE.md 也可以照做。
Aider 在 .aider.conf.yml 里加一行 read: AGENTS.md。
Gemini CLI 在 .gemini/settings.json 里设置 { "context": { "fileName": "AGENTS.md" } }。

顺带一提，我们自己这个仓库也是用 AGENTS.md 来写给代理看的录入与写作规范——它现在对 Claude Code 生效，正是这次更新带来的变化。