Claude Code 2.1.277 开始原生读取 AGENTS.md：一份项目指令文件跨工具生效

OpenAI 生态之外的智能体工具动态：Anthropic 的编程智能体 Claude Code 在 2.1.277 版加入了 AGENTS.md 支持——这是 OpenAI Codex 生态多年来的项目指令标准格式。本篇只转述可核实的内容：官方仓库 CHANGELOG 条目、mods/agents-md 目录 README（2026-09-22 重抓逐项核对）、npm registry 的版本时间戳，以及 AGENTS.md 官方站点的格式说明。对『两家为什么会走到一起』这类无源问题，本篇不做推演。

1. 发生了什么：官方变更条目与时间线

CHANGELOG.md 在 2.1.277 小节的原文只有一句：

Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under 'Project instructions' in /config (not yet on Bedrock, Vertex or Foundry)

翻译过来：项目里没有 CLAUDE.md 时，Claude Code 改为读取 AGENTS.md；行为可在 /config 的 Project instructions 里调整；Bedrock、Vertex、Foundry 三个平台暂不支持。

时间线（2026-09-22 核对）：

• 2026-09-18：PR #95409（mods/agents-md: the AGENTS.md project-instructions mod）合入 anthropics/claude-code 仓库，同日有一条跟进修复 #95417；
• 2026-09-18T16:22Z：npm 上 @anthropic-ai/claude-code 2.1.277 发布（registry 时间戳）；
• 2026-09-19T01:48Z：2.1.278 发布（本功能无进一步条目）。截至 2026-09-22，npm dist-tags 的 latest 与 next 都指向 2.1.278，而 stable 标签仍停在 2.1.267——用 stable 通道的安装方式暂时拿不到这个功能。

2. AGENTS.md：一个跨工具的开放指令格式

AGENTS.md 官方站点对它的定位是一句话：『给智能体看的 README』（a README for agents）——README 写给人看，AGENTS.md 专门给 AI 编程智能体提供构建步骤、测试命令与代码约定等上下文。官方站点称这一格式被超过 6 万个开源项目使用，并列出支持它的工具：OpenAI Codex、Google Jules、Aider、goose、Zed、Warp、VS Code、Devin、Cursor、Gemini CLI、GitHub Copilot 编程智能体、Windsurf 等。

在本站此前的工具对比里，AGENTS.md 一直是 Codex CLI 的协作入口：项目根目录写配置，Codex 自动读取。Claude Code 此前的对应物是自家的 CLAUDE.md。2.1.277 之后，这个格局变了——变的部分下面逐条拆。

3. 实现形态：内置插件 agents-md 与四种模式

值得注意的实现细节：AGENTS.md 支持不是一个写死在引擎里的新解析器，而是一个内置插件（官方叫 mod），代码在仓库的 mods/agents-md 目录。README 第一句概括了它的本质：以插件的形式，让 Claude Code 用读 CLAUDE.md 的方式读 AGENTS.md，全部行为由一个选项 instructionFiles 控制。

四种取值：

4. 默认模式的回退判定：什么时候读、什么时候让位

默认模式 claude-md-or-agents-md 的判定值得一篇单独小节，因为它比『没有 CLAUDE.md 就读 AGENTS.md』这句摘要细得多。

判定读的是『引擎为上下文实际加载了什么』：从仓库根到工作目录的路径上，任何目录里的 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 都算『项目有自己的指令文件』——此时插件完全不出手。有四类文件不参与这个判定：组织托管文件、个人的 ~/.claude/CLAUDE.md、.claude/rules 文件，以及通过 --add-dir 额外目录加入的 CLAUDE.md（嵌套遍历本来就看不到它们）。

判定为空时，该路径上每一份 AGENTS.md 与 .claude/AGENTS.md 都加入引擎渲染的指令文件；此后一次 Read 落到某个子目录，会附着那个目录的 AGENTS.md——除非同目录的 CLAUDE.md 认领了它。

5. 文件如何进入上下文与嵌套加载规则

