Claude Code 2.1.277 起支持 AGENTS.md：没有 CLAUDE.md 时自动读取，可在 /config 切换

北京时间 9 月 19 日凌晨，X 账号 @trq212 发帖宣布，Claude Code 开始支持 AGENTS.md：从 2.1.277 版起，如果文件夹里没有 CLAUDE.md，Claude 会检查并使用 AGENTS.md，这一行为可以在 /config 里切换。据 The Register 报道，发帖者是 Claude Code 工程师 Thariq Shihipar。原帖

帖文还说，这项支持构建在 Claude Code mods 之上：mods 被描述为一种「即将推出」的机制，用来定制 Claude Code harness（大致可以理解为驱动 Claude 的运行框架）。第二条帖文说明这是一个内置 mod，用户之后也能按需要构建「项目指令」类的自定义版本；第三条帖文给出了源码位置，位于 anthropics/claude-code 仓库的 mods/agents-md 目录。

判定条件：哪些 CLAUDE.md 会让回退不生效

Claude Code 官方文档的 changelog 把 2.1.277 的日期标为 9 月 18 日，条目写道：「新增 AGENTS.md 支持：项目没有 CLAUDE.md 时，Claude Code 改为读取 AGENTS.md；可在 /config 的 Project instructions 里更改。」

更细的判定条件写在官方文档的「记忆」页面：仓库里只有 AGENTS.md 时，读的就是它；只要工作目录或任何上级目录里存在 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md，Claude 就只读 CLAUDE.md 文件；如果 CLAUDE.md 本来就导入了 AGENTS.md，则随导入读到。用户自己的 ~/.claude/CLAUDE.md、组织管理的 CLAUDE.md 和 .claude/rules/ 规则文件不参与这个判定，它们会和 AGENTS.md 一起照常加载。

回退生效时，会话启动会加载工作目录及所有上级目录里的每个 AGENTS.md 和 .claude/AGENTS.md，交互式会话里会显示一行 no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md；当 Claude 用 Read 打开某个子目录里的文件、而该子目录没有上述任何一种 CLAUDE.md 时，这个子目录的 AGENTS.md 也会附加进上下文。AGENTS.md 里的 @ 路径导入会被展开。文档同时明确：AGENTS.local.md、AGENTS.override.md 和 .agents/ 目录下的文件都不会被读取。

有一个容易踩的坑：CLAUDE.local.md 同样算「项目自己的 CLAUDE.md」。给一个依赖 AGENTS.md 的项目随手放一份 CLAUDE.local.md，回退就会被挡住。

四种读法：默认值与设置方式

直接读取 AGENTS.md 需要 Claude Code 2.1.277 或更高版本。控制读取方式的地方是会话里的 /config：设置面板里多了一行 Project instructions（项目指令），提供四个值。

• claude-md-or-agents-md（默认）：有 CLAUDE.md 就读 CLAUDE.md，没有才读 AGENTS.md，也就是说，这个回退默认开着；
• claude-md-and-agents-md：两份都读，同一目录先 CLAUDE.md 后 AGENTS.md，已经加载过的文件不会重复读（上一节提到的 CLAUDE.local.md 问题，就用这个值解决）；
• claude-md：只读 CLAUDE.md；
• managed-only：只保留组织管理的 CLAUDE.md 和 auto memory（自动记忆），项目、本地、用户三级的 CLAUDE.md 与 .claude/rules/、以及全部 AGENTS.md 都不进入上下文。

不用面板的话，也可以直接写设置文件：在 ~/.claude/settings.json、--settings 指定的文件或组织管理的设置里，把 pluginConfigs 里 agents-md@builtin 插件的 options.instructionFiles 设为对应的值；项目和本地的设置文件不读这一项。改动从下一条消息开始生效，并延续到之后的新会话。如果完全不想启用，可以在 /plugin 列表里关掉内置的 agents-md 插件，关掉之后，引擎只读 CLAUDE.md。

四个内置 mod 与早期访问状态

仓库里 mods 目录的说明给出了 mod 的定义：一个 mod，就是一个行为写在 hooks（钩子）模块里的 Claude Code 插件。目前有四个内置 mod（sec-default、diff、telemetry 和 agents-md），随二进制一起打包进 Claude Code，这个目录发布的正是同一份源码。其中 agents-md 的职责，是用「一个选项」决定项目指令从哪里来：默认在项目没有自己的 CLAUDE.md 时改读 AGENTS.md，也可以设成两份并读、只读 CLAUDE.md，或只保留组织指令。

