Claude Code 读取 AGENTS.md：原生支持的正确配置方式

如何让 Claude Code 读取 AGENTS.md

按下面的顺序操作：

1. 运行 claude --version，版本必须是 v2.1.277 或更高。
2. 版本不够就先更新。原生安装可运行 claude update；Homebrew 和 WinGet 则使用各自包管理器的升级命令。
3. 确认当前会话能够获取 Anthropic 功能开关。通过 Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 等第三方服务提供商运行的会话无法原生加载 AGENTS.md；如果遥测或非必要流量设置阻止获取功能开关，同样无法使用。
4. 将 AGENTS.md 或 .claude/AGENTS.md 放到项目路径中。使用默认模式时，还要确认工作目录及其上级目录不存在项目级 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md。
5. 如果两套文件都需要加载，打开 /config，把 Project instructions 设为 claude-md-and-agents-md。
6. 在全新会话中测试。安装或升级后的第一个会话属于例外情况，不要急着下结论，再新建一个会话验证。

这就是原生加载方案。如果 /config 中没有 Project instructions，请继续在 CLAUDE.md 中使用已有的 @AGENTS.md 导入方式。

Claude Code 到底会选择哪个文件

新机制更像一套路由开关，并不是把所有指令文件统统扫描一遍。在默认的 claude-md-or-agents-md 模式下，Claude Code 会先查找项目级 Claude 指令；只有工作目录及其上级目录都没有符合条件的 Claude 文件时，才回退到 AGENTS.md。

最容易被忽略的是作用域：上级目录中的 CLAUDE.local.md 会阻止回退；个人的 ~/.claude/CLAUDE.md、组织托管的 CLAUDE.md 和 .claude/rules/ 则不会。这一区别，正是两名开发者打开同一个代码库却得到不同结果的常见原因。

满足回退条件时，Claude Code 会在会话启动时读取工作目录及其上级目录中的 AGENTS.md 和 .claude/AGENTS.md。当 Claude 之后读取某个子目录里的文件时，该目录的 AGENTS.md 也可能随之加载，前提是这个子目录没有自己符合条件的 Claude 文件。它不会直接读取 AGENTS.local.md、AGENTS.override.md，也不会读取 .agents/ 下的文件。

与其把它理解成文件夹搜索，不如把它看作建筑中的电路选择器：系统先决定哪条指令回路通电。另一条回路上的文件即使完全有效，也仍可能处于断开状态。

明确设置 Project instructions 模式

打开 /config，找到 Project instructions，再根据代码库希望采用的指令来源进行选择：

• 回退模式，claude-md-or-agents-md：适合已经使用 AGENTS.md、且不存在项目级 Claude 文件的代码库。这也是默认选项。
• 两者同时加载，claude-md-and-agents-md：适合用 AGENTS.md 存放共享规则、用 CLAUDE.md 补充 Claude 专属说明的项目。
• 仅 Claude，claude-md：适合尚未准备好向 Claude Code 开放共享智能体指令的团队。
• 仅托管内容，managed-only：适合受控的启动环境；启动时加载组织策略和自动记忆，但不加载代码库指令。

在两者同时加载模式下，Claude Code 会先读取每个目录里的 Claude 内容，再读取 AGENTS 内容。如果 CLAUDE.md 已经导入或通过符号链接指向同一个 AGENTS.md，它也会避免重复加载。

设置从下一条消息开始生效，并延续到新会话中。它还可以写入用户设置里的内置 agents-md@builtin 插件、--settings 文件或托管设置。Claude Code 会忽略项目和本地设置文件中的这一选项，因此代码库无法在开发者不知情的情况下强制改变其选择；管理员则可通过托管设置统一指定。

如何确认新会话加载了哪份文件

用一条无害信息测试，不要放入破坏性指令。把下面这一行加入你要验证的文件：

Project probe: BASALT-HERON.

然后关闭当前会话，在该代码库中启动下一个全新会话，并询问：What is the project probe?。如果回答是 BASALT-HERON，就说明这段内容已进入会话上下文。验证后删除测试行。

不要只靠 /context 下结论。直接加载的 AGENTS.md 不会出现在其中的 Memory files 列表里。在默认回退模式下，交互式会话启动时可能显示 AGENTS.md loaded；而无害探针在其他选择模式中也同样适用。

如果探针失败，请按以下顺序排查：

1. **版本：**是否为 v2.1.277 或更高。
2. **会话次数：**当前是否并非安装或升级后的第一个会话。
3. **服务提供商：**当前会话所用的服务提供商是否允许获取 Anthropic 功能开关。
4. **环境：**是否有遥测或非必要流量环境变量关闭了该请求。
5. **插件与策略：**内置 agents-md 插件是否启用，disableAllHooks 或 allowManagedHooksOnly 是否将其拦截。
6. **文件层级：**在默认模式下，当前目录及其上级目录是否存在符合条件的 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md。
7. 模式：/config 是否指向你真正需要的行为。

如果 /config 中完全没有 Project instructions，这本身就是诊断信号：当前会话使用的版本不受支持，或者无法启用该功能。

原生支持不可用时，继续保留导入桥接

对于 Bedrock、Vertex、Foundry、其他第三方服务提供商会话、限制遥测的环境，以及版本混用的团队，原有导入方式仍是最稳妥的兼容层。请在与 AGENTS.md 同级的 CLAUDE.md 中写入：

