Aim for 40-80 lines of CLAUDE.md, not 200

You added a rule to CLAUDE.md. Claude ignored it. You reworded it, added IMPORTANT, ignored again. Then you counted lines: 180 — under the 200 the docs name as the target, so you rule length out and go looking for a phrasing problem.

That inference is the trap. 200 is where the docs stop endorsing a file, not where adherence starts to fall. Adherence degrades continuously with length; the number is a ceiling, and a ceiling is a bad place to live.

What the docs commit to

The official position is consistent across four pages and is about mechanism, not a magic number:

• memory — "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence."
• best-practices — "Bloated CLAUDE.md files cause Claude to ignore your actual instructions" and, directly on your symptom: if Claude keeps violating a rule you wrote, "the file is probably too long and the rule is getting lost."
• context-window — its illustrative project CLAUDE.md is budgeted at 1800 tokens, with the tip "keep it under 200 lines."
• costs — same ceiling, framed as a per-session token cost you pay on every unrelated task.

So the docs corroborate the direction — shorter files are followed more reliably — and give you exactly one number, 200.

What the community write-ups add

Two independent posts (linked below) argue the working target is far lower, roughly 40–80 lines, and offer a mechanism the docs do not:

• An instruction budget. Frontier models track on the order of 150–200 instructions before compliance visibly degrades, and Claude Code's own system prompt has already spent a chunk of that pool before your file is read. Every rule you add competes with rules the harness needs.
• A corpus signal. An analysis of 2,500+ repositories reportedly found agent-instruction files past ~1,000 words correlating negatively with agent performance, with the median well-performing file around 300–350 words — which is 40–80 lines of terse bullets, not 200.

The move: relocate before you rewrite

Most of what makes a file 180 lines does not need to be there at all. Sort every rule by when it is true:

The last two rows are usually the biggest single cut. Note that @path imports do not help: imported files load at launch and land in the same context, so splitting for tidiness buys you nothing in adherence. Only paths:-scoped rules and skills are genuinely deferred.

Then apply the discipline that makes this stick:

When a rule is being ignored, delete two other rules before you rewrite it.

Rewriting an ignored rule adds instructions to a budget that is already over. Deleting two makes room for the one you care about. It also forces the honest question the docs pose per line: would removing this cause Claude to make a mistake?

/doctor does part of this for you on a checked-in CLAUDE.md — it proposes cuts for content derivable from the codebase and offers to migrate always-loaded guidance into skills and nested files. It reports before it changes anything, so run it and read the proposal rather than accepting blind.

That is a recent shape for the command, which matters if you are working from older notes or an older install. The docs date both halves: "The trim check requires Claude Code v2.1.206 or later," and "Before v2.1.205, /doctor opened a read-only diagnostics screen and pressing f sent the report to Claude." Below v2.1.206 there is no trim check, so the sorting table above stays a manual job.

What is unverified here

Be clear about which half of this tip is which:

• Corroborated by the docs: longer files reduce adherence; a persistently ignored rule is a length symptom; scoped rules and skills are the escape hatch.
• Not in the docs, and not verified by anyone here: the 40–80 line figure, the 150–200 instruction budget, the ~50 instructions attributed to Claude Code's own system prompt, and the 2,500-repo correlation. These come from blog posts whose methodology is not fully published. The corpus study also spans mixed tools and agents via AGENTS.md, not Claude Code specifically, so the transfer is an assumption.

Nothing about the specific numbers has been reproduced. What would settle it is an A/B on your own repo, not a line count: run the same task headlessly twice, once with the full file and once with a trimmed one, and grade each transcript against your rule list for violations. Until someone runs that, treat 40–80 as a hypothesis worth testing, and treat "my file is under 200 so length is fine" as the belief that is actually costing you.

Checkpoint

• Which of your CLAUDE.md rules are true in every session, and which are true only when Claude touches a particular directory?
  ›Show answerAnswer

  That sort is yours to make, and the test is when the rule is true. Always-true rules — the build command, the branch convention — stay in CLAUDE.md and load in every session; rules true only under a path move to .claude/rules/*.md with paths: frontmatter and load when Claude touches a matching file; a multi-step procedure (deploy, release, migration) becomes a skill and loads when invoked. Two categories leave entirely: anything a linter, formatter or CI already enforces, and anything derivable by reading the code — usually the biggest single cut. Count imperatives rather than newlines as you sort, and on v2.1.206 or later /doctor's trim check proposes part of this for you and reports before it changes anything.

• Why does splitting the file with @path imports fail to improve adherence?
  ›Show answerAnswer

  Because imported files load at launch and land in the same context. You have moved text between files without deferring anything, so the instruction count Claude carries is identical and compliance does not move. Only paths:-scoped rules and skills are genuinely deferred; @path buys tidiness, not adherence.

• Your rule is being ignored and the file is 150 lines. What do you do before rewriting the rule?
  ›Show answerAnswer

  Delete two other rules first, then rewrite. best-practices points straight at this symptom: when Claude keeps violating a rule you wrote, "the file is probably too long and the rule is getting lost" — and being under 200 proves nothing, because 200 is where the docs stop endorsing a file, not a target. Rewriting adds an instruction to a budget already over; deleting makes room for the one you care about. Cut the linter-enforced and the derivable first, and relocate anything you are unsure about rather than deleting it — a rule moved to a paths:-scoped file still applies. Do not cut to hit 40-80: that figure is blog-level and nobody here has reproduced it.