How to Write a CLAUDE.md That Claude Code Actually Follows

A good CLAUDE.md is short, specific and points to other files instead of holding everything itself. It contains what a model cannot work out by reading your repository: commands to run, conventions that differ from the defaults, and rules that always apply. Anthropic’s docs give a target of under 200 lines per file, and everything else belongs somewhere that loads only when needed.

What is a CLAUDE.md and where does Claude Code look for it?

A CLAUDE.md is a plain markdown file that Claude Code reads at the start of a session, so you do not have to repeat the same instructions in every chat. Per the memory docs (checked 2026-10-23), there are four locations, from broadest to most specific: a managed policy file set by an organization, your user file at ~/.claude/CLAUDE.md, the project file at ./CLAUDE.md or ./.claude/CLAUDE.md, and a personal ./CLAUDE.local.md that you add to .gitignore.

Files in the working directory and every directory above it load at launch. Files in subdirectories load on demand. They are all concatenated into context rather than overriding each other, so two files that disagree both reach the model. That is why contradictions matter (see the maintenance section below).

How long should a CLAUDE.md be?

Aim for under 200 lines per file. The docs word it as a target: “target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence” (checked 2026-10-23, memory docs). It is not a hard limit. The separate hard ceiling is 4 MiB, above which a file is skipped.

Do not mix this up with the auto memory file, MEMORY.md. That one has its own rule: the first 200 lines or 25KB are loaded each session. It is a different mechanism, written by Claude rather than by you, and the number does not apply to your CLAUDE.md. The docs give no figure for how much adherence drops as a file grows, so treat the 200 as a sensible budget and not as a measured threshold.

We break our own advice in one place. The global file we keep for every project is 583 lines long (wc -l, 2026-10-23), and we know it is too long. It grew over time. About half of it is one block about memory, which is what a file looks like when nothing ever gets moved out. The sibling guide shows what we do about the rules that must hold anyway.

What goes in a CLAUDE.md, and what stays out?

Put in the facts Claude needs in every session, written so you could check them. The docs list “build commands, conventions, project layout, ‘always do X’ rules” and give examples of the style: “Use 2-space indentation” instead of “Format code properly”, and “API handlers live in src/api/handlers/” instead of “Keep files organized” (checked 2026-10-23, memory docs).

A good moment to add a line, per the same docs: Claude makes the same mistake a second time, a code review catches something it should have known, or you type the same correction you typed last session.

Keep out anything Claude can derive from the code itself, such as a list of folders or dependencies (the docs say /doctor proposes cutting exactly that, per the memory docs). Also keep out long procedures and detail that matters for one part of the codebase. The docs say to move those to a skill or a path-scoped rule. Our own practice is to leave reference material in separate files and have the CLAUDE.md say where to find it.

One limit to know about: the docs say Claude treats these files “as context, not enforced configuration”. If a rule must never be broken, a CLAUDE.md line is not enough. The sibling guide linked at the end covers that.

How do I structure a CLAUDE.md as a routing table?

Make the core of the file a table that says, for each kind of task, which folder to work in and which file to read first. The model then loads detail only for the task in front of it. This is our own convention, not an Anthropic recommendation, and we have no measurement showing it improves adherence. We use it because it keeps the file short and the detail close to the code.

This is a trimmed excerpt from this repository’s own CLAUDE.md, which was 84 lines long when we counted on 2026-10-23:

# AccrueDev Platform

## Routing Table

| Task | Path | Read | Agent/Skill |
|------|------|------|-------------|
| Landing page changes | apps/web/ | apps/web/README.md | @code-writer |
| CLI development | packages/cli/ | packages/cli/README.md | @code-writer |
| Content updates (skills/agents) | content/ | content/README.md | @content-extractor |
| Manifest generation | content/manifest.json | /build-manifest | @manifest-builder |
| API/auth worker | infra/workers/api/ | _meta/architecture.md | @code-writer |
| Billing webhook | infra/workers/billing/ | _meta/billing.md | @billing-integrator |

## Naming Conventions
- Files: kebab-case (build-manifest.ts, content-extractor.md)
- CLI commands: verb (login, pull, status, logout)

Each row answers one question: given this task, where do I look. The full file also has a stack summary above the table, and below it sub-agents, slash commands, a documentation rule, a development pipeline and a memory protocol. Our template caps a file at 80 lines (about 100 for complex projects), and if a file goes over, we move a section out rather than trimming sentences. That 80 is our own rule, and the file above is already over it. Our routing-table template is part of the paid course. It has seven sections: Project Identity, Stack, Routing Table, Naming Conventions, Agents / Tools Available, Memory / Session Protocol and References.

How do I split rules per folder?

Use the .claude/rules/ directory. The docs say to place markdown files there, with each file covering one topic, and they are discovered recursively. A rule without any frontmatter loads at launch, like a CLAUDE.md. A rule that starts with a paths: field containing globs, such as "src/api/**/*.ts", loads when Claude uses the Read, Write or Edit tool on a matching file (a single-file Bash read such as cat counts too, per the docs) (checked 2026-10-23, memory docs).

Two details from the docs. paths is the only frontmatter field Claude Code reads in a rule, and any other field is ignored without an error. And a path-scoped rule does not persist through compaction (the automatic summarising of a long conversation; context window docs, checked 2026-10-23): if a rule must always be there, drop the paths: field or move it to the project-root CLAUDE.md. You can also place a CLAUDE.md inside a subfolder, which loads when Claude works there.

How do I keep a CLAUDE.md from rotting?

Treat it like code: small edits when something goes wrong, and a periodic read-through. This routine is our own practice, not documented advice.

• When Claude repeats a mistake, add one specific line, not a paragraph.
• When a line has not mattered for a while, delete it.
• Reread the whole file now and then and look for two lines that contradict each other. The docs warn that when instructions conflict, “Claude may pick one arbitrarily”.
• Keep notes for human maintainers in block-level HTML comments, which the docs say are stripped before the content reaches Claude.
• Use /context to see which memory files actually loaded.

Claude Code also has /doctor prompt-audit, which the docs say looks for instructions written for older models, references to files or commands that do not exist, and files that contradict each other. It changes nothing until you ask (version 2.1.283 or later).

Should I use CLAUDE.md or AGENTS.md?

If you only use Claude Code, a CLAUDE.md is the simplest choice. If your repo already has an AGENTS.md and no CLAUDE.md, Claude Code reads it directly (version 2.1.277 or later; some sessions need 2.1.281 or later). Behaviour here changed recently, so we state the version: the docs say Claude Code reads AGENTS.md only when no CLAUDE.md or CLAUDE.local.md exists in the working directory or above, and needs version 2.1.277 or later (memory docs, checked 2026-10-23). With both files present, it uses your CLAUDE.md files only.

If other tools in your team read AGENTS.md, the docs suggest a CLAUDE.md that imports it with @AGENTS.md at the top and then adds Claude-specific notes. Check the current docs before relying on this, because it may change again.

Next step

If you want the routing-table template and the reasoning behind it, the AccrueDev course includes it, and the pricing page lists what each tier contains. If your CLAUDE.md is already written and Claude still ignores parts of it, read why Claude Code ignores your CLAUDE.md.