选AGENTS.md还是CLAUDE.md？这592个顶级仓库实际上包含什么内容

Anthropic基于AI的软件开发生命周期指南将软件交付的六个阶段全部围绕编码智能体进行重组。第三阶段要求创建一个具体的文件：CLAUDE.md，这是一种仓库级知识文件，每当智能体重复出现相同错误时就会更新。一项针对评分最高的公共仓库的调查分析了这些建议在实践中的落实程度，结果令人意外——CLAUDE.md在文件数量上占优，但在内容质量上却处于劣势。

关键数据

2026年9月8日，有调查团队对从六种编程语言排名（TypeScript、Python、Go、Rust、Java和JavaScript，去重后）中筛选出的592个评分最高的仓库进行了检查，寻找CLAUDE.md及若干相关文件。

• 有165个仓库（27.9%）包含CLAUDE.md文件。
• 在这165个仓库中，有94个（57.0%）根本不包含任何仓库相关知识，只是重定向链接而已。

在这165个仓库中，有94个（57.0%）完全不具备相关知识储备，属于重定向链接。

209个仓库（35.3%）包含AGENTS.md文件，其中93.8%的文件含有实际内容。

在同时存在这两个文件的132个仓库中，有89个将CLAUDE.md指向AGENTS.md，仅有10个反向指向。

仅有5.9%的仓库拥有.claude/settings.json文件，该文件用于配置剧本的第三阶段钩子功能。

内容完整的CLAUDE.md文件的中位大小为3,934字节，最大的文件大小可达66,176字节。

排除那些重定向链接后，顶级仓库中仅有12.0%的仓库拥有包含实际内容的CLAUDE.md文件，而内容完整的AGENTS.md文件则出现在33.1%的仓库中。

对于现在就开始采用该指南的人而言，所得结论并不一致。智能体确实需要一个经过版本控制的完整知识文件，但该指南指错了文件名称。在各个代码库中，CLAUDE.md 已经演变成一个位于 AGENTS.md 之前的兼容层，而 AGENTS.md 是一种与供应商无关、能被所有主流编程智能体读取的文件。那些已经解决此问题的项目会将知识内容一次性写入 AGENTS.md，再留下一行指向该文件的说明。

统计方法

样本来源是GitHub上的公开排名快照，即六种语言中按星标数排序的前100个仓库，去重后共得到592个唯一仓库。我们从raw.githubusercontent.com的HEAD版本获取了一组固定的路径，无需API密钥、无需认证，也不进行爬取操作。只需判断文件是否存在以及内容是什么即可。随后下载了所有CLAUDE.md和AGENTS.md文件，共计242个仓库中的374个文件，并手动阅读。

但在阅读过程中问题出现了：CLAUDE.md文件的中位数长度仅为两行，因此仅从这一数据来看几乎无法说明任何问题，占比27.9%更显得毫无意义。

这些文件的内容

其中没有任何一种常见格式代表真正的知识：

• 一个 git 符号链接。该文件仅有 9 字节，内容为 AGENTS.md 这段文本，且没有结尾换行符，因为 git 会将符号链接存储为包含其目标路径的数据块。openclaw、dify、ant-design、moby、home-assistant、superset、Stirling-PDF 和 nushell 都是此类示例。
• 一行导入语句，即 @AGENTS.md，长度为 11 字节，Claude Code 在加载时会解析它。n8n、supabase、grafana、nuxt、storybook、prometheus、traefik、ruff 和 pdf.js 也是采用这种方式。
• 一句散文式文字。在 lazygit 中，它表示先读取 AGENTS.md 并按照其指示操作。Google Workspace 的 CLI 则以更长的文字表达了相同含义。

对于任何构建分类器的人来说，一些边缘情况都很重要。Docusaurus的格式是先有标题，再跟进口令，除此之外没有其他内容。Jest则指向.github/copilot-instructions.md文件。Ansible由三行导入语句组成，没有正文内容。Zed则链接到一个名为.rules的文件。

排除了所有仅包含重定向指令的文件后，592个仓库中有71个拥有包含仓库相关信息的CLAUDE.md文件，占比为12.0%。这71个文件都是真实存在的，其中一些规模较大：中位数大小为3,934字节，第90百分位数为19,506字节，最大值为66,176字节。像bun、pytorch、swc、gstack和3x-ui这样的项目都维护着真实的操作指南，内容包括构建命令、仓库结构图、测试理念以及目录级规则。

知识实际存储的位置

在AGENTS.md中，这一差距更为明显。其实际使用率为93.8%，209个文件中有196个使用了该文件，而CLAUDE.md的这一比例仅为43.0%。正是这种差异揭示了问题所在：创建AGENTS.md的仓库几乎总会为其填充内容，而创建CLAUDE.md的仓库则往往只是作为通往其他地方的桥梁。

那些同时包含这两个文件的132个仓库进一步明确了这种差异：

• 其中89个仓库中，CLAUDE.md起指引作用，AGENTS.md则存储实际内容。
• 有10个仓库的角色相反：AGENTS.md负责重定向，而CLAUDE.md才是真正的文件，Pytorch、bun、milvus、anki和litellm都属于这类仓库。
• 31个仓库在两个文件中都保留了实际内容，这意味着相同的机构知识被重复保存了两次。
• 还有2个仓库在两个文件中都设置了指引，这表明还存在第三个文件。

