The CLAUDE.md that got too big

My CLAUDE.md hit 600 lines before I admitted there was a problem. This is the field note on how a Router file quietly turns into a dumping ground, how I noticed, and the rule I keep now so it doesn't happen again.

The symptom: the agent started missing things

It crept up. Every time something went sideways, I added a rule to CLAUDE.md so it wouldn't happen again — a convention here, an edge case there, a hard-won gotcha. Each addition felt responsible. Sensible, even.

Then the agent started missing things that were in the file. It would violate a rule sitting in plain text on line 380. It would ignore a convention I'd carefully written down. I was adding more rules, and compliance was getting worse, not better. That's the tell I'd learn to recognise: when the agent stops following a file you keep adding to, the file is too full to read.

The cause: everything lived in one file

The problem was exactly the thing I tell other people to avoid. I'd treated the Router as a vault — the one file I knew the agent read, so I put everything in it. Six hundred lines of rules, conventions, gotchas and history, all in the front door.

But a long file gets skimmed, not absorbed. Past a certain length the agent stops retaining it — the same finding the research on context files for agents keeps landing on. I'd made the most important file the least readable, one responsible addition at a time.

Stuart Leo

Every line I added to keep the agent in line made every other line less likely to be read.

The refactor: route, don't duplicate

The fix took an hour. I went through the 600 lines and asked of each block: is this an essential the agent needs every time, or detail that belongs in a linked doc?

• The conventions moved to docs/05-reference/, with one pointer left behind.
• The gotchas moved to docs/03-knowledge/gotchas/, with one pointer.
• The decisions moved to their own file, with one pointer.
• What stayed: the overview, the handful of truly non-negotiable rules, the "where things go" map, the common commands.

CLAUDE.md went from 600 lines to about 70. Nothing was lost — it just moved to where it belonged, with the Router pointing at it. The agent could read the whole front door again.

The rule I keep now

Two rules, actually:

1. The Router stays short enough to read in full — a screen or two. If it's longer, something needs to move out.
2. When I reach to add detail, I add a pointer instead. New convention → a reference file, linked. New trap → a gotcha file, linked. The Router gains a line, never a paragraph.

When the agent starts missing things, the Router is usually too full to read. Now I keep it lean on purpose.

Start here: read the Router file, line by line, how to write an AGENTS.md that agents follow, or read the method.