Short answer: CLAUDE.md is a plain text file that Claude Code reads at the start of every session. Put in it what you would otherwise explain again and again: how to work, how to build and test the project, where things live, and the rules that keep your app safe. Write each rule so Claude can check it, and keep the file under about 200 lines. Below is the template I use, taken from my free MVP System Design playbook, and the real file behind this site.
What CLAUDE.md is
Every Claude Code session starts with an empty memory. Yesterday's corrections are gone. CLAUDE.md is how your project's rules survive from one session to the next: Claude reads it first, every time.
One thing to know before you write it: Claude treats the file as context, not as a lock. It follows your rules because you asked, not because it can't break them. When something must never happen, like a commit straight to production, use a hook: a small script Claude Code runs before an action, which can block it.
Where the file goes
| File | Applies to | Who sees it |
|---|---|---|
./CLAUDE.md or ./.claude/CLAUDE.md | this project | everyone: commit it |
./CLAUDE.local.md | this project, only for you | only you: add it to .gitignore |
~/.claude/CLAUDE.md | every project on your computer | only you |
| a company-wide file set by IT | everyone in the organization | the organization |
Claude Code reads the CLAUDE.md in the folder you start it in and in every folder above it, joined together from the top down, so nothing overrides anything. Files in subfolders load when Claude starts working there. A CLAUDE.md can pull in another file with @path/to/file, up to four levels deep.
Starting from zero? Run /init in Claude Code. It reads your code and writes a first version with the build commands and conventions it finds. Then edit it: the first draft knows your code, but not your rules.
All of this is from Anthropic's documentation on memory, checked on 7 November 2026.
What to put in it
Anthropic's own advice is the best test: add a line when Claude makes the same mistake twice, or when you catch yourself typing the same correction you typed last session. In practice that comes down to five parts.
- How to work. Think before coding and say what you assume. Ask when something is unclear. Change only what the task needs. Prove every change with a test.
- The commands. How to run the app, the tests and the formatter, exactly as you would type them.
- Where things live. One line per important folder, so Claude doesn't guess.
- The rules that protect production. No commits straight to the main branch. No secrets in code. The test coverage below which the build fails.
- Where the details are. Point to your docs instead of pasting them: "Before you change the logs, read
docs/logs.md."
Write every rule so it can be checked. "Run npm test before committing" works. "Test your changes" doesn't, because Claude can't tell when it has done enough.
A CLAUDE.md template
This is the shape of the file I start every project with. Replace the parts in angle brackets.
# Project: <name> ## How to work - Think before coding. State your assumptions. If something is unclear, ask. - Simplicity first: the least code that solves the task. No features nobody asked for. - Change only what the task needs. Don't reformat or "improve" other code. - Prove each change: write a test that fails, then make it pass. ## Commands - Run the app: <command> - Run the tests: <command> (they must pass before every commit) - Format: <command> ## Where things live - <folder>: <what is in it> - docs/: read the doc for an area before you change it ## Rules that protect production - Never commit to main. Every change: branch, commit, pull request. - Never put secrets in code, logs or this file. - Test coverage under <N>% fails the build. - Tools or libraries not in docs/stack.md: ask first. ## Answer format 1. What is done. 2. What is not done. 3. What must be done next.
The full version, with the reasoning behind each rule and the 16 chapters it points to (stack, tests, security, releases and more), comes with the free playbook.
A real example: the CLAUDE.md behind this site
This site was built with Claude Code. Its CLAUDE.md has the playbook's rules, plus a few lines only this project needs:
- No inline scripts or styles in the pages: the site's security policy blocks them, and a test fails if one appears.
- Every change goes through a branch and a pull request before it reaches the live site.
- Test coverage under 99% fails the build.
- Client projects are under NDA, so their names never appear in the code, the site or e-mails.
Each line is something I would otherwise have to repeat in every session. That is the whole job of the file.
Mistakes to avoid
- Too long. Anthropic suggests under 200 lines per file. A longer file costs context, and Claude follows it less reliably. Move long procedures into skills, which load only when needed.
- Vague rules. "Write clean code" gives Claude nothing to check. Say what clean means for you.
- Rules that contradict each other. If two lines disagree, Claude may pick either one. Read the file again whenever your setup changes.
- Secrets. The file goes into the repository and into every session. Keys and passwords never belong in it.
- Pasted documentation. Link to the doc or import it with
@. A copy goes stale; a link doesn't.
CLAUDE.md and AGENTS.md
Codex and other coding agents read AGENTS.md instead. Claude Code reads AGENTS.md too when a project has no CLAUDE.md. To keep one file for every agent, write your rules in AGENTS.md and put one line in CLAUDE.md: @AGENTS.md. The guide to that file: what to put in AGENTS.md. Building with Codex? Here is the playbook for Codex.
Next: set up Claude for vibe coding. The whole workflow: Claude Code best practices. All guides: articles.