How to Write a CLAUDE.md File (With Examples) That Actually Works

You add a rule to your CLAUDE.md. Claude follows it for a while, then quietly stops. You add three more rules. Now it ignores the first one too. This is the most common complaint I hear from teams adopting Claude Code, and it usually traces back to a single misunderstanding: CLAUDE.md is not configuration that gets enforced. It is context that gets read.

Claude reads your CLAUDE.md at the start of every session and loads it as a user message after the system prompt. It tries to follow it. But there is no guarantee of strict compliance, especially for vague or conflicting instructions. Once you internalize that — advisory context, not enforced config — almost every "Claude won't listen" problem becomes solvable. This guide covers the scopes, what belongs in the file, the discipline that keeps it working, and when to stop writing prose and reach for a hook.

The four scopes (and which one you actually want)

CLAUDE.md exists at four levels, loaded from broadest to most specific. They are concatenated, not overridden — instructions closer to where you launched Claude are read last.

Within the directory tree, files are read from filesystem root down to your working directory, and CLAUDE.local.md is appended after CLAUDE.md in the same directory. Subdirectory CLAUDE.md files load on demand when Claude reads files there — useful for monorepos.

The one to start with is the project file, checked into git so your team contributes to it. Reserve the user file for genuinely personal preferences (your preferred commit style, your "don't narrate every step" rule) that have no business in a shared repo.

What to include — and what to leave out

Anthropic's guidance here is refreshingly blunt. The decision is not "what might be useful" — it's "what does Claude get wrong without this."

Include:

• Bash commands Claude can't guess (custom build/deploy scripts)
• Code style rules that differ from defaults
• Testing instructions and your preferred test runner
• Repository etiquette: branch naming, PR conventions
• Architectural decisions specific to your project
• Environment quirks: required env vars, setup gotchas
• Non-obvious behaviors and common gotchas

Exclude:

• Anything Claude can figure out by reading the code
• Standard language conventions
• Detailed API docs (link to them instead)
• Info that changes frequently
• Long explanations or tutorials
• File-by-file descriptions of your tree
• Self-evident advice like "write clean code"

The key word in the include list is differ. "Use 2-space indentation" earns its place only if your project actually uses 2-space and the default would be something else. A rule that tells Claude to do what it already does is pure noise.

Be specific enough to verify

Vague instructions are the second-biggest failure mode after bloat. The official examples make the contrast clear:

If you can't verify whether Claude followed a rule, Claude can't reliably follow it either. Use markdown headers and bullets, not dense paragraphs. Here is the shape of a minimal, effective file — close to the example in Anthropic's docs:

# Code style
- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible

# Workflow
- Typecheck when you're done making changes
- IMPORTANT: prefer running single tests, not the whole suite, for performance

That IMPORTANT is deliberate. Anthropic explicitly recommends emphasis like IMPORTANT or YOU MUST to tune adherence on the rules that matter most. Use it on the two or three rules you genuinely care about — if you bold everything, you've bolded nothing.

The pruning test

This is the single most valuable habit, straight from the best-practices docs. For each line in your file, ask:

Would removing this cause Claude to make mistakes? If not, cut it.

Run that test every time the file grows. The named failure pattern is "the over-specified CLAUDE.md" — when the file gets too long, Claude ignores half of it because the important rules drown in the noise. The fix is always the same: ruthlessly prune. If Claude already does something correctly without the instruction, delete the instruction. If the rule must always happen, convert it to a hook.

Two more tricks keep files lean. Block-level HTML comments (<!-- ... -->) are stripped before content is injected, so they cost zero tokens — use them for maintainer notes. And @path imports help you organize, but remember imported files still load into context at launch, so they don't cut token usage.

When CLAUDE.md isn't enough: use a hook

Here is the line that should govern your whole approach. Community estimates put adherence around 80% — fine for guidance, not fine for anything that must happen every single time.

If an instruction must run at a fixed point — format after each edit, lint before every commit, block writes to a protected path — a CLAUDE.md rule will eventually be skipped. Use a hook. Hooks execute as shell commands at fixed lifecycle events, regardless of what Claude decides. A PreToolUse hook can block an action outright. The mental model:

• CLAUDE.md = advisory. Claude reads it and tries.
• Hooks = deterministic. The shell runs them, no judgment involved.

A useful corollary: multi-step procedures and instructions relevant to only part of the codebase don't belong in CLAUDE.md at all. Move them to a skill (.claude/skills/, loaded on demand) or a path-scoped rule. CLAUDE.md is for what applies to every session.

Scaling up: rules directories and large repos

When a project file outgrows 200 lines, split it. Put topic files in .claude/rules/ — code-style.md, testing.md, security.md. Rules without paths frontmatter load every session at the same priority as .claude/CLAUDE.md. Add a paths glob in YAML frontmatter and the rule loads only when Claude touches matching files — perfect for "these rules apply to the API layer, those to the frontend."

In monorepos, claudeMdExcludes (in .claude/settings.local.json, glob patterns matched against absolute paths) skips irrelevant ancestor CLAUDE.md files. Managed policy files can't be excluded.

Debugging and maintenance

Treat CLAUDE.md like code. A few operational notes:

• Generate a starter with /init — Claude analyzes your codebase for build commands, test setup, and conventions. If a file already exists, /init suggests improvements instead of overwriting.
• Verify what's loaded with /memory. It lists every CLAUDE.md, CLAUDE.local.md, and rules file in context. If your file isn't there, Claude literally cannot see it — that alone explains a lot of "ignored" rules.
• It survives /compact — the project-root file is re-read from disk and re-injected after compaction. Nested subdirectory files are not re-injected automatically; they reload next time Claude reads a file in that directory.
• Don't confuse it with auto memory. CLAUDE.md is written by you (rules). Auto memory is written by Claude (learnings), stored under ~/.claude/projects/<project>/memory/ with a MEMORY.md index — and unlike CLAUDE.md, only the first 200 lines or 25KB of that index load each session.

Add to the file when Claude repeats a mistake, when a code review catches something it should have known, when you find yourself re-typing the same correction, or when a new teammate would need the same context. Prune it on the same schedule. One last caution worth heeding: aspirational rules you don't actually follow yourself just create noise — write what's true, not what you wish were true.

Bottom line

CLAUDE.md is the highest-leverage file in your repo for steering an AI coding agent — but only if you treat it as context to be earned, not a config to be filled. Keep it under 200 lines, write rules specific enough to verify, mark the critical few with IMPORTANT, and run the pruning test relentlessly. When a rule has to fire every time, stop writing prose and write a hook. And when something feels ignored, run /memory before you assume Claude is misbehaving — half the time, it just never saw the file.