How to write a CLAUDE.md that works
The short answer: A CLAUDE.md is a plain text file in your project that Claude Code reads at the start of every session. Keep it short and write only what Claude can't work out from your code.
Key points
- Claude Code starts every session with a fresh memory; CLAUDE.md is how you tell it what it would otherwise have to guess.
- Aim for under 200 lines: every line takes a little of Claude's attention on every task.
- Put in only what Claude could not work out from the code, starting with the commands that check the work.
- Claude treats the file as context, not as enforced configuration. For what must never happen, use a hook.
On this page
- What is a CLAUDE.md?
- Where does the file go?
- How long should it be?
- What should go in it?
- What should stay out?
- How do I write a rule Claude actually follows?
- What does a good one look like?
- Can a CLAUDE.md force Claude to obey?
- How do I keep it from going stale?
- What if my project already has an AGENTS.md?
- A short checklist
What is a CLAUDE.md?
It is a text file called CLAUDE.md that sits in your project folder. Each time you start Claude Code, it reads the file first. Claude Code starts every session with a fresh memory, so the file is how you tell it things it would otherwise have to guess or ask again (Claude Code docs: memory).
Think of it as the note you would leave for a new colleague on their first morning: how to run the project, what to be careful about, what has already been decided.
You write it in plain language. There is no special syntax to learn. A heading, a few bullet points and some short sentences are enough.
Where does the file go?
The docs list three places:
./CLAUDE.mdin your project. It is for everyone who works on the project, and you can commit it with the rest of your code.~/.claude/CLAUDE.mdin your home folder. It holds your personal preferences for every project on your machine../CLAUDE.local.mdin your project. It is for your own notes about this one project, and the docs suggest adding it to.gitignoreso it isn’t shared.
Your computer
Home folder
~/.claude/CLAUDE.mdYour preferences, for every projectProject folder
CLAUDE.mdShared: committed with the codeCLAUDE.local.mdOnly you: listed in .gitignoreClaude Code reads them at the start of every session
Tip
If you are new to this, start with the first one. Run /init inside Claude Code and it writes a starting file for you from what it finds in your project, such as build commands and conventions. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it.
How long should it be?
Short. The docs say to aim for under 200 lines per file, because longer files use more of Claude’s attention and make it follow the rules less reliably (memory docs).
The best-practices page gives the reason: every line in CLAUDE.md takes a little of Claude’s attention on every task, whether it is relevant or not (best practices). A long file of nice-to-have advice drowns the three rules that matter.
What should go in it?
The best-practices page suggests a simple test: put in what Claude could not work out from the code itself. Four kinds of things pass that test:
- How to check the work. The exact commands that run the tests, the type check and the linter.
- Places where the code is misleading. An old pattern that appears everywhere but must not be copied, or a folder that looks unused but isn’t.
- Decisions that aren’t in the project. How you deploy, which library you picked and why, what needs a second look before it ships.
- Anything you have had to correct twice. If you told Claude the same thing two sessions in a row, it belongs in the file.
What should stay out?
- Things Claude can read for itself, like what each file does.
- Long explanations. A rule needs one line, not a page.
- Vague advice such as “write clean code”. Claude can’t check itself against it, and neither can you.
- Rules that apply to only one part of the project. The docs suggest moving those into separate rule files under
.claude/rules/, which load only when Claude works on matching files.
How do I write a rule Claude actually follows?
Make every rule something you could check. The docs give three pairs:
| Vague | Concrete |
|---|---|
| Format code properly | Use 2-space indentation |
| Test your changes | Run npm test before committing |
| Keep files organized | API handlers live in src/api/handlers/ |
Group related rules under headings. The docs say organized sections are easier for Claude to follow than dense paragraphs.
Watch out
Avoid rules that contradict each other: the docs warn that Claude may pick one arbitrarily.
What does a good one look like?
Here is a small example for an imaginary recipe app. It is not from a real project.
# Commands
- Run the app: npm run dev
- Check everything: npm run check && npm test
- Run one test file: npx vitest run src/recipes/scale.test.ts
# How this project works
- Recipes are stored on the phone first and synced later. Never read recipes from the server directly.
- Amounts are stored as whole grams or millilitres, never as decimals.
# Gotchas
- src/old-import/ looks unused but the Sunday backup still calls it. Don't delete it.
- Never put API keys in the code. They live in .env, which is not committed.
# Before you say you're done
- Run the check command above and show me its output.
Line by line:
- Commands come first because they let Claude test its own work. If your project has a check that passes or fails, the single most useful line in your CLAUDE.md is the command that runs it, according to the best-practices page.
- How this project works holds two decisions Claude can’t see from reading one file. Without them it might happily add a feature that reads from the server.
- Gotchas warn about a trap. This is the kind of thing that costs an hour when nobody mentions it.
- The last section asks for proof. “Done” without output tells you very little.
That is about fifteen lines, and it already changes how Claude behaves.
Can a CLAUDE.md force Claude to obey?
No. The docs are direct about this: Claude treats the file as context, not as enforced configuration. The more specific and short your instructions, the more consistently they are followed. If something must never happen, for example editing a certain file, the docs point to a hook instead. A hook is a small script that Claude Code runs and that can block an action no matter what Claude decides.
How do I keep it from going stale?
Treat it like any other file in the project. When a rule stops being true, delete it. When Claude gets something wrong twice, add a line. Run /doctor prompt-audit now and then: the docs say it checks your instruction files for outdated or conflicting content, such as references to files that no longer exist.
You can also split a file that grows. A CLAUDE.md can pull in other files with @path/to/file, up to four levels deep. The docs are clear that this keeps the file tidy but does not save space, because the imported files load too.
What if my project already has an AGENTS.md?
Claude Code can read an AGENTS.md as your project instructions when there is no CLAUDE.md. If you have both, it reads the CLAUDE.md files only, unless your CLAUDE.md imports the other with @AGENTS.md. This needs a recent version of Claude Code, so check the memory docs for your setup.
A short checklist
- Under 200 lines, ideally far fewer.
- Starts with the commands that check the work.
- Every rule is concrete enough to check.
- Holds only what Claude can’t learn from the code.
- No two rules disagree.
- Nothing in it is a secret.
- You read it again every time something goes wrong twice.
A good CLAUDE.md is small and a little boring. It is the part of your setup that pays off in every single session.