How do you write a CLAUDE.md that Claude actually follows?

CLAUDE.md is not enforced config — why longer means less followed

CLAUDE.md is a file where you write your project's guidance — coding rules, structure, gotchas — and Claude Code reads it alongside every session. But it is not enforced configuration. It is not checked and blocked by code; it is instruction text Claude consults, which it may follow or miss.

So piling rules into one file backfires. The longer it gets, the more the rules compete, and the core instructions that hurt when broken get buried under many trivial ones and followed less precisely. The trick is not 'write more' but 'keep it tight.' The five points below are how.

Is CLAUDE.md even the right tool — hard rules go in hooks

A terminal where a hook blocks a push to main with the message 'never push to main', explained as a project-level hook that blocks regardless of permission settings — a deliberate guardrail. — A hook actually blocks 'never push to main' — enforcement, not a request (Anthropic official video)

Before writing a rule, ask: does this really belong in CLAUDE.md? A rule you must enforce, like 'never push directly to main,' belongs in a pre-tool-use hook, not an instruction. The hook is designed to stop the action the moment Claude tries it. It is not 'a request you hope is honored' but 'a block that actually stops the violation.'

The distinction: a CLAUDE.md line is something you want Claude to follow; a hook is something that actually stops it when broken. Rules that hurt when broken — production deploys, force pushes, dropping the production database — move to hooks instead of shouting 'IMPORTANT' in a CLAUDE.md line. Then CLAUDE.md gets shorter, and what must be enforced actually is.

CLAUDE.md lives in four places — managed, user, project, local

A diagram of the four places CLAUDE.md lives, with icons and descriptions — Managed Policy (org, can't exclude), User (personal, all projects), Project (shared with team), Local (git-ignored, personal notes for this repo). — The four places CLAUDE.md lives: managed policy, user, project, local — all load together (Anthropic official video)

CLAUDE.md is not just one file in your project folder. It lives in four places. Managed policy is the org-level file your platform team controls and you can't exclude. User is your personal settings applied across every project on your machine. Project is the file you share with your team. Local is git-ignored, your personal notes for this repo only.

Claude loads these memory files all together. Nothing is dropped, and org policy is always in play. So temporary context that is just yours — 'keep these architectural decisions in mind while I refactor this sprint' — goes in local, not the shared project file. The point is not to mix rules everyone should see with your own temporary notes.

Split with @path imports — but know what they buy

CLAUDE.md open in an editor with the comment 'Split into topic files for readability — all still load at launch', three @path import lines like @.claude/conventions/code-style.md, and a ## Rules section below. — @path imports help you organize, but they expand inline at launch and don't reduce context (Anthropic official video)

As CLAUDE.md grows, the @path import syntax lets you split instructions across files. Writing something like `@.claude/conventions/code-style.md` links that file's content in place. Splitting code style, testing, and workflow into topic files makes a large CLAUDE.md easier to maintain.

But know exactly what imports do. At launch, Claude expands imported files inline, right alongside the file that references them. So imports help you organize a large file, but since everything still loads up front, they do not reduce context (token) usage. Don't mistake 'I split it, so it got lighter' — organizing and reducing context are two different things.

Phrasing decides obedience — be specific, name the replacement

A CLAUDE.md conventions list written entirely as 'Don't' rules — 'Don't use default exports', 'Don't use any', 'Don't put business logic in components', and so on. — 'Don't use default exports' is vague with no alternative — 'Use named exports' is better (Anthropic official video)

The same rule is followed to different degrees depending on how you write it, and most rules fail because they are vague. First, be specific and checkable. 'Follow best practices' — no one knows exactly what that means, so don't expect Claude to. Instead write something verifiable, like 'put new API routes in src/api/handlers, one per file.'

Second, don't just forbid — name the replacement. 'Don't use default exports' leaves open what to use instead, so the interpretation stays loose. 'Use named exports, not default exports' closes the gap. If you only say what not to do, Claude may pick the wrong alternative; point at what to do instead.

Emphasis is a budget — spend IMPORTANT sparingly

A CLAUDE.md 'HARD RULES — DO NOT BREAK THESE' list where every line is plastered with uppercase emphasis like YOU MUST NEVER, IMPORTANT, and CRITICAL. — Put YOU MUST and IMPORTANT on every rule and nothing stands out — spend emphasis on just two or three (Anthropic official video)

Emphasis has a budget. IMPORTANT and YOU MUST raise a rule's priority, but only relative to the quieter rules around them. Put IMPORTANT and YOU MUST on every line and it is the same as emphasizing nothing. Shout everything and what actually matters disappears.

So spend emphasis only on the two or three rules that truly hurt when broken. Leave the rest as plain statements, and move whatever must be enforced into hooks (as above). The more sparingly you use emphasis, the more force the emphasis you keep actually carries.

Keep CLAUDE.md under revision — treat mistakes as bug reports

A terminal where the user types 'Ok, put in the CLAUDE.md file' to have the rule they just decided added to CLAUDE.md. — After seeing a mistake, tell Claude to 'put it in the CLAUDE.md file' and it writes the rule (Anthropic official video)

CLAUDE.md is not a write-once document but one you keep revising. When Claude does the wrong thing, treat it as a bug report against CLAUDE.md. After you see what went wrong and why, tell Claude 'add that to the CLAUDE.md file as a rule,' and it will write the rule for you.

This way CLAUDE.md sharpens gradually from problems you actually hit. Rules distilled from real failures are followed far better — and carry far less bloat — than rules you imagine and pre-load.

Conclusion — treat CLAUDE.md like production code

Treat CLAUDE.md like production code. You should be able to justify every line, and any line you can't justify, you delete. Move what must be enforced into hooks, and organize a grown file with @path imports.

And scope conventions that apply to only one area so they load only there (for example, a CLAUDE.md in the relevant subdirectory is read only when you work in that folder). The leaner the file, the more of it Claude follows. In the end, what makes Claude follow your CLAUDE.md is not how much you wrote but how much you held back.