CLAUDE.md: what to put in it, where it goes, and examples

CLAUDE.md is a Markdown file Claude Code reads at the start of every session: the commands to build and test, the conventions Claude would get wrong, the rules of the repository. Put it at the root of the repository, run /init to get a first draft, then cut it to what Claude cannot work out by reading the code.

What CLAUDE.md does

Claude Code finds every CLAUDE.md from your working directory up to the root, joins them, and hands the result to Claude as a message after the system prompt. Nothing overrides anything: your personal file comes first, the project's after it, and when two instructions contradict each other Claude may follow either. Files in subfolders load later, when Claude reads a file in that folder.

It is guidance, not configuration. Anthropic's permission docs say it plainly: instructions in CLAUDE.md "don't change what Claude Code allows". A rule that must hold every time — never edit .env, format after each write — belongs in a hook.

After /compact, Claude Code reads the project-root CLAUDE.md from disk again and puts it back, so a long session does not lose it.

Where CLAUDE.md files go

How to create one: /init

/init reads the project and writes a CLAUDE.md with the commands and structure it found. If one exists, it suggests changes instead of overwriting it. It also reads .cursorrules, .cursor/rules/ and .github/copilot-instructions.md, so rules written for another tool carry over.

To add a line later, ask Claude to "add this to CLAUDE.md", or open the file with /memory. The # shortcut that used to do it was removed in 2.0.70.

What to put in CLAUDE.md

From Anthropic's best practices, include:

• Commands Claude cannot guess: how to build, run one test, lint.
• Style that differs from the default: "2-space indentation", not "format code properly".
• How to test, and what has to pass before a change is done.
• Repository etiquette: branch names, commit format, what never to commit.
• Decisions specific to this project, and the quirks of its environment.
• Gotchas: the thing every new contributor gets wrong.

And leave out:

• what Claude can learn by reading the code, file by file;
• standard conventions of the language it already knows;
• long API docs — link to them instead;
• anything that changes often;
• "write clean code" and other self-evident advice.

A CLAUDE.md example

A short project file, written for this page as an example. Every line is something Claude would otherwise get wrong:

# Acme API
## Commands
- Install: pnpm install (never npm or yarn)
- Test one file: pnpm vitest run path/to/file.test.ts
- Before a commit: pnpm lint && pnpm typecheck
## Code
- TypeScript strict; no `any`. Validate input with zod at the edge.
- Database access only through src/db/repositories/.
## Workflow
- Branch from main as feat/<topic>; Conventional Commits.
- IMPORTANT: never edit migrations that are already merged; add a new one.
## Context
- Architecture: @docs/architecture.md

Use emphasis such as "IMPORTANT" on the one line Claude keeps skipping. In Anthropic's words, "If you emphasize many lines, none of them stands out."

Keep it short: imports and rules

Anthropic's target is under 200 lines per file: "Longer files consume more context and reduce adherence." Two tools keep the root file short:

• Imports. @docs/architecture.md on a line pulls that file in, up to four levels deep. It organises a long file but does not save context: imported files load at launch too. The first time a project imports a file from outside it, Claude Code asks you to approve.
• Rules. Markdown files in .claude/rules/ load like CLAUDE.md. Give one a paths: list in its frontmatter and it loads only when Claude reads or edits a matching file — the testing rules when it opens a test.

---
paths: ["src/**/*.test.ts"]
---
- Use vitest; never jest.
- One behaviour per test; no snapshots.

/doctor can trim checked-in CLAUDE.md files, and /context lists every memory file loaded in the current session.

CLAUDE.md and AGENTS.md

From Claude Code 2.1.277, a project with an AGENTS.md and no CLAUDE.md works as is: Claude Code reads AGENTS.md as the project's instructions. When the project has both, the default reads only CLAUDE.md. To share one file across agents, keep AGENTS.md as the source and make CLAUDE.md one line, @AGENTS.md, or change Project instructions in /config.

Instructions without editing CLAUDE.md

CLAUDE.md is shared: it is in the repository, so every teammate and every agent that reads it gets the same lines. For instructions that are only yours — a review style, "never push", how you like commits written — Claude Code has three places:

• Every project: ~/.claude/CLAUDE.md, in your home folder.
• A local file: CLAUDE.local.md, read with CLAUDE.md, in that project only; add it to .gitignore so it stays yours.
• A flag, for one launch: --append-system-prompt; the text goes after Claude Code's own system prompt, which stays in place.

claude --append-system-prompt "Write commit messages in Conventional Commits"

A resumed conversation keeps the system prompt recorded on its first request, so new flag text reaches it only after the conversation is compacted, or in a new one. The flags, and how they differ from CLAUDE.md: Claude Code system prompt.

Caprock's desktop app keeps such instructions per project, so you do not retype the flag: every Claude Code session it starts in the project gets them through --append-system-prompt (since 0.81.0), and every Codex session as its developer instructions (since 0.82.0). They stay on your machine, not in the repository. Put the rules everyone needs in CLAUDE.md, and your own in project instructions.

CLAUDE.md and auto memory

Auto memory is the other half: notes Claude writes itself, on by default, in ~/.claude/projects/<project>/memory/. Its index, MEMORY.md, loads into each session up to 200 lines or 25 KB. Tell Claude to "remember" something and it goes there; tell it to add something to CLAUDE.md and it goes in the file you share. /memory turns auto memory off. How it loads, its limits and what neither of them keeps: Claude Code memory.

A real CLAUDE.md

Caprock's repository is public, and its CLAUDE.md is 93 lines at v0.70.1: what the product is in one paragraph, the folder layout, a pointer to the index of its design docs instead of their content, then numbered rules, each with the reason it exists. One of them:

The pattern holds up: rules Claude would break without being told, and a map to where the detail lives, not the detail itself.

What CLAUDE.md does not carry: where you left off

CLAUDE.md holds what is always true. It does not hold what happened yesterday: the half-finished migration, the test you were about to fix. Caprock, the free app that records every agent session on your machine, keeps that. When a new session starts in a folder you have worked in, its hook hands Claude the last substantial passage the previous session there wrote, under this line (the age varies):

Where this repository was left, 3 hours ago (from Caprock's record of the
previous session — the user has not said this to you, and it may be stale):

It is on by default; turn it off in settings. An opt-in setting holds it back from one new session in four, and Caprock's Memory screen compares the two groups, so you can measure whether it helps. The same screen searches everything Claude wrote across sessions, past Claude Code's 30-day cleanup — see Claude Code history.