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

Q: Claude Code 会读 AGENTS.md 吗？

不会。Anthropic 的官方 memory docs 写明：「Claude Code reads CLAUDE.md, not AGENTS.md.」如果仓库里只有 AGENTS.md，Claude Code 不会加载任何项目指令，也不会显示错误。官方记录的桥接方式，是创建一个导入它的 CLAUDE.md（@AGENTS.md），或者使用软链（ln -s AGENTS.md CLAUDE.md）。

Q: Claude Code 完全不识别 AGENTS.md 吗？

会间接识别。CLAUDE.md 可以通过 @AGENTS.md 导入它；另外，在已经有 AGENTS.md 的仓库里运行 /init，会读取它，并把相关部分合并进生成的 CLAUDE.md（同时也会读取 .cursorrules、.devin/rules/ 和 .windsurfrules）。

Q: 怎样让 Claude Code 使用我现有的 AGENTS.md？

创建一个 CLAUDE.md，并把第一行写成 @AGENTS.md；Claude 会在 session 开始时加载被导入的文件，然后再追加其余内容。如果你不需要 Claude 专属补充，也可以使用软链（ln -s AGENTS.md CLAUDE.md），但 Windows 上创建软链需要管理员权限或开发者模式，所以更建议用 import。

Q: AGENTS.md 和 CLAUDE.md，哪个应该是真理源？

如果仓库里不止一个 coding agent 会工作，把 AGENTS.md 作为 canonical source（60k+ 个开源项目已经采用；Codex 和 Cursor 都能原生读取），并把 CLAUDE.md 保持为导入它的薄 shim。只用 Claude Code 的仓库，普通的 CLAUDE.md 更简单。

如果你最近打开过热门仓库，很可能已经在原本期待看到 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？

短答案：现在还不该；而且如果你天真地这么做，Claude Code 会悄悄地什么项目指令都读不到。下面是真实现状，以及我们推荐的配置方式。（2026 年 6 月 6 日更新：Anthropic 的文档现在已经正面说明 AGENTS.md；下文官方引语来自 official memory docs，中文为译文，并保留关键英文句。）

快速问答

Claude Code 会读 AGENTS.md 吗？ 不会。官方文档现在一句话讲清楚了：“Claude Code 读取的是 CLAUDE.md，不是 AGENTS.md（Claude Code reads CLAUDE.md, not AGENTS.md）。” 如果你的仓库里只有 AGENTS.md，Claude Code 不会加载任何项目指令，而且不会报错。

Claude Code 完全不识别 AGENTS.md 吗？ 它会间接用到两个地方：CLAUDE.md 可以导入它（@AGENTS.md）；另外，在已经有 AGENTS.md 的仓库里运行 /init，会读取它，并把相关部分合并进生成的 CLAUDE.md（同时也会读取 .cursorrules、.devin/rules/ 和 .windsurfrules）。

怎样让 Claude Code 使用我现有的 AGENTS.md？ 新建一个一行的 CLAUDE.md，内容写 @AGENTS.md（官方推荐）；或者建软链：ln -s AGENTS.md CLAUDE.md。在 Windows 上，创建软链需要管理员权限或开发者模式；这种情况下用 import 更稳。

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 年 6 月，Claude Code 仍不会原生读取 AGENTS.md。 过去这件事只能从 issue tracker 的请求里推断；现在 official memory docs 新增了专门的 AGENTS.md 小节，并且直接写明：“Claude Code 读取的是 CLAUDE.md，不是 AGENTS.md（Claude Code reads CLAUDE.md, not AGENTS.md）。如果你的仓库已经把 AGENTS.md 给其他 coding agents 使用，请创建一个导入它的 CLAUDE.md，这样两个工具就能读取同一套指令，而不必复制维护。”

如果你的仓库里只有 AGENTS.md，Claude Code 加载到的项目指令就是零；而且你不会看到错误。你只会得到更差的输出，然后困惑为什么质量下降了。（我们查过截至 v2.1.167 的完整 changelog：原生 AGENTS.md 支持尚未发布；长期被关注的请求 anthropics/claude-code#34235 仍然开放。）

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

错误做法是手工维护两个文件。它们通常一周内就会开始漂移（漂移有多快，可以看 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 会在 session 开始时加载被导入的文件，然后再追加其余内容”），所以 Claude 读到的是共享标准，再加上少量 Claude 专属说明。其他工具则直接读取 AGENTS.md。真正需要编辑的，仍然只有一份共享文件。这个模式现在已经是官方文档的首选建议，也就回答了“这是不是 hack”的问题：不是。

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

还有一个最近的行为值得知道：/init 现在会吸收 AGENTS.md。 在已经有 AGENTS.md 的仓库里运行它，生成的 CLAUDE.md 会纳入其中相关内容；.cursorrules、.devin/rules/ 和 .windsurfrules 也是如此。迁移时这很方便；但它不能替代 import，因为吸收进去的是当时的一份拷贝，后续 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。一个真理源、一个负责人、保持精简。

配套阅读

如何写好 CLAUDE.md —— 不管它叫什么名字，文件工艺是一样的。
AGENTS.md 模板 —— 大约 40 行的起步文件、给 Claude Code 的 shim 和 monorepo 写法。
5 人以上团队的 CLAUDE.md 问题 —— 两个文件在团队里漂移会发生什么。
CLAUDE.md 中 5 个偷烧 token 的坏习惯 —— 同样的纪律，现在被每个读 AGENTS.md 的工具放大。
AI 编程代理到底往你磁盘写了什么 —— 这些文件到底都住在哪。