What a CLAUDE.md file is for
A CLAUDE.md file sits at the root of your repo and gets loaded into Claude Code's
context automatically on every session. Think of it as the onboarding doc you wish
every new contributor read before touching the code — except this one is read every
single time, without fail.
The mistake people make is treating it like a README. A README explains the project to humans who will read it once. A CLAUDE.md gives an agent the rules it must follow on every task. The difference is subtle but it changes how you write.
Keep it short and specific
Every line in your CLAUDE.md competes for the model's attention with the actual task. A 2,000-line file full of aspirational guidelines is worse than a 60-line file with the five commands and three conventions that actually matter.
Prefer concrete over abstract:
- Bad: "Follow good testing practices and aim for high quality."
- Good: "Run
npm run testbefore every commit. Co-locate specs as*.spec.ts."
If a rule can't be acted on, it doesn't belong there.
Put the commands up top
The single highest-value thing you can add is the exact commands to build, test, and
lint. Agents waste turns guessing whether it's npm test, yarn test, or just test.
Tell them once:
npm run dev # start the dev server
npm run build # production build (also type-checks)
npm run test # run the test suite
This one section saves more back-and-forth than anything else.
Write rules as "always" and "never"
Claude follows imperative instructions well. State non-negotiables plainly:
- Never commit directly to the default branch — branch first.
- Always validate Server Action input with Zod before using it.
- Never expose the service role key to the client.
Sharp, testable statements beat soft suggestions. "Try to avoid" gets ignored under pressure; "never" does not.
Split large rule sets into files
When your conventions grow, don't cram everything into one file. Break domain rules into separate files (testing, security, database, UI) and let the root CLAUDE.md point to them. This keeps each file focused and makes the rules easier to maintain — you edit the security rules without scrolling past the CSS conventions.
Let it evolve
The best CLAUDE.md files are living documents. When you catch the agent making the same mistake twice, that's a signal: add a line so it doesn't happen a third time. Over a few weeks the file converges on exactly the guardrails your project needs.
Thanks for reading — more soon.