README 专门强调了一句边界：文件怎么到达模型是引擎的事，不是插件的。机制是 prompt.context 钩子：引擎把当前 claudeMd 背后的指令文件列表（每项含 path、kind、content、可选 parent；kind 分 managed / user / project / local / memory，按加载顺序）交给钩子，钩子答回变更后的列表，引擎再用自己的前导与框架渲染、按名宣布。

这意味着插件加入的 AGENTS.md 拿到的是 project 这个 kind——对下游一切逻辑来说，它就是项目指令文件：上下文里的位置一样、框架一样、省略规则一样（比如 Explore、Plan 或设置了 omitClaudeMd 的自定义智能体照旧只拿 managed 文件）。组织里若有排在更前面的插件也挂了 prompt.context，它对文件列表有最终决定权。

嵌套规则：Read 工具读某个文件时，插件只遍历项目根与被读文件之间（不含两端之上）的目录，把其中尚未给过本智能体循环、不在上下文指令文件里（按路径或正文比对）、也没被同目录 CLAUDE.md 认领的 AGENTS.md 附着在工具结果之后，框架逐字节照搬引擎给嵌套 CLAUDE.md 的『Contents of <path>:』式样；每份文件每个循环、每段会话只附着一次，压缩或 /clear 之后的上下文重建会让计数重新开始。项目根变动（/cd、宿主换目录、worktree 迁移）会被实时跟踪，迁移后重新走一遍判定与附着。

6. 与 CLAUDE.md 的八项已知差异

README 用一节列出插件模式（默认与 both）下 AGENTS.md 与 CLAUDE.md 的行为差异，每一条都点名了插件在今天的事件面上够不到的加载器事实：

1. 嵌套文件只在文本 Read 时附着；引擎还会在文件被 @ 提及、IDE 打开或选中、Read 返回 notebook / 图片 / PDF 时附着目录的 CLAUDE.md——插件对这些都不触发；
2. 插件附着的嵌套文件不进循环的已读文件登记：压缩后引擎不会把它恢复进最近读取文件（插件会在下一次 Read 时重新附着），会话中它发生变化也不会重新宣布；
3. /cd 携带新目录树的 CLAUDE.md 走自己的通知通道；插件的对应文件与引擎的指令宣布走同一请求；
4. 路径按拼写比较，而引擎在判定文件是否在项目内之前会先解析工作目录的符号链接别名；
5. --add-dir 目录不贡献 AGENTS.md，引擎则可以加载它们的 CLAUDE.md；
6. /memory 与 # 快捷方式不认识 AGENTS.md，引擎自己的初始加载计数行也不含它们（插件的 agents_md_load 行含）;
7. AGENTS.md 里指向工作目录之外的 @ 引用，要等引擎对 CLAUDE.md 外部引用的授权批过之后才生效（未批准则该引用被排除在外）；而授权弹窗本身只为 CLAUDE.md 的引用而弹；
8. 非 fork 的子智能体会在自己的第一次 Read 时拿到嵌套 AGENTS.md，哪怕父循环已经拿过；引擎对嵌套 CLAUDE.md 则不会发给这类子智能体第二次——fork 则两边行为一致。

7. 配置方法、旧设置键兼容与平台限制

作为内置插件，它的配置入口是 /config 里名为 Project instructions 的选项行——一个带说明的四值选择器。手写等价物是下面这段（放在用户设置 ~/.claude/settings.json、--settings 传入的文件或托管设置里；注意项目级 .claude/settings.json 不读取插件选项）：

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

更改会重载模块，下一个构建的上下文（重载后的下一轮、新会话、/clear 或一次压缩）才带上新模式下的文件。手打四值之外的值，转录里提示一次，然后按默认模式读取。

旧设置键兼容：这个选项最早叫 projectInstructions，取值 claude / agents-fallback / both / none。存储在旧键下的值暂时被按固定映射读取——none 映射 managed-only，claude 映射 claude-md，agents-fallback 映射默认模式，both 映射 both 模式，其他值映射 claude-md（什么都不加，并且永不等于默认模式——这点与手打新键无效值按默认读取不同）。每次加载的第一次 session.start 会在转录里说明旧键如何被读取；一旦把 instructionFiles 设为非默认值，旧键不再被读，转录提示移除。

