Claude Code AGENTS.md 配置指南：四种加载模式、与 CLAUDE.md 的区别、多工具共用

Name

Soren Atelier

更新于 2026/9/21

先说结论： 自 Claude Code v2.1.277（2026 年 9 月 18 日）起，如果仓库里有 AGENTS.md，而且路径上任何位置都没有 CLAUDE.md，Claude Code 会自动从 AGENTS.md 读取指令。不用安装任何东西，不用写 import 行，也不用建符号链接。如果工作目录或任一上级目录中存在 CLAUDE.md 或 CLAUDE.local.md，Claude Code 仍然只读那个文件并忽略 AGENTS.md，除非你在 /config 里修改 Project instructions 设置。

十秒钟就能验证。在一个只有 AGENTS.md 的仓库里开启新会话，在对话顶部附近找这一行：

no CLAUDE.md found; AGENTS.md loaded: /path/to/repo/AGENTS.md

如果没看到，说明下面四种情况之一成立，本文都会覆盖：你的版本较旧；某个上级目录里藏着 CLAUDE.md 或 CLAUDE.local.md；这是你升级后的第一个会话；或者你的会话类型根本无法加载 AGENTS.md（Bedrock、Vertex、Foundry，或关闭了遥测）。

下文标注实测的内容，都是 2026 年 9 月 21 日在 macOS 上用 Claude Code 2.1.278、在一个全新的临时仓库里通过 claude -p 跑出来的。其余内容来自官方 memory 文档 (opens in a new tab)和更新日志 (opens in a new tab)。

到底改了什么

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)

大意：新增 AGENTS.md 支持；在没有 CLAUDE.md 的项目中，Claude Code 改为读取 AGENTS.md；可在 /config 的 “Project instructions” 下修改（Bedrock、Vertex、Foundry 暂不支持）。

在这个版本之前，已经为 Codex、OpenCode、Cursor 等工具统一采用 AGENTS.md (opens in a new tab) 的团队，还得在旁边再放一个 CLAUDE.md：要么是一份重复内容，要么是一行 @AGENTS.md import，要么是一个符号链接。这次发布在 Hacker News 的讨论帖 (opens in a new tab)（725 分，273 条评论）里，大部分人都在描述自己此前一直维护的是哪一种变通方案。

这次发布并没有让 AGENTS.md 与 CLAUDE.md 平起平坐。它加的是一个带开关的回退机制。本文接下来讲的，就是回退在哪里止步、开关在什么时候起作用。

哪个文件优先：决策表

这是默认行为，即 claude-md-or-agents-md 模式。“存在 CLAUDE.md” 的判断范围包括工作目录及其所有上级目录中的 CLAUDE.md、.claude/CLAUDE.md 和 CLAUDE.local.md。你个人的 ~/.claude/CLAUDE.md、组织下发的托管 CLAUDE.md，以及 .claude/rules/ 下的文件不计入判断，它们会和 AGENTS.md 一起继续加载。

第三行是大多数人最先踩到的坑。CLAUDE.local.md 是文档规定的个人、不提交指令的存放位置。在一个依赖 AGENTS.md 的项目里加上它，Claude 就会悄悄切回忽略 AGENTS.md 的状态。修复只需一个设置，下一节讲。

我是怎么测的

临时仓库里的每个 AGENTS.md 或 CLAUDE.md 只包含一条指令：每次回复都以固定标记开头，例如 [AGENTS_MD_LOADED]。然后：

mkdir agentsmd-test && cd agentsmd-test && git init -q
printf '# AGENTS.md\n\nAlways begin your reply with the exact token [AGENTS_MD_LOADED].\n' > AGENTS.md
claude -p "What is 2+2? Answer in five words or fewer." < /dev/null

回复以 [AGENTS_MD_LOADED] 开头，说明文件被加载了；只回一个 4.，说明没有。这比 /context 粗糙，但 /context 和 /memory 都不会列出直接加载的 AGENTS.md（见下文的差异表），所以标记法是对两种文件都有效的那一种。

Project instructions 的四种模式

