What is CLAUDE.md? How to create and use it?

CLAUDE.md is a markdown file that gives Claude Code persistent instructions for a project, a personal workflow or a whole organization. Claude Code reads CLAUDE.md at the start of every session. Published tests show Claude follows written CLAUDE.md rules far more reliably.

TL;DR

• Claude rarely ignores a written CLAUDE.md rule. In 48 trials, 0 of 25 runs attempted a command banned in CLAUDE.md, against 23 of 23 runs with no written ban (source).
• CLAUDE.md rules can sometimes become redundant. A 1,350-line CLAUDE.md passed 399 of 400 rule checks, but 17 of its 20 rules also passed with no file at all (source).
• A very long CLAUDE.md is a token bill. A 2,004-word rule set added about 3,330 input tokens inline, and zero as a path-scoped rule until a matching file was read (source).
• Use hooks only for what you cannot undo. A CLAUDE.md rule yielded when the user claimed authorization; a hook did not (source).

What is a CLAUDE.md file?

A CLAUDE.md file is a plain markdown file that gives Claude Code persistent instructions for a project, a personal workflow or an organization. Claude Code loads CLAUDE.md into context at the start of every session. Claude treats CLAUDE.md as context, not enforced configuration, so it guides behavior but cannot block an action.

Anthropic's Claude Code documentation says CLAUDE.md should hold facts Claude needs in every session: build commands, conventions, project layout and "always do X" rules.

An illustrative CLAUDE.md for a small API project looks like this:

# billing-api

## Commands
- Build: `pnpm build`
- Test one file: `pnpm vitest run <path>`

## Conventions
- API handlers live in `src/api/handlers/`
- Use the `logger` module, never `console.log`

## Do not
- Do not edit files under `migrations/` by hand

Each line is specific enough to verify. The documentation makes the same point with its own examples: "Use 2-space indentation" works better than "Format code properly".

Does a CLAUDE.md file improve Claude's results?

A CLAUDE.md-style context file does not reliably make a coding agent more successful, but it can make the agent faster. An ETH Zurich benchmark found context files did not generally improve task success and raised inference cost by over 20%. A separate paired study measured 28.64% lower median runtime with an AGENTS.md present.

The two studies measure different things, so they do not contradict each other. The ETH Zurich authors also report that agents followed the instructions in context files well, while repository overviews did not help.

Both studies tested AGENTS.md-style files across agents, not CLAUDE.md alone. They are the closest controlled evidence available for CLAUDE.md, and the practical reading is the same, i.e., to write instructions and skip the overview.

Does Claude ignore CLAUDE.md?

In published tests, Claude Code rarely ignores a clearly written CLAUDE.md rule. One experimenter ran 48 trials on Claude Code 2.1.246. With no written ban, 23 of 23 runs attempted the banned command. With the ban in CLAUDE.md, 0 of 25 did. File length and rule position made no difference.

That 48-trial experiment buried the ban mid-file, moved it near the end of a 128-line file, and added competing instructions. The result stayed at zero attempts each time.

A second test agrees. Mayank Kaul put 20 checkable rules in a 1,350-line CLAUDE.md and ran 30 sessions. With the file present, 399 of 400 rule checks passed, and how deep a rule sat in the file predicted nothing.

CLAUDE.md does fail in four documented ways:

• The user overrides it. When a prompt claimed authorization, a CLAUDE.md rule gave way in 2 of 2 runs while a hook held in 2 of 2 (Rulestack).
• The session runs long. Both experiments used short sessions. One user reports rules lapsing after compaction across 163 logged sessions, which is a field report, not a controlled test.
• The rule sits in a nested file. The documentation says a project-root CLAUDE.md is re-read after /compact, but nested files reload only when Claude reads files in that directory.
• The rule is vague or contradicted. The documentation says Claude may pick arbitrarily between two conflicting instructions.

Read the zero with care. Zero attempts in 25 trials still allows a true rate of up to about 11%, by the author's own calculation. The author also sells a book about hooks, and still reported a result that weakened that pitch.

How long should a CLAUDE.md be?

