Claude Code 现在会读 AGENTS.md 了——但五种常见配置，仍会让它读不到

更新（2026 年 10 月 4 日）：stable 渠道已经跟上。 原生安装器、npm 和 Homebrew 默认安装包的 stable 渠道现在都会安装 2.1.285，已包含 AGENTS.md 原生支持，也不再要求开启遥测。你使用的 stable 版本更新后，下文第 4 种情形「stable 发布渠道和 Homebrew 默认安装」就不再适用（通过 Homebrew 安装的版本仍需运行 brew upgrade 更新）。其余四种情形不变。

30 秒看懂结论

9 月 18 日，Claude Code 2.1.277 开始原生读取 AGENTS.md。这份共享指令文件，Codex、Cursor 和许多其他编程代理早就在读了。此前，Anthropic 关闭了要求支持它的最高赞请求，给出的解决办法只是桥接。过了 32 天，原生支持才真正上线。争议的来龙去脉见我们 8 月的报道。

不过，默认行为只是回退，不是合并。只有工作目录及其所有上级目录里都没有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时，Claude Code 才会读取 AGENTS.md。

我们一共跑了 108 次无界面会话（claude -p）：30 种配置全部在当时的最新版 Claude Code 2.1.283 上测试，其中 6 种又在 2.1.280 上重跑。每次都以会话记录（transcript）中的加载记录为准。在同一版本上，每种配置重复运行 3 次，结果都一致。

• 项目里只有 AGENTS.md 时，会正常加载。只有 .claude/AGENTS.md 时也一样。从子目录启动会话，也能读到根目录的 AGENTS.md。
• 五种很常见的配置会让它读不到：个人的 CLAUDE.local.md、任何上级目录里的 CLAUDE.md、根目录有 CLAUDE.md 时子包里的 AGENTS.md、仍停在 2.1.274 的 stable 发布渠道，以及关闭遥测的 2.1.277 到 2.1.280。前三种在 2.1.283 上复现，最后一种在 2.1.280 上复现。stable 那种是按版本号推断的。
• 本周流传的「必须打开遥测」，已在 9 月 23 日发布的 2.1.281 中失效。我们分别设置了四个会阻止获取远程功能开关的环境变量。在 2.1.280 上，每个变量都会让 AGENTS.md 在 3/3 次运行中无法加载；在 2.1.283 上，四个变量都没有阻止加载。
• 保留一个只含 @AGENTS.md 的 CLAUDE.md，就能用一行导入完成桥接。我们在七种配置、两个版本上共跑了 21 次，每次都加载了它指定的文件，而且没有重复加载。在单体仓库（monorepo）里，根目录的桥接文件只管根目录那一份，每个子包都需要自己的桥接文件。

结论：保留这一行导入。只有团队所有人都使用 2.1.281 或之后的版本，而且每个人的工作目录及其所有上级目录里都没有 CLAUDE.md 类文件，才适合完全依赖原生支持。导入不受这两个条件限制。

我们怎么测的

每次运行都从一个新目录开始：先用 git init 初始化，再按待测配置写入指令文件。我们使用干净的环境，关闭自己安装的插件和 MCP 服务器，以无界面模式启动 Claude Code，模型选择 Claude Haiku 4.5。每份指令文件里都放了不同的口令，再让模型列出它收到的口令。

模型的回答只用来做第二道核对。判断文件究竟有没有加载，依据的是 Claude Code 写入 ~/.claude/projects/ 下的 .jsonl 会话记录文件。启动时加载的文件记在 instructions 条目里，包含每份文件的路径和内容；子目录里的文件，则在 Claude 打开该目录中的文件后另记一条。108/108 次运行中，模型回答都与这些记录一致，任何文件都没有在同一会话中出现两次。

30 种配置全部在 2.1.283 上跑过，共 90 次运行。其中 6 种又在遥测问题修复前的最后一个版本 2.1.280 上重跑，共 18 次运行。每种配置在每个受测版本上都重复 3 次。测试于 9 月 26 日在 macOS 上完成，总运行时间 402 秒，费用 $2.04。我们没有运行 2.1.274，也没有运行 2.1.277 到 2.1.279；文中涉及这些版本的说法，依据的是 Anthropic 的发布说明和文档。

默认规则：只是回退，不是合并

以下结果来自使用默认设置的 Claude Code 2.1.283：

