CLAUDE.md: How to Write One Claude Code Actually Follows

October 7, 2026

Claude Code starts every session with an empty context. CLAUDE.md is how it knows your build command, your test runner and the one folder it must never touch without being told again each morning. It's a plain markdown file that Claude reads at the start of every session, and it's the cheapest thing you can do to make Claude Code better on your project.

It's also easy to get wrong. A long CLAUDE.md gets followed less, not more, and it does nothing for the rules it can't see. Below: where the files go, what belongs in them, a template, and what to check when Claude ignores what you wrote. Everything here comes from Anthropic's Claude Code documentation as of October 2026.

CLAUDE.md and auto memory: two different things

Claude Code has two memory systems, and both load at the start of every session:

	CLAUDE.md	Auto memory
Who writes it	You	Claude
What's in it	Instructions and rules	What Claude learned: your preferences, your corrections, project context it can't read from the code
Scope	Organization, you, or one project	One repository, shared across its worktrees
How much loads	The whole file	The first 200 lines or 25KB of its index, whichever comes first

Both are context, not enforcement. Claude reads them and tries to follow them, but nothing stops it from doing otherwise. For a rule that must hold every time, like "never write to the migrations folder", use a hook, which runs as a script and blocks the action.

Where CLAUDE.md files go

Organization-wide. IT can place a managed file, such as /etc/claude-code/CLAUDE.md on Linux, for company standards and compliance reminders. Nobody can switch it off locally.
Just for you, everywhere: ~/.claude/CLAUDE.md, for your style and tools.
Shared with the team. Put the project file at ./CLAUDE.md or ./.claude/CLAUDE.md and commit it with the code: build and test commands, conventions and architecture decisions live here.
Private to one project: ./CLAUDE.local.md, listed in .gitignore, holds your sandbox URLs and test data.
Per subfolder. A file at <subfolder>/CLAUDE.md covers one part of a big repo and loads only when Claude opens something there.

Files don't override each other: Claude Code joins them together. Files in the folders above where you started Claude load at launch, from the top of the disk down, so the one closest to your working folder is read last. Subfolder files load on demand.

Create one in a minute

Run /init in a Claude Code session. Claude reads the codebase and writes a starting CLAUDE.md with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it. Then cut what Claude could have worked out by itself and add what it couldn't.

To open any of your memory files, run /memory. It lists every CLAUDE.md that applies to the session, creates the ones that don't exist yet, and opens them in your editor. You can also say "add this to CLAUDE.md" in the chat.

What to put in, and what to leave out

Anthropic's test for every line: would removing it make Claude make mistakes? If not, cut it.

Put in	Leave out
Commands Claude can't guess: build, test, lint, how to run one test	Anything Claude can find by reading the code
Style rules that differ from the language's defaults	Standard conventions it already knows
Branch naming, commit and pull request habits	Long API documentation (link to it instead)
Architecture decisions and the reasons behind them	A file-by-file tour of the codebase
Environment quirks, like a required variable or a local service	Things that change every week
Gotchas a new teammate would trip on	"Write clean code" and other rules nobody can check

Write instructions Claude can verify. "Use 2-space indentation" works; "format code properly" doesn't. "Run npm test before committing" works; "test your changes" doesn't.

The right moments to add a line: Claude makes the same mistake twice, a code review catches something Claude should have known, or you type the same correction you typed last session.

A template to start from

# Project: [name, one line on what it does]

## Commands
- Install: [command]
- Dev server: [command]
- Test all: [command]
- Test one file: [command with a path]
- Lint and typecheck: [command]

## Conventions
- [Language version and module style, e.g. TypeScript 5, ES modules only]
- [Where new code goes, e.g. API handlers live in src/api/handlers/]
- [Naming rule that differs from the default]

## Workflow
- Run the single relevant test after a change, not the whole suite.
- Typecheck before saying a task is done.
- [Branch and commit rule]

## Never
- [Action Claude must not take, and why in five words]

## Gotchas
- [The thing that breaks the build or wastes an hour, e.g. tests need a local Redis on port 6379]

Fill it in, then delete every section you don't need. A good CLAUDE.md for a small project is twenty lines.

Keep it short