这份说明把现状写得很清楚：这批 mod 处于早期访问（Early access），hooks 模块只在启用 function hooks 的环境加载，而且这些 mod 所依据的 API 可能在不同版本之间变化、不另行通知；它们也不在仓库的 marketplace（插件市场）列表里；真正起作用的是已经内置在各个 Claude Code 里的副本。mod 自身的说明里还有一条跟数据有关的细节：当遥测插件在场时，mod 会记录 agents_md_mode、agents_md_load、agents_md_nested 三个事件；按源码的说明，这些记录只含计数和封闭选项，不包含路径与文件文本。

两个文件、软链接与一条已关闭的功能请求

在这次更新之前，同时使用 Claude Code 和 Codex 等工具的开发者，需要在仓库里维护两套 Markdown 指令：CLAUDE.md 和 AGENTS.md，外加它们的项目专属版本；据 The Register 报道，一种绕法是做软链接，让两个文件保持同步。两套格式相似但不完全一样：CLAUDE.md 可以承载 Claude 专属指令，AGENTS.md 则面向工具无关。

在 anthropics/claude-code 仓库里，功能请求 #6235 于 2025 年 8 月 21 日提交，现已关闭。请求正文写着：Codex、Amp、Cursor 等工具正在围绕 AGENTS.md 走向统一，而 CLAUDE.md「太偏向 Claude Code」，在和不用 Claude Code 的开发者协作时并不好用。

据 The Register 报道，OpenAI 去年把 AGENTS.md 捐给了 Linux 基金会旗下的 Agentic AI Foundation；截至 2025 年 12 月，已有超过 60,000 个开源项目采用这个文件。这家媒体把 Anthropic 的转向形容为让开发者社区意外，并评论说，Claude Code 的走红本来给了 Anthropic 坚持自家标准的底气，但公司似乎认定继续分立规格没有收益。

「到亮处来吧」与删掉软链接的开发者

OpenAI 一侧也有人回应。据 The Register 报道，OpenAI 核心产品负责人 Thibault Sottiaux 回复说：「好耶！就该这么做，到亮处来吧。」该报道还记录，Shihipar 用一个握手 emoji 回应了他。

在帖子下面，开发者已经开始处理手里的软链接。@vvrdotdev 写道：「终于可以把 CLAUDE md 和 AGENTS md 之间的所有软链接删了。」@leonardo_lemos 写：「不错，现在我能把给所有项目做的那个软链接删掉了哈哈。（不过，这个改动确实受欢迎。）」

也有提醒的声音。@AndraxPentester 在回复里指出一个优先级问题：没有 CLAUDE.md 时改读 AGENTS.md，意味着一个未经审查的文件会直接成为指令集；他认为应该像审查代码一样对待这个文件，并且只在自己信任的仓库里依赖回退。截至发稿，主帖已有约 2.7 万次点赞、超过 370 万次浏览。

哪些场合读不到，哪些行为不一样

官方文档列了几种读不到 AGENTS.md 的情形：版本低于 2.1.277；不向 Anthropic 拉取功能开关的会话，例如第三方提供商环境、或关闭了遥测；刚安装或升级后的第一次会话（从下一次会话起才会读取）；以及在 /plugin 里关掉内置 agents-md 插件之后。在这些会话里，/config 面板不会出现 Project instructions 这一行。

即使读到了，行为和 CLAUDE.md 也有差别：这类 AGENTS.md 不会出现在 /memory 或 /context 的 Memory files 列表里，想确认只能看启动时那行加载提示，或直接问 Claude 它的项目指令是什么；InstructionsLoaded hooks 不会为它触发，通过 CLAUDE.md 导入或软链接的仍会触发；开启 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 后用 --add-dir 追加的目录，加载的只有它们的 CLAUDE.md，AGENTS.md 不在其列；AGENTS.md 里指向工作目录之外的 @ 导入，只有在项目此前已批准过外部导入时才会加载，而且不会再弹审批框。

官方 changelog 还标注：尚未支持 Bedrock、Vertex 或 Foundry。在这些环境里，官方文档给出的替代方案仍是写一个 CLAUDE.md，把 AGENTS.md 导入进来，和这次更新之前一样。

参考链接

• https://twitter.com/trq212/status/2101009392611278961
• https://twitter.com/trq212/status/2101009393731223817
• https://twitter.com/trq212/status/2101009395052343462
• https://www.theregister.com/ai-and-ml/2026/09/18/anthropic-decides-to-support-openais-markdown-instructions-spec/5297588
• https://github.com/anthropics/claude-code/tree/main/mods/agents-md
• https://code.claude.com/docs/en/changelog
• https://code.claude.com/docs/en/memory
• https://github.com/anthropics/claude-code/tree/main/mods
• https://github.com/anthropics/claude-code/issues/6235
• https://twitter.com/thsottiaux/status/2101026876647170092
• https://twitter.com/vvrdotdev/status/2101210768473763972
• https://twitter.com/leonardo_lemos/status/2101129393619816790
• https://twitter.com/AndraxPentester/status/2101052936512303132