CLAUDE.md best practices: what to write, what to cut, with examples

A good CLAUDE.md is a short, specific list of facts Claude Code can't learn from your code: commands, conventions, gotchas and repo etiquette, ideally under 200 lines. This guide covers what to include and cut, where each file lives, how loading works, path-scoped rules, imports, a copyable template and how to keep the file current.

What are CLAUDE.md best practices?

The core CLAUDE.md best practices are to keep the file short, write only what Claude can't infer from your code, and phrase every rule so you could check whether it was followed. Anthropic's memory docs recommend targeting under 200 lines per file, because longer files consume more context and reduce adherence.

CLAUDE.md is a markdown file Claude Code reads at the start of every session. Each session starts with an empty context window, so this file is how your build commands, conventions and hard-won lessons carry over from one session to the next. If you are new to the tool, start with our Claude Code tutorial and come back once you have run a few tasks.

Three facts shape every decision below:

1. CLAUDE.md is context, not configuration. The docs say Claude "treats them as context, not enforced configuration." Claude reads the file and tries to follow it, with no guarantee.
2. Every line costs context in every session. The file loads whether or not the current task needs it.
3. Vague and conflicting rules get dropped. If two instructions contradict each other, Claude "may pick one arbitrarily."

What should you put in CLAUDE.md?

Put in CLAUDE.md the things a new senior engineer would need to be told on day one because the code doesn't say them. The best practices page gives a clear include and exclude list.

The docs also suggest a test for each line: "Would removing this cause Claude to make mistakes?" If not, cut it.

When should you add a line?

Add to CLAUDE.md when you notice yourself repeating something. The memory docs list the triggers:

• Claude makes the same mistake a second time.
• A code review catches something Claude should have known about this codebase.
• You type the same correction you typed last session.
• A new teammate would need the same context to be productive.

This keeps the file grounded in real failures instead of guesses about what Claude might get wrong.

How do you write instructions Claude actually follows?

Write instructions that are concrete enough to verify, grouped under headings, with no contradictions. Specific beats general every time.

A few more habits that help:

• Use the imperative. "Run", "use", "never". A CLAUDE.md is an instruction set, not documentation.
• Group related rules under headings. The docs note that organized sections are easier to follow than dense paragraphs.
• Say why when the reason isn't obvious. "Use pnpm, not npm: the lockfile is pnpm-only" helps Claude handle edge cases the rule doesn't cover.
• Emphasize sparingly. If Claude keeps skipping one rule, the docs suggest adding "IMPORTANT" to that line alone. "If you emphasize many lines, none of them stands out."
• Tell Claude how to compact. A line like "When compacting, always preserve the full list of modified files and any test commands" shapes what survives summarization in long sessions.

A CLAUDE.md template you can copy

A useful CLAUDE.md for a typical web app fits on one screen. Start from this template, delete what doesn't apply, and replace the examples with your own commands.

## ProjectNext.js app with a Postgres database (Drizzle ORM). Monorepo: `apps/web`, `packages/db`.## Commands- Install: `pnpm install` (pnpm only; the lockfile breaks with npm)- Dev server: `pnpm dev` (port 3000)- Typecheck: `pnpm typecheck`- Test one file: `pnpm vitest run path/to/file.test.ts`- Never run the full e2e suite locally; CI runs it## Code style- TypeScript strict mode; no `any`, use `unknown` and narrow- Server code uses named exports; React components use default exports- Dates are stored in UTC and formatted with `formatDate()` from `lib/date.ts`## Architecture- All database access goes through `packages/db`; never import the driver in `apps/web`- Auth checks happen in `middleware.ts`, not in individual routes## Workflow- Typecheck after a series of changes, before saying you are done- Branches: `feat/<ticket>-<slug>`; open PRs as drafts- When compacting, keep the list of modified files and the test commands## Gotchas- `.env.local` needs `DATABASE_URL`; copy from `.env.example`- The `legacy/` folder is frozen; do not refactor it

Notice what is missing: no description of every folder, no explanation of what TypeScript is, no general coding advice. Claude can read the folder tree and already knows TypeScript.

Where do CLAUDE.md files live, and how do they load?

CLAUDE.md files can live at four scopes, and Claude Code concatenates all of the ones it finds instead of letting one replace another. More specific files load later, so they are read last.

The loading rules that matter in practice:

