In this guide
Claude Code reads a file called CLAUDE.md from your repository at the start of every session — project conventions, commands, architecture notes — and treats it as standing instructions. Written well, it's the difference between an agent that works like a teammate who knows your codebase and one that rediscovers (or violates) your conventions every session.
Written badly, it actively hurts: a bloated CLAUDE.md dilutes the rules that matter until the agent quietly stops following them. This guide covers what belongs in the file, what doesn't, and the structural techniques — plan mode, per-package files, hooks — that the best Claude Code setups share.
The 200-line rule
The single most important principle: keep CLAUDE.md concise — under roughly 200 lines, and shorter is better. Current frontier models reliably follow only so many standing instructions at once; past a couple hundred lines you get context rot, where every added rule dilutes adherence to all the others.
Treat lines in CLAUDE.md as a scarce budget. Every rule you add should earn its place by preventing a real, recurring problem — not document things that would be nice for the agent to know.
Tip
Instead of pasting long documentation into CLAUDE.md, reference it: 'For deployment steps see docs/deploy.md.' Claude Code reads referenced files on demand, keeping your standing instructions lean.
What belongs in CLAUDE.md
- Commands: how to build, test, lint, and run the project — the exact invocations, not descriptions.
- Architecture in brief: the two or three structural facts someone must know before touching code (e.g. 'all routes must be registered in scripts/routes.ts').
- Conventions a linter can't enforce: naming philosophies, patterns to prefer, forbidden approaches and why.
- Verification expectations: what 'done' means in this repo — build passes, which tests run, what to check manually.
What doesn't belong
- Anything a linter or formatter already enforces — that's duplicated noise the tools handle at 100% reliability anyway.
- Long API or schema documentation — reference the files instead.
- Aspirational essays about code quality — vague rules get vague compliance. 'Prefer small functions' does nothing; 'no file over 300 lines without discussion' is checkable.
- Session-specific state — that belongs in a checkpoint file (see our context window guide), not in standing instructions.
Per-package CLAUDE.md files for larger repos
CLAUDE.md files nest: a lean root file for repo-wide conventions, plus a focused CLAUDE.md inside each package or major directory with rules specific to that area. Claude Code picks up the relevant file when working in that part of the tree.
This is the escape hatch from the 200-line budget — instead of one thousand-line megafile trying to describe everything, each area carries its own small, high-signal instructions, and each team can own its own context.
Start hard tasks in plan mode
The most effective Claude Code workflow starts complex tasks in plan mode: Claude reads files and proposes an approach without changing anything, you correct the plan while corrections are still cheap, and only then does implementation begin. A one-line nudge in CLAUDE.md — 'for multi-file changes, present a plan before editing' — bakes this into every session.
This is the same discipline that makes every agentic tool reliable — our Cursor Agent Mode workflow guide covers the equivalent habits there.
Instructions suggest; hooks guarantee
The most important distinction experienced Claude Code users learn: CLAUDE.md instructions are followed most of the time, not all of the time — community testing puts real-world adherence around 70% for any given rule. For preferences ('use our logger'), that's fine. For safety rules ('never push to main', 'never touch production data'), a rule that holds 70% of the time is an incident waiting to happen.
Claude Code's hooks close that gap: scripts that run at fixed points in the agent's workflow and can block actions outright, making the forbidden thing structurally impossible rather than merely discouraged. The rule of thumb — preferences go in CLAUDE.md, guarantees go in hooks.
Watch out
Audit your CLAUDE.md for any rule where 70% compliance would be a disaster. Each of those should be a hook (or a branch protection / permission setting), not a sentence.
A starter template
# Project: [name]
## Commands
- Build: npm run build
- Test: npm test (must pass before any commit)
- Lint: npm run lint
## Architecture
- [The 2-3 structural facts that prevent broken changes,
e.g. "new routes must be added to scripts/routes.ts AND src/lib/seo.ts"]
## Conventions
- [Only rules a linter can't enforce, stated checkably]
- For multi-file changes, present a plan before editing.
## Verification
- A task is done when build + tests pass and you've run the
affected feature — "the code looks right" doesn't count.
## Detailed docs
- Deployment: docs/deploy.md
- Data model: docs/schema.mdKey takeaways
- Keep CLAUDE.md under ~200 lines — past that, context rot quietly erodes adherence to every rule.
- Include commands, brief architecture, and unlintable conventions; reference detailed docs instead of pasting them.
- Use per-package CLAUDE.md files in larger repos rather than one megafile.
- Instructions are followed ~70% of the time; anything that must hold 100% of the time belongs in a hook, not a sentence.
- Bake plan mode into your workflow for multi-file changes — corrections are cheapest before code exists.
Frequently asked questions
CLAUDE.md is a markdown file in your repository that Claude Code reads at the start of every session as standing instructions — project commands, architecture notes, and conventions. It's how you give the agent durable knowledge of your codebase without re-explaining it each session.