这些结果与 Anthropic 文档描述的规则一致。检查范围从工作目录一直向上，直到文件系统的顶层。不过，有三类文件不参与这个判断，也不会妨碍 AGENTS.md 加载：个人的 ~/.claude/CLAUDE.md、组织的托管 CLAUDE.md，以及 .claude/rules/ 下的文件。它们会照常加载。

子目录的 AGENTS.md 不会在会话启动时就被读取。只有 Claude 第一次用 Read 工具打开该目录中的文件时，才会加载它。前提是回退仍然生效，而且这个子目录里也没有自己的 CLAUDE.md 类文件。

这个变化也影响了安全边界。在 2.1.277 或之后的版本中，默认设置下只要没有 CLAUDE.md 类文件挡住回退，仓库里的 AGENTS.md 就会在启动时进入 Claude 的上下文，和过去的 CLAUDE.md 一样。我们关于攻击面的文章讨论了启动时加载文件会带来哪些安全影响。

五种常见配置，会让它读不到

读不到时，没有任何提示。我们跑的无界面会话里，加载成功和未加载这两种情况都没有任何提示。交互式会话的情况来自官方文档和问题报告：Anthropic 文档说，成功加载 AGENTS.md 时会显示一行提示，内容是 AGENTS.md loaded: 加上文件路径；issue #95690、#95589 和 #96117 则都报告，跳过文件时没有任何提示。我们没有测试交互式会话。 要可靠地确认加载情况，应使用下文介绍的 /memory。

1. 个人的 CLAUDE.local.md

CLAUDE.local.md 通常用来保存开发者自己的指令，不提交到 git。它也算 CLAUDE.md 类文件。因此，只要某位开发者加了这份文件，这位开发者的会话就不再读取团队的 AGENTS.md。队友的会话仍然正常加载，便可能只有这一个人的结果变了。

Anthropic 文档明确说这是预期行为：在依赖共享指令的项目里，新增一份不提交到仓库的个人指令，会让当前开发者的会话停止读取共享指令（原文：“Because CLAUDE.local.md counts, adding one to keep your own uncommitted instructions in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you.”）。目前仍未关闭的 issue #96117，要求 Anthropic 不再把 CLAUDE.local.md 纳入这个判断。

2. 任何上级目录里的 CLAUDE.md

默认设置下，上级目录里只要有一个 CLAUDE.md，从它下方任何目录启动的会话就都不会读取 AGENTS.md。这个上级目录是否位于当前 git 仓库内，没有区别；仓库内、仓库外两种配置都是各 3/3 次复现。

举两个例子：monorepo 根目录里的 CLAUDE.md，以及留在用户主目录中的同名文件。要留意，享有例外的是 ~/.claude/CLAUDE.md；~/CLAUDE.md 照样会阻止回退。

3. 根目录有 CLAUDE.md，子包有自己的 AGENTS.md

在 monorepo 中，只要根目录有 CLAUDE.md，默认设置下子包自己的 AGENTS.md 就不会加载。从子包启动 Claude 是这样，从根目录启动后让 Claude 打开子包里的文件也是这样，两种配置都是各 3/3 次复现。

即使根目录的 CLAUDE.md 只负责导入根目录的 AGENTS.md，也一样。导入能带进根目录那份文件，子包那份仍然读不到，结果为 3/3。Codex 的行为不同：如果从子包启动，它会从仓库根目录一路向下查找到启动目录，因此能读到子包的 AGENTS.md。

4. stable 发布渠道和 Homebrew 默认安装

Claude Code 有两个发布渠道。Anthropic 对 stable 的说明是：通常比最新版晚约一周，并跳过有严重回归问题的版本；latest 则会在每个新版本发布时跟进。

截至 9 月 26 日，无论使用原生安装器、npm，还是 Homebrew 默认的 claude-code 安装包，stable 对应的都是 2.1.274。这个版本发布时，还没有 AGENTS.md 原生支持。Homebrew 安装的版本也不会自行更新。因此，使用 stable 渠道或 Homebrew 默认安装的团队，只能通过导入读取 AGENTS.md。这一条是按版本号推断的，我们没有实测这个版本。 用 claude --version 可以确认实际版本。如果 stable 下次更新到 2.1.277 至 2.1.280，仍然会遇到下面的遥测问题。

5. 在 2.1.277–2.1.280 上关闭遥测

