The CLAUDE.md file: 431 lines from a running project
By Marco Kohns, Co-founder of ENLIX, lecturer in AI and growth
· 11 min read
CLAUDE.md is a Markdown file in your project root that Claude Code reads at the start of every session. What belongs in it is whatever you would otherwise explain again every time. Most guides answer the question of what you could put in there. The harder question is what earns a line, and that can only be shown on a file that has been running for months.
Ours is 431 lines long and steers the site you are reading. That makes it more than twice the target length Anthropic names in its own documentation. Below is what those 431 lines consist of, which rules in them name a cost anyone can count, and why we break the recommended ceiling on purpose.
What is the CLAUDE.md file?
A Markdown file of instructions that Claude Code reads at the start of every session, because every session begins with an empty context window. It carries what the code does not say: why a decision was made the way it was, which command builds the project, which part has broken before.
Anthropic's memory documentation names four occasions to add a line: Claude makes the same mistake a second time, a code review catches something Claude should have known about this codebase, you type the same correction you typed last session, or a new teammate would need the same context. All four have one shape: something has already happened. None of them reads "write down how you like to work".
Next to it sits auto memory, which Claude maintains itself. The split is clean: you write CLAUDE.md, Claude writes auto memory. Both load at the start of a session, and both are context rather than a guarantee.
Where does the file go, and which ones apply at once?
In the project root, as ./CLAUDE.md or ./.claude/CLAUDE.md, and from there into version
control. Three further scopes apply at the same time, loaded in this order, broadest first:
| Scope | Location | For |
|---|---|---|
| Managed policy | /etc/claude-code/CLAUDE.md on Linux, separate paths on macOS and Windows | What IT sets for everyone |
| User | ~/.claude/CLAUDE.md | Your preferences across all projects |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md | The team, shared through Git |
| Local | ./CLAUDE.local.md, added to .gitignore | Your notes on this one project |
The sentence that matters most sits in the documentation and gets skipped often: all discovered files are concatenated, not overridden. No scope replaces the one above it. What sits closer to your working directory is read last, and where two instructions contradict each other, the documentation says Claude may pick one arbitrarily. Two rules that disagree are therefore worse than a missing one.
Files in subdirectories behave differently from the ones above you: they do not load at launch,
only once Claude reads or edits a file in that subdirectory. Whether a file actually loaded is
answered by /context, under "Memory files". That check is the difference between "the rule is
written down" and "the rule arrived".
What belongs in it and what does not?
In it goes what applies in every session and cannot be derived from the code: build and test
commands, project layout, conventions, architectural decisions with their reasons. Out of it goes
anything that matters for one part of the codebase only, and anything that is a multi-step
procedure. Those belong in skills and in path-scoped rules under
.claude/rules/, which use a paths frontmatter field to load only when Claude touches a
matching file.
The documentation hands you a wording test that is shorter than any checklist: write instructions
concrete enough to verify. "Use 2-space indentation" instead of "Format code properly". "Run
npm test before committing" instead of "Test your changes". An instruction whose compliance you
cannot look up is one you cannot enforce either.
We put a second test next to it, which comes out of daily operation and is harder: a rule may stay if it names an incident that has already cost something. Everything else is a wish list. The difference looks harmless in the file and less so in practice:
Two ways a line gets into the file
Step only a person can supply
From the wish list
- You write down how work should be done
- The rule stays general
- Nobody can check whether it was followed
- It stays in place long after it stopped applying
0 of 4 steps need a person
From an incident
- Something breaks and costs time or money
- You find the cause
- The rule names the cause and the price
- It comes out once the cause is gone
3 of 4 steps need a person
Both routes produce a line. Only the second produces one you can delete again later.
The second route has a property the first one lacks: the rule carries its own expiry date. If the line says why it exists, you can check in six months whether the reason still holds. If it does not, the line stays forever and spends context every session.
What does a CLAUDE.md look like after months in operation?
Mostly not like a style guide. It looks like architecture. We measured this repository's file on 21 October 2026: 431 lines, 3,836 words, 6 top-level sections and 7 second-level ones. The weight sits like this:
Lines per section in our CLAUDE.md
Own measurement on 21 Oct 2026 of CLAUDE.md in the enlixai/enlix-academy repository. 431 lines in total.
| Architecture | 260 lines |
|---|---|
| Design system | 65 lines |
| Preamble before any heading | 35 lines |
| Hard rules | 33 lines |
| What this is not | 14 lines |
| Open items | 10 lines |
| Gotchas | 8 lines |
Sixty percent of the file describes how the application is put together and where it is fragile. The section holding the style rules is the second smallest. That is the opposite of what most templates suggest, and it follows automatically once rules only ever come from incidents: incidents happen at interfaces, not at indentation.
The same file carries 27 lines that state a prohibition, meaning they contain a "never", a "do not" or a "must not". Twelve of those rules name a specific incident with a number or an error message. Those twelve are the core of the file, and they are the reason it is not shorter:
| What the rule forbids | What it cost before |
|---|---|
Reading searchParams, cookies() or headers() in a page component | A 97x spike in Vercel CPU time on another project |
| Importing the Supabase client into the header component | 74 kB of auth library in the shared chunk of every page |
| Offering a GET endpoint for checkout | 75 genuine Stripe sessions minted by corporate mailbox link scanners, and zero humans |
| Writing quiz answers into named columns | Columns that drifted until q10_flow_state held goal text |
| Adding a parameter to an existing RPC | PostgREST then answers every call with PGRST203 |
Creating a discount as percent_off instead of amount_off | 50% of 3999 is 1999.5, which cannot be charged |
Running next build while next dev is running | A blank page and __webpack_modules__[moduleId] is not a function |
| Adding an RLS policy to fix a failing read | Direct access is rejected with 42501; the route is an RPC |
| Computing the Digistore24 signature instead of pinning the documented one | Ten days of retries and not one buyer gets access |
| Restoring the light theme | The assumption behind it was never tested: 1 session, 1 lead, 0 purchases |
| Serving German pages under an English root layout | Until 2 Oct 2026 every German page carried lang="en" |
| Dropping back to next 15.1.x | A vulnerability rated critical |
Each of those lines runs two to four lines in the file, because the price is written next to it. Without the price they would be twelve one-liners, and every one of them would read like a matter of taste.
Why is this file twice the recommended length?
Because we know the cost and pay it, which is different from never having read the ceiling. The documentation names a target of under 200 lines per file and gives a clear reason: longer files consume more context and reduce adherence. Both are true.
File size against the documented target
Target per code.claude.com/docs/en/memory, retrieved 21 Oct 2026. Our own file measured the same day.
| Our CLAUDE.md | 431 lines |
|---|---|
| The architecture section alone | 260 lines |
| Anthropic's target per file | 200 lines |
The chart also shows the way out. What pushes the file over the line is not the twelve expensive
rules, it is the 260 lines of architecture description. That is exactly what .claude/rules/
exists for: a path-scoped rule loads only once Claude touches a matching file, and the database
layout does not need to ride along in every session where somebody edits a heading.
Two routes that do not work, so you do not have to try them. The first is moving text out behind
an @path import: imported files load at launch too, the file looks shorter and the context cost
stays the same. The documentation says so explicitly. The second is shortening by cutting the
reasons. Nobody can delete a rule that has no reason attached, and a file nothing ever falls out
of keeps growing in a straight line.
What can a CLAUDE.md not do?
It cannot enforce anything. That is not a wording problem, it is the design: Claude treats these files as context and not as enforced configuration. Blocking an action regardless of what the model decides takes a PreToolUse hook. The more specific and concise an instruction is, the more consistently it is followed, but "more consistently" is not "always".
That implies a division of labour worth keeping. What hurts when it slips through belongs in a
test or a hook. What merely annoys belongs in CLAUDE.md. On this project the build itself is the
check for the most important rule: every marketing route has to stay static, and npm run build
stops when a page turns dynamic. The sentence in CLAUDE.md explains the why; the check makes the
mistake impossible.
Second, the file cannot clean itself. For that there is /doctor prompt-audit: Claude scans your
instruction files for contradictions, for references to files that no longer exist, and for rules
written for older models. You get a report with proposed edits, and nothing changes until you ask.
How do you start?
With /init in a session. Claude reads the project and writes a first version with the build
commands, the test instructions and the conventions it finds. If the file already exists, /init
proposes improvements instead of overwriting it.
After that the automation stops, and it stops in a sensible place: /init can write down what is
in the project, but not what cost you hours last Tuesday. Those lines come out of operation, one
at a time, always on the day something goes wrong. Our file grew from 414 to 431 lines across four
days in early October, not in a tidy-up session but in five separate commits alongside the actual
work.
A workable order for the first weeks: run /init, use /context to confirm the file is being
loaded, and from then on add one line every time you type the same correction twice. Where that
sits in the wider learning path is in Learn Claude Code; which surface
sees which files at all is in Claude Code CLI. What the session looks
like in which you type that same correction for the first time is in
your first session with Claude Code.
If you would rather walk through this on a running project with somebody who paid for the twelve rules above: that is the third block of The Claude Code System.
Frequently asked
What is the CLAUDE.md file?
A Markdown file in your project directory that Claude Code reads at the start of every session. It holds what the code cannot tell you: build commands, architectural decisions, conventions, and the things a new teammate would be told on day one. Anthropic's own documentation calls it context, not enforced configuration.
Where does the CLAUDE.md file go?
In the project root, as `./CLAUDE.md` or `./.claude/CLAUDE.md`, and from there into version control so the team shares one file. Three further scopes sit alongside it: an organization-wide managed policy file, your personal `~/.claude/CLAUDE.md` across all projects, and a `CLAUDE.local.md` you add to `.gitignore`. All discovered files are concatenated, not overridden.
How long should a CLAUDE.md be?
Anthropic names a target of under 200 lines per file, because longer files consume more context and reduce adherence. Our project file is 431 lines, more than double that. It is a deliberate deviation and not a free pass: the way back is `.claude/rules/`, not deleting rules.
How do I create a CLAUDE.md?
Run `/init` in a session. Claude analyses the codebase and writes a first version with build commands, test instructions and the conventions it finds. If the file already exists, `/init` suggests improvements instead of overwriting it. Everything after that comes out of daily operation, not a template.
What does not belong in a CLAUDE.md?
Anything that only matters for part of the codebase, and anything that is a multi-step procedure. Those belong in skills or in path-scoped rules under `.claude/rules/`, which load only when Claude touches a matching file. And anything that has to block: that belongs in a PreToolUse hook or a test, not in a sentence.
Keep reading
How to learn Claude Code: four steps, in this order
Not the feature list, the learning order. Four steps with a stop criterion each, measured against the rules file that runs this website.
19 October 2026
Claude Code Skills: When a Skill, When the CLAUDE.md
A skill is a folder with a SKILL.md in it. What belongs inside, where it has to live, and what measuring our own library turned up.
25 September 2026
Claude Code CLI: Terminal, IDE, Desktop or Web?
Four surfaces, one program. Which one to use for what, decided on 224 commits from our own repository.
5 October 2026