在会话中打开 /config 设置 Project instructions，或者在 ~/.claude/settings.json 里内置的 agents-md 插件下设置同一个值。Claude Code 会忽略项目级和本地设置文件中的这个键，所以它不能提交进仓库；这是按用户或由组织托管的选择。

设置文件写法：

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

实测： 在同时包含两个文件的仓库里，通过 --settings both.json 传入上面这段 JSON，回复以 [CLAUDE_MD_LOADED] [AGENTS_MD_LOADED] 开头，顺序正是如此。在只有 AGENTS.md 的仓库里传入 "instructionFiles": "claude-md"，回复只有一个 4.，说明文件按文档所述被忽略了。

为什么升级后的第一个会话不生效

这一点让我多跑了两轮测试。文档说，“安装或升级后的第一个会话” 不支持该功能，Claude 会 “从下一个会话开始” 读取 AGENTS.md。

实测： 全新安装 2.1.278，在只有 AGENTS.md 的仓库里，第一次 claude -p 忽略了这个文件，第二次也是，第三次才加载。非交互式的 -p 运行很短，所以控制 AGENTS.md 支持的功能开关可能在第二次运行开始时还没拉取到。实用规则：升级后先开一个一次性会话，关掉，然后再判断 AGENTS.md 有没有被读取。

按文档，以下会话完全无法加载 AGENTS.md：

• Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry
• 关闭了遥测，因为无法拉取功能开关
• 设置了 disableAllHooks 或 allowManagedHooksOnly，或在 /plugin 中禁用了内置的 agents-md 插件
• 安装或升级后的第一个会话，如上所述

在这些情况下，/config 里根本不会出现 Project instructions，这是最快的判断方法。这些会话的替代方案是下一节介绍的 import。

直接加载的 AGENTS.md 与 CLAUDE.md 有何不同

通过该设置读取的 AGENTS.md 并不能原样替代 CLAUDE.md。文档列出了三处可见差异：

子目录中的 AGENTS.md 按需加载：当 Claude 用 Read 工具打开该目录下的文件、且该目录本身没有 CLAUDE.md 时加载。AGENTS.md 内部的 @path import 会被展开，claudeMdExcludes 的匹配规则同样对它生效。

迁移：现有的变通方案怎么处理

如果你在 2.1.277 之前就配置过 AGENTS.md 的读取方式，下面是文档针对每种配置给出的指引，以及我对何时该动手的理解。

• 只包含 @AGENTS.md 的 CLAUDE.md：如果你使用的每种会话都支持新行为，可以删掉。如果团队里有人通过 Bedrock、Vertex 或 Foundry 工作，就保留，因为那些环境仍然需要 import。保留它不会导致重复读取。
• 用文字写着 “请阅读 AGENTS.md” 的 CLAUDE.md：把那句话换成 @AGENTS.md，或者删掉文件。文字描述只有在 Claude 决定去打开文件时才起作用；import 是确定性的。
• 符号链接到 AGENTS.md 的 CLAUDE.md：两种方式都能用，但 Edit 和 Write 工具拒绝通过符号链接写入，会重定向到目标文件。在 Windows 上，除非开启了 core.symlinks，否则提交的符号链接检出后会变成一个单行文本文件，所以那里更适合用 import。
• 通过 SessionStart 钩子打印 AGENTS.md：删掉。一旦 Claude 直接读取 AGENTS.md，这个钩子就会往上下文里注入第二份副本。
• 两个文件内容不同：先决定 Claude 专用的部分是否值得单独成文件。值得的话，用 AGENTS.md 放共享规则，用一份简短的 CLAUDE.md 放 Claude 专用规则，并设置 claude-md-and-agents-md 让两者都加载。不值得的话，合并进 AGENTS.md 并删除 CLAUDE.md。

对于必须保留 CLAUDE.md 的仓库，文档还推荐了这种共享写法：

@AGENTS.md
 
# Claude-specific
- Use the `Bash` tool for git; do not call the GitHub MCP for pushes.

Claude 先读 import，再读 Claude 专用的几行。

其他工具各自读什么

统一采用 AGENTS.md 的意义在于一份文件服务所有 agent。下面是各工具根据当前文档对它的实际处理方式。

