AGENTS.md 有多普及？这问题我最近在好几个地方刷到，答案给得都挺干脆：6.2%。
九月十九号 dev.to 上那篇调查，GitHub 上扒了将近一千九百个仓库，一个一个数出来的。听着挺扎实。
可同一个调查里还躺着另一个数字：1.0%。
同一个文件，同一个人数的，同一套匹配规则。差六倍。
我第一眼看到这儿，脑子里只有一句——数错了吧。结果不是。两个数都是真的，而且作者自己清楚它们都是真的。
来，画开看看。差的不在分子，在分母。
先把两把尺子摆出来。这张图就讲一件事：同一份文件，两套框法。
stock rate （全部公共仓库，无权重抽样）
924 个仓库 ──► 9 个带 AGENTS.md ──► 1.0%
active rate （活跃仓库）
817 个仓库 ──► 51 个带 AGENTS.md ──► 6.2%
活跃的定义：最近九十天有推送、不是 fork、不是归档。
六倍差距的来源，作者一句话说穿了：GitHub 整体不是一片工地，是一座墓地。全部公共仓库里约 93% 超过九十天没推过东西，29% 是 fork，8.3% 根本是空的。
你在这个池子里随机撒网，捞上来的绝大多数是墓碑。在墓地里统计"有多少房子住着人"，数当然难看。这不是我编的比喻，是他写在文里的原话。
打个比方：stock rate 好比统计整座城有多少栋楼挂了门牌，active rate 好比只站在还亮着灯的工地上数。两个都成立，只是问的问题不一样。
这个比喻在哪儿漏风？亮灯灭灯是二值的，而"活跃"是一根连续的时间轴，九十天只是一刀。切在三十天和切在三百六十五天，出来的比率会完全不同。所以这两个数不是"真值"跟"偏差"的关系，是两把不同的尺子——谁也别拿自己那把去否定另一把。
作者自己把尺子分得挺清：stock rate 答"这做法是不是主流"，active rate 答"正在干活的项目有没有在用"，按创建年份的比率答"是不是在扩散"。引用哪个，取决于你想问哪个问题。不标尺子就引用，那才是问题。
我记到这儿的时候还挺得意，心想这不就是采样口径的常识嘛，标题上标一下分母就完事了。
等等等等，先别急。他接着往下讲"什么算命中"的时候，我坐直了。
大小写不敏感匹配坑了他一次。抽出来的命中里有一份 content/posts/agents.md——注意，是小写的 agents.md，属于一篇 2017 年的博客文章，标题叫 The Agents Are Coming。跟 agent 指令半毛钱关系没有，纯粹撞名。规则不看内容，直接算进去了。他自己把这条揪出来排掉，6.2% 降到 6.1%。
还有一个 vendored 副本。openshift/must-gather 的 vendor 目录里躺着一份 AGENTS.md，跟上游 openshift/build-machinery-go 根目录那份是同一个 blob（91c04f1f，1656 字节）。同一份文件，能在不同仓库里被各数一次。
顺手还有一条更狠的：如果只算根目录下的 AGENTS.md，不算 docs/、.github/、vendor/ 这些嵌套路径，活跃比率从 6.2% 掉到 5.6%，stock 从 1.0% 掉到 0.8%。"算不算子目录"这一条一改，又是两个新数字。
再叠上递归 tree API 的截断。评论区有位 ANP2 指出，目录树超过十万条目或 7MB 时会返回 truncated:true，只看那截数组，大仓库会被误判成"没有 AGENTS.md"。作者回去查了缓存里一千七百四十二个 tree 响应，真找到 5 个截断，活跃 frame 里 3 个、stock 里 2 个，这 5 个的截断部分都没 AGENTS.md 或 CLAUDE.md。然后他甩了个最坏边界：假设三个活跃截断各藏一个，活跃就是 54/817，6.6%——整件事在这个样本里最多动 0.4 个百分点。子模块不展开这一点他没修，同样会造成低估。
所以你手里拿到的不是"6.2%"，是一个范围，大概 2% 到 6%。这不是我替他打圆场——两个 frame 在一个 57 个仓库的子样本上给出 6.2% 对 1.8%，他在文里自己写：诚实答案落在这个区间。
我第一版理解这题的时候，以为关键是分母。画完才发现分母只是第一层。第二层是匹配规则有多宽，第三层是算不算嵌套路径。三层各拧一圈，同一个事实就摊出好几个数来。这就是我当时没画上的那一格。
咔哒一下扣上的那一下，不是"到底 6.2 还是 1.0"。✨
是任何一个"XX% 的仓库用了 YY"背后，都埋着三件事：分母是谁、匹配规则多宽、算不算嵌套路径。这三样任意换一个，同一个事实就能摊出好几个数。而这三件事，基本没有哪篇报道会写进标题。
我不觉得这是那篇调查的弱点，恰恰反过来。他干的是一件反直觉的事——把数出来的数字往下修，还把修的过程给你看。6.2% 到 6.1% 是排除撞名，6.1% 到 5.6% 是限定根目录，再往下是 vendored 副本。大部分人引用的时候，只会拿走最大的那个。
还有个跟比率无关的细节，我特别喜欢。
他扔出一大堆数字——活跃、stock、重叠率、文件陈旧度——然后在最后老实说：这些全是描述性的，我没有任何证据表明带 AGENTS.md 的仓库产出更好。
他连实验都设计好了：三臂，真实 charter、不附加任何文档、附加一份等长的无关文档。第三臂是为了把"更多上下文有用"和"这份文档本身有用"分开——这个设计比前两臂更见功力。指标也想清楚落好了：机械规则违规次数、返工轮次、盲评可用性子集。
实验还没跑。
所以你现在能看到的所有比率，都在回答"有多少"，没有一个回答"有没有用"。前者被引用得热火朝天，后者一片空白。这两个问题之间隔着一整个实验，而实验比数数难得多——数数只需要一次 API 调用，实验需要你先定义一个"更好"。
这玩意儿真的太酷了。一个普及率调查，认真做到最后，交出来的是一份"我还没测什么"的清单。
照例留个自检：下次有人甩给你一句"AGENTS.md 普及率 6.2%"，你能不能三句话内问出它的分母是谁、匹配规则多宽、算没算嵌套路径？问不出来，那数字就还没被你真正接住。
顺便，作者把抽样代码和完整报告都放仓库里了，随机种子写死 20260918。
下期想画开哪个概念，你说了算。
本期画开：百分比背后，永远站着一个你没看见的分母。