Under 200 lines per file is Anthropic's target. Longer files cost more context on every turn and get followed less reliably. Claude Code warns you at startup and in /status when a file is over the recommended length.
Imports don't shrink anything. You can pull other files in with @path/to/file, up to four hops deep, but imported files load at launch too.
Emphasis works once. If Claude keeps skipping one rule, add "IMPORTANT" to that line. Mark many lines and none of them stands out.
Hide notes from Claude. HTML comments like  are stripped before the file reaches Claude, so you can explain a rule to humans without spending tokens.
Let Claude prune it. /doctor proposes cuts for content Claude can work out from the code. /doctor prompt-audit checks all your instruction files for outdated or contradicting rules.

Rules for one part of the codebase

When an instruction only matters for some files, move it out of CLAUDE.md and into .claude/rules/. Each rule is a markdown file. Give it a paths field and it loads only when Claude reads or edits a matching file:

---
paths:
  - "src/api/**/*.ts"
---
# API rules
- Every endpoint validates its input.
- Errors use the standard error response format.

Rules without paths load every session, like CLAUDE.md. Personal rules for all your projects go in ~/.claude/rules/. For a procedure with several steps that you only need sometimes, a skill is the better home: it loads only when it's used.

Auto memory

Auto memory is on by default in local sessions. As Claude works, it saves short notes about you (your role and preferences), your feedback (corrections and approaches you confirmed), the project (decisions and deadlines it can't read from the code) and references (where things live outside the repo). It skips what the code or your CLAUDE.md already says.

The notes live in ~/.claude/projects/<project>/memory/: a MEMORY.md index plus one file per memory. They stay on your machine.
Only the first 200 lines or 25KB of MEMORY.md load at the start. Claude opens the topic files when it needs them.
When you say "remember to always use pnpm", it goes to auto memory. Say "add this to CLAUDE.md" if you want it in the shared file instead.
Turn it on or off with the toggle in /memory, per project with "autoMemoryEnabled": false in the project's settings, or everywhere with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Everything in that folder is plain markdown. Read it from time to time and delete what's wrong; Claude trusts it as much as you let it. For memory that also records what happened in each session and lets Claude search it, see the community plugin Claude-Mem.

CLAUDE.md and AGENTS.md

If your repository already has an AGENTS.md for other coding agents, Claude Code reads it when there's no CLAUDE.md or CLAUDE.local.md in your working folder or above it (version 2.1.277 or later). When both exist, it reads only the CLAUDE.md files by default. To keep one file for every tool, write the instructions in AGENTS.md and put a CLAUDE.md next to it that imports it with @AGENTS.md. You can also change the default under Project instructions in /config.

When Claude ignores your CLAUDE.md

Check it loaded. Run /context and look under Memory files. A subfolder CLAUDE.md won't be listed there, because it loads only when Claude opens a file in that folder.
Look for contradictions. If two files say different things about the same behavior, Claude may follow either one.
Make the rule concrete. Vague instructions get followed loosely.
Check the length. A rule lost in a 400-line file is a rule Claude didn't weigh.
Check for a built-in instruction. If your commit rules clash with Claude Code's own git guidance, turn the built-in one off with the includeGitInstructions setting.
Use a hook for anything that must happen at a fixed moment, like linting after each edit.

After /compact, the project-root CLAUDE.md is read again from disk, so it survives. An instruction you only gave in the chat doesn't. If you keep repeating it after compaction, it belongs in the file.

Questions people ask

Is CLAUDE.md the same as a system prompt?

No. Claude Code delivers it as a message after the system prompt, which is why it guides behavior without guaranteeing it. For instructions at system-prompt level in scripts, Claude Code has the --append-system-prompt flag. Our guide to system prompts explains the difference.

How long should CLAUDE.md be?

Under 200 lines per file, per Anthropic. Most good ones are much shorter. Claude Code reads a file up to 4 MiB in full and skips anything larger, but adherence drops long before that.

Should CLAUDE.md go in git?

The project file, yes: it's shared knowledge, and it gets better as the team adds to it. Keep personal settings in CLAUDE.local.md and out of git.

Do I need CLAUDE.md if auto memory is on?

Yes. Auto memory holds what Claude picked up from you; CLAUDE.md holds the rules you decided on. Team conventions belong in a file everyone can read and review.

For the rest of Claude Code's commands in one place, see our Claude Code cheat sheet, and for getting started, how to use Claude Code.

Sources

Anthropic, How Claude remembers your project, Claude Code Docs, accessed October 2026
Anthropic, Best practices for Claude Code, accessed October 2026