变了什么：AGENTS.md 不再需要桥接文件
Claude Code v2.1.277 于 2026 年 9 月 18 日发布，从这一版开始，它可以直接把仓库里的 AGENTS.md 当作项目指令读取，不再必须通过 CLAUDE.md 里写 @AGENTS.md 导入。对于同时使用多个编码代理的团队，这意味着只需要维护一份共享的指令文件，而不是两份容易走偏的文件。
AGENTS.md 原本由 OpenAI 在 2025 年 8 月提出，后来移交给 Linux 基金会下的 Agentic AI Foundation 维护，Codex、Cursor、Gemini CLI、GitHub Copilot 都读取它。此前 Claude Code 是名单外的那个异类，做同一件事的仓库不得不准备两份指令。
需要明确的是，这次改动是回退机制而不是无条件扫描：只有在工作目录及其上层目录都不存在 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时，Claude Code 才会读取 AGENTS.md。
三步验证流程
第一步，确认版本。运行 claude --version，需要 v2.1.277 或更高。原生安装可用 claude update 升级，Homebrew 与 WinGet 走各自的包管理器升级命令。
第二步，确认会话能拉取 Anthropic 的功能开关。原生 AGENTS.md 加载在第三方提供商会话中不可用，包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry；遥测或非必要流量被关闭时，这个开关同样拉不到。
第三步，放置文件并排除干扰。把 AGENTS.md 或 .claude/AGENTS.md 放在项目路径下，同时确保工作目录及其上层目录没有项目级 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md。然后在全新的会话里测试，因为安装或升级后的第一个会话是例外情况。如果 /config 里根本没有 Project instructions 这一项，说明当前环境不支持，继续用 CLAUDE.md 里 @AGENTS.md 的导入写法即可。
默认模式是回退而不是合并：版本与会话支持在前，是否加载 AGENTS.md 由有没有合规的 CLAUDE.md 决定。很多同一个仓库两个开发者行为不同的困惑，根源就在这个作用域差异。
Project instructions 的四个取值
打开 /config 找到 Project instructions，按仓库意图选择：第一，claude-md-or-agents-md（默认），适合已经在用 AGENTS.md 且没有项目级 Claude 文件的仓库；第二，claude-md-and-agents-md，两个文件族都读，每个目录先读 Claude 内容再读 AGENTS 内容，适合 AGENTS.md 放共享规则、CLAUDE.md 补 Claude 专属指引；第三，claude-md，只读 Claude 文件；第四，managed-only，只加载组织托管指令与自动记忆，不加载仓库指令。
作用域上有两个容易踩的坑。一是 CLAUDE.local.md 位于上层目录时会抑制回退，而个人 ~/.claude/CLAUDE.md、组织托管的 CLAUDE.md 以及 .claude/rules/ 下的文件不计入这个判断，会与 AGENTS.md 一起加载。二是不会被读取的文件包括 AGENTS.local.md、AGENTS.override.md 和 .agents/ 目录下的任何内容。如果团队原来有 CLAUDE.md 想迁移到 AGENTS.md，必须先删除或重命名原来的文件，否则它会一直被优先读取；也可以在设置文件里通过 pluginConfigs 下的 agents-md 内置插件选项 instructionFiles 来固定行为，注意项目级与本地设置文件对这个值不生效。
参考来源：Anthropic Claude Code 更新说明；实操指南 https://www.ayautomate.com/blog/claude-md-vs-agents-md
粤公网安备44130202001736号