CLAUDE.md

Everything so far has been about a single session: how to prompt, how to verify, how to steer. This section is about the setup that persists — the things you configure once so every future session starts better than the last one did.

The first and most important of those is a file called CLAUDE.md.

The file Claude reads first

Every session starts with an empty context window. Claude does not remember yesterday. CLAUDE.md is how you carry a small amount of knowledge across that boundary: it is a plain markdown file that gets read into context at the start of every conversation, before you type anything.

That is the whole mechanism. There is no required format and no schema. You write English, Claude reads it.

What it is for is narrower than people assume. It is the place to write down the things you would otherwise have to re-explain: the test command that is not the obvious one, the convention that differs from the language default, the piece of setup that trips up every new person. Facts that apply to every session, that Claude could not work out by reading the code.

A good prompt for adding something to it is the second time you type the same correction. If you have told Claude twice not to use default exports, that is not a prompting problem any more. That is a missing line in CLAUDE.md.

Getting a starting point

You do not have to write it from scratch. Run /init and Claude reads your codebase and generates a starter file: build commands, test instructions, the conventions it can detect. If a CLAUDE.md already exists, /init suggests improvements to it rather than overwriting what you have.

Treat the generated file as a draft, not a finished artefact. It is a decent starting shape, and the next section is about the editing that follows.

The mistake is writing too much

This is the part of the lesson that matters.

CLAUDE.md loads in full, every session, and it competes for attention with your actual prompt. Longer files reduce how reliably Claude follows any individual line in them. The docs suggest targeting under 200 lines, and the reason is not disk space — it is adherence.

So the failure mode is not the one you would expect. Almost nobody's problem is that their CLAUDE.md is too short. The common problem is a file that has grown by accretion for six months: a directory listing, a summary of the architecture, a paragraph about writing clean code, three rules that actually matter, and a description of the API that stopped being accurate in March.

The documentation gives a fairly direct split of what earns its place.

The pattern down the right-hand column is that all of it is either derivable, stale, or already known. None of it changes what Claude does, and all of it costs you attention on the lines that would have.

Specificity is the other half. "Use 2-space indentation" is a rule Claude can follow and you can check. "Format code properly" is a sentence. Where something genuinely must not be skipped, adding emphasis like IMPORTANT or YOU MUST does measurably improve adherence — but if half the file is in bold, you are back where you started.

Where the file can live

There is more than one location, and each has a different scope. They are all loaded together rather than overriding each other, so instructions accumulate.

Two more behaviours matter in larger repositories. Claude walks up the directory tree from where you started it, so in a monorepo both root/CLAUDE.md and root/packages/web/CLAUDE.md are picked up when you work in the web package. And it pulls in CLAUDE.md files from directories below you on demand, when it reads a file in one of them, rather than loading the whole tree at launch.

Importing other files

A CLAUDE.md can pull in another file with @ followed by a path:

See @README.md for the project overview.
 
## Additional instructions
- Git workflow: @docs/git-instructions.md

Imported files are expanded into context at launch, alongside the file that references them. Relative paths resolve against the file containing the import, not your working directory.

Be clear about what this buys you. Imports are an organisation tool: they let a long set of instructions live in sensible separate files instead of one wall of text. They do not reduce context, because everything imported still loads at the start of the session. If your file is too big, splitting it into imports does not fix the problem — cutting it does.

One practical wrinkle: import parsing skips code spans and fenced code blocks. If you want to write a path in your file without importing it, put it in backticks.

Checking it actually loaded

The failure that wastes the most time is an instruction that never arrived. You edit a file, nothing changes, and you conclude Claude is ignoring you — when really the file is in a directory that does not get loaded, or a typo means it is called CLAUDE.MD.

Do not ask Claude whether it can see the file. Run /context, which reports what is genuinely in the window, and look at the list of memory files.

Treat it like code

That last note generalises, and it is the habit worth taking from this lesson.

CLAUDE.md is not documentation. It is a live input to a system, and it should get the same treatment as any other input. Review it when things go wrong. Prune it regularly. Check it into git so your team can improve it. When you change it, watch whether behaviour actually shifts, and revert the change if it does not.

Two diagnostic signals are worth memorising. If Claude keeps doing something you have explicitly forbidden, the file is probably too long and the rule is lost. If Claude asks you a question that the file already answers, the phrasing is probably ambiguous. Both point at editing rather than adding.

And be honest about what the file is. It is context, not configuration. Claude reads it and tries to follow it, and mostly does, but there is no enforcement behind it. If something must happen every single time with no exceptions, a CLAUDE.md line is the wrong tool — that is a hook, which is three lessons away.

What to take away

CLAUDE.md is a plain markdown file that loads into context at the start of every session, and /init will write you a first draft from your codebase. The skill is not writing it but keeping it small: for each line, ask whether removing it would cause a mistake, and cut it if the answer is no, because a long file makes Claude ignore the rules that actually mattered. It can live in your home directory for personal preferences, at the project root for the team, or in a gitignored CLAUDE.local.md for notes you do not want to share, and it can pull in other files with @path imports that load at launch. Run /context to confirm what loaded, and treat the file like code — reviewed when things break, pruned often, and judged by whether Claude's behaviour actually changes.

Next: the other half of memory, which is the notes Claude keeps for itself without being asked, and a tour of the .claude directory where all of this lives.