The CLAUDE.md files that started from Claude Code's /init score higher than the rest, at every file size.
You can tell them by the line /init puts at the top:
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
We scored 8,220 CLAUDE.md files from the 10,000 most-starred repos on GitHub for the Q3 report. One in five has that line. On ails check's 0 to 10 scale, their median is 8.4, against 7.7 for the rest. Six in ten of them score 8 or above. Of the rest, fewer than half do.
A short file has fewer chances to pick up findings, so we split all 8,220 into four equal groups by size. The /init files lead in every group, by 0.6 to 0.9 points.
A map, then a few rules
Claude Code's docs describe what /init produces: "Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers."
That's what the files look like. About a fifth of what an /init file says tells the agent what to do. The rest describes the repo: where things live, what each command runs, how the parts fit together. In other CLAUDE.md files, the share of instructions is close to three in ten.
The layout repeats from repo to repo. 87% of /init files have an Architecture section and 84% a Commands section. Among the other files, about one in five has each. Nearly nine in ten /init files carry at least one code block, against 44% of the others, and that gap holds at every file size.
Where its rules go wrong
Fewer rules leave fewer places for a rule to go wrong, and the findings show it. 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". Prohibitions are also a smaller share of their instructions: 16.8%, against 21.2%.
About one instruction in four still names no file, command or tool, against nearly one in three in other CLAUDE.md files.
One finding runs the other way. A file that's mostly description puts prose on the same topic right 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 one.
What to do with yours
You can delete the line. The checker reads it as description. It marks how the file started, and removing it costs nothing we can measure.
Keep the shape. It does some of the work: 646 CLAUDE.md files without the line have both an Architecture and a Commands section, and their median is 7.9. That's above the 7.7 of all files without the line, and under the 8.4 of files with it.
The same shape works in an AGENTS.md or a GEMINI.md: a map of the repo, its commands in code blocks and a short list of rules. We measured it on CLAUDE.md because that's the file /init leaves a marker in.
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. Right after describing /init, the docs add: "Refine from there with instructions Claude wouldn't discover on its own." That's the part you write by hand. When you add a rule:
- Give it what
/initwould have: the command, in a code block. - If it's a "never", write the case where the agent may as clearly as the one where it may not.
- Keep the explanation around it short. The file already has plenty.
To see where your own file stands:
head -5 CLAUDE.md
npx @reporails/cli check -v
The first command shows whether your file started from /init. The second scores it and lists each finding with its line number. Run git blame CLAUDE.md on those lines to see whether they came with the first version of the file or were added later.
One more thing about the line. The longest main instruction file in all 10,000 repos, 129,121 words, opens with it too. That one is in the habits post.
From The State of AI Instruction Quality: Q3 2026: 10,000 of the most-starred GitHub repos, 15,237 agent setups, September 2026 snapshot. Scores are from that run; the checker has been updated since, so your own file may score a little differently.
/init files are CLAUDE.md files with the /init line in their first 4,000 characters: 1,641 files in 1,539 repos. Counting every instruction file, 1,604 repos carry the line. File-size groups cut at 37, 75 and 137 items. Finding rates count findings per 100 directives and constraints, the same denominator as the report.
Counted per repo instead of per file, the gap narrows as setups grow, from 1.3 points in the smallest quarter of setups to 0.2 in the largest. The Architecture-and-Commands shape accounts for part of the gap; the files alone don't show what accounts for the rest.
I work on Reporails, deterministic diagnostics and governance for the instruction files, rules, and prompts that steer coding agents. If your CLAUDE.md started from /init, it starts from the shape that scored higher here. Reporails reads the rest of what you wrote, measures which instructions couple to behavior, and points to the lines worth tightening.
Top comments (2)
The Architecture-plus-Commands pattern is actionable, but the content-dilution result is a good warning. A repository could test this by giving an agent two equivalent instruction files—one monolithic and one with a short task index linking to details—and measuring whether it finds the relevant command without violating a scoped rule.
The reason Architecture plus Commands holds up across scale is that commands give the model mechanical targets it can verify against shell exit codes.
When instruction files bloat with procedural advice like 'write clean code' or 'check your work carefully', the model treats them as conversational tone rather than invariants. You end up burning prompt cache space on guidance that has no falsifier in the repo.
The pattern that survived in my own agent workflows is treating the instruction file strictly as environment topology. That means the exact entrypoint scripts, the test runner invocation with flags, and the directories where writes are forbidden. If a rule cannot fail a build or trigger a linter error, it usually belongs in a human PR review rather than the context window.