CLAUDE.md best practices: what to put in, what to leave out

CLAUDE.md best practices come down to one test from Anthropic: keep a line only if Claude would get something wrong without it. That leaves the commands it can't guess, rules that differ from the defaults and your project's gotchas, in under about 200 lines, because the file loads into every session. Docs get a pointer, not a copy, and rules that must always hold go in hooks or permissions.

The one test: would Claude get this wrong without it?#

Anthropic's best practices give a single question for every line: "Would removing this cause Claude to make mistakes?" If not, cut it. The same page warns: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!"

Their include and exclude lists, in short:

How long should CLAUDE.md be?#

Under 200 lines per file. Anthropic's memory docs give the reason: "Longer files consume more context and reduce adherence."

Both halves matter. Context: CLAUDE.md is part of what Claude Code sends with every request, so every line rides along on every turn of every session. Our guide on why Claude Code uses so many tokens shows how that adds up. On a subscription, /usage will even flag it, with rows like Trim ~/code/api/CLAUDE.md · 49k tokens per request. Adherence: the more rules there are, the more each one gets lost. If Claude keeps breaking a rule that's in the file, Anthropic's guess is that "the file is probably too long and the rule is getting lost."

@imports don't change the context cost. An imported file loads at launch along with the file that imports it, so @docs/conventions.md costs the same as pasting that file in.

Write commands as commands#

"Run the tests" leaves Claude to pick between npm test, npx vitest run and npx jest. The command itself, in a code block, leaves nothing to pick. Four lines from the Quick start block in our own root file:

npm run typecheck                    # Always run after changes
npm run lint                         # Always run after changes
npm run format                       # Auto-format with Biome
npm run format:check                 # Check formatting without writing

Its test rule names the command too: npx vitest run <file> --bail=1, and never npm run test for a whole workspace.

Rules need the same precision. Anthropic's example is "API handlers live in src/api/handlers/" in place of "Keep files organized". If one rule keeps getting skipped, mark that one line IMPORTANT; mark many lines and none of them stands out. Our file has no IMPORTANT, but five of the 12 rules in its Critical rules section open with a bold NEVER, which is the many-lines case.

Pointers, not copies#

Detail that lives somewhere else gets one line in the root file and stays where it is.

• A doc. "Architecture: docs/architecture.md" is one line; pasting the architecture doc is a hundred, and it goes stale in two places.
• .claude/rules/api.md with a paths: list ("src/api/**/*.ts") holds rules for one area, and they load only when Claude touches a matching file.
• A CLAUDE.md in packages/server/ loads when Claude works in that folder, not at startup.
• A skill takes a workflow you need now and then, a release checklist or a migration recipe. Anthropic's cost guide says skills "load on-demand only when invoked."

One catch: path-scoped rules and subfolder files are summarised away by /compact and come back only when Claude touches a matching file again. A rule that must survive a compact goes in the root file. More on that in /compact vs /clear.

Rules that must hold go in hooks and permissions#

In the memory docs' words, Claude treats CLAUDE.md "as context, not enforced configuration." "Never edit migrations" in the file is a strong hint, not a lock. Anything that must happen every time, or must never happen, needs something that runs.

• A PreToolUse hook can block a command or an edit before it runs, whatever Claude decided.
• A permission deny rule in .claude/settings.json stops a tool or a path outright.
• A hook on edits or on Stop runs the formatter or the tests every time, instead of asking nicely.
• A test in your suite turns a team rule into a red build. Our repo does this for one naming rule: a line in CLAUDE.md explains it, and a test script under scripts/ refuses any change that breaks it.

Where CLAUDE.md files live#

From the memory docs:

Files above your working directory load at launch and are joined, not overridden; the one closest to where you started is read last.

If you also use Codex, it reads AGENTS.md (Codex docs). Since v2.1.277, Claude Code reads AGENTS.md too, but only when there's no CLAUDE.md. The simplest way to keep one source of truth: make one file a link to the other, or import @AGENTS.md from your CLAUDE.md.

The Shuriken app sets up that import for you. When you add a project, it offers to make AGENTS.md the one instruction file. With a single CLAUDE.md, it moves the content to AGENTS.md and leaves CLAUDE.md with the line @AGENTS.md. If the project already has several instruction files, one call on a helper model merges them; the app shows that call's cost first, and you review the merged file before anything is written. The originals are copied to a backup folder.

Our own file, as it is today#

We write this as people who haven't got it right either. As of 22 October 2026, the root CLAUDE.md in the Shuriken repo is 287 lines, well over Anthropic's target. Two commits on 23 October took it to 298: a nine-line section on moderating blog comments, and two more rows in the docs table. Its sections at 298 lines:

AGENTS.md is a link to CLAUDE.md, so Codex reads the same file. The server package has its own 196-line CLAUDE.md that loads only when Claude works there.

While checking it for this guide, we found a second top-level title a quarter of the way down, over an old intro that still calls Shuriken a mobile app and lists five supported agents (it supports 67). That's Anthropic's "information that changes frequently" failure, in our own repo. What we'd cut first: the stale intro, the docs table (one pointer to the docs index does the job) and any rule a test already enforces.

Keep it fresh#

• /init writes a starter CLAUDE.md from your project. Treat it as a draft.
• /memory opens your CLAUDE.md files and auto memory for editing.
• /doctor prompt-audit (Claude Code v2.1.283 or later) looks for outdated instructions, references to files that don't exist and rules that contradict each other, and proposes edits without changing anything.
• Auto memory is the notes Claude keeps itself. Only its first 200 lines or 25KB load, so it needs pruning too.

Treat CLAUDE.md like code, as Anthropic puts it: "review it when things go wrong, prune it regularly." The same habit makes sense in any agent harness you run Claude Code in, because every agent reads the file on every start.