在 2.1.281 之前，不获取 Anthropic 远程功能开关的会话不会启用原生支持。我们在 2.1.280 上分别设置上述四个环境变量，都复现了这个问题。根据 2.1.281 的发布说明，Amazon Bedrock、Google Vertex AI、Microsoft Foundry 和大模型网关此前也受影响。这些环境我们没有实测。在 9 月 25 日之前，2.1.277 的更新日志却只列出了 Bedrock、Vertex 和 Foundry 三种例外；遥测导致无法加载的问题，已有用户在 9 月 20 日提交的 issue #95690 中报告。

9 月 23 日发布的 2.1.281 修复了这个问题。我们对比了两个二进制文件：内置插件是否默认开启的值，在 2.1.280 中是 false，在 2.1.283 中变成了 true。两版都仍然会查询远程功能开关，只是使用的默认值不同。 因此，本周那些建议重新打开遥测的文章，对 2.1.281 及之后的版本已经不适用。还在用旧版的话，可以升级，也可以使用一行导入；我们测试的两个版本都能在关闭遥测时通过导入加载文件。

Anthropic 文档还列出了两种仍可能读不到的情况。一种是在 /plugin 中关闭了内置的 agents-md 插件。另一种是从 2.1.276 或更早的版本升级后，第一次会话可能漏读，直到下一次会话才加载。升级后第一次会话的情况我们没有测试，依据的是官方文档。

同时读两个文件，设置放在哪里

如果想把 Claude 专属说明留在 CLAUDE.md，共享规则放在 AGENTS.md，又不使用导入，可以在 /config 中调整 Project instructions（项目指令）。它有四个取值：

在 2.1.283 上，我们用 claude-md-and-agents-md 测了所有准备好的混合配置，两类文件都能加载。具体包括：CLAUDE.md 与 AGENTS.md 同时存在，CLAUDE.local.md 与 AGENTS.md 同时存在，上级目录有 CLAUDE.md、项目里有 AGENTS.md，以及根目录有 CLAUDE.md、子包里有 AGENTS.md。最后一种配置中，子包文件是在 Claude 打开该目录中的文件后加载的。四种配置都是各 3/3 次成功，覆盖了前文第 1 到第 3 种问题。

但这个设置放在哪里，决定了它会不会生效。有效的位置只有用户设置（~/.claude/settings.json）、通过 --settings 指定的文件，以及托管设置（managed settings）。写在项目的 .claude/settings.json 里会被忽略。我们实测了这个位置，3 次运行都只加载了 CLAUDE.md。

因此，把配置提交到仓库，并不能替整个团队开启。需要每位开发者自行设置，或者由管理员通过托管设置统一下发。配置写在内置插件的标识符下面：

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

保留这一行导入

原生支持出现之前，Anthropic 文档给出的办法就是保留一个 CLAUDE.md，里面只写 @AGENTS.md。这就是桥接文件。我们把它放进多种配置，结果都如预期：

• 21 次运行，始终能加载它导入的文件。 测试覆盖默认设置、claude-md-and-agents-md、2.1.280 和 2.1.283 上关闭遥测、同目录存在 CLAUDE.local.md，以及两种 monorepo 目录布局。
• 从未重复加载 AGENTS.md。 桥接文件本身属于 CLAUDE.md，所以默认回退不会启动；使用 claude-md-and-agents-md 时，Claude Code 也会跳过已经读过的 AGENTS.md。把 CLAUDE.md 做成指向 AGENTS.md 的软链接，结果相同。
• 2.1.277 之前的版本也能用。 当前 stable 发布渠道安装的就是更早的版本。
• 导入下面还能继续写 Claude 专属指令。

它有一个明确的边界：一行导入只管它指定的那一个文件。在 monorepo 里，每个子包都要有自己的单行 CLAUDE.md。我们在 sub/ 放入这样一个桥接文件后，Claude 一打开该目录中的文件，子包的 AGENTS.md 就会加载，结果为 3/3。

文档还列出了一处差异，导入在这里更合适：通过导入加载 AGENTS.md 会触发 InstructionsLoaded 钩子，原生读取则不会。

确认 Claude 已经能够读取 AGENTS.md 后，就该清理两种旧办法了。文档提醒，如果 SessionStart 钩子还在输出 AGENTS.md 的内容，而 Claude Code 自己也会读取，就会多出一份副本。另外，在 CLAUDE.md 里用自然语言要求 Claude 去读 AGENTS.md，是否奏效取决于模型会不会决定打开文件。把这句话换成真正的 @AGENTS.md 导入即可。