平台限制：changelog 原文注明 not yet on Bedrock, Vertex or Foundry。另外在引擎本来就不加载指令文件的运行方式下（不带 --add-dir 的 --bare、--safe-mode、设置 CLAUDE_CODE_DISABLE_CLAUDE_MDS），插件的遍历同样一无所获——CLAUDE.md 与 AGENTS.md 一样不会加载。

8. 观测、遥测与测试

插件只记计数与封闭选项，不记路径与文件内容，且都经过 telemetry 插件（没装该插件时调用被静默丢弃）：agents_md_mode 每次新加载记一条（模式与是否交互式）；agents_md_load 在默认与 both 模式下的首个上下文记一条（交给引擎的文件数、@ 引用数、总内容长度、是否因项目有自己的 CLAUDE.md 而让位、遍历是否失败），并打一个 agents_md 特性标记；agents_md_nested 在有 Read 触发嵌套附着时记一条。

测试入口：claude plugin test mods/agents-md。仓库自带的测试覆盖默认模式的四个场景——只有 AGENTS.md 的项目拿到它并有一行点名转录、有自己的 CLAUDE.md 的项目不做遍历、遍历失败时上下文保持原样、telemetry 名词在座与不在座时启动都不受影响。

9. 对 Codex 用户意味着什么（本站观察）

以下是本站基于上述可核实事实的观察，不是官方口径：

• 一份文件、两家生态。AGENTS.md 官方支持列表里的 Codex 与新加入的 Claude Code，恰好是命令行编程智能体里两家最大生态的旗舰。同一仓库的同一份指令文件现在可以同时服务两边——本站 8 月的工具对比文曾把 AGENTS.md 列为 Codex 的差异化协作入口，这个表述从 2026-09-18 起需要加上『Claude Code 也读了』的脚注。
• 格式没变，加载语义各自实现。AGENTS.md 仍是那份『给智能体看的 README』；本文列出的回退判定、嵌套附着、八项差异都是 Claude Code 侧的实现语义。Codex 侧怎么读这份文件，以 Codex 自己的文档与行为为准——本篇不跨工具对比加载细节。
• 配置面上，默认值偏向不惊扰：有 CLAUDE.md 的存量项目一行都不用改；想让 AGENTS.md 无条件生效，才需要动 /config。

10. 常见问题与排查

• 设了 AGENTS.md 没生效：先看项目里是否有自己的 CLAUDE.md（含 .claude/CLAUDE.md 与 CLAUDE.local.md）——默认模式下插件会让位；再确认改动发生在『下一个上下文』之前（改完设置要等重载后的下一轮或新会话）；还要排除 --bare / --safe-mode / CLAUDE_CODE_DISABLE_CLAUDE_MDS 这类引擎本就不加载指令文件的运行方式。
• 把配置写进了项目 .claude/settings.json 却无效：插件选项不读取项目级设置，放到用户设置、--settings 或托管设置里。
• 嵌套 AGENTS.md 没有附着：触发条件是 Read 工具以文本方式读到该目录下的文件；@ 提及、IDE 打开、notebook / 图片 / PDF 读取不触发（八项差异第一条）；同目录若有 CLAUDE.md，它优先。
• 转录里出现旧键读取说明：说明设置里还存着 projectInstructions，按第 7 节的映射理解；切到新键的非默认值后把旧键删掉。
• stable 通道没拿到功能：截至 2026-09-22，npm stable dist-tag 停在 2.1.267，latest 是 2.1.278；功能自 2.1.277 起。

11. 下一步

• Codex CLI vs Cursor vs Aider vs Claude Code：四大 AI 编程工具选型对比（2026）——AGENTS.md 所在的工具格局全景，含四工具的 git / CI 适配对比；
• OpenAI Codex CLI 入门：从零配置到日常编码流——Codex 侧怎么用项目指令与 worktree 工作流；
• GPT-6-Astra 落地：进入 Codex 模型选择器与 Amazon Bedrock 目录——Codex 侧模型面的最新变化。