3.2
CLAUDE.md — The Map
Why this exists
This is the single highest-return file you will ever write. Fifteen minutes on it and you stop re-explaining yourself at the start of every session, permanently.
It's also the one people get wrong in a specific, predictable way — they write too much — and the damage from that is invisible, so it never gets fixed.
The idea
It's what you'd tell a new hire in their first two minutes.
CLAUDE.md sits at the root of your project and gets read every time, before anything else. That's the whole mechanism. You write it once; it's there in every session forever.
Which means the only real design constraint is length. It loads every time, so every word in it is a word competing with your actual question — and by 2.2 you know what that does. Four things belong in it, and nothing else:
| Part | What it says |
|---|---|
| Who and what | Who you are, what this project is. Two or three sentences. |
| What's here | The folders that exist and what's in them |
| Where to go | The routing table — that's 3.3 |
| How things are named | Your naming convention, so files can be found without a database |
The test: if it's longer than one screen, you have room-level detail hiding in it. Pull it out into a
CONTEXT.mdand the map gets its job back.
That test matters because the failure is silent. A bloated CLAUDE.md doesn't throw an error. It quietly loads three thousand words into every session you'll ever run, and the answers get a bit worse in a way you'd never trace back to a file you wrote once in week three.
Two more things worth getting right first time.
Write about the project, not about Claude. The instinct is to fill it with instructions — be concise, don't use bullet points, always check your work. Some of that is fine, but it should be the small end. Spend most of it describing the actual thing: what the project is, who it's for, what standards apply. Claude is good at working out how to behave when it knows what it's working on. It cannot guess what your project is.
Treat it as alive. It's the file you edit when the project changes, not a thing you wrote once. The most common version of a broken setup isn't a bad CLAUDE.md — it's an accurate one that stopped being true four months ago and is now confidently sending Claude to folders that no longer exist.
Do
Use the sketch from 3.1.
- Make a real project folder for something you actually do — not
sandbox. Something with a purpose. - Create
CLAUDE.mdat its root. - Write the four parts: - Who and what — two or three sentences. - What's here — the folders, one line each. - Where to go — leave a placeholder. You build this in 3.3. - How things are named — pick a convention and state it.
- Check the length. Does it fit on one screen without scrolling? If not, cut until it does.
- Now test it. Open a fresh session in that folder and ask:
based on what you know about this project, what am I working on and where would you put a new draft? - Read the answer. Anything wrong or missing is a gap in your map, not a mistake by Claude. Fix the file.
- Repeat step 5 once more after fixing.
Steps 5 to 7 are the actual lesson. A CLAUDE.md you wrote is a guess; a CLAUDE.md you tested is a map. That loop takes two minutes and almost nobody does it.
Done when
Never do
Don't let it grow past one screen. Every time you're tempted to add something, ask whether it's map or room. Map is where things are. Room is how this kind of work gets done. Almost everything you want to add is room.
Don't fill it with instructions about how Claude should behave. Describe the project. If you find yourself writing a fourth rule about tone, you're solving the wrong problem.