What CLAUDE.md actually is
CLAUDE.md is loaded into context when a session begins and stays resident for the rest of that session. It is the first thing the agent sees and the thing it weighs against every later instruction. That makes it powerful - and it is exactly why it is so easy to ruin.
The most useful mental model is institutional memory, not a prompt. A prompt is a one-shot request you tune for a single answer. CLAUDE.md is the standing context every session inherits: how this repo is built, how it is laid out, and the norms a new teammate - human or agent - would need on day one. Write it for the next session, not for the current message.
Keep it lean - this is the whole game
The single most important rule is length. A CLAUDE.md that fits in roughly under 200 lines gets read end to end. One that runs to many hundreds of lines does not get the attention you imagine - the agent skims, weights the top, and effectively ignores half of what you wrote. A long file does not give Claude more guidance. It gives it less, because the important rules are now buried in noise.
So prune ruthlessly. Every line competes for attention with every other line, and with the actual work. If a sentence is not earning its place, it is costing you the lines around it. When you are tempted to add a paragraph, ask whether it belongs in CLAUDE.md at all, or somewhere the agent can read it only when relevant.
Turn “must always happen” rules into hooks
A large share of bloated CLAUDE.md files are really a pile of rules that must fire every single time - “always run the linter after editing,” “never commit to main,” “format before you finish.” Those do not belong in prose at all. An instruction is a request the model may or may not honor under load; a Claude Code hook is deterministic code that runs no matter what the model is thinking. Anything that must always happen should be a hook, not a line.
Moving those rules out does double duty: the behavior becomes reliable instead of hopeful, and CLAUDE.md gets shorter, which makes the rules that remain more likely to be read. Hooks and a lean instruction file are two halves of the same idea - shape behavior on purpose rather than hope for it.
Structure the file so it can be scanned
A good CLAUDE.md reads like a short reference, not an essay. A structure that holds up across projects:
- Build & commands - how to install, run, test, lint, and build. The handful of commands the agent needs constantly, stated once and correctly.
- Architecture & layout - where things live and how the pieces relate, so the agent does not have to rediscover the repo every session.
- Conventions - the patterns this codebase actually follows: naming, error handling, the libraries you prefer and the ones you avoid.
- Norms - the working agreement. What goes straight to main versus a branch, what requires review, what the agent should never do without asking.
Headings and short lists matter here because the agent, like a person, locates the relevant section rather than re-reading the whole file. This is a core part of good Claude Code practice generally, and it starts the moment you do your project setup.
Push the long stuff out of the file
Some context genuinely is long - a detailed package contract, a sprawling style guide, the deploy runbook. The fix is not to cram it in. Keep CLAUDE.md at the root lean and let it point outward: a per-package CLAUDE.md for a workspace that needs its own rules, or an import of a longer doc the agent reads only when it touches that area. Things that must run every time still belong in a hook or in settings.json and your permission allowlist, not in prose. The root file stays a map; the detail lives where it is relevant.
Treat CLAUDE.md as a living document. When a convention changes or a decision is made, update the file in the same change - a stale instruction is worse than a missing one, because the agent trusts it.
How claudesetup fits
Writing a CLAUDE.md that stays lean, structured, and honest is a discipline, and claudesetup bakes that discipline into the scaffold in one command. You start with a right-sized CLAUDE.md, a small docs system so the reasoning behind your decisions lives in files rather than a chat that gets compacted away, and a layout that gives the long content a home outside the root file - so the instructions Claude reads are the ones that still matter.