CLAUDE.md: presence matters, formatting may not

You are editing CLAUDE.md for the fourth time this month. You moved the important rule to the top. You split it into a nested per-directory file. You cut the file to 80 lines. Claude still skipped it on the last refactor. The implicit theory behind all four edits is that adherence is a formatting problem — and there is now a measurement that says it probably is not.

What the measurement reports

Before the numbers, the chain of custody, because it changes how you should read them. Nobody in this repo has run this. What follows is a blog post summarizing a preprint that was not read directly and whose identifier could not be confirmed. Every figure below is reported, not reproduced.

With that stated: Damon McMillan's study, as written up by Alex Dunlop, is said to have run 1,650 Claude Code sessions across two real TypeScript codebases on Sonnet 4.6, checking one mechanically verifiable rule (an annotation on every function) across 16,050 functions. The variables were manipulated deliberately, one at a time.

The two rows in bold are the only ones that moved. Everything you have been tuning is in the rows that did not.

The docs say something different

This is not a gap in the documentation. It is a head-on conflict, and you should know which pages you are contradicting before you act on it.

• memory.md — "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence," and later, "Shorter files produce better adherence."
• memory.md again, on consistency — "if two rules contradict each other, Claude may pick one arbitrarily."
• debug-your-config.md — adherence drops "when two files give conflicting direction, or when the file has grown long enough that individual rules get less attention."
• claude-directory.md repeats the 200-line target in its inline tips.

So the docs claim length and contradiction both hurt; the study reports neither did.

What both sides actually agree on

The two findings that survived the study are the ones the docs also gesture at, from a different direction:

• Decay over a session. best-practices.md says outright that as the context window fills, Claude "may start 'forgetting' earlier instructions or making more mistakes," and recommends /clear between unrelated tasks. That is the same shape as the study's per-function odds decay, arrived at independently.
• Restating a rule in the prompt works. sub-agents.md and debug-your-config.md both prescribe exactly this for Explore and Plan subagents, which skip CLAUDE.md entirely: "restate the instruction in your delegating prompt."

Nobody documents the edit-versus-create gap. That one is the study's alone, and it is the most interesting claim in it — a convention that reads as obvious when you are producing a new file apparently competes with the surrounding style of the file you are modifying.

What to do differently on Monday

Stop treating CLAUDE.md as the lever and treat the prompt as the lever:

• When the task is editing existing code, name the convention in the prompt. Not "follow CLAUDE.md" — the actual rule, in the actual sentence.
• When you are deep into a long session, restate it again, or /clear and reopen with the rule in the first message.
• When you delegate to Explore or Plan, restate it, because those agents never load the file at all. That part is documented, not inferred.
• Keep maintaining the file anyway. The one enormous effect in the whole study is presence versus absence.

What is unverified here, plainly

The provenance is stated at the top rather than here, because a reader who meets a table of decimal percentages fifty lines before its disclaimer has already believed it. Take the figures as a hypothesis worth testing on your own repo rather than as a result.

What would settle it is a small headless harness. Put one mechanically checkable rule in CLAUDE.md, run the same task headless N times in each condition, and count violations with a grep rather than by reading transcripts:

#!/usr/bin/env bash
# Sketch only — not run. Adapt the rule and the checker to your repo.
set -euo pipefail
RULE_CHECK='grep -c "@invariant" src/generated.ts'

for cond in create edit; do
  for i in $(seq 1 25); do
    git checkout -- . && git clean -fd src/generated.ts || true
    if [ "$cond" = "edit" ]; then cp fixtures/existing.ts src/generated.ts; fi
    claude -p "Add a function that validates a user record to src/generated.ts" \
      --output-format json > "runs/${cond}-${i}.json"
    printf '%s %s %s\n' "$cond" "$i" "$(eval "$RULE_CHECK" || echo 0)"
  done
done

Two conditions, one rule, a countable outcome. Twenty-five runs per arm will not reproduce a 1,650-session study, but a 26-point gap is large enough that it should be visible at that sample size — and if it is not visible in your repo, that is the answer you actually needed.