@AGENTS.md

可以在下面继续添加 Claude 专属指令。Claude 会先读取导入的共享文件，再读取后续的 Claude 专属补充。即使支持该功能的用户选择两者同时加载模式，保留这层桥接也不会导致重复加载。

从 CLAUDE.md 建立指向 AGENTS.md 的符号链接同样可行，但跨平台场景下，显式导入更稳妥。在 Windows 上，创建符号链接可能需要管理员权限或 Developer Mode，Git 也必须采用正确的符号链接设置。原生直读验证成功后，应移除负责输出 AGENTS.md 的 SessionStart 钩子，否则它可能重复注入同一份内容。

这次更新改变了维护成本。此前，一套跨智能体策略往往要配两份文件、一个导入垫片或一个钩子；在受支持的会话里，现在只需提交一份指令文件即可。Claude 的授权费用并不会因此降低：Anthropic 将 Claude Code 纳入每月 $20 的 Pro 方案。真正省下的是同步节点，也减少了会话误用过期规则的概率。

如需了解其余配置，Claude Code 完整使用指南涵盖安装、项目上下文和日常命令流程。如果代码库还定义了专用智能体，子智能体指南会说明它们各自独立的启动上下文。

最值得采用这套机制的七类场景

以下排序依据是新选择器能消除的协作问题规模。

前三类场景的收益最大，因为一次失效会在多人、多代码库中被成倍放大。对只用一种智能体的个人代码库来说，确实更方便，但收益有限。

可以围绕这项能力做什么产品

1. 跨智能体指令诊断工具

开发一个本地 CLI 和 CI 检查工具，准确解释每种编程智能体会加载哪些指令文件。平台团队和咨询公司愿意为代码库正式推广前的一份可靠答案付费。

需求已经出现：claude code setup 在美国每月约有 1,900 次搜索，claude md vs agents md 则有 480 次，且同比增长 1,500%。最小可售版本只需扫描文件树、读取 Claude Code 版本和服务提供商配置、标记造成遮蔽的文件，并输出加载顺序方案。面向团队的付费层则可以在多个代码库中执行同一套策略。

这是最有潜力的方向，因为它解决的是诊断问题，而不是模板问题。风险在于平台方可能自行补齐能力：Anthropic 可能把这些检查并入 claude doctor。因此，真正可持续的产品必须覆盖多种编程智能体，并记录策略漂移历史，而不能只围绕一条 Claude 命令。

2. AGENTS.md 策略生成器与检查器

制作一款引导式编辑器，把构建命令、测试规则、目录边界和评审要求整理成简洁的 AGENTS.md，再检查冲突与含糊表述。目标买家是正在采用多种智能体的小型工程团队。

agents md 在美国每月约有 2,900 次搜索。更具体的 agents md best practices 每月有 210 次，且同比增长 750%。一个 MVP 需要代码库扫描器、一组简短问答、自动生成的初稿，以及检查重复或矛盾指令的规则。生成结果应遵循服务提供商对项目文件精简度的建议，而不是堆出一份冗长的策略手册。

难点是壁垒较弱：任何编程智能体都能起草 Markdown。只有当验证机制真正反映加载顺序，并且能够证明每个受支持的编程工具都读到了结果，这款产品才有存在价值。

3. 混合智能体体系迁移审计

提供一份审计报告，梳理 CLAUDE.md、AGENTS.md、导入、符号链接、钩子、嵌套规则和服务提供商例外，再给出安全迁移到单一指令源的方案。潜在买家是同时使用多种智能体工具的代理机构和大型团队。

claude md vs agents md 每月 480 次搜索、同比增长 1,500%，非常直接地说明了市场的困惑。MVP 可以是只读的代码库分析器，再附上一份拉取请求实施方案。它绝不能自动删除桥接，因为不受支持的会话可能仍依赖它。

短板是机会窗口可能不长。团队一旦稳定采用共享文件规范，一次性迁移需求就会减少；产品最终必须把定期策略审计和服务提供商兼容性检查变成核心服务。

局限与客观结论

原生回退省掉了一层桥接，但它不会把项目指令变成强制策略，不会让所有服务提供商自动兼容，也不会替你解决互相冲突的规则。Anthropic 将指令文件定义为上下文。如果某条命令必须始终被阻止，应使用权限规则或 PreToolUse 钩子。

它也没有让 AGENTS.md 获得与 CLAUDE.md 相同的诊断可见性。直接加载不会显示在 /memory，也不会出现在 /context 的 Memory files 列表中。正因为这种不一致，无害探针值得长期保留在迁移检查清单里。

不要因为一台笔记本通过了原生测试，就删除混合服务提供商体系中正常工作的导入。没有先检查规则冲突，也不要启用两者同时加载模式。同一目录内，Claude 内容会先于 AGENTS 内容读取，但上下文顺序并不是强制性的策略优先级系统。

这次更新依然是一次有意义的运维改进。已经把 AGENTS.md 视为共享指令源的代码库，现在终于能直接配合 Claude Code 使用，而不必假装第二个文件名才是源头。功能看似不大，对协作的影响却很明显。

如果你希望为自己的代码库搭建一套可靠的多智能体指令系统，我可以协助设计智能体架构并完成落地。