对共享文件来说有两个后果：

1. Codex 完全不读 CLAUDE.md，所以只写在那里的内容对 Codex 不可见。如果你在同一个仓库里用两个文件同时跑 Codex 和 Claude Code，AGENTS.md 是两者唯一都能看到的文件。
2. OpenCode 只在没有 AGENTS.md 时才读 CLAUDE.md，正好和 Claude Code 的默认行为相反。在同时有两个文件的仓库里，Claude Code 读 CLAUDE.md，OpenCode 读 AGENTS.md。如果两个文件内容不一致，两个 agent 会各自遵循不同的规则，而且都不会提醒你。

因此多工具仓库的安全终态是：一份放共享规则的 AGENTS.md；除非有 Claude 专用规则，否则不放 CLAUDE.md；如果确实需要，就让 CLAUDE.md 以 @AGENTS.md 开头。

按场景推荐的配置

排查：AGENTS.md 没有加载

按顺序逐条检查；每一条要么在上文复现过，要么是文档明确指出的原因。

1. 运行 claude --version。 需要 2.1.277 或更高版本。版本较旧就用 claude update 更新。
2. 搜索每一级上级目录，查找 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md：

d="$PWD"; while [ "$d" != "/" ]; do for f in CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md; do [ -f "$d/$f" ] && echo "blocks AGENTS.md: $d/$f"; done; d=$(dirname "$d"); done

除 ~/.claude/CLAUDE.md 之外的任何命中，都意味着 Claude 读的是那个文件，除非你切换到 claude-md-and-agents-md。

3. 刚升级的话，再开一个会话。 在我的测试中，第三次运行才首次加载文件。
4. 打开 /config，确认 Project instructions 不是 claude-md 或 managed-only。如果这个设置完全不存在，说明你的会话类型无法加载 AGENTS.md；改用 @AGENTS.md import。
5. 不要依赖 /memory 或 /context 来确认。 直接加载的 AGENTS.md 不会列在那里。请找 AGENTS.md loaded 那一行，或者让 Claude 复述它的项目指令。

常见问题

Claude Code 默认会读取 AGENTS.md 吗？

会，从 v2.1.277 起，但前提是工作目录及其所有上级目录中都没有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md。只要存在其中之一，Claude Code 就读取它并忽略 AGENTS.md，除非你把 Project instructions 设为 claude-md-and-agents-md。

能让 Claude Code 同时读取 CLAUDE.md 和 AGENTS.md 吗？

能。在 /config 中把 Project instructions 设为 claude-md-and-agents-md，或者在 ~/.claude/settings.json 的 pluginConfigs → agents-md@builtin → options.instructionFiles 下设置。每个目录先加载 CLAUDE.md，再加载 AGENTS.md。已经从 CLAUDE.md import 的文件不会被读两次。

为什么刚更新完 Claude Code，AGENTS.md 就是不加载？

安装或升级后的第一个会话无法读取 AGENTS.md，支持从之后的会话开始。用 claude -p 测试时，第三次运行才首次加载。先开一个一次性会话再关掉，然后重新检查。

已经有 AGENTS.md 了，要不要删掉 CLAUDE.md？

如果 CLAUDE.md 只包含 @AGENTS.md，而且团队里没人用 Bedrock、Vertex 或 Foundry，可以删掉。如果它包含 Claude 专用规则，就保留，并把 @AGENTS.md 放在第一行，这样在任何环境下两者都会加载。

Codex 会读取 CLAUDE.md 吗？

不会。Codex 从仓库根目录向下到工作目录，逐目录读取 AGENTS.override.md 或 AGENTS.md，再加上 ~/.codex/AGENTS.md，回退文件名可在 config.toml 中配置。只存在于 CLAUDE.md 里的内容对 Codex 不可见。

相关指南

• Codex 使用指南
• OpenCode 使用指南：安装、配置，以及何时搭配 Oh My OpenCode
• Claude Code 绕过权限：桌面端开关、CLI 参数与报错修复
• Claude Code Routines 使用指南
• DeepSeek Harness 安装教程