If you have used Claude Code for more than a day, you have felt the tax: every fresh session, you re-explain your stack, your conventions, the things it keeps getting wrong. The CLAUDE.md file exists to end that. It is small, it is boring, and it is the single highest-leverage file in your repo.
What is a CLAUDE.md file?
A CLAUDE.md file is a markdown file that Claude Code reads automatically at the start of every session. It is persistent memory for a project: the rules, the context, and the commands the agent should carry into every task without being told. You write it once, commit it, and it loads every time. It is the only file that, by default, goes into every conversation.
Why one CLAUDE.md file went viral
Earlier this year a single CLAUDE.md file made the rounds because it did something most do not. It took a handful of observations about how AI agents fail, plan too little, assume missing details, overbuild simple tasks, touch files nobody asked them to, and turned them into plain rules the agent had to follow. It was not a list of your framework versions. It was a description of how to behave.
That is the whole insight. The default agent has strong instincts and no restraint. A CLAUDE.md full of project trivia does not change that. A CLAUDE.md full of behavior does.
What actually goes in a CLAUDE.md file
Think in three layers, in this order. The order matters, because the model pays the most attention to what sits near the top.
Notice what is not here: a wall of documentation, your entire architecture, a copy of the README. Those bloat the file, push the rules that matter out of the model's attention, and get ignored. A CLAUDE.md is not where knowledge goes. It is where behavior goes.
Write it so your agent follows it
A few rules that decide whether the file works or just sits there:
- Keep it lean, under about 200 lines. Models reliably follow a limited number of instructions, and Claude Code's own system prompt already spends some of that budget. A 600-line CLAUDE.md is a 600-line file the agent skims.
- Put the highest-priority rules first. The file is read top to bottom, and the top gets the most consistent attention.
- Only document what differs from the default. The agent already knows how to write React. Tell it the things it would otherwise get wrong about your project.
- Treat it as living. Every time you correct the agent, add the rule so it does not make that mistake again. That single habit compounds faster than anything else.
Put project rules in ./CLAUDE.md at the repo root so your team shares them through git. Put your personal defaults in ~/.claude/CLAUDE.md so they follow you across every project.
The shortcut: behavior, done for you
Writing good behavior rules is its own skill, and getting them phrased so an agent actually obeys takes iteration. That is the bet behind kitstarter: a CLAUDE.md and a set of commands that make Claude Code, Codex, and Antigravity ask before they build, stay lean, and stop looking AI-made, written down where the agent will read it. You can absolutely write your own. Start with the four behavior rules above, keep it under 200 lines, and add a rule every time it slips. If you want the phrasing that already works, we shipped it.
Common questions
Where does the CLAUDE.md file go? Project rules in ./CLAUDE.md at the repo root (shared via git); personal defaults in ~/.claude/CLAUDE.md. Both load automatically.
How long should it be? Under about 200 lines. Past that, the model starts skimming and your important rules lose attention.
What is the difference between CLAUDE.md and AGENTS.md? Same idea, different filename. AGENTS.md is the cross-tool convention several agents read; CLAUDE.md is Claude Code's. Many teams keep one and point the other at it. See our best-practices guide.
Skip the trial and error
kitstarter ships the CLAUDE.md and commands that make your agent ask first, stay lean, and not look AI-made.