CLAUDE.md best practices: what to write, with a full example
Zihua Li · · 10 min read
CLAUDE.md is the one file Claude Code reads at the start of every session, so every line in it is spent on every task. The best ones are short and hold only what Claude can’t learn by reading the code.
CLAUDE.md best practices come down to one test: write down only what Claude can’t find by reading the repository, such as the exact test and typecheck commands, misleading code, and decisions made outside the code. Keep each file under 200 lines, move rules for one part of the codebase into .claude/rules/, procedures into skills, and rules that must never be broken into hooks or permission rules.
What CLAUDE.md is and how Claude Code loads it
A CLAUDE.md file is plain Markdown that Claude Code reads when a session starts. It isn’t configuration: Claude Code delivers it as a user message after the system prompt, and Claude reads it the way it reads anything else you tell it. That shapes everything about writing one. A vague line gets a vague response, two contradicting lines get one picked at random, and an important line buried at line 340 gets less attention than it deserves.
There are four places a CLAUDE.md can live, from broadest to most specific:
| Scope | Location | Use it for |
|---|---|---|
| Managed policy | /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux and WSL) | Organization-wide standards deployed by IT. Can’t be excluded. |
| User | ~/.claude/CLAUDE.md | Your preferences in every project. |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md | Team instructions, committed to the repository. |
| Local | ./CLAUDE.local.md | Your notes for this one project. Add it to .gitignore. |
Nothing overrides anything. Claude Code walks from your working directory up to the filesystem root, collects every CLAUDE.md and CLAUDE.local.md it finds, and concatenates them, root first, so the file closest to where you launched is read last. Within a directory, CLAUDE.local.md comes after CLAUDE.md. Files in subdirectories below your working directory don’t load at launch; each one loads the first time Claude reads or edits a file in that directory. In a monorepo, that means packages/billing/CLAUDE.md costs nothing until someone touches billing.
To see what actually loaded, run /context all and look under Memory files. This is the first thing to check when Claude seems to ignore an instruction: a file that isn’t on that list doesn’t exist as far as Claude is concerned. One small trick from the docs: block-level HTML comments (<!-- like this -->) are stripped before the file reaches Claude, so you can leave notes for human maintainers without paying for them in context.
CLAUDE.md best practices: what to write and what to leave out
Anthropic’s best practices page gives a two-question test before writing anything down: could Claude find this by reading the code, and would it actually go and look? If both answers are yes, leave it out. Claude starts each task by reading the repository and is good at it. It finds your framework, your folder layout and how existing components are built faster than a paragraph could explain them.
What passes the test is a short list:
- How to check work in this repository. The exact install, typecheck and lint commands, and how to run a single test file. If you keep one line, keep this one: a command Claude can run is how it knows it’s finished.
- Places where the code misleads. An old pattern that appears everywhere but must not be copied, or a directory that looks dead and still serves traffic. Reading the code teaches Claude the wrong lesson here, so it needs to be told.
- Decisions that never made it into the code. Which error helper the team settled on, how deploys work, which changes need a migration review.
- Anything you’ve corrected twice. The docs suggest adding a line when Claude repeats a mistake, when code review catches something Claude should have known, or when you type the same correction you typed last session.
Just as useful is knowing what to cut:
- Architecture overviews and directory trees. These are what
/inittends to generate and what Claude reads for itself. They also go stale silently. - Style your formatter enforces. Indentation and import order belong to the linter in CI, which applies them every time.
- Multi-step procedures. A twelve-step release checklist weighs on every unrelated bug fix. Put it in a skill, covered below.
- Rules with zero exceptions. “Never read .env” in CLAUDE.md will be followed almost every time. For the cases where almost isn’t enough, use a permission deny rule or a hook.
- Generic advice. “Write clean code” and “be careful” change nothing. Every line should be concrete enough to check: “Run
pnpm testbefore committing,” not “test your changes.”
A CLAUDE.md example you can adapt
Here is a complete project CLAUDE.md for a TypeScript service. It’s about 35 lines, and every line is something a capable model would get wrong or waste time rediscovering without it.
# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit
- Lint and format: pnpm lint --fix
- A task is done when the typecheck passes and the tests for the
files you changed pass. Paste the command output, not a summary.
# Conventions
- Throw AppError from src/lib/errors.ts with an error code.
Never throw strings or plain Error.
- Route handlers call functions in src/db/queries/. They don't
import the database client directly.
- Money is an integer number of cents. Format it only in the UI,
with formatCents().
- A new environment variable goes in src/env.ts (zod schema) and
.env.example in the same change.
# Watch out
- src/legacy/ still serves the v1 API. Fix bugs there, but don't
copy its patterns into new code.
- src/gen/ is generated by pnpm codegen. Change api/openapi.yaml
and regenerate instead of editing it.
- Integration tests need DATABASE_URL (see .env.example) and run
against a real Postgres, not mocks.
# Migrations
- Generate with pnpm db:generate. Never hand-edit files in drizzle/.
- One migration per pull request, and say in the description
whether it locks a table.
<!-- Owner: platform team. Before adding a line, check that
Claude gets it wrong without it. -->Notice what isn’t there: no description of the stack, no folder tree, no “we use React.” The Watch out section carries the most weight per line, because it covers exactly the cases where reading the code points Claude the wrong way. The done criterion in Commands asks for command output rather than a summary, which is the cheapest way to catch “all tests pass” when they don’t. And the closing HTML comment tells the next person editing the file how to judge a new line, at zero context cost.
Keeping it short: .claude/rules, imports and CLAUDE.local.md
The docs target under 200 lines per CLAUDE.md file. Past that, files take more context and Claude follows them less reliably, and Claude Code warns at startup when a file is over the recommended length. When a file grows, there are three ways to shrink it, and only two of them actually save context.
Path-scoped rules in .claude/rules/
Markdown files in .claude/rules/ are discovered recursively. A rule without frontmatter loads at launch like CLAUDE.md. A rule with a paths field loads only when Claude reads or edits a matching file, which is where the savings come from:
---
paths:
- "src/api/**/*.ts"
---
- Validate request bodies with the zod schemas in src/api/schemas/.
- Every new endpoint needs an entry in api/openapi.yaml. CI fails
without it.Save it as .claude/rules/api.md and your API conventions stay out of the way while Claude works on the frontend. Personal rules for every project go in ~/.claude/rules/.
@imports organize, but don’t save context
A line such as @docs/git-instructions.md pulls that file into context next to the CLAUDE.md that references it. Paths resolve relative to the importing file, imports can nest up to four hops, and a path wrapped in backticks stays literal text. Imports are for organization only: the imported file loads at the same time as the CLAUDE.md that imports it, so splitting a 400-line file into four imports still costs 400 lines. The first time a project imports a file from outside its directory, Claude Code asks you to approve it.
CLAUDE.local.md for personal notes
Your sandbox URL and preferred seed data don’t belong in the team’s file. Put them in CLAUDE.local.md at the project root and add it to .gitignore:
# My setup
- My local API runs on port 4001, not 3000.
- Seed data: pnpm db:seed --tenant my-sandboxOne catch: a gitignored file exists only in the worktree where you created it. If you work across several worktrees, keep the notes in your home directory and import them with @~/.claude/my-project-instructions.md instead.
Starting with /init and keeping the file honest
/init analyzes the codebase and writes a first CLAUDE.md with the build commands and conventions it finds; on a repository that already has one, it suggests improvements instead of overwriting. Setting CLAUDE_CODE_NEW_INIT=1 switches it to an interactive flow that asks whether to set up CLAUDE.md files, skills and hooks, and shows a proposal before writing anything. Either way, the Claude Code docs are blunt about what comes next: from the generated draft, the work is mostly removing lines.
After that, the file changes in small, deliberate steps:
- Add a line when a mistake repeats. Tell Claude “add this to CLAUDE.md,” or open the file with
/memory, which lists every memory file across user and project scope. Asking Claude to “remember” something saves it to auto memory instead, which is Claude’s own notebook rather than your instructions. - Audit it occasionally.
/doctorproposes trims for content Claude can derive from the code, and/doctor prompt-auditlooks for instructions written for older models, references to files that no longer exist and files that contradict each other. Nothing changes until you accept the edits. - Don’t escalate with capital letters. If a line keeps getting missed, adding IMPORTANT rarely fixes it. Either the file is too long and the line is lost, or the line is a rule with no exceptions, which belongs in a hook.
- Review it like code. A project CLAUDE.md is shared through version control, so changes to it should go through pull requests like any other change that alters how code gets written.
One reassurance for long sessions: the project-root CLAUDE.md survives /compact. Claude Code re-reads it from disk afterwards. An instruction that disappears after compaction was given only in conversation, which is a good sign it should have been in the file.
A good CLAUDE.md is a list of things Claude would otherwise get wrong: the commands that prove work is done, the code that misleads, and the decisions that live outside the repository. Keep it under 200 lines, scope part-of-the-codebase rules with .claude/rules/, and move anything that must never be broken into a hook.
CLAUDE.md vs AGENTS.md
The two files do the same job. CLAUDE.md is Claude Code’s own name; AGENTS.md is the shared one that Codex, Cursor and other agents read. Recent versions of Claude Code (v2.1.277 and later) read AGENTS.md directly when there is 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.
When several agents work in one repository, keep the conventions in AGENTS.md and make CLAUDE.md a thin layer that imports it:
@AGENTS.md
## Claude Code
- Use plan mode for changes under src/billing/.
- Release steps live in the /release skill. Don't release by hand.A symlink (ln -s AGENTS.md CLAUDE.md) works too when there’s nothing Claude-specific to add, but the docs recommend the import if anyone clones the repository on Windows, where Git can check a committed symlink out as a one-line text file.
CLAUDE.md vs skills and hooks
The three mechanisms split along two lines: how often something matters, and whether Claude is allowed to decide.
- CLAUDE.md is for facts that matter in almost every session. It loads every time, and Claude may judge that a guideline doesn’t fit a particular case.
- Skills are for procedures and team knowledge that matter sometimes. Claude sees only a skill’s name and description in each session and reads the full
SKILL.mdwhen a task calls for it, so a long release procedure costs almost nothing on an unrelated bug fix. Adddisable-model-invocation: trueto a skill with side effects so only you can start it. For ready-made ones, see the best Claude Code skills. - Hooks and permission rules are for things that must happen, or never happen, every time. A
PreToolUsehook that blocks edits undermigrations/doesn’t depend on Claude remembering anything.
A useful habit: when you’re tempted to add a line to CLAUDE.md, ask which of the three it is. A surprising share of long CLAUDE.md files turn out to be a skill and two hooks wearing a trench coat.
CLAUDE.md in code review
The conventions in CLAUDE.md describe how code in your repository should look, which makes them review criteria too. An automated reviewer that reads them can flag a handler that imports the database client directly, without anyone restating the rule in a prompt.
HeyDeer reads CLAUDE.md in any directory that has no AGENTS.md, from the pull request’s own commit, and applies each file to its directory and below. It reads up to 32 KiB of these files from the root down, so the 200-line habit pays off here as well. HeyDeer works from the text in the file itself, so write conventions that matter in review directly in CLAUDE.md or AGENTS.md rather than behind an @import. Guidance that only matters in review, such as which findings to rate Critical or which paths to leave alone, goes in a REVIEW.md.
Changes to the guidance itself get special handling. When a pull request changes a plan, a specification or AGENTS.md, HeyDeer works through what following the new instructions would lead to and reports the cases they leave open or contradict. And HeyDeer leaves approval of any pull request that changes review guidance, such as AGENTS.md, CLAUDE.md, repository checks or skills, to a person.
That second rule matters because a pull request is reviewed against its own version of these files. An edit to CLAUDE.md changes how every later change is written and reviewed, so it deserves a human signature even when the diff is three lines.
Sources
Frequently asked questions
What should I put in CLAUDE.md?
CLAUDE.md should hold what Claude can’t learn from the code: the exact commands to install, test one file, typecheck and lint; patterns in the code that new code must not copy; decisions made outside the repository, such as which error helper the team chose; and anything you have had to correct twice. Leave out architecture overviews and file layouts, which Claude reads from the repository itself.
How long should CLAUDE.md be?
A CLAUDE.md file should stay under 200 lines, the target Anthropic’s Claude Code docs give. Longer files take more context and Claude follows them less reliably. Splitting a long file with @imports doesn’t help, because imported files load with the file that imports them; path-scoped rules in .claude/rules/ do, because they load only when Claude works on matching files.
Where does CLAUDE.md go?
A project CLAUDE.md goes at the repository root as ./CLAUDE.md or ./.claude/CLAUDE.md and is committed for the team. Personal instructions for every project go in ~/.claude/CLAUDE.md, and personal notes for one project go in ./CLAUDE.local.md, which you add to .gitignore. A CLAUDE.md in a subdirectory loads when Claude works on files in that directory.
What is CLAUDE.local.md?
CLAUDE.local.md is a personal, project-specific instruction file at the project root. Claude Code loads it after CLAUDE.md in the same directory and treats it the same way. Add it to .gitignore so it stays out of the repository; it exists only in the worktree where you created it, so import a file from your home directory to share notes across worktrees.
What does /init do in Claude Code?
The /init command analyzes your codebase and writes a starting CLAUDE.md with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it. Treat the result as a draft: most of the work afterwards is deleting lines Claude would have worked out anyway.
Why is Claude ignoring my CLAUDE.md?
Claude ignores a CLAUDE.md instruction most often because the file never loaded, the instruction is vague, two files contradict each other, or the file has grown long enough that the line gets lost. Run /context all to see which memory files loaded, make the instruction concrete, and remove conflicts. A rule that must hold every time belongs in a hook or a permission deny rule.
Should I use CLAUDE.md or AGENTS.md?
Use AGENTS.md when other coding agents work in the same repository, and CLAUDE.md when only Claude Code does. Claude Code reads AGENTS.md when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it, and a CLAUDE.md that starts with @AGENTS.md imports the shared file and adds Claude-specific notes below it.
How do @imports work in CLAUDE.md?
An @path line in CLAUDE.md, such as @docs/git-instructions.md, loads that file into context with the CLAUDE.md that references it. Relative paths resolve from the file containing the import, imports can nest up to four hops deep, and a path inside backticks stays literal. Imports outside the project trigger a one-time approval dialog.



