How to write a CLAUDE.md file: where it loads and what goes in it

What is a CLAUDE.md file?

Each Claude Code session starts with a fresh context window. CLAUDE.md is one of two ways knowledge survives from one session to the next. You write it in plain Markdown, and Claude reads it at the start of every conversation. The other mechanism is auto memory, which is notes Claude writes itself from your corrections and preferences. The official memory documentation covers both.

The part most people miss is that Claude treats CLAUDE.md as context, not as enforced configuration. The file is delivered as a message after the system prompt. Claude tries to follow it, and the docs say there is no guarantee of strict compliance, especially for vague or conflicting instructions. That shapes how you write it, and it tells you when not to use it: for a rule that must hold every time, use a hook.

A CLAUDE.md is the cheapest improvement you can make to a Claude Code project. It turns a tool that asks the same questions every morning into one that already knows how your project runs. If you are new to the tool, start with the Claude Code tutorial and come back.

Where does Claude Code load CLAUDE.md from?

CLAUDE.md files can live in several places, each with a different scope. The table lists them from broadest to most specific, which is also the order they load, so a project instruction lands in context after a user instruction.

Loading follows the folder tree. Claude Code loads CLAUDE.md and CLAUDE.local.md from your current working directory and every directory above it. Start Claude in foo/bar/ and it reads foo/bar/CLAUDE.md and foo/CLAUDE.md. All of them are concatenated into context; none overrides another. The ones closer to where you launched Claude are read last, and within a folder, CLAUDE.local.md comes after CLAUDE.md.

Files in subdirectories below your working directory are different. They load on demand, the first time Claude reads or edits a file in that subdirectory. That makes nested CLAUDE.md files a good home for instructions that only matter in one part of a monorepo.

• Check what loaded. Run /context and look under Memory files. Use /memory to open and edit them.
• AGENTS.md. If your repository uses AGENTS.md for other coding tools, Claude reads it only when no CLAUDE.md exists in your working directory or above. To share one file, create a CLAUDE.md containing @AGENTS.md on its own line and put any Claude-specific notes below it.
• Extra directories. Folders you add with --add-dir do not load their CLAUDE.md files unless you set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.

How do you create a CLAUDE.md?

1. Open Claude Code in your project root.
2. Run /init. Claude analyzes the codebase and writes a CLAUDE.md with the build commands, test instructions and conventions it finds. If one already exists, /init suggests improvements instead of overwriting it.
3. Open the result and cut it down. Delete anything Claude could work out from the code itself, such as a directory listing or a dependency list.
4. Add what Claude cannot guess: why a decision was made, what bit you last time, which commands you actually use.
5. Run /context to confirm the file loads, then work normally.
6. Whenever Claude makes the same mistake twice, add a one-line rule.

The docs give a useful test for what to add: write down what you would otherwise re-explain. Add an entry when Claude repeats a mistake, when a code review catches something Claude should have known, when you type the same correction you typed last session, or when a new teammate would need the same context.

Setting the environment variable CLAUDE_CODE_NEW_INIT=1 before /init gives an interactive, multi-step flow that also offers to set up skills and hooks.

What should go in CLAUDE.md, and what should stay out?

Keep to facts Claude should hold in every session: build commands, conventions, project layout, and always-do-X rules. Everything else belongs somewhere else.

The single biggest lever is being concrete enough to verify. The docs' own pairs:

Also include reasons when a rule looks arbitrary. "Do not use the ORM for reports, it generated a slow query in production" prevents Claude from "fixing" your workaround. Avoid contradictions: if two instructions conflict, Claude may pick one arbitrarily, and that includes conflicts between a nested CLAUDE.md and the root one.

What does a good CLAUDE.md look like? A full template

Copy this, delete the lines that do not apply, and replace every bracket. It is written for a typical web project; the structure carries over to any stack. Aim to keep your finished file under 200 lines.

# [Project name]

[One or two sentences: who uses this and what it does.]

## Commands
- Install: `[pnpm install]`
- Dev server: `[pnpm dev]` (runs on port [3000])
- Run all tests: `[pnpm test]`
- Run one test file: `[pnpm test path/to/file.test.ts]`
- Type check: `[pnpm tsc --noEmit]`
- Lint and format: `[pnpm lint]`

## Layout
- `[src/app/]`: pages and routes
- `[src/lib/]`: shared logic; no UI code here
- `[src/components/]`: UI components
- `[supabase/migrations/]`: SQL migrations, write new files, never edit applied ones

