Claude Code 原生支持 AGENTS.md，Shopify 首席执行官诉求终获回应

Anthropic 于 9 月 18 日发布 Claude Code 2.1.277 版，更新日志的第一项便是原生支持 AGENTS.md。Shopify 首席执行官 Tobi Lütke 于 8 月底公开抱怨 Claude Code 只读取 CLAUDE.md，并称考虑禁用该工具；这成为直接推动此次更新的业界压力之一。

Claude Code 2.1.277 支持 AGENTS.md：四种模式的设置方式与适用条件

根据 Anthropic 的更新日志和说明文件，Claude Code 2.1.277 版读取 AGENTS.md 的方式可分为以下四种模式：

只读取 CLAUDE.md：维持原有行为，不读取 AGENTS.md。

仅在不存在 CLAUDE.md 时读取 AGENTS.md（默认模式）：只要从根目录到工作目录之间存在任何一份 CLAUDE.md，Claude Code 就不会读取 AGENTS.md。

同时读取两者：同时读取 CLAUDE.md 和 AGENTS.md，但会跳过已由 CLAUDE.md 导入或链接的 AGENTS.md，以避免同一份内容被加载两次；Shopify 这类同时使用两种文件的代码库需要切换到此模式。

仅保留企业统一分发的说明文件：适用于由企业集中管理说明文件的场景。

上述设置需要写入用户或企业的配置文件，项目目录内的配置文件不会被读取。此功能目前暂不支持 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 这三个云端渠道。

Shopify 首席执行官的公开投诉：monorepo 环境下 AGENTS.md 与 CLAUDE.md 不兼容

Shopify 首席执行官 Tobi Lütke 于 8 月底公开表示，正在考虑让 Shopify 禁用 Claude Code，「直到他们改变心意，去读取 AGENTS.md 和 .agents/skills 这些文件」。他指出，Claude Code 坚持只读取 CLAUDE.md；当团队成员使用不同工具时，部分成员可能会拿到两套不同的规则，「完全没必要」。

Lütke 进一步说明了背景：Shopify 有数千名开发者在同一个 monorepo 中工作，两种说明文件都会沿着目录树逐层应用，因此总会有某个目录漏掉其中一份——「这代表有一部分开发者，是在被切除脑叶的状态下工作」。Shopify 当时使用自动化程序来填补这一缺口，Lütke 称这是「一笔愚蠢的复杂度税，本来就不该付」。

Claude Code 工程师 Thariq Shihipar 的说明：模型不可互换的原始理由与 mods 机制

Claude Code 工程师 Thariq Shihipar 在 Lütke 投诉后回复，解释了 Claude Code 只读取 CLAUDE.md 的原因：Anthropic 认为「不同模型家族不能互换，系统提示词对表现影响很大」，Claude Code 内部也为每个模型准备了不同的系统提示词。

Shihipar 承认，这需要不少维护工作，「不见得每个人都觉得值得」；短期内，他建议用户在 CLAUDE.md 中使用 @AGENTS.md 语法导入 AGENTS.md。2026 年 9 月 18 日，Shihipar 宣布通过 Claude Code 的「mods」机制实现对 AGENTS.md 的支持——mods 是 Anthropic 即将推出的 Claude Code 定制机制，开发者之后也可以根据自身需求打造不同版本的项目指令加载方式。Anthropic 同时在 GitHub 上开源了 agents-md mod 的源代码，同一目录下还有 diff、telemetry 和 sec-default 三个内置 mod。

AGENTS.md 的背景：OpenAI 推出后捐赠给 AAIF，已有超过 6 万个项目采用

AGENTS.md 是供 AI 程序代理阅读的项目说明文件，通常包含构建指令、测试方式和代码规范，代理在开始工作前会先读取。OpenAI 于 2025 年 8 月推出 AGENTS.md 规范，并于同年 12 月将其捐赠给 Linux 基金会新成立的 Agentic AI Foundation（AAIF）。AAIF 当时公布，已有超过 6 万个开源项目和代理框架采用该规范，Codex、Cursor、Gemini CLI 和 GitHub Copilot 均已支持。

值得注意的是，同一天捐赠给 AAIF 的还有 Anthropic 自家的 MCP（模型上下文协议）；Anthropic 也是 AAIF 的白金会员。尽管如此，从 AAIF 成立算起，Claude Code 又过了约 9 个月才开始读取 AGENTS.md；开发者早在 2025 年 8 月就已在 GitHub 上提交提案，要求支持该文件。

常见问题

Claude Code 2.1.277 版如何支持 AGENTS.md？

根据 Anthropic 的更新日志，Claude Code 2.1.277 版在项目中不存在 CLAUDE.md 时，会自动改为读取 AGENTS.md（默认模式）；用户也可以在 /config 的 Project instructions 选项中切换为同时读取两份文件。目前，此功能暂不适用于 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry。

AGENTS.md 和 CLAUDE.md 有什么不同？

两者都是供 AI 程序代理使用的项目说明文件，内容包括构建指令、测试方式和代码规范。AGENTS.md 由 OpenAI 于 2025 年 8 月推出，已有超过 6 万个开源项目采用，Codex、Cursor、Gemini CLI 和 GitHub Copilot 均已支持；CLAUDE.md 则是 Claude Code 的专用格式。

Anthropic 为什么花了 9 个月才支持 AGENTS.md？

根据 Claude Code 工程师 Thariq Shihipar 的说明，Claude Code 此前只读取 CLAUDE.md，是因为 Anthropic 认为「不同模型家族不能互换，系统提示词对表现影响很大」，而且 Claude Code 内部会为每个模型准备不同的系统提示词；此次更新通过「mods」机制实现了对 AGENTS.md 的支持，开发者也可以根据需求定制加载方式。