Codex 读取的文件不一样

共用一份 AGENTS.md，并不代表两个代理最终拿到的指令相同：

• 覆盖文件。 Codex 会检查自己的主目录，默认是 ~/.codex，还会检查从项目根目录到启动目录之间的每一级目录。在每个目录里，只要 AGENTS.override.md 非空，就会优先读取它，而不是 AGENTS.md。Claude Code 不会自动加载覆盖文件，实测加载次数为 0/3。
• 查找范围。 Codex 先检查自己的主目录，再从项目根目录（通常是 git 仓库根目录）向下查找到启动目录。Claude Code 则从启动目录一路向上查找，即使超出仓库边界也会继续；子目录里的指令文件，要等它打开该目录中的文件后才会读取。
• 大小限制。 Codex 加入上下文的指令文件累计达到 32 KiB 后，就会停止添加。这是 project_doc_max_bytes 的默认值。
• 技能（skills）。 Shopify 的首席执行官在 8 月要求支持的有两项：AGENTS.md 和 .agents/skills。AGENTS.md 已经获得原生支持。Claude Code 的技能文档没有提到 .agents/skills，它的 AGENTS.md 文档还明确说不会读取 .agents/ 下的内容。我们没有测试放在该目录中的技能。

怎么确认加载了什么

先运行 claude --version。原生支持要求 2.1.277 或之后的版本；关闭遥测时，则要到 2.1.281 或之后的版本。

在交互式会话中，运行 /memory，查看是否列出了 AGENTS.md 的路径。这个检查方法要求 2.1.280 或之后的版本，更早的版本不会列出通过原生回退加载的 AGENTS.md。

无界面会话或持续集成环境中，可以像我们一样检查会话记录：

