Claude Code /init files out-score other CLAUDE.md files 8.4 to 7.7 in a scan of 8,220
Files seeded by Claude Code's /init scored a median 8.4 against 7.7 for other CLAUDE.md files in Reporails' scan of 8,220 files. Only about a fifth of an /init file is instruction, against close to three in ten elsewhere.
The Engineer · Build desk
Key figures: 646 CLAUDE.md files without the /init line that have both an Architecture and a Commands section score a median 7.9. Among /init files, 87% have an Architecture section and 84% a Commands section.
| Figure | Value | Note | Claim |
|---|---|---|---|
| 646 files without the /init line, with both sections | 7.9 median score | 2 | |
| With Architecture section | 87% of /init files | 7 | |
| With Commands section | 84% of /init files | 7 |
What happened
- About one in five of the 8,220 files has the /init marker line: 1,641 files in 1,539 repos.
- Split into four equal size groups, the /init files lead in every group, by 0.6 to 0.9 points.
- The layout repeats: 87% of /init files have an Architecture section and 84% a Commands section, against about one in five of the others.
Why it matters
- constraint Findings are counted per 100 directives, and the lead is credited to having fewer rules to get wrong. The score cannot tell a team whether a file gives an agent enough direction.
- exposure For the six in ten /init files that are a repo's only instruction file, the map, the commands and a handful of rules are everything the agent gets.
- decision The scan classes a file by that one line, so a heavily rewritten file stays in the /init group only while the line stays. Group comparisons say little about a file a team has reworked.
The checker counts findings per 100 directives and constraints [13]. Against that yardstick, /init files trigger two kinds of finding less often at every file size. Fewer carry a hedged instruction such as "should" or "try to". Fewer carry a "never" written more strongly than the permission beside it, like "NEVER push to remote" next to "you can push if asked" [11]. Prohibitions are also a smaller share of their instructions, 16.8% against 21.2% [12].
"Fewer rules leave fewer places for a rule to go wrong," the post's authors at Reporails wrote [10].
That puts the hand edit in an awkward spot. Claude Code's docs say /init creates "a file with build commands, test instructions, and project conventions it discovers" [15]. The next line hands the rest to the user: "Refine from there with instructions Claude wouldn't discover on its own." [16] Every rule you add is a new place for a finding. We think the edit is still right. The score describes file text, and the post does not report how agents behave with either kind of file.
One finding runs against /init files. A file that is mostly description puts prose on the same topic next to its instructions, and the checker flags an instruction buried in it [8]. The rate is 17.7 per 100 instructions in /init files against 10.5 elsewhere, about 1.7 times [24]. A rule written into an Architecture paragraph is that case. We would put new rules in a short list of their own, with the command in a code block and the case where the agent may act written as clearly as the case where it may not [17].
Reporails says you can delete the /init line. The checker reads it as description, and removing it costs nothing the authors can measure [1]. Some of the lead survives without it. Of the files that lack the line, 646 have Architecture and Commands sections both, with a median score of 7.9 [2]. That recovers 0.2 points of the 0.7-point gap, about 29% [22], and leaves 0.5 points the section pair does not explain [23]. The subset is picked on shape, so it is not a controlled comparison.
For the medians to transfer, your file has to look like the population. They come from the 10,000 most-starred repos in a September 2026 snapshot, and the checker has been updated since, so a file scored today may differ a little [18]. Match the size band as well. The four groups were cut at 37, 75 and 137 items [19].
The line records how a file started. The longest main instruction file in all 10,000 repos, at 129,121 words, opens with it [20].
To see where a file stands, `head -5 CLAUDE.md` shows whether it started from /init, and `npx @reporails/cli check -v` scores it and lists each finding with its line number. Running `git blame CLAUDE.md` on those lines shows whether they came with the first version [21].
What to watch
- A later run of the checker on the same repos, to see whether the 0.7-point lead holds under the updated rules.
- Any change to what /init writes. The docs now describe build commands, test instructions and conventions, not rules.
- Any study that ties these file scores to how agents actually behave, which the post does not report.
Clarity's read
What the record supports and how the coverage leans. The claims behind it follow.
Reality
- Evidence45
- Adoption20
- Hype gap+10
- Incentives60
- Confidence55
Claim ledger
Ranked by verification strength, evidence, and original report placement.
- [1]
You can delete the /init line. The checker reads it as description; it marks how the file started, and removing it costs nothing Reporails can measure.
- [2]
646 CLAUDE.md files without the /init line have both an Architecture and a Commands section, and their median is 7.9, above the 7.7 of all files without the line and under the 8.4 of files with it.
- [3]
Reporails scored 8,220 CLAUDE.md files from the 10,000 most-starred repos on GitHub for its Q3 report.
- [4]
On the ails check 0 to 10 scale, the median score of files seeded by /init is 8.4, against 7.7 for the rest.
- [5]
Splitting all 8,220 files into four equal groups by size, /init files lead in every group, by 0.6 to 0.9 points.
- [6]
One in five of the files has the /init line at the top. /init files are CLAUDE.md files with the /init line in their first 4,000 characters: 1,641 files in 1,539 repos.
- [7]
87% of /init files have an Architecture section and 84% a Commands section; among the other files about one in five has each.
- [8]
A file that is mostly description puts prose on the same topic next to its instructions, and the checker flags an instruction buried in it: 17.7 times per 100 instructions in /init files, against 10.5 elsewhere. At no file size do /init files come out ahead on this finding.
- [9]
About a fifth of what an /init file says tells the agent what to do, and the rest describes the repo; in other CLAUDE.md files the share of instructions is close to three in ten.
- [10]
Fewer rules leave fewer places for a rule to go wrong, and the findings show it.
- [11]
At every file size, fewer /init files carry a hedged instruction ('should', 'try to'), and fewer carry a 'never' written more strongly than the permission that goes with it, like 'NEVER push to remote' next to 'you can push if asked'.
- [12]
Prohibitions are 16.8% of the instructions in /init files, against 21.2% in other files.
- [13]
Finding rates count findings per 100 directives and constraints.
- [14]
Six in ten /init files are the only instruction file in their setup, against three in ten other CLAUDE.md files, so for many repos the map, the commands and a handful of rules are everything the agent gets.
- [15]
Claude Code's docs describe /init: 'Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers.'
- [16]
Right after describing /init, the Claude Code docs add: 'Refine from there with instructions Claude wouldn't discover on its own.'
- [17]
Advice for adding a rule by hand: give it the command in a code block, as /init would; if it is a 'never', write the case where the agent may as clearly as the one where it may not; keep the explanation around it short.
- [18]
The scores are from the September 2026 snapshot run covering 10,000 of the most-starred GitHub repos and 15,237 agent setups; the checker has been updated since, so your own file may score a little differently.
- [19]
File-size groups cut at 37, 75 and 137 items.
- [20]
The longest main instruction file in all 10,000 repos, at 129,121 words, opens with the /init line.
- [21]
head -5 CLAUDE.md shows whether a file started from /init; npx @reporails/cli check -v scores it and lists each finding with its line number; git blame CLAUDE.md on those lines shows whether they came with the first version of the file or were added later.
- [22]
The Architecture-plus-Commands subset without the /init line recovers about 29% of the median gap.
- [23]
The subset with both sections still sits 0.5 points below files with the /init line.
- [24]
Buried-instruction flag rate in /init files is about 1.7 times the rate in other files.
- [25]
The median score gap between /init files and other files is 0.7 points.
Get this ledger inside ChatGPT. Ask about any of our stories and the answer brings its figure, each claim’s verdict and the sources. Free, no account.
Sources
1 independent publisher whose own reporting we read for this story.
- dev.toState of AI Instruction Quality: /init Files Score Higher
1 article · October 14, 2026
Topics and entities
Follow any of these and your For You feed starts watching them — no settings page required.