A CLAUDE.md file loads into every Claude Code session, so a good one compounds and a bloated one quietly costs you every task. Here are the best practices that actually move the needle, in the order they matter.
1. Keep it under about 200 lines
This is the one that fixes most broken CLAUDE.md files. Frontier models reliably follow only so many instructions, and Claude Code's own system prompt already spends part of that budget before your file is read. A 600-line CLAUDE.md is not six times as helpful. It is a file the agent skims, with your important rules buried somewhere in the middle. Lean is not a style choice here. It is what makes the file work.
2. Lead with behavior, not documentation
The single most common mistake is treating CLAUDE.md as a place for knowledge: architecture, full conventions, a pasted README. The agent already knows how to code. What it lacks is restraint. So the top of the file should be behavior rules, the things it would otherwise get wrong on instinct.
3. Only document what differs from the default
Every line you spend telling the agent something it already knows is a line stolen from the rules that matter. Do not tell it React uses components. Tell it you use named exports only, that you never add a dependency without asking, that tests live in a specific place. Context the agent could not guess, nothing it could.
4. Put the highest-priority rules first
The file is read top to bottom and the top gets the most consistent attention. If a rule is non-negotiable, it goes near the top, not on line 180. Order is a lever, so use it.
5. Treat it as a living file
The habit that compounds fastest: every time you correct the agent, add the correction as a rule so it never makes that mistake again. Over a few weeks your CLAUDE.md becomes a precise map of exactly how your agent tends to fail, and it stops failing that way. End your corrections with a plain instruction to update the file.
6. Commit it, and split personal from project
Project rules go in ./CLAUDE.md at the repo root, committed to git, so your whole team gets the same agent behavior instead of everyone tuning their own. Your personal defaults, the way you like the agent to work across every project, go in ~/.claude/CLAUDE.md and stay local to you.
The hard part is the phrasing
None of these practices are complicated. The work is in the wording: writing behavior rules an agent actually obeys, not ones it nods at and ignores, takes real iteration. That is what kitstarter is, a CLAUDE.md and a set of commands tuned so the agent asks before it builds and stays lean, ready to drop in. Write your own with the rules above, or start from one that already works.
Common questions
How long should a CLAUDE.md file be? Under about 200 lines. Past that the agent skims and your rules lose attention.
What is the most common mistake? Filling it with documentation instead of behavior. Lead with behavior rules; keep context to only what differs.
Should CLAUDE.md be in git? Yes for project rules (./CLAUDE.md). Personal defaults go in ~/.claude/CLAUDE.md, local to you.
A CLAUDE.md that already works
kitstarter ships the behavior rules and commands, phrased so your agent follows them, for Claude Code, Codex, and Antigravity.