The CLAUDE.md file, or how to tell Claude Code what your project is

Once you have had your first conversation with Claude Code, the second one brings a surprise: it remembers nothing. Every session starts with an empty memory. It does not know how your tests run, that you use four spaces rather than tabs, or that one folder must never be touched. It will guess, and now and then it will guess wrong.

CLAUDE.md fixes that. It is a plain Markdown file that Claude reads at the start of every session. You write down what you would otherwise have to repeat. It is the difference between a good week and a bad week with the tool, and it is a single file.

Where it lives

There are three places that matter, from the most general to the most specific:

• ~/.claude/CLAUDE.md: your personal preferences, for every project. The code style you like, how you want it to talk to you, the tools you use.
• CLAUDE.md at the root of the project (or .claude/CLAUDE.md): the rules for that project. It goes into git, so the whole team shares it.
• CLAUDE.local.md at the root of the project: your personal notes for that project only. Keep it out of git by adding it to .gitignore.

All three are read and combined in that order; none replaces another. The file closest to where you started Claude is read last. Claude also reads CLAUDE.md files in the folders above the one where you started it. If the project has subfolders with their own CLAUDE.md, those load only when Claude works on files in those folders. In a company there may also be a file managed by the organization, which applies to everyone and cannot be switched off.

To confirm a file was loaded, type /context in a session and look for it under "Memory files". If it is not there, Claude cannot see it.

Start with /init

You do not have to write the file from scratch. Inside a session, type:

> /init

Claude looks through the project and creates a CLAUDE.md with the build and test commands it finds and the conventions it can work out. If the file already exists, it suggests improvements instead of overwriting it. From there, your job is to add what it cannot discover on its own: the house rules.

What to put in it

One question decides every line: if I remove this, will Claude get something wrong? If the answer is no, cut it.

Worth including:

• Commands it cannot guess: how to run the app locally, how to run the tests, how to deploy.
• Style rules that differ from the language's usual defaults. "Four spaces" only if your project does something different from what the tool would do anyway.
• Architecture decisions specific to the project. Why there is no framework, why the configuration lives outside the public web root.
• Repository etiquette: branch names, the language of commit messages, whether it commits on its own or waits.
• Known traps: the environment variable without which nothing starts, the folder that looks like junk and is not.

Not worth including:

• Anything it learns by reading the code: the folder layout, the dependency list, what each file does.
• Normal conventions of the language. It already knows them.
• Long API documentation. Put a link instead.
• Things that change every week.
• Empty phrases like "write clean code".

How to write it

Three rules, all from the official documentation and all confirmed by people who learned the hard way:

1. Short. Under 200 lines. A long file uses up context in every session and, worse, the important rules get lost among the others. If Claude ignores a rule that is clearly written down, the file is probably too big.
2. Concrete. Write things that can be checked. "Run php vendor/bin/phpunit before every commit" works; "test your changes" does not. "Handlers live in src/api/handlers/" works; "keep files organized" does not.
3. No contradictions. If two rules contradict each other, it picks one more or less at random. Every so often, read the file top to bottom and delete what is no longer true.

Use headings and lists. Claude reads structure the way a person does: clear sections are easier to follow than dense paragraphs. If you want to leave a note for the people who maintain the file, use an HTML comment (<!-- like this -->): it is removed before the text reaches Claude and costs no context. If there is one rule it keeps skipping, put "IMPORTANT" on that line, and only that one. If you put it everywhere, nothing stands out.

A complete example

A small PHP site with no framework, run by one person. The CLAUDE.md at the project root could be this:

# Shop (PHP 8.4, no framework)

## Commands
- Local server: `php -S localhost:8080 -t www`
- Tests: `php vendor/bin/phpunit` (run before every commit)
- Check the syntax of a changed file: `php -l file.php`

## Rules
- Plain PHP. No new dependency without asking first.
- All SQL uses prepared statements. Never concatenate variables into a query.
- `config/app.php` exists only on the server: never in git, never in packages.
- Dark and light themes, both required. Colors are CSS variables.

## Git
- Branches: feature/<short-name>. One change per commit.
- Do not commit unless I ask.

## When you change something
- Always bump the version in `config/app.php`: x.x.1 fixes, x.1.0 improvements, x+1.0.0 new features.
- Explain why, not just what.

About twenty lines. Notice what is missing: it does not say that www/ is the public root or list the files, because Claude can see that. Every line is something it would get wrong without it.

When to add a line

The file grows with use, not all at once. The documentation gives four signs that it is time to add something:

• Claude made the same mistake a second time.
• A code review caught something it should have known about this project.
• You typed the same correction in chat that you typed last session.
• A new teammate would need the same information to be productive.

You do not need to open an editor. Tell it "add this to CLAUDE.md" and it will. To open the files yourself, /memory lists them all and opens the one you pick.

Importing other files

A CLAUDE.md can pull in other files with @path, for example @README or @docs/git.md. Their content is loaded at startup as if it were written there. This helps you organize, not save space: imported files still count toward the size. To mention a path without importing it, wrap it in backticks.

If you already use AGENTS.md

Other AI coding tools read a file called AGENTS.md. Claude Code does not. To avoid keeping two copies, create a CLAUDE.md that imports it, and add anything Claude-specific below:

@AGENTS.md

## Claude Code
- Use plan mode for changes under `src/billing/`.

What about auto memory?

There is a second mechanism. It is not the subject of this guide, but you should know it exists. Besides what you write in CLAUDE.md, Claude writes notes for itself: corrections you gave it, your preferences, context it cannot get from the code. They live in ~/.claude/projects/<project>/memory/. The index, MEMORY.md, loads in every session (the first 200 lines or 25 KB, whichever comes first); the detailed notes are read only when needed. It is on by default, and /memory shows what it saved and lets you delete anything. A rule of thumb: project rules go in CLAUDE.md; your personal habits it learns on its own.

Common problems

• It is not following what I wrote. First run /context to check the file loaded. Then check whether the rule is vague or contradicts another. CLAUDE.md is context, not law: Claude reads it and tries to follow it, but there is no guarantee. For something that must happen every time without exception (a lint after every edit, for example), the right tool is a hook, not a line in CLAUDE.md.
• It has grown huge. Cut what Claude discovers on its own. The /doctor command suggests trims for a CLAUDE.md that is checked into git.
• It lost the rules after /compact. The project-root CLAUDE.md survives compaction; what gets lost is anything you only said in the conversation. If it mattered, move it into the file.

Sources

• How Claude remembers your project, official documentation, read on 16 September 2026: locations, load order, the 200-line target, /init, /context, /memory, imports, AGENTS.md, auto memory.
• Best practices for Claude Code, section "Write an effective CLAUDE.md": what to include and exclude, and the warning about long files.