调查显示六分之一同时含 CLAUDE.md 和 AGENTS.md 的仓库中 Claude Code 从不加载 AGENTS.md

2026年10月18日发布 · 2026年11月14日更新 2026年10月18日，我们Harbor（gethrbr.com）从公开的GitHub仓库中抓取了3,905个CLAUDE.md和AGENTS.md文件，并用与我们的免费规则文件检查器相同的检查项逐一运行。有四项结果值得注意。 GitHub代码搜索统计到公开仓库中有839,680个CLAUDE.md文件和1,142,784个AGENTS.md文件，不含fork。一次搜索最多返回1,000条结果，按GitHub自身的相关度排序，因此我们把每个文件名拆成十个大小区间，从不足500字节一直到384 KB——GitHub能索引的最大文件。 我们从每个区间取前100条结果，再从其内部一个随机窄大小窗口中另取100条。我们按GitHub索引时的提交抓取每个文件，并按GitHub对该区间的计数为每个区间加权。这里的百分比就是这些加权后的估计值。GitHub的计数本身也是估计值，所以每个数字请按正负一两个百分点的误差来理解。 配对是从AGENTS.md一侧读取的。对于仓库根目录下的每个AGENTS.md，我们在同一提交下抓取紧邻它的CLAUDE.md（如果存在）：共745个仓库。搜索几乎从不返回符号链接文件，然而紧邻AGENTS.md的CLAUDE.md中近四分之一是符号链接，所以从CLAUDE.md一侧入手会漏掉它们。 默认不会加载。Anthropic的记忆文档说，如果你启动所在的文件夹或其上层目录中有CLAUDE.md、.claude/CLAUDE.md或CLAUDE.local.md，Claude只读取你的CLAUDE.md文件。这种情况很常见：仓库根目录下36%的AGENTS.md旁边有一个CLAUDE.md。这些CLAUDE.md就是如此处理它的。 这16%中有一部分是刻意的：其中少数AGENTS.md写明是为Codex、Cursor等工具编写的，Claude由它自己的文件覆盖。无论刻意与否，Claude和Codex随后就在同一个仓库里依据不同的规则工作，加到其中一个文件里的规则只能到达部分agent。 句子形式的写法是人们以为会生效的那种。诸如“Read AGENTS.md before starting any task”这样的一行是纯文本，不是导入。文档说，在这种设置下，Claude只有在决定打开该文件时才会看到AGENTS.md。 发生漂移的副本失效得更慢。两个文件最初是同一个，有人编辑了其中一个，而两个文件都没有说明哪一个是当前版本。当CLAUDE.md包含AGENTS.md的部分行、但缺失至少五行且缺失不超过90%时，我们把这一对计为已漂移。 修复只需一行：在CLAUDE.md顶部单独一行写@AGENTS.md，任何Claude专属内容放在它下面。符号链接也可以，但Anthropic指出，未启用core.symlinks的Windows克隆会把它检出为一个单行文本文件。各种模式和陷阱见“Claude Code会读取AGENTS.md吗”。 CLAUDE.md的中位行数是81行，十分之一超过309行。19%超过了Anthropic文档设定的200行目标，4%超过500行。Anthropic的理由是遵循度：文件越长，占用的上下文越多，被遵循的程度越低。 AGENTS.md文件更短，中位数为63行，不过18%超过200行。该先删什么见“CLAUDE.md应该多长”。 这一项不需要抽样。GitHub的计数是30,080个AGENTS.md文件超过32 KiB，占全部文件的2.6%；超过24 KiB的有51,840个——再多一个嵌套文件就会让仓库越过上限。 Codex从根目录向下合并AGENTS.md文件，并在默认32 KiB处停止添加（project_doc_max_bytes）。其余内容永远到不了模型，而在我们的测试中终端什么也没说。删减文件，或在~/.codex/config.toml中提高上限。详情见“Codex为何忽略AGENTS.md”。 关于概览的研究见“AGENTS.md有用吗”。 有四篇研究论文研究同样的文件。它们问的是文件里有什么、如何变化，或者是否有帮助。本研究问一个更窄的问题：文件究竟有没有到达agent。从它们的摘要看，这四篇都没有检查紧邻AGENTS.md的CLAUDE.md是否会加载它，也没有检查有多少文件通过了Codex的大小限制。 各样本在规模、来源和日期上不同，因此各行之间的百分比不可比较。上下文文件究竟是否对agent有帮助是另一个问题，见“AGENTS.md有用吗”。 本页每个数字都在一个CSV中，并附有其背后的样本或计数：claude-md-agents-md-study-2026-10-18.csv。它只包含汇总数据，不含仓库名称。方法见“我们如何抽样”，重新运行会使加权数字移动一两个百分点，因为每个区间都会抽取新的随机窗口。 引用格式：Harbor, “We checked 3,905 CLAUDE.md and AGENTS.md files on GitHub”, October 18, 2026, https://gethrbr.com/blog/claude-md-agents-md-github-study。 规则文件检查器会对你粘贴的文件运行本研究中的每一项检查，并说明哪些agent会加载它。它在你的浏览器中运行，你粘贴的任何内容都不会离开页面。 两个逐渐漂移分开的文件是更广泛问题的一个版本：团队的规则存在于多个地方，每个agent读取的是不同的子集。Harbor维护一套团队规则，并把同样的规则提供给Claude Code、Codex和Cursor。 是的，截至2026年11月arXiv上有四篇：253个CLAUDE.md文件（2509.14744）、466个带AGENTS.md的项目（2510.21413）、2,303个上下文文件（2511.12884），以及一项在124个pull request上对有和没有AGENTS.md的agent进行的测试（2601.20404）。它们研究内容和效果；本研究检查文件是否到达agent。 默认不会。如果启动所在的文件夹或其上层目录中有CLAUDE.md、.claude/CLAUDE.md或CLAUDE.local.md，Claude Code只读取CLAUDE.md文件。在CLAUDE.md中单独一行写@AGENTS.md，或让CLAUDE.md成为指向AGENTS.md的符号链接。 2026年10月18日，GitHub代码搜索统计到公开仓库中有1,142,784个AGENTS.md文件和839,680个CLAUDE.md文件，不含fork。GitHub的计数是估计值，其索引会跳过超过384 KB的文件。

（原文较长，此处译出前 6000 字，完整内容请点「打开原文」。）