Claude Code 2.1.277 终于读 AGENTS.md 了：内置 mod 插件机制首次亮相

项目根目录里总躺着一份 AGENTS.md，里面写满代码风格、提交规范、测试流程。Cursor 读它，Codex 读它，Copilot 也读它，唯独 Claude Code 一直很“高冷”：我只看 CLAUDE.md。

这个尴尬局面在 9 月 18 日结束了。Claude Code 团队成员 Thariq Shihipar 宣布：

我们正在给 Claude Code 加上 AGENTS.md 支持。

从今天的 2.1.277 版本开始，如果一个文件夹里没有 CLAUDE.md，Claude 会检查并使用 AGENTS.md。

AGENTS.md 支持建立在 Claude Code mods 之上——那是我们即将推出的、用来定制 Claude Code harness 的方式。

这是一个内置 mod，但以后你也可以自己构建自定义版本的项目指令。

源码已经放在 github.com/anthropics/claude-code/tree/main/mods/agents-md。

三条信息量：标准收编了，实现方式是插件，而且插件机制本身开放了。

为什么这件事值得单独说

AGENTS.md 正在变成跨工具的事实标准。逻辑很简单：同一份项目规矩，你不想维护三份——CLAUDE.md、.cursorrules、copilot-instructions.md，然后每次改规范都要同步三个地方，还总有一个忘了改。

一个文件、多个工具复用，这是开发者用脚投票投出来的需求。Claude Code 是最后几个坚持自有格式的大玩家之一，它这次松口，意味着你可以开始认真考虑「只维护一份 AGENTS.md」这件事了。

但更值得注意的是第二层：它不是一个写死的功能，而是一个 mod。

mods 是 Claude Code 即将推出的定制机制。官方这次把 AGENTS.md 支持做成内置 mod，等于顺手做了一次示范：原来 harness 的行为是可以被插件替换和扩展的。以后你想让 Claude Code 用一套自己的项目指令加载逻辑，写个 mod 就行。

四种模式，默认那个最保守

从 mod 的 源码 读下来，它只暴露一个选项 instructionFiles，四个取值：

• claude-md：只加载 CLAUDE.md，由引擎自己处理，插件什么都不加。这就是旧行为。
• claude-md-or-agents-md（默认）：项目自己没有任何指令文件时，才把 AGENTS.md 顶上去，加载的位置和方式和 CLAUDE.md 完全一致。
• claude-md-and-agents-md：每个 AGENTS.md 都和 CLAUDE.md 一起加载，上下整棵树都读；已经被 CLAUDE.md 用 @ 引入过、或者本身就是软链指向的，不会重复加载。
• managed-only：项目检入的、私有的、以及个人的指令文件全部丢掉，只留组织的 managed CLAUDE.md 和引擎的 memory。

注意默认值里那句「项目自己没有任何指令文件」。它的判定相当严格：从根目录到工作目录，任何一层只要有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md，整个项目就归引擎管，插件直接退场。组织的 managed 文件、你个人的 ~/.claude/CLAUDE.md、.claude/rules、以及 --add-dir 加进来的目录，都不算「项目自己的」。

怎么改

最省事的是 /config 里的「Project instructions」那一行，一个四选一的下拉框。

想手写的话，放在用户设置 ~/.claude/settings.json、--settings 或 managed settings 里：

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": {
        "instructionFiles": "claude-md-and-agents-md"
      }
    }
  }
}

有个坑要记住：项目的 .claude/settings.json 不读插件选项。别往那儿写，写了不生效。

生效时机也很明确：改完会重新加载模块，下一个 context 生效——reload 之后的下一轮、新会话、/clear，或者一次 compaction。

嵌套行为：读子目录会带上它的 AGENTS.md

这个细节很实用。当 Claude Read 一个子目录里的文件时，那个目录的 AGENTS.md 会被附加进来——除非那里有 CLAUDE.md 抢先占了位置。

反过来，AGENTS.md 的 @ 引入也会被展开成独立条目，跟在文件后面。

也就是说，monorepo 里那种「根目录一份全局规范 + 每个子项目一份局部规范」的组织方式，是能正常工作的。

和 CLAUDE.md 相比，还有八处不一样

官方很诚实地列了差异清单，挑几条对日常使用有影响的：

• 嵌套文件只在文本 Read 时附加。 CLAUDE.md 还能在 @ 提及、IDE 打开的文件或选区、以及 Read 的 notebook、图片、PDF 结果时附加，AGENTS.md 目前不行。
• 插件附加的嵌套文件不进 read-file 状态。 所以 compaction 之后，引擎不会把它当成「最近读过的文件」恢复；插件会在下次 Read 到那个目录时重新附加。副作用是：会话中途你改了那个 AGENTS.md，不会重新播报。
• 路径按字面比较。 引擎会解析工作目录的软链别名，插件不会。
• --add-dir 的目录不贡献 AGENTS.md。
• /memory 和 # 快捷键不认识 AGENTS.md。 引擎自己那行初始加载统计也不算它们（插件自己的 agents_md_load 行会算）。

还有一条挺微妙：非 fork 的 subagent，在它自己第一次 Read 到某个目录时，会再拿一遍那个目录的 AGENTS.md——即使父 loop 已经拿过了。fork 则和引擎行为一致。

官方也给了测试命令，想自己改这个 mod 的人可以直接跑：

claude plugin test mods/agents-md

该选哪个模式

• 只想「没有 CLAUDE.md 的时候兜底」→ 默认的 claude-md-or-agents-md 就够了，零迁移成本。
• 想让 CLAUDE.md 和 AGENTS.md 并存（比如团队在渐进迁移）→ 切到 claude-md-and-agents-md。
• 团队或组织想统一管控、不让个人指令文件干扰 → managed-only。
• 完全不想变 → claude-md。

另外，/plugin 里能看到这个内置插件，可以整个关掉；关掉之后引擎就只读 CLAUDE.md 了。

更大的信号

这次更新表面上是「多读一个文件」，实际上透露出 Claude Code 的架构方向：harness 的行为正在被插件化。

项目指令怎么加载只是第一个被做成 mod 的东西。按这个路子，以后上下文怎么组装、工具怎么接、agent 怎么起，都可能变成可替换的模块。对只写业务代码的人来说，这是「配置更灵活了」；对做 AI 编码工具链的人来说，这是一个新的扩展点——你可以不改 Anthropic 的源码，就把自己的 harness 逻辑塞进去。

顺带一个现实提醒：如果你手上有一堆 CLAUDE.md 和 AGENTS.md 混着放的项目，别急着删。按默认模式的判定规则，只要项目里有 CLAUDE.md，AGENTS.md 就是不被加载的那一个。想两边都生效，记得把 instructionFiles 显式改成 claude-md-and-agents-md。

来源：simonwillison.net/2026/Sep/18/thariq-shihipar/ 实现细节见 github.com/anthropics/claude-code/tree/main/mods/agents-md