← 返回全部文章
实战指南 · 2026年5月27日 · 7 分钟阅读 · 更新于 2026年9月26日

CLAUDE.md vs AGENTS.md：Claude Code 到底读哪个？

更新（2026 年 9 月 26 日）：Claude Code 现在会自行读取 AGENTS.md，但仅作为回退。 从 v2.1.277（9 月 18 日）起，如果项目有 AGENTS.md，且工作目录及其上级目录中都没有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md，它就会自动加载 AGENTS.md。两类文件同时存在时，只加载 CLAUDE.md。下方快速问答已更新。本页推荐的一行 @AGENTS.md 导入，仍然能在所有版本和配置下加载共享指令。我们实测了 30 种配置，其中五种常见配置下，原生回退不会读取 AGENTS.md。

更新 — 2026 年 8 月 26 日： Anthropic 已将这项请求关闭，Shopify CEO 也注意到了。2026 年 8 月 17 日，Anthropic 将 Claude Code 仓库里获赞最多的 issue #6235 关闭为「已完成」；它当时已开放 361 天，获得 5,026 个赞。官方没有加入原生支持，而是指向了本页推荐的同一种桥接方案。8 天后，Tobi Lütke 公开表示，他正考虑因此在 Shopify 禁用 Claude Code。本页下面的结论依然成立；我们还逐一实测了 Anthropic 文档列出的桥接方式，并发现其中一种在 Windows 上有个值得留意的缺口。

如果你最近打开过热门仓库，很可能已经在原本期待看到 CLAUDE.md 的位置，看到了一个 AGENTS.md。到 2026 年，AGENTS.md 已经从“Codex 想要的那个文件”变成真正的跨厂商标准：它由 Linux Foundation 旗下的 Agentic AI Foundation 托管（该基金会成立于 2025 年 12 月，OpenAI 把 AGENTS.md 贡献进去，Anthropic 则贡献了 MCP），并且按标准官网自己的统计，已经被 60k+ 个开源项目采用。这个承诺很诱人：写一份文件，所有 agent 都读，换工具几乎没有迁移成本。

于是，每个 Claude Code 团队都会遇到同一个问题：我们是不是应该扔掉 CLAUDE.md，统一用 AGENTS.md？

建议统一使用 AGENTS.md，但要保留一个只有一行导入语句的 CLAUDE.md。Claude Code 2.1.277 及之后的版本能自行读取 AGENTS.md，前提是工作目录及其上级目录里没有任何 CLAUDE.md 类文件。更早的版本完全不会读取它，包括 9 月 26 日的 stable 发布渠道。下面是真实现状，以及我们推荐的配置方式。

快速问答

Claude Code 会读 AGENTS.md 吗？ 会。从 v2.1.277（2026 年 9 月 18 日）起支持，但这是回退读取，不会合并两类文件。只有工作目录及其上级目录里都没有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时，才会读取 AGENTS.md；其中任何一个存在，就改读它。更早的版本完全不读 AGENTS.md。五种常见配置会让它读不到，而且没有任何提示。

Claude Code 完全不识别 AGENTS.md 吗？ 会识别。除了原生回退读取，CLAUDE.md 也可以通过 @AGENTS.md 导入它。设置 CLAUDE_CODE_NEW_INIT=1 后，在已有 AGENTS.md 的仓库里运行 /init，还会读取它并把相关内容合并进生成的 CLAUDE.md。默认情况下，/init 读取的是 Cursor 和 Copilot 的规则。

怎样让 Claude Code 使用我现有的 AGENTS.md？ 在 v2.1.277 及之后的版本中，只要工作目录及其上级目录里没有 CLAUDE.md，就会自动读取，无需额外配置。要让所有版本和配置都能加载，新建一个只有一行 @AGENTS.md 的 CLAUDE.md；或者建软链：ln -s AGENTS.md CLAUDE.md。在 Windows 上，创建软链需要管理员权限或开发者模式；这种情况下用导入更稳。

AGENTS.md 和 CLAUDE.md，哪个应该是真理源？ 如果仓库里不止一个 agent 会动代码：把 AGENTS.md 作为 canonical source，把 CLAUDE.md 做成只负责导入它的薄 shim。只用 Claude Code 的仓库：直接用 CLAUDE.md，不必追标准。

两个文件分别是什么

AGENTS.md 是放在仓库根目录的、厂商中立的指令文件：构建命令、代码约定、测试规则，以及 agent 无法单靠读代码推断出来的约束。它存在的核心理由是可移植性：Codex、Cursor、VS Code 的 agent 模式、Windsurf、Kilo 以及更多工具，都能不经转换直接读取它。

CLAUDE.md 是 Claude Code 的原生 memory 文件。它早于这个标准出现，是分层的（项目级 CLAUDE.md 叠加个人的 ~/.claude/CLAUDE.md），并且支持用 @ 导入其他文件。它不是 AGENTS.md 的同义词；它是另一个文件，只是为某一个特定 agent 做着相似的事。

没人提醒你的那个坑

真正会坑到团队的是这一点：即使把共享指令统一放进 AGENTS.md，也不能保证它会被读取。2026 年 9 月之前，Claude Code 不会原生读取 AGENTS.md。官方记忆文档 当时明确写道，它读取 CLAUDE.md，不读 AGENTS.md（原文：“Claude Code reads CLAUDE.md, not AGENTS.md.”）。2.1.277 版本（9 月 18 日）改变了这一点，但仅限回退：只有工作目录及其上级目录里都没有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时，才会读取 AGENTS.md。只要出现其中任意一种文件，例如队友的个人 CLAUDE.local.md，或单体仓库根目录的 CLAUDE.md，AGENTS.md 就会悄悄停止加载。