## Conventions
- [TypeScript strict mode. No `any`.]
- [2-space indentation, double quotes, no semicolons.]
- [Validate every external input with Zod at the boundary.]
- [Money is stored in integer cents. Dates are UTC.]
- [Name test files next to the code: `thing.ts` and `thing.test.ts`.]

## Workflow
- Before you start a feature, read the files involved and state a plan. Do not edit during planning.
- Make the smallest change that works. Do not refactor code you were not asked to touch.
- After a change, run the type check and the tests. Fix failures before saying you are done.
- Commit in small steps with a message that says why, not just what.

## Do not
- Do not edit `.env*` files or anything under `[migrations/applied/]`.
- Do not add a dependency without asking. Say what it replaces and how big it is.
- Do not delete or skip a failing test to make the suite pass.

## Known pitfalls
- [The staging database resets every night; never rely on data surviving a day.]
- [The `[date lib]` parses '01/02' as [format]. Always pass an explicit format.]
- [Why we do X instead of the obvious Y: reason.]

## More detail
- Architecture notes: @docs/architecture.md
- API conventions: @docs/api.md

Two notes on that template. The @docs/architecture.md lines are imports: the files are expanded into context alongside the CLAUDE.md that references them. Imports help you organize a long file, but they do not reduce its cost, because imported files load together with the importer. And the "Known pitfalls" section is where a CLAUDE.md earns its keep, because those are the facts no tool can read off your code.

What if you are not a developer?

A CLAUDE.md is just as useful if you are building your first project from an idea and cannot read the code Claude produces. Use it to set the working rules, not the tech details. Here is a short version for that case.

# [App name]

## What we are building
[Who it is for, in one sentence. The one thing it does, in one sentence.]

## How to work with me
- I am not a developer. Explain what you changed in plain language after every step.
- Build one feature at a time. Stop after each one so I can try it.
- Before installing any package or running a command that deletes files, tell me and wait for a yes.
- If my request is unclear, ask one question rather than guessing.

## Rules for the code
- Pick the simplest approach that works. No extra features I did not ask for.
- Tell me how to run the app and how to check that the change worked.
- Commit to git after each working step with a short message.

## Not in the first version
- [Accounts and logins]
- [Payments]
- [Anything I list here later]

The "not in the first version" list does more than it looks. It stops the scope from growing without you noticing. The same idea underlies the guide to scoping an MVP. If you do not yet have an idea to build, browse the ideas on the board, where each one comes with a generated build prompt you can paste in after your CLAUDE.md is in place.

How do imports and .claude/rules keep it short?

Once a CLAUDE.md passes about 200 lines, adherence drops and context cost rises. The docs suggest moving instructions that matter for only part of the codebase into path-scoped rules. Put Markdown files in .claude/rules/, one topic per file, and add a paths field in the frontmatter so each loads only when Claude works with matching files.

---
paths:
  - "src/api/**/*.ts"
---
# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

• Rules without `paths` load at launch with the same priority as .claude/CLAUDE.md.
• Imports use @path/to/file, resolve relative to the file containing them, and nest up to four hops. Wrap a path in backticks to mention it without importing it.
• Private notes for maintainers: block-level HTML comments in CLAUDE.md are stripped before the content reaches Claude, so they cost no context.
• Personal, uncommitted preferences go in CLAUDE.local.md. If you work across several git worktrees, import a file from your home directory instead, such as @~/.claude/my-project-instructions.md.
• Size limits. A file over 4 MiB is skipped. Files that load on demand have a per-file character limit, and Claude receives only the start of anything longer.

To have Claude audit your instruction files for stale or conflicting content, run /doctor prompt-audit. It reports findings with proposed edits and changes nothing until you ask.

Why is Claude not following my CLAUDE.md?

Work down this list in order. It follows the troubleshooting section of the memory docs.

1. Is it loaded? Run /context and check Memory files. If your file is missing, Claude cannot see it. A CLAUDE.md in a subdirectory will not appear there, because it loads on demand.
2. Is it in a location that loads for your session? Check the table above, and the folder you started Claude from.
3. Is the instruction concrete? "Use 2-space indentation" beats "format code nicely".
4. Does anything contradict it? Search your other CLAUDE.md files and .claude/rules/ for conflicting guidance.
5. Is the file too long? Past about 200 lines, adherence suffers. Trim it or split it into rules.
6. Must it hold every time? Then it is not a CLAUDE.md job. Write a hook, which runs as a shell command at a fixed event regardless of what Claude decides.

One reassurance for long sessions: the project-root CLAUDE.md survives /compact. Claude re-reads it from disk afterwards. An instruction you only gave in conversation does not, so add it to the file if it should persist.