CLAUDE.md: explaining your project to the agent

5 min read

CLAUDE.md sits in the project root and loads automatically. It's the place for rules you'd otherwise repeat in every task — and that the agent will break if you don't write them down.

What to put in it

What the project does not use. “No styled-components”, “no shadcn/ui” — otherwise the agent brings them in from a ready-made snippet, because that's what the internet does.
Non-obvious traps. Places where it's easy to get it wrong and where the mistake isn't visible right away: duplicated markup, files that must change in pairs, the order migrations run in.
The commands that check the work. What to run before committing: types, tests, build. Then the agent checks itself without being reminded.
Rules about money and access, if you have them. That's where a mistake costs the most.

What to leave out

Anything visible from the code. The agent will read your folder names and components itself, and they'll go stale faster than you update them.
Generalities like “write clean code” and “follow best practices”. That's a wish, not a rule, and nothing can be checked against it.
Long architecture write-ups. The file is read every time, and the longer it is the worse it works. Keep it to a screen or two.
Secrets. Keys, passwords, internal hostnames — never.

How to tell a rule is needed

If you've explained the same thing twice across different tasks, it belongs in CLAUDE.md.
If the agent did something wrong and you corrected it, write down not the correction but the rule behind it.
A good rule says why, not just what. “Rows of buttons need flex-wrap, otherwise they run off the edge at 360px” works better than “use flex-wrap”.

A sample structure

A short description of the project: what it is and what it's built on. Two or three lines.
A section on what the project doesn't use.
A section per area where it's easy to get things wrong.
The commands to run before committing.