这些情况都不会报错。你只会得到更差的输出，然后困惑为什么质量下降了。2.1.277 之前的版本，包括 9 月 26 日的 stable 发布渠道，仍然不会加载单独存在的 AGENTS.md。我们在当前版本上实测了 30 种配置，逐一确认它在什么情况下会加载。

怎么同时运行两者而不用维护两份文件

错误做法是手工维护两个文件。它们通常一周内就会开始漂移（漂移有多快，可以看 5 人以上团队的 CLAUDE.md 问题）。你真正需要的是一个真理源，再加一座很薄的桥。常见做法有两种：

方案 A：import（推荐）。 保留 AGENTS.md 作为所有工具共同读取的共享文件，再把 CLAUDE.md 做成一个很短的 shim，把它导入进来：

# CLAUDE.md
@AGENTS.md

# Claude 专属说明（与 AGENTS.md 不同的部分）
- 搜索用 ripgrep MCP server，别用 bash grep。

Claude Code 加载时会展开 @AGENTS.md 导入：先读被导入的文件，再读后续内容（原文：“Claude reads the imported file first, then the rest”）。所以 Claude 读到的是共享标准，再加上少量 Claude 专属说明。其他工具则直接读取 AGENTS.md。真正需要编辑的，仍然只有一份共享文件。Anthropic 仍在文档中列出这种方式，用于原生读取不生效的情况。因此，这不是临时绕过限制的做法；无论使用哪种配置，也不会把 AGENTS.md 加载两次。

方案 B：symlink。 ln -s AGENTS.md CLAUDE.md。这非常简单，Claude Code 会把这个链接文件当成自己的文件来读。代价是：你无法再添加 Claude 专属说明（它们实际上是同一个文件），并且官方文档直接点出了平台限制：在 Windows 上，创建软链需要管理员权限或开发者模式，所以更建议使用 @AGENTS.md import。再加上常规的 CI 注意事项（确认 git 存进去的是链接，而不是副本），个人仓库可以接受，混合团队里就没那么稳。

还有一个行为值得知道：/init 可以读取 AGENTS.md 并整合其内容。 设置 CLAUDE_CODE_NEW_INIT=1 后，在已经有 AGENTS.md 的仓库里运行它，生成的 CLAUDE.md 会纳入其中相关内容；.devin/rules/、.windsurfrules 和 .clinerules 也是如此。默认情况下，它读取 Cursor 和 Copilot 的规则。迁移时这很方便，但不能替代导入，因为复制进去的只是当时的内容。后续 AGENTS.md 再改，它不会自动跟进。

它们冲突时谁说了算

使用 import 模式时，合并顺序基本符合直觉：导入进来的 AGENTS.md 是基线，你直接写在 CLAUDE.md 里的内容叠加在其上，你个人的 ~/.claude/CLAUDE.md 再叠加在最上层。因此，Claude 专属 override 会压过共享标准，而你的个人偏好又会压过两者；但只对你自己的机器生效，不会影响队友。

这个区别正是团队最容易搞错的地方。把个人偏好写进共享文件，是 5 个偷烧 token 的坏习惯 里的第 3 条；如果再把这份共享文件升级成 AGENTS.md，就等于把这个错误扩散到团队里的每一个工具。

token 账只会更糟，不会更好

臃肿的指令文件，本来就是每个 Claude session 的隐形税。把它升级成 AGENTS.md 后，它会被团队里每一个 agent 加载：Claude、Codex、Cursor，或者其他任何工具；并在它们的每个 session 中继续计费。一份草率文件的影响范围，会随着你们使用的工具数量一起放大。

纪律本身没有变，只是更重要了：AGENTS.md 应该短、应该“反常识”（只写全新模型不会自动做到的事），并且不能包含个人偏好。如果它是整个工具栈共同读取的文件，它就更值得保持精简。（如果你正要新建，我们的可复制 AGENTS.md 模板就是按这个克制原则写的。）

换作我们会怎么做

  • 个人、只用 Claude Code： 直接使用 CLAUDE.md。在你引入第二个工具之前，AGENTS.md 没有带来实际收益；不要为了追标准而追标准。
  • 一个人、多个 agent： 把 AGENTS.md 作为真理源，CLAUDE.md 写成 @AGENTS.md 加少量 Claude 专属内容。个人偏好放进 ~/.claude/CLAUDE.md。
  • 团队、多个 agent： 仍然采用上面的方式，再指定一个 owner 负责编辑 AGENTS.md，并每月通读一次。真正拖垮团队的不是格式，而是两个文件各自漂移，却没有人对任何一个负责。

格式之争基本已经有了答案：AGENTS.md 拿下了“共享基线”的位置；Cursor 现在已经原生读取它（包括嵌套子目录里的文件，见 rules docs），而且 Codex 仍然以 AGENTS.md 为先，并明确不读取 CLAUDE.md。Claude Code 现在也能原生读取，但仅作为回退。因此，推荐配置仍然是：面向所有工具的 AGENTS.md，再配一个给 Claude 用的薄 CLAUDE.md shim。一个真理源、一个负责人、保持精简。

配套阅读

这篇对你有帮助吗?

相关阅读

文章独立产出 · 编辑政策

继续阅读 →