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.
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 review covers the equivalent habits there.
Instructions suggest; hooks guarantee
The most important distinction experienced Claude Code users learn: CLAUDE.md instructions are advisory: Claude interprets them, and Anthropic’s docs say plainly that an instruction like “never edit .env” is a request, not a guarantee. For preferences (‘use our logger’), that’s fine. For safety rules (‘never push to main’, ‘never touch production data’), a rule that can be missed 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.
The pruning test, and the tools that help
Anthropic’s best-practices page gives one test for every line: “Would removing this cause Claude to make mistakes?” If not, cut it. Run /init to generate a starter file from your project, /context to confirm it loaded, and /doctor on a checked-in file to get proposed cuts for anything Claude could derive from the code. Files can import others with @path/to/import, and if your repo already has an AGENTS.md for other agents, Claude Code reads it when there is no CLAUDE.md, or alongside CLAUDE.md if you change the Project instructions setting in /config, or you can import it from CLAUDE.md with @AGENTS.md. For rules that only matter in some folders, the docs point to .claude/rules/ files scoped by path, and for reference material used only sometimes, to skills.
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 advisory; anything that must hold every time belongs in a hook, not a sentence.
- Bake plan mode into your workflow for multi-file changes - corrections are cheapest before code exists.
Related
If Claude Code is new to you, start with how to use Claude Code. When a rule must hold every time, the choice is laid out in hooks, subagents, skills or CLAUDE.md. Using Cursor as well? Its equivalent is covered in Cursor rules.
Method
Re-checked against Anthropic’s Claude Code documentation on 29 September 2026. We have not measured how closely any model follows a given file.
Common questions
What is a CLAUDE.md file?
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.
How long should a CLAUDE.md file be?
Under roughly 200 lines, and shorter is better. Models reliably follow a limited number of standing instructions; overlong files cause ‘context rot’ where adherence to every rule quietly degrades. Reference detailed docs by path instead of pasting them.
Why does Claude Code ignore my CLAUDE.md rules sometimes?
Standing instructions are advisory, and Anthropic says a bloated file makes Claude ignore half of it because important rules get lost in the noise. Trim the file to high-signal rules, state them checkably, and enforce anything critical with hooks, which block actions structurally instead of relying on compliance.
Should every package in a monorepo have its own CLAUDE.md?
In larger repos, yes - a lean root file for org-wide conventions plus a focused CLAUDE.md per package keeps each file small and relevant, and lets each team own its own context instead of maintaining one thousand-line megafile.