博客 · 2026-11-06

CLAUDE.md 和 AGENTS.md 放在同一个仓库：Claude Code 只读 CLAUDE.md，2,744 个两者都有的公开仓库里 1,072 个没把 AGENTS.md 传过去

从 2.1.277 起 Claude Code 能读 AGENTS.md，但只在没有 CLAUDE.md 的时候。2,744 个两个文件都有的公开仓库里，1,072 个在 AGENTS.md 里写了不同的说明，Claude Code 不会加载。在 2.1.314 上实测。

概述

如果你的仓库里同时有 CLAUDE.md 和 AGENTS.md，在 CLAUDE.md 里单独写一行 @AGENTS.md，或者让其中一个文件链接到另一个。

原因很简单。从 2.1.277（9 月 18 日）起，Claude Code 能读 AGENTS.md，也就是 Codex 等 agent 用的说明文件。但默认只在仓库里没有 CLAUDE.md 时才读它。两个都有时，Claude Code 加载 CLAUDE.md，AGENTS.md 不读，除非 CLAUDE.md 导入了它。

这会让多少说明漏掉？我们读了 5,864 个活跃公开仓库的说明文件。2,744 个两个文件都有。其中 1,072 个的 AGENTS.md 写的内容不一样，CLAUDE.md 既没导入它，也没链接到它。在这些仓库里打开 Claude Code，会话一开始就没有这份说明。

怎么测的

  1. 加载规则实测。 在四个空项目的 AGENTS.md 里放一个暗号，关掉读文件的工具，问 Claude Code 2.1.314（claude -p，Haiku）暗号是什么：
    • 有 CLAUDE.md 和 AGENTS.md，不导入：Claude 不知道暗号。
    • CLAUDE.md 里单独一行 @AGENTS.md：Claude 说出了暗号。
    • CLAUDE.md 里写成反引号包着的 `@AGENTS.md`：不知道暗号。文档写明代码片段里的导入会被跳过。
    • 只有 AGENTS.md：Claude 说出了暗号。
  2. 仓库样本。 和我们的项目设置调查同一批：5,864 个公开仓库，5 星以上，10 月 7 日以后有推送，排除 fork，截至 2026 年 11 月 6 日。每个都有 .claude/settings.json，也就是已经配置过 Claude Code 的仓库。我们按抽样时的提交下载了根目录的 CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md、AGENTS.md 和 .claude/rules/ 文件，共 15,063 个。
  3. 会话开始时加载什么。 照文档的规则算：根目录的 CLAUDE.md 系列文件，没有时换成 AGENTS.md；每个指向仓库内文件的 @path 导入，最多四层；没有 paths 字段的 rules。代码块和代码片段里的导入不算，块级 HTML 注释去掉，和文档说的一样。整个文件内容只是另一个文件路径的，算作链接。

测试结果

仓库里有哪些说明文件

仓库数（共 5,864）
根目录有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md4,709（80.3%）
根目录有 AGENTS.md3,333（56.8%）
两个都有2,744（46.8%）
只有 AGENTS.md，2.1.277 起 Claude Code 会读589（10.0%）
都没有566（9.7%）

两个都有的 2,744 个仓库，Claude Code 拿到 AGENTS.md 的内容了吗

仓库数
拿到：CLAUDE.md 导入了 AGENTS.md972
拿到：CLAUDE.md 是指向 AGENTS.md 的链接448
拿到：AGENTS.md 是指向 CLAUDE.md 的链接208
两个文件内容一样，没漏44
没拿到：内容不同，没导入也没链接1,072（39.1%）

这 1,072 个里，465 个在 CLAUDE.md 正文里提到了 AGENTS.md，Claude 照着那句话去打开时还能读到。另外 607 个提都没提。没被读到的 AGENTS.md 长度中位数 4,970 字符。有 12 个仓库把导入写在了反引号里，结果导入不生效。

每次会话一开始要加载多少

先猜一下：在你打第一个字之前，这些仓库通常往 Claude 面前放多少文字？在启动时会加载内容的 5,322 个仓库里，中位数是 9,766 字符，算上导入和 rules。10.4% 超过 40,000 字符，2.7% 超过 100,000。

根目录 CLAUDE.md 长度中位数91 行
根目录 CLAUDE.md 超过 200 行，也就是文档建议的上限24.5%
根目录 CLAUDE.md 超过 500 行6.4%
启动时加载的文件里至少有一个超过 200 行的仓库33.7%
有启动时就加载的 .claude/rules/ 文件（没写 paths）的仓库787
有只在碰到对应文件时才加载的 rules 的仓库79
子目录里有 CLAUDE.md 的仓库1,035（17.7%）
有指向仓库外的 @ 导入、需要你批准的仓库17

推荐

我们现在这样管理说明文件：

  1. 只留一份正本，然后导入。 如果 AGENTS.md 是共用的那份，就在 CLAUDE.md 开头单独写一行 @AGENTS.md，下面只放给 Claude 的补充。这一行不要包进反引号。
  2. 没人在 Windows 上 clone，才用链接。 ln -s AGENTS.md CLAUDE.md 能用，但文档提醒：Windows 上的 Git 没开 core.symlinks 时，会把软链检出成一行文字。那份 clone 里的 CLAUDE.md 就只剩一行 AGENTS.md。
  3. 或者改设置。 在 /config 里把 Project instructions 设成 claude-md-and-agents-md，两个文件都读，先读 CLAUDE.md。
  4. 看看实际加载了什么。 运行 /context all，看 Memory files 下面的列表。
  5. 长段落挪进只按路径加载的 rules。 文档建议每个文件不超过 200 行。带 paths 字段的 rule 只在 Claude 处理匹配的文件时才加载，而这批仓库里只有 79 个用了。

你常用的那个 agent 在你的仓库里读的是哪个说明文件？另一个文件里有没有写不一样的东西？

该忽略什么

把很长的 CLAUDE.md 拆成几个 @ 导入来省上下文。文档写明，导入的文件会和导入它的文件一起加载，拆分方便整理，加载的文字一样多。

HTML 注释。CLAUDE.md 里的块级注释在交给 Claude 之前就被去掉了，写给维护者的备注放在里面不占上下文。

局限

  • 都是配置过 Claude Code 的仓库。 样本里每个仓库都有 .claude/settings.json，比 GitHub 上的平均仓库用 Claude Code 用得更重。
  • 按默认设置算。 我们数的是 Project instructions 保持默认时加载什么。把它设成 claude-md-and-agents-md 的人两个文件都会读到。
  • 静态读取。 导入按文档的规则解析，四种情况在 Claude Code 2.1.314 上实测过；没有在每个仓库里真的打开 Claude Code。
  • 算的是字符，不是 token。 长度是去掉注释后的字符数。token 数取决于语言和模型。
  • 是样本。 5 星以上的活跃仓库，截至 2026 年 11 月 6 日，按代码搜索的相关度选出来，不是随机样本。

自己复现

计数在 claude-md-agents-md-2026-11.json 里，不含仓库名和文件内容。想查自己的仓库：在 AGENTS.md 里放一个暗号，打开 Claude Code，问它暗号是什么。

clone 一个仓库还会带来什么，见5,864 个公开仓库在 .claude/settings.json 里打开了什么。

来源

  1. Claude Code 文档：Memory（AGENTS.md、Import additional files、How CLAUDE.md files load、My CLAUDE.md is too large） · official
  2. Claude Code CHANGELOG，2.1.277：支持 AGENTS.md · official
  3. AgentCraft：信任一个 clone 来的仓库之前，先读它的 .claude/settings.json · blog