Anthropic's documentation recommends keeping each CLAUDE.md under 200 lines, because longer files consume more context and reduce adherence. In published tests, the measurable penalty of a long CLAUDE.md was cost, not disobedience: a 2,004-word rule set added about 3,330 input tokens to the first request of a session.

Rulestack measured the same rule set in four places on a fresh Claude Code session:

Splitting a CLAUDE.md into imports does not save tokens. The documentation says the same: imported files load at launch.

Worked example. In Mayank Kaul's deletion test, the same 20 rules were delivered two ways:

The short version was about 36% cheaper per run with no loss in compliance. The limit: one repository, one task, one model, five runs per arm. Rulestack sells rule packs, so treat its token figures as vendor-measured.

What should you delete from CLAUDE.md?

Delete any CLAUDE.md rule that a careful reader of the repository would follow anyway. In one deletion test, 17 of 20 rules passed every check even with no CLAUDE.md, because the code already demonstrated them. The only rules that mattered were the two that contradicted what the repository showed.

That finding comes from Mayank Kaul's 30-run test of a 1,350-line CLAUDE.md. Without the file, Claude followed the conventions the repository's own changelog and history demonstrated.

Three sources support the delete column. The ETH Zurich study found repository overviews did not help agents. An alphaXiv summary of its ablation reports generated files helped by about 2.7% only once existing documentation was removed. Claude Code's own /doctor checkup proposes trimming content Claude can derive from the codebase.

The add column comes from a study of 2,303 context files: only 14.8% specified security requirements and 14.5% specified performance.

One warning from Kaul's test: the rules worth keeping are the ones your codebase contradicts, and those are also the ones most likely to be wrong. Reconcile each one with the code before keeping it.

Should you use /init to create CLAUDE.md?

Use /init to draft a CLAUDE.md, then cut the draft hard. Anthropic's documentation recommends /init as a starting point to refine with instructions Claude would not discover on its own. ETH Zurich's benchmark found LLM-generated context files did not generally improve task success, so an unedited /init file mostly adds cost.

1. Run /init in a Claude Code session. Claude analyzes the codebase and writes a CLAUDE.md with the build commands, test instructions and conventions it finds.
2. Delete what Claude can derive. Remove directory layouts, architecture overviews and dependency lists, which the ETH Zurich study found unhelpful.
3. Add what Claude cannot discover. Write down conventions that differ from tool defaults, known pitfalls, and security and performance requirements.
4. Confirm CLAUDE.md loaded. Run /context and check the list under Memory files.
5. Ask for trims. Run /doctor, which proposes cuts to a checked-in CLAUDE.md on Claude Code v2.1.206 or later.

Our view: treat /init output as a list of candidates for deletion, not as a finished file. The commands and behavior above come from the Claude Code documentation.

Should a rule go in CLAUDE.md, a path-scoped rule, a skill or a hook?

Put a rule in CLAUDE.md only if it applies to every session and a mistake is reversible. Rules the repository already demonstrates get deleted. Rules whose failure is irreversible go in a hook or a permission rule. Rules for certain paths or tasks go in a path-scoped rule or a skill.

The four-question placement test for a CLAUDE.md rule:

1. Would a careful reader of the repository already do this? Delete the rule.
2. Is a failure irreversible? Move the rule to a hook or a permission rule. Think production data, credentials and force-pushes.
3. Does the rule apply only to some paths or tasks? Move it to a path-scoped rule in .claude/rules/ or to a skill.
4. None of the above? The rule earns a line in CLAUDE.md.

Verdict: CLAUDE.md is best for always-on, reversible conventions; hooks are best for anything you cannot undo.

Two results look contradictory and are not. Vercel's evals found an always-loaded 8 KB docs index reached a 100% pass rate, while skills reached 79% even with explicit instructions to use them. Vercel was testing Next.js 16 APIs absent from model training data. Knowledge the model lacks and always needs belongs in the always-loaded file; procedures belong in skills.

Hooks have their own failure mode. The 48-trial experiment found a PreToolUse hook blocks only on exit code 2. A script that crashes with exit code 1 lets the tool call through, and a hook matched to Bash does not cover the Write tool. Test every hook by attempting the action it should stop.

Where does CLAUDE.md go and how does it load?

