How to write a CLAUDE.md file that steers Claude Code reliably

A CLAUDE.md file is the set of standing instructions Claude Code reads at the start of every session. Get it right and Claude stops guessing your build command, your conventions, and your project layout. Bloat it and Claude quietly ignores the very rules you wrote to control it. By the end of this guide you will have a lean CLAUDE.md that Claude follows on the first try, plus a method for growing it without turning it into documentation nobody reads.

What CLAUDE.md actually is, and what it is not

CLAUDE.md is a Markdown file loaded into the context window automatically when Claude Code launches. It is not documentation and it is not a wiki. It is a context-injection file: every line competes with the task in front of the model for a share of its attention.

Claude Code walks upward from your working directory to the repository root and loads every CLAUDE.md it finds, so files stack by scope. The official memory docs set the precedence order: enterprise policy first, then project memory (./CLAUDE.md), then user memory (~/.claude/CLAUDE.md), then local overrides (./CLAUDE.local.md). Files in subdirectories below your working directory are not loaded at launch. They enter the context only when Claude reads a file in that subdirectory during the session.

This matters because context is finite. As the number of instructions grows, instruction-following quality drops across the board, not just for the new rules. A file that tries to say everything ends up enforcing nothing.

What you need before you start

• Claude Code installed and a project open in your terminal.
• A short list of the commands you run most: build, test, lint, typecheck.
• The three or four conventions a new engineer would get wrong on day one.
• Ten minutes. A good CLAUDE.md is short by design.

Step 1: Generate a baseline with /init

Do not write the file from scratch. Run /init in your project root. Claude explores the codebase with a subagent, fills gaps with follow-up questions, and proposes a CLAUDE.md you can review before it writes anything. Treat the output as a first draft. It over-includes on purpose, and your job in the next step is to cut.

Step 2: Cut everything Claude can infer

Read every generated line and apply one test: if you delete this, will Claude make a mistake? If the answer is no, delete it. Claude reads your package.json, your folder names, and your imports on its own. It does not need a paragraph explaining that you use React, or that components live in src/components. Keep only the facts that change decisions and cannot be inferred from the code: the non-obvious build step, the convention that contradicts the framework default, the directory that looks safe to edit but is generated.

Length is the proxy metric. The root CLAUDE.md at HumanLayer, a team that ships heavily with Claude Code, runs under sixty lines. A widely shared rule of thumb keeps a high-signal file in the 80 to 120 line range. Past roughly 200 lines, Claude cannot hold every instruction while also doing the work.

Step 3: Write positive, universal rules

Two phrasing rules move adherence more than any structure change. First, write what to do, not what to avoid. "Use the design-system utilities for spacing" beats "do not hardcode margins": Claude follows positive instructions more reliably than negations. Second, keep each rule universal. CLAUDE.md loads into every session, so a rule about how to build one specific database table is noise on the sessions that touch something else. Push situational guidance into the files it applies to, and keep the root file to rules that hold everywhere.

Group related rules under Markdown headers and use bullets, not prose. The header hierarchy is not decoration: models exploit it to locate the relevant block, and imperative bullets parse more cleanly than paragraphs.

Step 4: Split by scope and import the rest

Personal habits and team standards do not belong in the same file. Put machine-wide preferences, like how you want commit messages written, in ~/.claude/CLAUDE.md so they load in every project. Put team-shared, project-specific facts in the committed ./CLAUDE.md. Put anything private or experimental in ./CLAUDE.local.md, which stays out of version control.

When the project file starts to sprawl, split it. CLAUDE.md supports an @path/to/file import syntax, so a short root file can pull in @.claude/testing.md or @.claude/api-conventions.md and give each topic its own owner. One honest caveat: imported files still load at launch and count against the context window, so imports buy readability and clean ownership, not a smaller footprint. Keep the combined total lean no matter how many files you split it across.

Step 5: Move fixed checks to hooks, not prose

Some rules must run at a fixed moment: format after every edit, lint before every commit, never write to a generated directory. A CLAUDE.md line asking for this will eventually be skipped, because the model decides each turn whether to honor it. Hooks do not decide. They execute as shell commands at fixed lifecycle events regardless of what Claude does. If a rule is non-negotiable and mechanical, it belongs in a hook, not in prose. We cover the event model in our guide to Claude Code hooks.

Step 6: Grow it reactively, not speculatively

The fastest way to bloat a CLAUDE.md is to front-load every rule you can imagine needing. Do the opposite. Start minimal and add a rule only after Claude makes the same mistake twice. A rule earned by a real error is worth its line. A rule added speculatively is context tax you pay every session for a mistake that may never happen. Newer Claude Code versions also keep an auto-memory: Claude writes its own notes about build commands and fixes as it works, which trims how much you maintain by hand.

How do you know your CLAUDE.md is working?

Two quick checks. First, start a fresh session and ask Claude to summarize the project rules it is operating under. If it misses a rule you wrote, that rule is either buried or the file is too long. Second, watch for repeated corrections. If you keep re-explaining the same thing across sessions, that fact belongs in the file. If you are correcting Claude for applying a rule too literally in the wrong context, that rule was not universal and should move out of the root.

Common failures and fixes

• Claude ignores rules that are clearly written. The file is too long. Cut it toward 120 lines and the survivors get followed.
• A rule works in one project and misfires in another. It sits in ~/.claude/CLAUDE.md but should be project-scoped, or the reverse. Move it to the right tier.
• A formatting or lint rule keeps getting skipped. Prose cannot guarantee a fixed-point action. Convert it to a hook.
• The file grew to 400 lines and nobody trusts it. Split by topic with imports, delete anything inferable, and enforce the hard parts with hooks.

Going further

A CLAUDE.md is one piece of a working Claude Code setup. Once the file is lean, the next levers are the workflow patterns you run day to day and knowing when a skill earns its place versus when it is overhead. The file steers behavior, hooks enforce it, skills and workflows scale it.

Sources

• How Claude remembers your project (Claude Code Docs)
• Writing a good CLAUDE.md (HumanLayer)
• How to Write a Good CLAUDE.md File (Builder.io)
• Writing the Best CLAUDE.md (DataCamp)