CLAUDE.md Isn’t Enough. The Three-File Pattern Every Project Needs.
A CLAUDE.md that grows past 200 lines is almost always doing three jobs at once — entry, routing, and state — and each one wants a different reload cadence.
My CLAUDE.md hit 412 lines before I noticed what it had become.
Originally, the file was a clean entry doc: who I am, what the project is, what the non-negotiable rules are. Then I added a routing section. Then a status section. Then today’s task list. Then a list of conventions. Then a few “remember to do this” notes. Each addition felt small. Each made the file roughly 30 lines longer.
By the time I caught it, every new session opened by Reading 412 lines of mostly-irrelevant context. The file was the most-read artifact in the project, and almost none of it was load-bearing for whatever I was doing that morning.
That’s when I split it.
The three jobs CLAUDE.md was secretly doing
A CLAUDE.md that grows past 200 lines is almost always doing at least three jobs at once.
Entry. Identity and non-negotiables. Who you are, what the project is, what rules apply across every session. Stable. Changes maybe twice a quarter.
Routing. Where to look for what. “For task type X, load files A and B.” A decision tree that grows as the project gains modes. Changes whenever you add a new kind of work.
State. What’s happening right now. Active threads, next moves, what just shipped, what’s blocked. Changes every session.
Three jobs, three reload patterns, three reasons for the file to grow. Combined into one file, every reason to update any one section means the whole file gets longer and the whole file gets re-Read.
That’s a 200-line file becoming a 400-line file in three weeks. None of the growth is wrong individually. The aggregation is the bug.
The split
CLAUDE.md — the entry. Identity, project frame, non-negotiable rules. Read first, every session. Stable across weeks. Target length: under 100 lines. If it crosses 150, something else has crept in.
CONTEXT.md — routing. “For task X, load A and B. For task Y, load C.” Decision tree. Read as a slice, only the relevant branch. Reloads when the project gains a new mode (a new task type, a new worker, a new artifact class). Target length: under 200 lines, structured so any single branch is around 30 lines.
STATUS.md — state. Active threads, next moves, blocked-on items, recently shipped. Read in full at session start. Written at session end. Reloads every single time. Target length: under 60 lines, with older items rolling to an archive.
Three files, three jobs. Each file has one reason to grow and one reason to be Read.
How each gets used in a session
The read patterns are the point. The split only pays off if the load behavior changes too.
CLAUDE.md — Read once at session start. Stays in context. You don’t re-Read it.
CONTEXT.md — Read as a slice. Grep the header for the task type, Read with offset and limit to pull only that branch. Never Read the whole file. The branches that aren’t relevant don’t enter the session’s context.
STATUS.md — Read fully at start. The “what’s the live state” question is exactly what this file answers, and the file is short enough that reading it fully is cheaper than slicing. At session end, the part of the session that ships, dispatches, or shifts a thread gets one line appended.
The result: a session opens with maybe 150 lines across the three files instead of 400 lines in one. The relevant routing slice adds another 30. Total entry cost: 180 lines, of which every line is load-bearing.
Markers — your CLAUDE.md is doing too much
If any of these are true, the split is overdue.
The file is longer than 200 lines. Most reliable signal. CLAUDE.md only stays under 200 lines if you’ve been actively separating concerns. If it grew past that, growth has been mixing jobs.
The file contains current status updates. Anything starting with “as of [date]” or “currently working on” is state. State doesn’t belong in entry.
The file contains a routing decision tree. Anything that branches by task type belongs in CONTEXT.md. If a section starts “for X, do Y; for A, do B,” it’s routing.
The file contains a task list or todo. Today’s work is state. Today’s work also doesn’t survive the week. Neither belongs in the file that gets Read every session.
When any of these hit, the split is small surgery. Cut the routing section into a new CONTEXT.md. Cut the state section into a new STATUS.md. Leave CLAUDE.md with the entry job only. The work takes an hour. The cost was running every session.
This pattern is the project-level cousin of Article 1’s role-boundary rule. There, the boundary was between orchestrator and worker. Here, the boundary is between three different jobs the project doc was quietly carrying. Both fix the same class of bug: one artifact doing too many things, getting too long, costing context the work doesn’t need.
(The brief is the per-dispatch equivalent of STATUS.md. Article 8 unpacks that one.)
What I’m giving you, and what I’m not
You have everything you need to apply this: the three file roles (entry, routing, state).
The target lengths per file.
The read patterns per file.
The four over-loading markers.
What I’m not giving you: my CLAUDE.md, my CONTEXT.md, my STATUS.md. They’re full of project-specific content and internal references that don’t generalize. The structure travels. The contents won’t.
A weekend’s work to split. The first session afterward will feel different.