TokenPlus

一份说明书喂两个 agent：AGENTS.md 和 CLAUDE.md

更新·markdown 原文

我核了一遍官方文档，结论跟中文社区流传最广的那句话正好相反，而且这个错不会报错——它只是让你的说明书安静地没被加载。

传得最广的那句话是错的

搜「AGENTS.md CLAUDE.md 区别」，排在前面的中文文章基本都写着同一句：

Claude Code 同时读取 CLAUDE.md 和 AGENTS.md，两者内容会合并。

Claude Code 官方文档的原文是：

Claude Code reads `CLAUDE.md`, not `AGENTS.md`.

读的是 CLAUDE.md，不读 AGENTS.md。 一个字的余地都没留。

这个错之所以难发现，是因为它的表现不是报错，是什么都没发生：你写了一份很用心的 AGENTS.md，Claude Code 启动，一个字都没读到，然后照着它自己的默认习惯干活。看起来就像「它不听话」。

我在写这几篇的仓库上就撞到了。 这个项目只有 AGENTS.md，没有 CLAUDE.md——会话启动时它没有出现在加载列表里，我是后来手动读的文件。如果我没手动读，那份写了几百行的红线和判据，等于不存在。

怎么验：一条命令

/context

看 Memory files 那一栏。列在里面的才是真加载了的。没列出来的文件，Claude 看不见——不管它写得多好，放在多正确的目录。

排查「说明书不管用」的第一步永远是这个，不是改文案。

怎么修：两种，都一行

一、在 CLAUDE.md 里导入（推荐，跨平台）：

@AGENTS.md

## Claude Code

`src/billing/` 下的改动一律先走 plan mode。

Claude 在会话开始时加载被导入的文件，然后接着读下面的内容。Claude 专属的东西写在导入下面，通用的留在 AGENTS.md 里，两边不用抄两遍。

二、软链接（不需要加 Claude 专属内容时）：

ln -s AGENTS.md CLAUDE.md

成功时没有任何输出。下一次会话跑 /context 确认 CLAUDE.md 出现在 Memory files 里。

Windows 上建软链接要管理员权限或开发者模式，所以在 Windows 上直接用第一种。

为什么会有两份文件

AGENTS.md 是开放标准。 2025 年 8 月由 OpenAI、Google、Cursor 等一起发布，现在挂在 Linux 基金会的 Agentic AI Foundation 下面，二十多个工具认它——Codex、Cursor、Aider、Copilot 等等。它的价值就是「一个名字，所有工具都认」。

CLAUDE.md 是 Claude Code 的原生格式，功能更全：@path 导入、.claude/rules/ 目录、paths: frontmatter 做路径范围限定、CLAUDE.local.md 私有层、claudeMdExcludes 排除。这些在 AGENTS.md 里都没有对应物。

所以不是二选一，是一个当共同底座，一个当 Claude 侧的扩展。

两份怎么分工

一条线就够：跟工具无关的进 AGENTS.md，只有 Claude Code 认的进 CLAUDE.md。

进 AGENTS.md进 CLAUDE.md（导入之后的部分）
项目是什么、红线、口径plan mode 用在哪些路径
构建和测试命令.claude/rules/ 的组织方式
目录约定、命名约定哪些 skill 该在什么时候调
踩过的坑和判据子代理/worktree 的用法

别把同一条规则抄两份。 两处不一致的时候，Claude 会任意挑一条走，而且不报错——这跟 CLAUDE.md 内部规则打架是同一个失败模式。

/init 会读别的工具的规则

跑 /init 生成 CLAUDE.md 的时候，它会顺带读走这些并把相关部分并进去：

从别的工具迁过来的仓库，这是最省事的起点——但它是一次性的合并，不是持续同步。之后 AGENTS.md 再改，CLAUDE.md 不会跟着变。想要持续同步，还是回到上面的 @AGENTS.md 导入。

一个容易忽略的副作用

@AGENTS.md 这种导入不省 context——被导入的文件在启动时全量加载，跟直接写在 CLAUDE.md 里占的 token 一样多。导入解决的是组织问题，不是体积问题。

所以那条 200 行的建议是对加载进来的总量说的。AGENTS.md 本身也得瘦。要真减体积，得用 paths: 限定范围的 rules，或者把多步流程搬进 skill——CLAUDE.md 到底该写什么那篇讲了取舍判据。

参考