CLAUDE.md Best Practices: The File That Makes Claude Code Reliable

The best CLAUDE.md is short, written by a human, and covers only what Claude Code cannot already learn by reading your code. A lean file under 200 lines produces more reliable behavior than the long auto-generated files most teams commit. But CLAUDE.md is advice, not a rule Claude must obey, so for behavior that can never break you need a hook, not a longer file.

---

---

What CLAUDE.md actually is

CLAUDE.md is a plain text file Claude Code reads at the start of a session. Think of it as a sticky note you hand to a new contractor before they touch your project. It tells them how this specific project works.

Here is the part most people miss. CLAUDE.md is injected as a user message, the same kind of message you type. It is not a system directive that Claude is forced to follow. Claude tries hard to honor it, but compliance slips as the chat gets longer and the file gets bigger. One reported pattern is instruction compliance starting above 95% at the top of a session and falling to between 20% and 60% by the sixth to tenth message.

So treat CLAUDE.md as strong guidance for preferences, and reach for a hook when something must happen every single time.

Why this matters to you

If your Claude Code keeps ignoring your rules, the file itself is often the problem. A bloated CLAUDE.md does not make Claude more obedient. It makes things worse. A February 2026 ETH Zurich study (300 tasks from SWE-bench Lite, a standard coding benchmark) reported that auto-generated /init output, committed straight to the repo, cut task success rates by about 3% and raised inference costs by over 20%. Human-written files improved performance by about 4%. The lesson is direct: run /init to get a draft, then rewrite it before you commit. Never ship the raw output.

What to put in CLAUDE.md

Put in only what Claude cannot infer from the code in front of it:

• Build and test commands. The exact line to run your tests, your linter, your dev server.
• Conventions that break common defaults. If your team does something unusual, say so. Claude assumes the common pattern otherwise.
• Hard constraints. For example, "never use the service role key in client code" if you run row-level security on every table.
• Where the important stuff lives. Entry points, the main config file, the folder that holds business logic.

Leave out the tech stack, generic best practices, and anything already obvious from the files. Claude can read package.json. It does not need you to retype it.

The four scopes (and the table that ends the confusion)

Most developers cram everything into one giant root CLAUDE.md. There are actually four separate scopes plus two related systems, and each one is the right tool for a different job. The table below lets you pick at a glance instead of defaulting to CLAUDE.md for everything.

The full list of scopes, from widest to narrowest:

1. Managed policy sits at the organization level (a macOS system path) and applies to everyone in a company.
2. User level lives at ~/.claude/CLAUDE.md and follows you across every project on your machine.
3. Project level is ./CLAUDE.md, committed to the repo so the whole team shares it.
4. Personal project level is ./CLAUDE.local.md, added to .gitignore so it stays on your machine only.

Keep it lean: the lost-in-the-middle problem

Long context hurts. Language models show a reported accuracy drop of more than 30% on instructions buried in the middle of a long context, a pattern researchers call "lost in the middle." Your most important rules should sit at the top and the bottom of the file, not in the middle of a wall of text.

Practical limits:

• Aim for under 200 lines, the official recommendation. High-signal teams keep root files under 60 lines.
• Past roughly 300 lines, compliance drops and costs climb with no real gain in accuracy.
• Use HTML block comments (<!-- like this -->) for notes to your teammates. They are stripped before the file reaches Claude, so they cost zero tokens.

To keep the root file small without losing detail, move folder-specific rules into .claude/rules/. Add a paths: glob in the file's YAML header (a glob is a pattern like src/api/**). That rule then loads only when Claude touches a matching file. A rule about your API folder never wastes token budget on a CSS task.

Imports, AGENTS.md, and auto memory

You can pull other files into CLAUDE.md with an @path/to/file import. This is good for organizing a modular instruction set. Be honest about what it does though. Imports expand recursively up to four levels deep and still load at launch. They cut visual clutter in the root file. They do not cut total token cost.

If your monorepo uses several AI tools, the AGENTS.md bridge pattern keeps them consistent. Put shared instructions in AGENTS.md, import it with @AGENTS.md, then add Claude-specific notes below.

Auto memory is a separate system (Claude Code version 2.1.59 and later). Claude writes its own notes across sessions to a MEMORY.md file, and the first 200 lines load each session. Let Claude maintain its own memory for things it discovers about your project. Keep CLAUDE.md for stable conventions you curate by hand. Mixing both jobs into one file is the most common cause of bloat.

If you want a faster start, the Build This Now $29 Code Kit ships a ready-made harness for Claude Code with CLAUDE.md, scoped rules, hooks, and a production SaaS skeleton (auth, Stripe payments, and row-level security on every table) already wired together, so you are not assembling this setup from scratch.

FAQ

What should I put in my CLAUDE.md file?

Put only what Claude cannot infer from code: build and test commands, project conventions that break common defaults, hard constraints (for example, never use the service role key client-side), and where the key entry points live. Leave out the tech stack and anything already documented in the codebase.

How long should a CLAUDE.md file be?

Under 200 lines, per the official recommendation. Strong teams keep root files under 60 lines and push the rest to .claude/rules/. Past 300 lines, compliance drops and token costs rise with no matching gain in accuracy.

Does CLAUDE.md actually work?

Partially. CLAUDE.md is advisory context, not enforced configuration, and reported instruction compliance falls from above 95% at the start of a session to between 20% and 60% by message six to ten. The February 2026 ETH Zurich study found auto-generated files hurt performance more than having no file at all. Human-written, minimal files do help. For guarantees, use hooks.

What is the difference between CLAUDE.md and hooks in Claude Code?

CLAUDE.md tells Claude what to prefer. Hooks enforce what Claude must do or cannot do. A CLAUDE.md line saying "never run destructive migrations" can be overridden in a long session. A PreToolUse hook that exits with code 2 blocks the Bash tool call every time, no matter what Claude decides. Pair the two: CLAUDE.md for guidance, hooks and Claude Code subagents for the hard limits.