How to Write a CLAUDE.md That Actually Works

The trap: writing everything into it

The moment you understand what it's for, the temptation is irresistible: write everything into it. How you work, what you like, every exception, every edge case, the project's history.

And here's the counterintuitive part, the one worth the whole lesson: a longer file doesn't get followed better. It gets followed worse.

Two reasons, and you already know both. First: that file enters the working space at every session, so the longer it is, the more room it takes. Second, and more important: buried among two hundred lines, the three that actually matter carry less weight. The signal dilutes into the noise — exactly like in a conversation that's run too long.

The practical benchmark: under two hundred lines. If you're going over, you don't need more room: you need to cut.

Write things that are verifiable, not wishes

The difference between an instruction that works and one that's almost always ignored comes down to this: can you check whether it was followed?

• "Keep the files organized" → "New contracts go in Documents/Contracts/year, named client-date"

• "Write professionally" → "In emails: no exclamation marks, always close with name and role"

• "Be careful with numbers" → "Every total gets double-checked by adding it up again before writing it down"

The first ones are wishes: there's no way to know if they were honored, so there's no way to honor them. The second ones are checks.

What goes in and what doesn't

• Goes in: how your stuff is organized, naming conventions, things to always do, the commands you use, what things are called in your world.

• Doesn't go in: long step-by-step procedures. They take up room in every session even when they're not needed. There's a tool made just for those, and it's the chapter right after this one.

• Also doesn't go in anything that's obvious from looking at the folder: if it's visible on its own, writing it down is wasted space.

When you add a line

Not by anticipating. The file grows from experience, and the signal is precise:

• you've corrected the same thing for the second time;

• you've caught yourself typing in chat a sentence you'd already typed the session before;

• a new person, to do your job in your place, would have needed to know that exact thing.

If any of these is true, that line earns its space. Otherwise, wait.

Real maintenance is removing

There's a habit that sets apart people who use these tools well: they remove things every once in a while. Try deleting a rule and see if it gets that wrong again. If nothing happens, that line wasn't doing anything for you — and you were paying for it every session.

Two signs it's time to clean up: instructions that contradict each other (if two lines say opposite things, it'll follow one at random) and stale instructions, ones that describe how you worked six months ago.

What's next

I've said twice now that things "take up space", and I've been acting like you already know what space I mean. In the next lesson we actually look at it: the context window, meaning how much it can hold on the table at once.

Did you get it?

Two minutes, no grade. Trying to answer — even getting it wrong — cements the concepts far more than rereading. Not in the mood? Skip it: the lesson still counts as complete.

1A very long CLAUDE.md that explains everything: what happens?

Claude follows it better, because it has more information It takes up more space and the instructions get followed worse, not better Nothing changes, it gets read the same way

2Which of these two instructions is well written?

Keep the files organized and tidy New contracts go in Documents/Contracts/<year>, named client-date

3When is it worth adding a line to CLAUDE.md?

Before you start, anticipating everything that might be needed When you notice you've corrected the same thing for the second time