数据揭示：/init 生成的 CLAUDE.md 质量为何更高

8220 份来自 GitHub 万星仓库的 CLAUDE.md 文件被放上了同一把尺子——Reporails 的 ails check 评分体系。结果呈现出一种整齐的分层：那些由 Claude Code 的 /init 命令生成的文件，在每一个文件尺寸区间里都跑赢了其他文件。

一条不起眼的行，区分了两个群体

识别 /init 文件的方法出奇简单：它们的前 4000 个字符里包含这样一行——

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

在所有被评分的文件中，每五个就有一个带着这行标记，共 1641 个文件、分布在 1539 个仓库里。这些文件的中位数得分是 8.4（满分 10 分），而没有这行的文件是 7.7。差距不止在中位数上：六成的 /init 文件拿到 8 分及以上，非 /init 文件中这一比例不到一半。

考虑到短文件本身就更难积累问题项，研究者把 8220 份文件按大小均分成四组。结论没有变化——/init 文件在每个尺寸组里都领先，优势在 0.6 到 0.9 分之间。

CLAUDE.md 是 Claude Code 在启动时自动读取的项目级指令文件，放在仓库根目录，内容会作为系统提示的一部分注入上下文。/init 是 Claude Code 提供的一个内置斜杠命令，执行后 Claude 会扫描代码库，自动生成一份初始的 CLAUDE.md，其中通常包含构建命令、测试方式和项目结构说明。由于生成过程由模型完成，文件结构相对统一，也带上了一句固定的引导语。

Reporails 是一套面向 AI 指令文件的静态检查工具，ails check 是其命令行评分命令。它把 CLAUDE.md 这类文件解析成结构化的指令单元，再按若干维度打分：是否指明了具体文件或命令、是否包含可执行的代码块、规则之间是否自相矛盾、指令是否措辞模糊等。满分 10 分，分数越高意味着 agent 越容易准确执行。

地图优先，规则其次

Claude Code 的官方文档对 /init 的描述是："Claude 分析你的代码库，创建包含构建命令、测试指令和项目约定的文件。" 实际产出的文件确实符合这个定位。

/init 文件中大约五分之一的内容是在告诉 agent 该做什么，其余部分都在描述仓库本身：东西放在哪、每条命令执行什么、各部分如何衔接。相比之下，其他 CLAUDE.md 文件中指令占比接近十分之三——翻了一倍。

这种差异体现在结构上。87% 的 /init 文件包含 Architecture 部分，84% 包含 Commands 部分。而在非 /init 文件中，拥有这两个部分的比例都在五分之一左右。代码块的差距更加悬殊：近九成 /init 文件至少包含一个代码块，其他文件只有 44%。这个差距在所有尺寸组中稳定存在。

值得留意的是，这种"以仓库地图为主、规则为辅"的结构本身就贡献了一部分得分优势。646 个没有 /init 标记但同时拥有 Architecture 和 Commands 部分的文件，中位数为 7.9——高于普通非 /init 文件的 7.7，但低于 /init 文件的 8.4。这说明结构对了能提分，但 /init 的优势不全来自结构。

大型语言模型在处理长上下文时存在“迷失在中间”的现象：位于提示中段的信息容易被忽略，而开头和结尾的内容权重更高。因此，一份全是规则条目的 CLAUDE.md 并不一定比一份先描述仓库结构、再列出少量规则的文件更有效。

仓库地图的作用是给模型建立空间参照——告诉它哪些目录对应哪些功能、哪个命令做哪件事。当模型知道“测试在 tests/ 下，用 pnpm test 运行”时，后续遇到相关任务就能自行推断，而不需要为每种情形单独写一条规则。这也是 /init 文件得分领先的结构性原因：它把大量隐性知识转成了显式但紧凑的描述，减少了规则数量和相互冲突的概率。

少量规则，少量破绽

指令越少，出错的空间越小——数据支持这个直觉。

/init 文件在每一档尺寸中都更少出现"hedged instruction"（模糊指令，如使用 "should"、"try to" 这类措辞），也更少出现"never"与对应权限相互矛盾的写法（例如一边写着 "NEVER push to remote"，另一边又写着 "you can push if asked"）。禁止性指令在所有指令中的占比也更低：16.8%，而其他文件是 21.2%。

另一项指标同样指向这个方向：/init 文件中大约每四条指令有一条没有点名文件、命令或工具，其他文件则是接近每三条就有一条。

但有一项数据反向而行。由于 /init 文件以描述性内容为主，同一主题的叙述文字会紧挨着其指令出现，检查器会标记出"埋在描述中的指令"——/init 文件中每 100 条指令出现 17.7 次，其他文件为 10.5 次。在任何文件尺寸下，/init 文件在这一项上都没有优势。

“hedged instruction”指的是语气不确定的指令，例如“you should probably run tests”或“try to keep functions small”。这类措辞在人类协作文档里是礼貌，但对 agent 来说意味着执行边界模糊，模型可能选择性忽略，也可能过度执行。检查器会把这类措辞标记为潜在问题。

“埋在描述中的指令”则指一条本该独立成行的规则被夹在叙述段落里，例如在介绍构建流程时顺带写一句“不要修改 dist/ 目录”。模型在解析时可能把它当作背景信息而非必须遵守的约束。/init 文件因为描述性内容多，这类情况出现频率更高，是它唯一明显落后的指标。把这类规则单独拎出来、配上标题或加粗，就能消除这个隐患。

如何用好你自己的文件

如果你想知道自己的 CLAUDE.md 处于什么位置，可以运行：

head -5 CLAUDE.md
npx @reporails/cli check -v

第一条命令检查文件是否以 /init 的那行开头，第二条给出评分并逐条列出带行号的问题。再用 git blame CLAUDE.md 定位这些行是随初版文件一起进来的，还是后来手动添加的。

那行 /init 标记本身可以删掉——它被检查器当作描述性内容处理，删除不会对得分产生可测量的影响。真正值得保留的是它的结构：仓库地图、代码块中的命令、一小组规则。

这个模式同样适用于 AGENTS.md 或 GEMINI.md。格式是一样的：一张仓库地图，命令放代码块里，再配一份简短的规则清单。

当你需要手动添加规则时，有三个原则：给规则配上 /init 会提供的上下文，把命令放进代码块；如果是"绝不要"类的禁令，把允许的情形写得和禁止的情形一样清楚；解释文字保持简短——文件里已经够多了。

这一点在数据上尤其重要：六成 /init 文件是所在项目中唯一的指令文件，而非 /init 文件中这一比例只有三成。对很多仓库来说，那份仓库地图、命令和少量规则就是 agent 能获得的全部信息。Claude Code 文档在描述完 /init 后紧接着补了一句："在此基础上，用 Claude 自己发现不了的指令来完善它。" 那部分需要你手动写。

还有一个值得一提的数据：在全部 10000 个仓库中，最长的主指令文件达到 129121 个单词——它同样以那行 /init 标记开头。

AGENTS.md 和 GEMINI.md 是其他 AI 编码工具采用的同类约定文件。AGENTS.md 由 OpenAI 等团队推动，定位是跨工具的通用 agent 指令文件；GEMINI.md 则是 Gemini CLI 读取的项目上下文文件。它们与 CLAUDE.md 的格式要求基本一致：Markdown 编写、放在仓库根目录、启动时自动加载。

不同工具对文件名的偏好不同，但内容结构可以复用。如果仓库同时使用多个工具，可以维护一份主文件，再用符号链接或简短转发文件指向它，避免多份文件之间出现规则不一致。ails check 同样支持对这些文件评分，因此同一套改进方法可以迁移过去。