Budget CLAUDE.md in instructions, not lines

Community configs treat CLAUDE.md as a fixed instruction budget, not a line budget: every rule added makes every other rule less likely to be obeyed. The reframe is sound, but two rules repeated with it - never put code style in CLAUDE.md, never use /init - contradict the docs.

Your CLAUDE.md is four hundred lines. Claude keeps ignoring the rule about migrations that you added three months ago, so you add it again with IMPORTANT in front. It works for a week. Then it stops working, and the rule about branch naming stops working too.

The docs give you a size number for this — under 200 lines — which is easy to read as a formatting nicety. The community frame is sharper: the file is a fixed budget, and the unit is instructions, not lines. HumanLayer's root CLAUDE.md is under sixty lines. abhishekray07/claude-md-templates states the rule as "every line you add makes every other line less likely to be followed." Once you hold that frame, adding a rule stops being free and starts being a trade: this rule, or the one it will crowd out.

What the docs actually back

The mechanism is documented, and it is worth knowing which half is official.

Claim	Docs status
Longer files reduce adherence	Stated. `memory.md`: "Longer files consume more context and reduce adherence"
Length is why a specific rule gets ignored	Stated. `debug-your-config.md`: rules "get less attention" as a file grows
The pruning test	Stated. `best-practices.md`: "Would removing this cause Claude to make mistakes?" If not, cut it
Emphasis is also a budget	Stated. `best-practices.md`: "If you emphasize many lines, none of them stands out"
A specific instruction count you are spending against	Absent. No number like it appears anywhere in the docs

So the direction is official and the arithmetic is not. The ~50-instructions- already-spent figure is a community estimate about a system prompt nobody outside Anthropic has measured. Use it as a reason to be ruthless, not as a number you can budget against to two significant figures.

Where the community advice is wrong

Two rules that travel with this frame are contradicted by the docs, and both are worth knowing before you act on a blog post.

"Never put code style in CLAUDE.md." best-practices.md does the opposite. Its worked example opens with a # Code style heading, and its include/exclude table puts "Code style rules that differ from defaults" squarely in the include column — with "standard language conventions Claude already knows" as the thing to exclude. The community rule overshoots a real point. The real point is that a formatter should be enforced by a formatter:

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

That hook is straight out of hooks-guide.md, and it runs deterministically whether or not Claude read your file. What it cannot encode is a convention with no lint rule behind it — "use ES modules, not CommonJS," "destructure imports." Those stay in CLAUDE.md. The honest version of the rule: move anything a linter can enforce to the linter, and keep the rest.

"Never run /init." Both best-practices.md and memory.md recommend it as the starting point, and /init on an existing file suggests improvements instead of overwriting. The defensible version is "don't ship /init output unedited" — which is a different claim, and one the docs already support from the other side: /doctor proposes trims for a checked-in CLAUDE.md, cutting exactly the derivable content (directory layouts, dependency lists, architecture overviews) that auto-generation tends to produce.

What to do this week

Run /context and confirm which memory files actually loaded. People prune the wrong file surprisingly often.
Run /doctor on a checked-in CLAUDE.md and read the trim proposals before accepting them. It is the official version of this tip — and a recent one. memory.md: "The trim check requires Claude Code v2.1.206 or later." commands.md adds that "Before v2.1.205, /doctor opened a read-only diagnostics screen and pressing f sent the report to Claude," so on an older build this step is not available to you at all and the pruning test in point 3 is the whole of your tooling.
Apply the pruning test line by line: would removing this cause a mistake?
Move task-specific content to a skill or a path-scoped rule in .claude/rules/ so it loads only when it matters, rather than to an @import — imports load at launch and save you nothing.

What is unverified, and what would settle it

Nobody has run a controlled test of the budget claim in public. The observable prediction is specific and testable: hold one instruction constant, vary the amount of filler around it, and compliance with the constant instruction should fall. That is a headless A/B run, not an opinion: same prompt, same one rule, two CLAUDE.md files that differ only in how much filler surrounds it, and a count of how often the rule is obeyed. Until someone runs it across several models and rule counts, treat this entry as a well-motivated frame with a documented direction and an undocumented magnitude.

Checkpoint

Which part of this tip is stated in the official docs, and which part is a community estimate with no published number behind it?
Show answerAnswer
The direction is official; the arithmetic is not. memory.md states that "Longer files consume more context and reduce adherence", debug-your-config.md says rules "get less attention" as a file grows, and best-practices.md supplies both the pruning test ("Would removing this cause Claude to make mistakes?") and the emphasis budget ("If you emphasize many lines, none of them stands out"). The instruction count — the roughly 50 already spent, and a ceiling in the low hundreds — appears nowhere in the docs; it is a community estimate about a system prompt nobody outside Anthropic has measured. Treat it as a reason to be ruthless, not a number to budget against.
Where do the docs directly disagree with the community rule about code style, and what is the narrower version of that rule that survives?
Show answerAnswer
best-practices.md does the opposite of "never put code style in CLAUDE.md": its worked example opens with a # Code style heading, and its include/exclude table puts "Code style rules that differ from defaults" in the include column, reserving exclusion for standard language conventions Claude already knows. The narrower version that survives is about enforcement, not location — move anything a tool can enforce to the tool, such as the PostToolUse hook on Edit|Write from hooks-guide.md that runs your formatter whether or not Claude read your file, and keep the rest in the file.
If you have a formatting convention with no lint rule behind it, where does it go?
Show answerAnswer
It stays in CLAUDE.md. That is precisely the residue a hook cannot encode — "use ES modules, not CommonJS", "destructure imports" — and it is what the include column of best-practices.md is for. Pair each prohibition with its alternative ("don't use any — use unknown and narrow"): undocumented, but it costs one clause and gives a negative rule something to do.