A project CLAUDE.md goes at ./CLAUDE.md or ./.claude/CLAUDE.md and is shared through version control. Personal instructions go in ~/.claude/CLAUDE.md, private per-project notes in ./CLAUDE.local.md, and organization policy in a managed system path. Claude Code concatenates every CLAUDE.md it finds rather than letting one override another.

How CLAUDE.md files load, per the Claude Code documentation:

• Upward at launch. Claude Code loads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it.
• Downward on demand. A CLAUDE.md in a subdirectory loads only when Claude reads files in that subdirectory.
• Closest last. Files nearer the working directory appear later in context, and CLAUDE.local.md is appended after CLAUDE.md at each level.
• Imports expand at launch. @path/to/file imports load with the CLAUDE.md that references them, to a maximum depth of four hops.
• Comments are free. Block-level HTML comments are stripped before CLAUDE.md enters context.

To verify which CLAUDE.md files loaded, run /context and read the list under Memory files.

What is the difference between CLAUDE.md and AGENTS.md?

CLAUDE.md is Claude Code's own instruction file; AGENTS.md is the cross-tool equivalent. Claude Code reads both, but by default it reads AGENTS.md only when no CLAUDE.md or CLAUDE.local.md exists in the working directory or above it. Reading AGENTS.md directly requires Claude Code v2.1.277 or later.

Three details from the Claude Code documentation catch teams out:

• CLAUDE.local.md switches AGENTS.md off. Adding a personal CLAUDE.local.md to a project that relies on AGENTS.md stops Claude reading AGENTS.md, unless Project instructions is set to claude-md-and-agents-md in /config.
• One shared file needs one line. A CLAUDE.md containing @AGENTS.md keeps AGENTS.md as the single source for every tool, with Claude-specific instructions below the import.
• Symlinks break on Windows. ln -s AGENTS.md CLAUDE.md works on macOS and Linux, but the documentation recommends the import when anyone on the team uses Windows.

How do you test your own CLAUDE.md?

To test a CLAUDE.md, run the same task several times with and without one rule, and count the outcomes with a script. Published experimenters used three to five runs per condition, a deterministic checker, and a repository where CLAUDE.md never existed in git history.

1. Pick checkable rules. Choose rules whose outcome a script can verify from the file tree or the command log, such as "never use sed".
2. Build a clean baseline. Use a repository where CLAUDE.md was never committed. In Kaul's test, 10 of 10 runs recovered a deleted CLAUDE.md from git history.
3. Close the other channels. Remove memory plugins and turn off auto memory with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Both leaked rules into Kaul's first attempt.
4. Observe every condition. Run the same logging hook in all arms. Without it, zero violations and nothing watching look identical.
5. Repeat each condition. Run at least three to five sessions per arm. One experimenter nearly published a wrong result from a single run.
6. Change one thing at a time. The cleanest comparison in the 48-trial test differed by exactly four lines of CLAUDE.md.

Record the Claude Code version with every result. The author of the 48-trial test warns that a new model generation could move every number.

Frequently asked questions about CLAUDE.md

Does CLAUDE.md survive /compact? A project-root CLAUDE.md survives compaction. After /compact, Claude Code re-reads the project-root CLAUDE.md from disk and re-injects it. Nested CLAUDE.md files reload only when Claude next reads a file in their directory.

Should CLAUDE.md be committed to git? Commit the project CLAUDE.md so the whole team shares it. Keep personal notes in CLAUDE.local.md and add that file to .gitignore.

Is there a size limit for CLAUDE.md? Claude Code loads a CLAUDE.md of up to 4 MiB in full and skips a larger file. The recommended target is under 200 lines per file.

Is CLAUDE.md part of the system prompt? No. Claude Code delivers CLAUDE.md as a user message after the system prompt. For system-prompt-level instructions, use the --append-system-prompt flag.

Can Claude audit a CLAUDE.md automatically? Yes. /doctor prompt-audit reports outdated, missing-reference and conflicting instructions, and changes nothing until asked. It requires Claude Code v2.1.283 or later.

How do you check that CLAUDE.md loaded? Run /context in a session and look for the file under Memory files. If CLAUDE.md is missing from that list, Claude cannot see it.