CLAUDE.md vs AGENTS.md（2026）—— Claude Code 到底读哪个？

如果你最近打开过热门仓库，很可能已经在原本期待看到 CLAUDE.md 的位置，看到了一个 AGENTS.md。到 2026 年，AGENTS.md 已经从“Codex 想要的那个文件”变成真正的跨厂商标准 —— 现在由 Linux 基金会托管，被 30 多个工具采用，出现在 60,000+ 个仓库里。它的卖点很诱人：写一个文件，所有 agent 都能读，换工具几乎没有迁移成本。

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

短答案：现在还不该 —— 而且如果你天真地这么做，Claude Code 会悄悄地什么项目指令都读不到。下面是真实现状，以及我们推荐的配置方式。

两个文件分别是什么

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 年年中，Claude Code 还不会原生读取 AGENTS.md。 它读的是 CLAUDE.md。如果你的仓库里只有 AGENTS.md，Claude Code 加载到的项目指令就是零 —— 而且不会报错。你只会得到更差的输出，然后困惑为什么质量下降了。

这不是假设。“把 AGENTS.md 作为原生 context 文件支持”是 Claude Code issue tracker 上关注度最高的开放请求之一（anthropics/claude-code#34235）。在它真正落地之前，“只保留 AGENTS.md”对 Claude Code 来说就等于“盲飞”。

怎么同时用两个文件，又不用维护两份

错误做法是手工维护两个文件。它们通常一周内就会开始漂移（漂移有多快，可以看 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 读到的是共享标准，再加上少量 Claude 专属说明。其他工具则直接读取 AGENTS.md。真正需要编辑的，仍然只有一份共享文件。

方案 B —— symlink。 ln -s AGENTS.md CLAUDE.md。这非常简单，Claude Code 会把这个软链当成自己的文件来读。代价是：你无法再添加 Claude 专属说明（它们实际上是同一个文件）、部分 Windows checkout 和 CI runner 不会保留软链，而且你还需要确认 git 存进去的是链接而不是副本。个人仓库可以接受，混合工具栈团队则不太稳。

它们冲突时谁说了算

使用 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 应该短、应该“反常识”（只写全新模型不会自动做到的事），并且不能包含个人偏好。如果它是整个工具栈共同读取的文件，它就更值得保持精简。

换作我们会怎么做

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

格式之争基本已经有了答案：AGENTS.md 拿下了“共享基线”的位置。但 Claude Code 还没有原生跟上，所以现阶段正确的配置是：面向所有工具的 AGENTS.md，再配一个给 Claude 用的薄 CLAUDE.md shim。一个真理源、一个负责人、保持精简。

如果你的指令文件已经散落在两三个工具里，而团队没人说得清 Claude 到底在读哪个，这正是 CLAUDE.md 审计要解开的结 —— $299 个人版，$799 适用于 2–10 人团队。