CLAUDE.md

A CLAUDE.md is a markdown file that Claude Code reads at the start of every session. It is where you write down the things you would otherwise re-explain: the commands, the conventions, and the decisions that are not visible in the code.

Checked against the official documentation in August 2026. These tools change quickly, so the date is part of the answer.

A short, useful CLAUDE.md

# Code style
- ES modules, not CommonJS
- 2-space indentation

# Commands
- `npm run dev` starts the dev server on port 3040
- `npm test` runs vitest; prefer a single test over the whole suite

# Rules that are not obvious from the code
- Nothing a visitor supplies may be sent to a server
- The site sets no cookies; the privacy page says so, so keep it true

Code style

ES modules, not CommonJS
2-space indentation

Commands

npm run dev starts the dev server on port 3040
npm test runs vitest; prefer a single test over the whole suite

Rules that are not obvious from the code

Nothing a visitor supplies may be sent to a server
The site sets no cookies; the privacy page says so, so keep it true

Short, specific, and every line is something you would otherwise type again.

Importing another file

See @README for the project overview and @package.json for the scripts.

# Individual preferences
- @~/.claude/my-project-instructions.md

See @README for the project overview and @package.json for the scripts.

Individual preferences

@~/.claude/my-project-instructions.md

The @path syntax expands the file into context at launch. Imports can nest four deep. A path inside backticks is left alone, so `@README` in code formatting stays literal.

Where it can live

Four locations, listed in load order from broadest to most specific. All of them are concatenated rather than overriding each other, so a project instruction lands in context after a user instruction.

Scope	Location
Managed policy	`/Library/Application Support/ClaudeCode/CLAUDE.md` on macOS, `/etc/claude-code/CLAUDE.md` on Linux and WSL, `C:\Program Files\ClaudeCode\CLAUDE.md` on Windows
User	`~/.claude/CLAUDE.md`
Project	`./CLAUDE.md` or `./.claude/CLAUDE.md`
Local, personal, gitignored	`./CLAUDE.local.md`

Claude Code loads these from your working directory and every directory above it, ordered from the filesystem root down, so the file closest to where you started is read last. Files in subdirectories are not loaded at launch: they come in when Claude reads a file in that directory.

What belongs in it

Include	Leave out
Commands Claude cannot guess	Anything derivable from the code
Style rules that differ from the defaults	Standard conventions of the language
Testing instructions and the preferred runner	Detailed API documentation, link to it instead
Repository etiquette: branch names, PR conventions	Information that changes often
Architectural decisions specific to this project	Long explanations and tutorials
Environment quirks, required variables	File-by-file descriptions of the codebase
Gotchas and non-obvious behaviour	"Write clean code" and other self-evident advice

The test for each line: would removing this cause a mistake? If not, cut it.

What usually goes wrong

Target under 200 lines. The file is loaded into every session and competes for attention with your actual conversation, so a long one makes Claude ignore half of it. A file over 4 MiB is skipped entirely.
It is context, not configuration. The content arrives as a message rather than as an enforced rule, so there is no guarantee of compliance. For something that must happen every time, write a hook instead.
Contradictions get resolved arbitrarily. If two files disagree, or a nested file contradicts the root, Claude may pick either. Review the set periodically.
Claude Code reads CLAUDE.md and not AGENTS.md. If your repository already has an AGENTS.md, import it with @AGENTS.md or symlink the two rather than maintaining both.
Imports do not save context. Splitting a long file into @path imports organises it, but the imported files still load at launch.
Emphasis only works if it is rare. Marking one line IMPORTANT makes it stand out; marking ten makes none of them stand out.
Block-level HTML comments are stripped before the file enters context, so a  costs no tokens and the agent never sees it. A comment inside a code block is kept, because there it is content.

The commands that matter

Command	What it does
`/init`	Writes a starter file from your codebase. If one already exists it proposes improvements instead of overwriting.
`/context`	Lists the memory files that actually loaded this session, which is how you find out that the file you edited is not the one being read.
`/memory`	Opens the loaded files for editing.
`/doctor`	Proposes cuts for a checked-in CLAUDE.md: removes what Claude can derive from the codebase, keeps the pitfalls and the conventions.

Questions

How long should a CLAUDE.md be?

Under 200 lines is the documented target. Beyond that it consumes context and adherence drops. If yours keeps growing, move the parts that only matter sometimes into a skill, or into a path-scoped rule under .claude/rules/ so they load only when Claude touches matching files.

Why is Claude ignoring my CLAUDE.md?

Three usual causes, in order of likelihood. The file is too long and the rule is lost in the noise. The instruction is vague, so "format code nicely" loses to "use 2-space indentation". Or the file never loaded, which `/context` will tell you in a second.

Should I commit it?

Yes, for the project file: it is team context and it compounds in value. Keep personal preferences in `~/.claude/CLAUDE.md` or in a gitignored `CLAUDE.local.md` so they do not land on your colleagues.

Does it survive compaction?

The project-root file does: it is re-read from disk and re-injected after a compaction. Instructions you only gave in conversation do not, which is the argument for writing them down.