CLAUDE.md, measured
Every guide to this file argues about how long it should be, and none of them counted. We counted: 843,944 public CLAUDE.md files, of which the median runs 88 lines and 51.6% have been committed once and never edited since.
What CLAUDE.md is
CLAUDE.md is a plain markdown file that Claude Code loads into context at the start of every session. It holds the things about your repository a model cannot infer from the code: which test command is the real one, which directory is dead, which conventions the team enforces in review. Claude Code reads it from your home directory, your repository root and, on demand, from subdirectories, and concatenates all of them rather than letting the nearest one win.
It is guidance, not enforcement. Anthropic's documentation says so directly, and that one sentence explains most of the disappointment people report with it.
How long should it be?
The advice in circulation ranges from 60 lines to 300. Here is where the files actually sit.
88 lines
The median public CLAUDE.md. Half are shorter, and the median word count is 533.
n = 680, weighted to the full population
0.9%
Exceed 64KB. The bloated CLAUDE.md is real and it is rare, which makes it a bad thing to design your file around.
Census of all 843,944 public files
16.5%
Are under a kilobyte, roughly a dozen lines. The common failure is a file too thin to change anything, not one too fat to read.
Census of all public files
HumanLayer's guidance, cited in Google's own AI Overview for this query, puts the ceiling at about 300 lines and the ideal under 60. The median file lands between those two numbers. Their reasoning is sound: frontier models follow somewhere around 150 to 200 instructions reliably, and Claude Code's system prompt has already spent some of that budget before your file is read.
Length is the wrong variable to optimise, though. A 200-line file of corrections specific to your repository outperforms a 60-line file of advice that would be true of any repository. The question to ask of each line is whether a competent engineer new to the codebase would get it wrong without being told. If not, delete it.
What people put in it
Sampled across the size distribution, then weighted so each size bucket counts for its real share of the population.
| Contains | CLAUDE.md | AGENTS.md |
|---|---|---|
| Median length | 88 lines | 67 lines |
| Median word count | 533 | 402 |
| Median headings | 11 | 7 |
| Names a test command | 40% | 35% |
| Names a build command | 23% | 19% |
| Names a lint command | 29% | 28% |
| Sets code style rules | 47% | 51% |
| Sets commit or PR rules | 25% | 41% |
| Mentions secrets or security | 24% | 30% |
| References the other file | 15% | 9% |
Two gaps stand out. Three in five files never name the test command, which is the single instruction that most reliably stops an agent inventing one. And CLAUDE.md carries commit or PR rules far less often than AGENTS.md does (25% against 41%), even though those rules are exactly what a reviewer notices when an agent gets them wrong.
How Claude Code resolves the files it finds
This is the part people get wrong, and it differs from every other tool that reads a file of this shape.
Claude Code looks in four places: a managed file from managed-settings.json, ~/.claude/CLAUDE.md for your personal preferences, ./CLAUDE.md or ./.claude/CLAUDE.md in the repository, and ./CLAUDE.local.md for anything you do not want committed. Files in subdirectories load on demand, when Claude reads a file that lives there.
Then comes the part worth knowing: all discovered files are concatenated into context rather than overriding each other. The AGENTS.md convention is the opposite, where the nearest file wins. So a rule you wrote in your home directory a year ago does not get replaced by the repository's file. Both arrive, and if they disagree, the model resolves the contradiction however it likes. Run /doctor prompt-audit when an instruction is being ignored and you want to see what actually reached the context window.
What about AGENTS.md?
With an AGENTS.md and no CLAUDE.md, Claude Code reads AGENTS.md. With both present, it reads CLAUDE.md only, unless you change the project instructions setting to claude-md-and-agents-md. The workaround most teams land on is a one-line CLAUDE.md that imports AGENTS.md, which keeps a single source of truth. See our AGENTS.md reference for how the other tools handle the same file.
| Tool | Reads | When it finds more than one |
|---|---|---|
| Claude Code | CLAUDE.md, or AGENTS.md when no CLAUDE.md is present | Concatenates every file it finds, root first |
| Codex, Jules, Aider, Zed and 19 others | AGENTS.md | Nearest file in the tree wins |
| Cursor | .cursor/rules/*.mdc, plus AGENTS.md | Frontmatter decides: always, glob-matched, agent-picked or manual |
| GitHub Copilot | .github/copilot-instructions.md, AGENTS.md, CLAUDE.md | Nearest AGENTS.md wins; personal beats repo beats org |
Where it stops working
The file is context. The model reads it, weighs it against everything else in the window, and decides. Anthropic puts it plainly:
Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.
Anthropic, Claude Code memory docs
The file as written just seems to assume an authority that open source software explicitly relinquishes.
FeepingCreature, lobste.rs
At some point, you will end up in a situation where Claude Code cannot read it because it's too large.
Stanislav Silin, dev.to
So the rule that must never break does not belong in this file. It belongs in a PreToolUse hook, which runs before the action and can refuse it outright. Guidance in markdown, enforcement in code, and the two are not interchangeable no matter how emphatically the markdown is worded.
The second failure is quieter
We pulled the commit history for 246 repositories with a root CLAUDE.md. 51.6% of those files have exactly one commit, written once and never revised. Meanwhile 74% of the repositories kept pushing code for at least a month afterwards, with a median gap of 88 days between the last edit to the file and the last push to the repository. The codebase moved and the file describing it did not.
That is the honest case against writing one, and it is the harder problem. A file nobody updates is worse than no file, because the agent trusts it.
A CLAUDE.md worth committing
Six things a competent engineer would get wrong on their first day. Nothing that can be read off the code.
## Commands- Tests: make test (not go test ./..., which skips the fixtures)- One test: go test -run TestName ./internal/pkg/- Lint before pushing: make lint ## Conventions- Pass ctx first on anything touching the database.- Errors wrap: fmt.Errorf("doing X: %w", err).- No new HTTP client without the audit transport. CI blocks it. ## Landmines- internal/legacy/ is dead. Do not extend it.- Migrations need a matching .down.sql or the deploy fails.Each line names a thing that costs a review cycle when it is missed. None of them tells the model to write clean code or think step by step, because a model that needs to be told that will not be saved by being told.
What people ask first.
What is a CLAUDE MD file for?
Telling Claude Code the things it would otherwise guess wrong. Across 680 files we measured, the most common contents are project structure (71%), the commands to run (60%), how testing works (48%) and code style (43%). The file is read at session start, so it is the cheapest place to put a correction you would otherwise retype every morning.
Is CLAUDE MD really useful?
It is useful for anything Claude gets wrong repeatedly, and useless as a rule book. Anthropic's own documentation is blunt about the limit: Claude treats the file as context, not enforced configuration, and points you at a PreToolUse hook when an action must be blocked regardless of what the model decides. Write guidance in the file. Put the non-negotiable in a hook.
How long is too long for a CLAUDE MD?
The median public CLAUDE.md is 88 lines and 533 words, which is shorter than the argument about bloat suggests. Only 0.9% of the 843,944 files we counted exceed 64KB. HumanLayer's widely quoted advice, keep it under 300 lines and ideally under 60, sits just below where most repositories actually land. Length is the wrong variable anyway: a 200-line file of specific corrections beats a 60-line file of generic advice.
Why not use CLAUDE MD?
Two reasons hold up. It is Anthropic-specific, so a team running Codex or Cursor alongside Claude Code ends up maintaining the same rules twice, which is the problem AGENTS.md exists to solve. And it rots: 52% of the files we sampled were committed once and never edited again, while 74% of those repositories kept shipping code for a month or more afterwards.
How we measured this. Measured 28 September 2026 against the public GitHub corpus. Size distribution from code search result counts across 17 size buckets, which covers every public file rather than a sample. Content from 40 files per bucket, 680 per filename, reweighted to that distribution. Upkeep from the commit history of 246 root-level files per filename. Private repositories are out of reach, and code search ranks by popularity, so the upkeep figures describe repositories with some traction rather than the long tail.
Counts are from a single day, and the corpus grows weekly, so treat the shares as stable and the absolute counts as a floor.
The file goes stale.
Trail keeps it current.
Trail reads your commits, your PR history and the corrections you keep repeating, then proposes the rules worth writing into CLAUDE.md. You approve each one. The rules that must never break become hooks instead of notes.
Or read how Trail works for coding agents first.