• Upward at launch. Claude Code loads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it. Files closer to where you launched are read last.
• Downward on demand. A CLAUDE.md in a subdirectory loads once Claude reads, writes or edits a file in that subdirectory. This is how you give packages/api/ its own instructions without loading them for frontend work.
• Local is appended, not an override. Within a directory, CLAUDE.local.md comes after CLAUDE.md. If the two conflict, you have a contradiction, not a precedence rule.
• HTML comments are stripped. Block-level <!-- notes --> don't reach Claude's context, so you can leave notes for human maintainers at no token cost.
• Compaction keeps the root file. After /compact, Claude re-reads the project-root CLAUDE.md from disk. Instructions you gave only in chat do not survive, which is a good reason to move repeated corrections into the file.

To confirm what loaded, run /context and look under Memory files. Run /memory to open and edit the files from inside a session.

How do you keep CLAUDE.md short as the project grows?

Keep CLAUDE.md short by moving anything that applies to only part of the codebase into path-scoped rules, anything procedural into skills, and anything that must always happen into hooks. The root file then holds only what every session needs.

Path-scoped rules in .claude/rules/

Markdown files in .claude/rules/ work like extra CLAUDE.md files, one topic each. Add paths frontmatter and a rule loads only when Claude touches a matching file:

---paths:  - "src/api/**/*.ts"---## API rules- Every endpoint validates input with the schemas in `src/api/schemas/`- Errors use `ApiError` and the standard response shape- Add an OpenAPI comment to every new route

Rules without paths load at launch, like the main file. Personal rules for every project go in ~/.claude/rules/.

Imports

A CLAUDE.md can pull in other files with @path/to/file, for example See @README for an overview. Imports nest up to four levels deep. They help organize a long file but do not save context, because imported files also load at launch. To mention a path without importing it, wrap it in backticks.

Skills, subagents and hooks

The docs put it plainly: CLAUDE.md instructions are advisory, hooks are deterministic. Our guide to Claude Code hooks has copyable recipes for the formatter and the blocked-file cases.

How do CLAUDE.md and AGENTS.md work together?

Claude Code can read AGENTS.md, the instruction file other coding agents use, when your repository has no CLAUDE.md or CLAUDE.local.md in the working directory or above it. If both exist, Claude reads only the CLAUDE.md files by default.

If your team uses several agents, keep one shared file and import it:

@AGENTS.md## Claude CodeUse plan mode for changes under `src/billing/`.

Claude reads the imported AGENTS.md first, then the Claude-specific lines. A symlink (ln -s AGENTS.md CLAUDE.md) also works, but the docs advise the import if anyone on the team uses Windows, where symlinks often check out as plain text files. You can also change which files load with the Project instructions setting in /config.

How do you keep CLAUDE.md current?

Treat CLAUDE.md like code: review it when Claude misbehaves, prune it on a schedule, and test changes by watching whether Claude's behavior shifts. The docs list two failure signals worth memorizing:

• Claude keeps doing something despite a rule against it. The file is probably too long and the rule is getting lost.
• Claude asks questions CLAUDE.md already answers. The phrasing is ambiguous.

A monthly maintenance pass takes ten minutes:

1. Run /context and confirm every expected file loads.
2. Delete rules Claude already follows without being told; if a rule must stay enforced, convert it to a hook.
3. Search for contradictions between the root file, nested files, .claude/rules/ and your user file.
4. Check that every command in the file still exists and works.
5. In recent versions, run /doctor prompt-audit to have Claude report outdated or conflicting instructions; nothing changes until you approve the edits.

Don't confuse CLAUDE.md with auto memory, the notes Claude writes for itself. Auto memory lives in ~/.claude/projects/<project>/memory/, only the first 200 lines or 25KB of its MEMORY.md load at startup, and you can browse or switch it off with /memory. Use CLAUDE.md for rules you want the whole team to share.

A well-kept CLAUDE.md matters most when nobody is watching. Agents you run unattended, for example on a remote box overnight, can't ask you which test command to use, so the file is their only briefing. If you run Claude Code that way, Orkio gives you an always-on cloud box where agents keep working and open pull requests while your laptop is closed; the same CLAUDE.md in your repository applies there. For more on what to give an agent beyond this file, see context engineering.

CLAUDE.md checklist

Use this list on your current file today:

• Under 200 lines, grouped under clear headings.
• Exact commands for install, dev, typecheck, lint and running a single test.
• Only style rules that differ from language defaults.
• Architecture decisions and gotchas the code doesn't reveal.
• Every rule checkable; no "write clean code".
• No contradictions with nested files, rules or your user file.
• Area-specific rules moved to .claude/rules/ with paths.
• Procedures moved to skills, must-always behavior moved to hooks.
• Personal preferences in CLAUDE.local.md or ~/.claude/CLAUDE.md, not the team file.
• Project CLAUDE.md committed to git and reviewed like code.

Frequently asked questions