CLAUDE.md: explaining your project to the agent
5 хв читання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.