CLAUDE.md. Claude reads it at the start of every session, but it doesn't enforce anything

For the third time this week a developer tells Claude the same thing. Tests run with npm test, and new database tables only come in through migrations. Claude apologises, fixes it and does the same thing again in the next session. Things like that belong in the CLAUDE.md file, written down once.

Every Claude Code session starts with a fresh context. What was said in yesterday's conversation isn't there today unless someone wrote it down. Anthropic suggests adding to CLAUDE.md exactly when Claude makes the same mistake a second time, or when you type a correction you already typed last session.

Where the CLAUDE.md file lives

CLAUDE.md is a plain Markdown file that Claude Code reads at the start of every session. It can live in several places, and each one has a different scope.

The project file sits in the root folder as CLAUDE.md or .claude/CLAUDE.md. It goes into the repository, so the whole team sees it. This is where build and test commands, code conventions and important architecture decisions go.

The user file, ~/.claude/CLAUDE.md, applies to all your projects. It's the place for personal preferences. Private notes for a single project go into CLAUDE.local.md in the root folder, which you add to .gitignore. A company can also have IT roll out one shared file to every machine.

Files in the folder where you start Claude Code and in the folders above it load at startup. Files in subfolders load only when Claude starts working with files in that subfolder. They're joined into one context rather than overriding each other. To check that a file loaded, run /context and look at the Memory files list.

Context, not settings

This sentence from Anthropic's documentation is worth remembering. Claude treats CLAUDE.md as context, not enforced configuration. The file's content reaches the model as a message after the system prompt. Claude reads it and tries to follow it, but there's no guarantee it always will, especially when instructions are vague or contradict each other.

That leads to a simple rule. If something has to be blocked no matter what Claude decides, it's not a job for CLAUDE.md. A ban on editing a file or running a command belongs in the permission rules in your settings files. Things that must happen at a fixed moment, such as formatting after every edit, go into a hook, a command that Claude Code runs on its own when a given event happens.

CLAUDE.md is for knowledge and working rules. Bans belong in settings and hooks.

How to write a CLAUDE.md that Claude follows

Anthropic gives examples. "Use 2-space indentation" instead of "Format code properly". "Run npm test before committing" instead of "Test your changes". "API handlers live in src/api/handlers/" instead of "Keep files organized".

An instruction should be concrete enough that you can check whether it was followed. The same principle works in ordinary prompts.

The second piece of advice is about length. The documentation recommends under 200 lines per file, because a longer file takes up more context and Claude follows it less reliably. When two instructions contradict each other, Claude may pick one of them arbitrarily. So group related rules under headings and clear out what's outdated every so often.

A short file for an invented project could look like this.

# Order panel

## Commands
- `npm install` installs dependencies
- `npm test` runs the tests, run it before every commit
- `npm run dev` starts the local server

## Rules
- TypeScript, 2-space indentation
- API handlers live in `src/api/handlers/`
- New database tables only through migrations
- User-facing text only through the translation files in `src/i18n/`

## Ask before changing
- files in `src/legacy/`
- the dependency list in `package.json`

There's no description of the company here and no request for "good, clean code". Claude sees the code by itself. The file only tells it what it can't read from the code.

/init, /memory and imports

You don't have to start from a blank page. The /init command looks through the project and creates a first CLAUDE.md with the build commands, test instructions and conventions it finds. If the file already exists, /init suggests improvements instead of overwriting it.

Read the result and cut it down, like any instruction written by AI. We covered that in the article on consistent AI results.

/memory opens your CLAUDE.md files for editing and lets you turn auto memory on or off. That's a separate mechanism where Claude writes its own notes based on your corrections.

Longer documentation can be pulled in with an import, a path written after @, for example @docs/git.md. Imports keep the file organised but don't save context, because imported files also load at startup. Rules for one part of the project are better moved to the .claude/rules/ folder with a paths field. A rule like that loads only when Claude works with matching files.

Start with /init and cut everything Claude would see in the code anyway. Then add one sentence each time the same mistake comes back a second time.