因此，流量大致以九比一的比例流向与供应商无关的文件格式。这种单向分布往往只是测量带来的假象，所以人们特意去寻找相反的情况。虽然存在这种情况，但仅占少数。

各语言的采用情况

不同语言之间的差异足够大，可以据此制定计划。CLAUDE.md的采用率居首，AGENTS.md位居其次：

• TypeScript：46.5%和53.5%。
• Rust：33.3%和43.4%。
• Go：32.3%和37.4%。
• Python：25.5%和31.6%。
• JavaScript：19.0%和23.0%。
• Java：10.3%和22.7%。

在所有语言中，AGENTS.md 的普及率均居首。Java 的差距最为明显，拥有 AGENTS.md 的仓库数量是拥有 CLAUDE.md 的两倍多，而 TypeScript 项目拥有 CLAUDE.md 的概率则是 Java 项目的四倍以上。在这六种语言中，43.2% 的顶级仓库都存在某种代理指令文件，无论是 AGENTS.md、CLAUDE.md、.cursorrules 还是 Copilot 的指令文件；其中包含 Copilot 指令文件的仓库占比为 9.3%。而 .cursorrules 这一格式的普及率则几乎为零，仅为 0.5%，这很好地说明了特定供应商的习惯能多快消失。

Stage-3 技术栈的其他组件

平台团队应仔细阅读这部分内容。该方案要求的不仅仅是知识文件：它还将知识文件、技能以及钩子功能结合在一起，而钩子功能正是用于在构建过程中阻止危险操作的强制执行层。

在592个仓库中，仅有35个（5.9%）存在.claude/settings.json文件，而同时包含CLAUDE.md文件的仅有32个（5.4%）。人们采用的是那种任何人都可以编写的文档文件，而真正能够限制智能体行为的那层强制机制，则仅存在于大约1/18的仓库中。那些依赖hook来实现安全功能的方案，目前几乎还无人实现。

数据的局限性

• 这些样本来自按星标排序的公开仓库。类似这样的方案实际上被部署在无法查看的私有企业仓库中，因此那里的采用率可能更高且更为规范。
• 这只是一个在2026年9月8日HEAD状态下获取的单一快照。技术采用速度很快，一个月之内这些百分比就会失准，因此趋势比具体数值更为重要。

一个文件本身并不能说明什么。一份内容完整的CLAUDE.md仅能表明有人编写了它，却无法证明有人在维护它，也无法说明智能体的输出质量有所提升。已有研究质疑这类文件是否真的能帮助编码智能体，而这一指标对此毫无说明。

settings.json文件只是钩子的代理指标，并非全面统计。在其他位置定义的钩子将不会被记录，因此5.9%只是一个最低数值。

指针内容边界的具体划分属于主观判断。在剔除标题、导入代码及重定向语句后，剩余的冗余文本约为120个字符。距离该阈值最近的14个文件经过了人工审核，其中最接近“实质性内容”标准的文件lazydocker实际上包含172个字符的真正构建标志。调整阈值会改变这一数值。通过对25个仓库的实时文件进行二次核查，发现错误仅出现在某一方向：当重定向语句是以对代理的指令形式表述而非像zeroclaw那样说明文档位置时，分类器偶尔会将此类重定向误判为实质性内容。因此57.0%是一个下限，实际的指针内容占比略高一些。

还有一处差点被采用的失误值得提及。首次统计显示27.9%的顶级代码库已采用CLAUDE.md，相关数据本应被公布，但两行数据的中位数导致了这一结果未能呈现。

实际解决方案

内容应存储在哪个文件中？证据表明AGENTS.md更为合适，而CLAUDE.md则可仅作为引用。132个双文件代码库中有89个就是如此处理的。知识内容只保留一份，那些不会搜索特定Claude文件名的智能体依然能够读取它。

Claude Code会直接读取AGENTS.md吗？与CLAUDE.md不同，它并不遵循这种命名规则，正是由于这一差异才出现了指针模式。实际上有两种可行方式：一种是创建名为CLAUDE.md的git符号链接，指向AGENTS.md；另一种是使用@AGENTS.md导入方式。new-api项目在其自身的CLAUDE.md中甚至提醒，这种导入方式并不总能可靠地加载文件，并建议让代理程序直接打开该文件。

27.9%的采用率是好还是坏？对于如此新近出现的规范而言，这一比例高于预期，但低于相关指南所暗示的水平。还有两个数据更能说明问题：12.0%的仓库拥有包含实际内容的CLAUDE.md文件，而仅有5.4%的仓库会将此类文件与强制执行钩子结合使用。

为何会有31个仓库同时保留这两个内容相同的文件？目前尚未对副本之间的差异进行过测量，这显然是下一步需要研究的问题。一旦副本内容出现不一致，重复的机构知识就会变成负担，而相关工具也不会发出任何警告。

其他人能重复这项研究吗？可以。数据样本来自一个公开的明星排名系统，检测方式只是向raw.githubusercontent.com发送未经认证的HTTP请求，而分类器仅由大约40行代码构成。

对于那些使用编码代理管理仓库的人，还有一个最后的检查点：上次构建命令发生变化时，该代理的知识文件是否也在同一次提交中更新，还是过三次会议后才出现过时的命令？