CLAUDE.md best practices, judged by token cost

Most CLAUDE.md advice ranks rules by taste - short versus long, one file versus many. None of it prices what a rule actually costs: every line loads on every session, whether that session ever touches the thing the rule is about or not. Judge a CLAUDE.md by token cost instead, and the rules mostly write themselves - keep what earns its place every time, move out what only matters sometimes.

TL;DR: Keep CLAUDE.md to standing rules a fresh session always needs - target under 200 lines. Move anything conditional to a path-scoped rule in .claude/rules/*.md (with paths: frontmatter) or a skill. Splitting a file with @importdoes not save tokens - imported content still loads in full at launch. Let Claude's own auto memory handle what it learns on its own.

What actually costs you tokens

Every CLAUDE.md file in the load hierarchy - managed policy, user, project, local - is read in full at the start of every session, and it stays in context for the rest of that session, re-billed as a cache read on every later turn. The measured setup behind this site carries three of these at once:

None of that is wrong to have. The problem is never the file existing - it is content sitting in the always-on tier when it only applies sometimes.

What belongs in CLAUDE.md

A rule earns a place in the global or project file when a fresh session needs it regardless of what you ask next: build and test commands, naming conventions, architectural decisions, the workflows every task passes through. The official guidance is to add a rule the moment it would otherwise get re-explained - Claude repeats a mistake, a code review flags something project-specific, a new teammate would need the same context to be productive.

Specificity is what makes a kept rule worth its tokens. "Use 2-space indentation" is verifiable and gets followed; "format code properly" burns the same tokens for a rule Claude has to guess at. Vague instructions cost exactly as much as precise ones and do less - there is no token argument for keeping a mushy rule around.

What to move out - and where

Claude Code actually has four places an instruction can live, and they load on four different schedules. Picking the right one is most of what "best practices" means in practice:

Path-scoped rules are the underused lever here. A pattern like paths: ["src/api/**/*.ts"]in a rule's frontmatter means that content only enters context when Claude actually opens a matching file - it costs nothing on sessions that never touch that part of the codebase, unlike an unscoped rule or a CLAUDE.md entry, which pay every time regardless.

The @import trap

The most common mistake is treating @import as a way to shrink the always-on footprint. It is not - it is a way to organize files, and the two get confused constantly.

This repo's own root CLAUDE.md is a working example of the legitimate use case: it is a single line, @AGENTS.md, so Claude Code and any other agent that reads AGENTS.md share one source of project instructions instead of maintaining two files that drift apart. That is a real reason to import - avoiding duplication. Token savings was never part of the deal.

How long is too long

The official target is under 200 lines per CLAUDE.md file - past that, adherence drops along with the added context cost, since instructions are delivered as a user message Claude reads and tries to follow, not an enforced setting. If a checked-in CLAUDE.md has grown past that, /doctor can now audit it directly: it proposes trims for content Claude can already derive from the codebase - directory layouts, dependency lists, architecture overviews - while keeping the pitfalls and conventions that differ from tool defaults.

Honest limit: none of this is enforced. CLAUDE.md is context, not configuration - Claude reads it and tries to comply, but a vague or contradictory rule can still get skipped. For anything that must run every time no matter what (a lint check before every commit, a blocked command), that belongs in a hook, not a CLAUDE.md line.

FAQ

• How long should a CLAUDE.md file be? Under 200 lines is the official target. Longer files consume more context and reduce how reliably Claude follows them - move overflow to path-scoped rules or a skill instead of letting one file grow.
• Does @import save tokens by splitting CLAUDE.md into smaller files? No. Imported files are expanded and loaded into context at launch alongside the file that references them. Splitting helps organization; it does not reduce what loads.
• Should I use CLAUDE.md or AGENTS.md? Claude Code only reads CLAUDE.md. If a repo already has an AGENTS.md for other tools, add a one-line CLAUDE.md that imports it with @AGENTS.md so every tool reads the same instructions without duplicating them.
• What is auto memory, and does it replace CLAUDE.md? Auto memory is a separate system - notes Claude writes itself about corrections and preferences it picks up as you work, stored in a project-specific MEMORY.md. Only its first 200 lines (or 25KB) load each session. It complements CLAUDE.md; it is not a substitute for instructions you want guaranteed to load.
• What should move to a path-scoped rule instead of the global CLAUDE.md? Anything that only matters for a subset of files - frontend conventions, API design rules, test patterns. Put it in .claude/rules/*.md with a paths: glob, and it loads only when Claude actually opens a matching file.
• Will Claude Code tell me if my CLAUDE.md is too big? Yes - /doctor checks a checked-in CLAUDE.md and proposes specific trims, favoring content Claude can rediscover from the codebase over rules and conventions it cannot.

The pattern behind all of this is the same one that drives every setup fix on this site: the file itself is never free, so the question is always whether a given line earns the tokens it spends every session. See the full list of levers beyond just CLAUDE.md, or measure what your own sessions actually use before deciding what to trim - the free scan sizes your own CLAUDE.md and every other header cost for you.

See your own numbers

These are aggregates from real sessions. Your setup is different - run the free scan and get the breakdown for your own Claude Code history. It runs locally; nothing about your code or prompts leaves your machine.