sid=$(claude -p "ok" --output-format json | jq -r .session_id)
jq -r 'select(.attachment.type? == "instructions") | .attachment.files[] | "\(.type)\t\(.path)"' \
  ~/.claude/projects/*/"$sid".jsonl

这段命令会为启动时加载的每份文件输出一行，例如 Project /repo/AGENTS.md。子目录中的 AGENTS.md 会在 Claude 打开该目录中的文件后另行记录，因此不会出现在这段命令的输出里。会话记录格式没有官方文档，今后可能变化；/memory 才是官方支持的检查方式。

哪些情况我们没有测

• 2.1.274、2.1.277 到 2.1.279，以及 Bedrock、Vertex、Foundry 和网关。 涉及这些版本和环境的说法，依据的是 Anthropic 的发布说明和文档。
• 交互式会话和后台会话。 issue #95589 报告，在 2.1.278 上，AGENTS.md 有时能在交互式会话中加载，有时不能。我们的无界面会话结果一致，每种配置的 3 次运行都得到了相同结果。
• Windows，以及升级后的第一次会话。 我们只测了 macOS 上的无界面会话。
• 模型是否遵守指令。 我们只验证了文件有没有加载，没有比较原生读取和导入两种方式下，Claude 遵守指令的程度。

相关阅读

• CLAUDE.md vs AGENTS.md：Claude Code 到底读哪个？：快速回答常见问题，已补充原生支持的最新规则。
• Shopify CEO 因 AGENTS.md 考虑禁用 Claude Code：桥接明明能用，争议为何还没结束：8 月的争议经过，以及我们当时在 2.1.243 上验证过的桥接方式。
• AGENTS.md 模板：精简的起步文件和一行导入。
• Anthropic 删掉 Claude Code 80% 的系统提示词后效果更好：这对你的 CLAUDE.md 意味着什么：指令文件会改变哪些代理表现，又有哪些改变不了。
• CLAUDE.md 已经成了攻击面：Miasma 蠕虫证明了什么：启动时加载的文件为什么与安全有关，如今 AGENTS.md 也在其中。

来源

1. Anthropic：管理 Claude 的记忆：AGENTS.md。说明默认规则、哪些文件参与判断、Project instructions 的四个取值、设置在哪些位置会被忽略、哪些文件不会读取，以及原生加载与导入的区别。上文关于 CLAUDE.local.md 的引语也出自这里。
2. Anthropic：Claude Code 更新日志。2.1.277 加入 AGENTS.md 支持。在 9 月 25 日之前，该条目还注明尚不支持 Bedrock、Vertex 和 Foundry（原文：“(not yet on Bedrock, Vertex or Foundry)”）。2.1.281 将支持范围扩展到 Bedrock、Vertex、Foundry、大模型网关，以及关闭遥测的会话。
3. Anthropic：环境变量。说明哪些变量会阻止获取远程功能开关，以及安装或升级后第一次会话的情况。
4. Anthropic：安装与配置 Claude Code。介绍 latest、stable 两个发布渠道，以及 Homebrew 的两种安装包。
5. npm：@anthropic-ai/claude-code。记录发布时间：2.1.277 为 9 月 18 日，2.1.281 为 9 月 23 日。9 月 26 日的发布标签分别指向 stable 2.1.274、latest 2.1.283。原生安装器的渠道文件 stable 和 latest，返回的也是这两个版本。
6. Homebrew：claude-code 和 claude-code@latest。9 月 26 日分别对应 2.1.274 和 2.1.283。
7. GitHub：issue #95690。9 月 20 日提交，报告 AGENTS.md 支持受到远程功能开关控制。
8. GitHub：issue #96117。9 月 22 日提交，报告 CLAUDE.local.md 会关闭回退，尚未关闭。
9. GitHub：issue #95589。报告 2.1.278 的交互式会话有时会加载、有时不会加载，尚未关闭。
10. OpenAI：Codex：AGENTS.md。介绍覆盖文件、Codex 的查找范围，以及默认的 32 KiB 上限。
11. blog.szypowi.cz：Claude Code 只有打开遥测才读取 AGENTS.md，9 月 23 日发布。这一说法适用于 2.1.277 到 2.1.280。
12. DEV Community：Claude Code 的 AGENTS.md 支持需要打开遥测，9 月 26 日发布，此时 2.1.281 已经发布 3 天。

我们自己的测量：2026 年 9 月 26 日，在 macOS 上使用 Claude Haiku 4.5，共运行 108 次 claude -p 会话。30 种配置全部在 Claude Code 2.1.283 上测试，其中 6 种又在 2.1.280 上重跑，每种配置在每个受测版本上各运行 3 次。启动时加载的文件依据会话记录中的 instructions 条目，子目录文件则依据 Claude 打开该目录中的文件后写入的条目。模型回答与记录的核对结果为 108/108 一致，任何文件都没有在同一会话中出现两次。总费用 $2.04。默认开启值的对比，来自两个版本二进制文件中打包的 agents-md 插件。

FAQ

Claude Code 现在会读 AGENTS.md 吗？ 会，从 9 月 18 日发布的 2.1.277 起支持，但默认只是回退。只有工作目录及其所有上级目录里都没有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时，才会读取 AGENTS.md。我们在 2.1.283 上测试时，两个文件同时存在且使用默认设置，加载的就只有 CLAUDE.md。

为什么我的 AGENTS.md 没有被加载？ 检查项目里是否有 CLAUDE.local.md、上级目录里是否有 CLAUDE.md，以及当前子包上方的仓库根目录是否有 CLAUDE.md。另外两种常见原因是使用 stable 渠道或 Homebrew 默认的安装包（2.1.274），以及在 2.1.277 到 2.1.280 上关闭了遥测。再运行 claude --version 和 /memory 确认。

读取 AGENTS.md 还需要打开遥测吗？ 9 月 23 日发布的 2.1.281 起，不再需要。在 2.1.280 上，我们分别设置四个会阻止获取远程功能开关的变量，每种配置都在 3/3 次运行中阻止了加载；到了 2.1.283，四种配置都能加载。

可以删掉导入 AGENTS.md 的桥接文件吗？ 可以，但建议保留。它在 21 次运行中都加载了所导入的文件，而且从未重复加载。删除前，先用 /memory 确认团队实际使用的版本和设置加载了什么。在 monorepo 中，每个子包都需要自己的桥接文件。

怎样同时加载 CLAUDE.md 和 AGENTS.md？ 在 /config 中把 Project instructions 设为 claude-md-and-agents-md，或写入用户设置。项目的 .claude/settings.json 不能启用这项设置。

Claude Code 会像 Codex 一样读取 AGENTS.override.md 吗？ 不会自动读取，而 Codex 会优先读取它。AGENTS.local.md 和 .agents/ 下的内容也都不会加载。