# Claude Code 能读 AGENTS.md，但只是备胎

**Summary:** Claude Code 2.1.277 在没有 CLAUDE.md 时会读取 AGENTS.md，减少多智能体仓库的重复设置，但团队仍需明确单一事实来源。

- Canonical: https://markhuang.ai/zh/news/claude-code-agents-md-is-plan-b
- Language: zh-CN
- Author: [Mark Huang](https://markhuang.ai/about)
- Published: 2026-09-18
- Section: News
- Tags: Claude Code, AGENTS.md, 编码智能体
- Source: [Claude Code Docs](https://code.claude.com/docs/en/changelog)
- License: https://creativecommons.org/licenses/by-nc/4.0/

---

![两份空白指令文档沿着各自发光的路径汇入同一个编码智能体核心](https://cdn.markhuang.ai/news/claude-code-agents-md-is-plan-b/hero.webp)

*Claude Code 现在有了第二条项目指令路径，但两条路径的权重并不相等。*

Claude Code [2.1.277 版本](https://code.claude.com/docs/en/changelog)（发布于 2026 年 9 月 18 日）新增了对 `AGENTS.md` 的原生支持。关键细节藏在冒号之后：只有当项目中没有 `CLAUDE.md` 时，Claude Code 才会读取它。Anthropic 还表示，该功能目前尚未在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上线。

我喜欢这个改动，因为它省掉了同时使用多种编码智能体时一份虽小却挥之不去的重复劳动。称之为“指令文件统一”有些言过其实。Claude 把 `AGENTS.md` 当备胎，团队还是得搞清楚当前会话到底加载了哪个文件。

## 一份文件，跨一个工具的边界

`AGENTS.md` 的定位刻意保持低调。[其官方网站](https://agents.md/)把它描述成一个固定位置，用来存放构建步骤、测试规范和仓库约定，并称已有超过 6 万个开源项目在使用它。团队可以把入职指南留在 `README.md` 里，把智能体专用的工作规则放到单独的文件中。

仓库一旦在不同工具之间流转，这个好处就体现出来了。[GitHub Copilot CLI 文档](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions)就明确列出了 `AGENTS.md`、`CLAUDE.md` 和 `GEMINI.md` 作为它能识别的指令文件。Claude Code 加入这套约定之后，已经以 `AGENTS.md` 为标准的仓库可以直接在 Claude Code 里打开，不用再急着加一份带厂商名字的副本。

最直接的好处是，维护者想试几种不同的智能体时，不用再复制同一套规则。开源项目也没法预判贡献者会带什么工具来。少一份近乎重复的指令文件，测试命令或审查规则出现偏差的概率就低一些。这是个实用的改进，只是实际边界比标题暗示的要窄。

## 回退规则制造了静默分叉

Anthropic 的措辞确立了一个简单的优先级规则：如果存在 `CLAUDE.md`，就不会触发新的回退条件。发布说明并未提及 Claude Code 会合并这两个文件，或在两者同时存在时发出警告。它只提到用户可以在 `/config` 中的“项目指令”下更改选择。

这让一个旧的兼容层变得意外关键。仓库里可能早就躺着一个简短的 `CLAUDE.md`——也许指向某份共享指南，也许加了几条 Claude 专属行为，也许早就没人记得它了。升级之后，维护者可能写好了一个完整的 `AGENTS.md`，以为 Claude Code 已经自动用上。但那个被遗忘的厂商文件，照样能挡住回退的触发。

> **Info:**
>
> 把这次升级当作一次优先级变更，先验证再删东西。打开 `/config`，看一下“项目指令”，然后给智能体一个无害的小任务——这个任务的行为取决于某一条特定规则，这样你就能确认它到底加载了哪份文件。

这与我关心的另一个产品边界问题如出一辙——即区分 Claude 的模型提示词与 Claude Code 外壳。一条规则可能存在于 Git 中，却因产品从未将其加载到活跃上下文中而毫无作用。我希望产品能同时向我展示发现过程和优先级规则。

## 最初的反应是迁移焦虑

目前公开的讨论还不多，不足以当成定论来看。但已经能看出一些端倪。在一个 [r/ClaudeAI 帖子](https://www.reddit.com/r/ClaudeAI/comments/1wjxvwz/claude_code_is_getting_native_agentsmd_support/)里，第一个实际问题就是：要不要把 `CLAUDE.md` 删掉？有人回复说应该保留 Claude 专属结构，让一个文件指向另一个。在另一个 [r/ClaudeCode 帖子](https://www.reddit.com/r/ClaudeCode/comments/1wk2q8v/agentsmd_now_supported_in_claude_code/)里，有用户夸这个改动对同时用 Claude Code 和 Codex 的人很方便，另一个人则希望 Claude Code 也能自动发现 `.agents/skills` 下的技能。

人们用“支持”一词表达了两种不同含义。第一种是基本的文件名兼容性：工具能否读取共享的根指令？2.1.277 版本在回退条件下给出了肯定答复。更难满足的期望是，嵌套指令、技能、导入和优先级能在不同工具间保持一致。此更新日志并未作出此类承诺。

这种质疑说得过去：团队本来就可以维护两个小 Markdown 文件、用链接串起来，或者让一个文件导入另一个。就单个仓库来说，原生支持省不了多少事。但我的回答是，惯例的价值在于跨仓库、跨贡献者时的一致性。每个私有变通方案都是一个潜在的故障点——换个克隆、换个操作系统、换个对链接和导入解析方式不同的工具，就可能出问题。

## 我会选一个权威文件

如果仓库要在多个编码智能体之间通用，我会把 `AGENTS.md` 作为共享命令、架构说明、审查要求和安全限制的唯一来源。如果 Claude 需要额外指导，我会让 `CLAUDE.md` 保持简短，并明确指向通用规则的位置。我不会维护两份完整的副本。

然后，我会在团队实际用到的每个平台上跑一遍测试。这里有个前提条件要注意：本地 Claude Code 会话可能支持回退机制，但 Bedrock、Vertex 或 Foundry 上的部署还没跟上。在 Anthropic 把这个缺口补上之前，删掉 `CLAUDE.md` 可能在这台机器上解决了可移植性问题，却在别的地方把指令弄丢了。

我欢迎 Claude Code 采纳 `AGENTS.md`，因为仓库指令本来就应该跟着仓库走。理想状态是一套维护良好的规则，而且能证明每个智能体都加载了它。2.1.277 版本让 Claude Code 离这个目标更近了一步。眼下，我还是会先检查 `/config`，再跑一个小测试看看行为是否符合预期。