How to write a CLAUDE.md that Claude Code actually follows

A CLAUDE.md is a markdown file that Claude Code reads at the start of every session. It holds the things you would otherwise type again: how to run the tests, which conventions differ from the defaults, what not to touch. It works best when it is short, specific and limited to facts Claude cannot work out from the code. Where it lives decides who it applies to. Below: where the files go, what to put in and leave out, what we saw when we tried it, and the problems people report.

Everything here reflects Anthropic's docs as of November 2026, and our test ran on Claude Code 2.1.316.

Where the files go

The memory docs list four places, from broadest to most specific:

How the files load matters more than the table. Claude Code loads the file in your working directory and in every directory above it, concatenates them from the filesystem root down, and puts CLAUDE.local.md last in each directory. Nothing overrides anything. Files in subdirectories load later, once Claude reads or edits a file there.

Three tools help when one file is not enough:

• *`.claude/rules/.md** holds one topic per file. A rule with paths: frontmatter, such as src/api/*/.ts`, loads only when Claude touches a matching file.
• @path/to/file imports another file. Imports go up to four hops deep, but they do not save context: the imported file loads with the file that imports it.
• claudeMdExcludes in a settings file skips CLAUDE.md files you never need, which helps in a monorepo. The large codebases guide shows the layout with one root file and one per package.

If your team also uses Codex or Cursor, the AGENTS.md section matters. Claude reads AGENTS.md only when there is no CLAUDE.md, so write @AGENTS.md in your CLAUDE.md to share one file.

If you work in several git worktrees, a gitignored CLAUDE.local.md exists only in the worktree where you made it. Import a file from your home folder instead, as the worktrees guide covers.

What to put in

Anthropic's best practices page says to keep CLAUDE.md short and to write only what Claude cannot work out from the code. It names four kinds of content:

• The exact test, typecheck and lint commands, and how to run one test file.
• Places where the code is misleading, such as an old pattern new code must not copy.
• Decisions that are not in the repo: how deploys work, which helper the team settled on.
• Anything you have had to correct twice.

Each line should be checkable. The memory docs give the contrast: "Use 2-space indentation" instead of "Format code properly", and "Run npm test before committing" instead of "Test your changes".

A file in that shape fits on one screen:

## Commands
- Typecheck and build before committing: pnpm typecheck && pnpm build
- Run one test file: node --test scripts/routines.test.mjs

## Gotchas
- Schema changes go in a new file under migrations/. Never edit an applied one.
- Ingestion must stay idempotent on event_id.

Our own project file is 10 lines and follows the same shape. Run /init to get a first draft, then spend your time deleting from it.

What to leave out

• Things the code already says. Directory layouts, dependency lists and architecture overviews. The /doctor checkup proposes cutting these from a checked-in file, and makes the cuts once you confirm.
• Style rules a tool can enforce. HumanLayer's post Writing a good CLAUDE.md puts it as "never send an LLM to do a linter's job". Run the formatter from a hook instead.
• Long procedures. A release checklist belongs in a skill, which loads only when it applies. Our skills guide explains the difference.
• Shouting. The best practices page says current models follow a plainly worded line and that piling on emphasis "mostly makes Claude over-apply the rule".
• Rules that must never break. CLAUDE.md is advisory.

That last point is the one people miss. The docs say Claude treats CLAUDE.md as "context, not enforced configuration". For "never read .env" or "don't touch migrations", the best practices page says to use a hook, a deny rule or a managed setting. A PreToolUse hook that exits with code 2 blocks the call every time. Our hooks guide has working examples, and the official hooks guide covers the events.

What happened when we tried it

We made a throwaway folder with a root CLAUDE.md that sets a codeword, and a second CLAUDE.md in sub/ with another. Then we ran claude -p with no file reads allowed:

$ claude -p "What is the project codeword and the sub codeword? ..." --permission-mode dontAsk
Project codeword: PELICAN-41.
Sub codeword: none in my instructions. Only one codeword given.

The root file was in context. The nested one was not. Then we asked Claude to read sub/a.txt first, with --allowedTools Read:

Project codeword: PELICAN-41
Sub codeword: HERON-77

That matches the docs: a subdirectory file loads after Claude touches that directory, so a rule there cannot protect the first edit in it. The single-turn call took about 10 seconds and cost $0.12 in the JSON output.

Next we put a block-level HTML comment and an @deploy.md import in the root file:

Codeword: PELICAN-41
Hidden word: none
Deploy secret word: KESTREL-09

The comment was stripped and the import was expanded, as the docs describe. So you can leave notes for maintainers in comments without paying for them in context.

We did not test --bare, which the docs say skips CLAUDE.md. Our headless guide covers when that matters in scripts.

One more thing we noticed from inside this routine. Our project file says to run pnpm typecheck && pnpm build before committing, and the task prompt for this run said to skip both because CI runs them. We followed the prompt. The more specific, more recent instruction won, and the file stayed a guideline. That is what "advisory" means in practice, and it is why we keep checks that must run in CI.

Problems people hit

1. A long file gets ignored. In issue 17530 a user with a roughly 400-line file said Claude skipped required steps in about half of sessions, even with "MUST" and "HARD RULE". The issue was closed as not planned by a stale-issue bot, with no maintainer reply. The fix the docs give is a shorter file and plainer lines. For the rule that cannot bend, use a hook.

2. Rules seem lost after compaction. Issue 6354 is still open. A maintainer could not reproduce it: in the maintainer's test the CLAUDE.md was still in context after /compact. The docs say the project-root file is re-read from disk after compaction, while nested files and path-scoped rules reload on demand. So an instruction that vanished was probably given only in chat, or sits in a nested file that has not reloaded. Move it into the root file, and check /context all.

3. AGENTS.md is not picked up. The request in issue 6235 drew over a thousand reactions. Native support arrived in v2.1.277, but with a catch: a CLAUDE.md anywhere on the path, including a CLAUDE.local.md, makes Claude skip AGENTS.md. Fix it with @AGENTS.md at the top of CLAUDE.md, or set Project instructions to claude-md-and-agents-md in /config.

Our take

These are our opinions, from a short file and a short test.

Keep the file small enough that you can read it in one breath. We would rather have ten lines that are all true than two hundred that are mostly obvious. The tests we ran suggest the loading rules are sound. What fails in practice is the file itself: stale lines, contradictions and rules that were never going to be followed every time.

We would use CLAUDE.md for commands, gotchas and decisions. We would use hooks for anything with zero exceptions. We would use skills for procedures, and nested files only when a monorepo package really has its own conventions. We would not paste in the architecture, because Claude reads the repo.

Once a month, delete every line Claude would do correctly without it. To check yours, paste it into the roaster at /roast. It gives a score out of 100 on five criteria drawn from Anthropic's and HumanLayer's advice, quotes your own lines back, and writes fixes you can paste. Briefkin built it, so we are biased, but it needs no account and the file is not kept.

Sources

• How Claude remembers your project (Anthropic docs)
• Best practices for Claude Code (Anthropic docs)
• Automate actions with hooks (Anthropic docs)
• Set up Claude Code in a monorepo or large codebase (Anthropic docs)
• Writing a good CLAUDE.md (HumanLayer)
• Claude Not Reading Claude.md, issue 17530 (GitHub issue)
• Claude forgets everything in CLAUDE.md after compaction, issue 6354 (GitHub issue)
• Support AGENTS.md, issue 6235 (GitHub issue)