Prune Your CLAUDE.md, Then Test Whether Adherence Moves
Three hundred lines of instructions, and Claude still ignores the rule about where results files go. So you add the rule again in capitals. It still slips.
The Claude Code best-practices guide has a direct diagnosis: "If Claude keeps doing something you don't want despite having a rule against it, the file is probably too long and the rule is getting lost." The file is also the fixed part of every context. Per the memory documentation, CLAUDE.md and its @ imports, up to four hops deep, load at launch in every session. A 3,000-token import across 40 sessions a day is 3,000 × 40 = 120,000 input tokens before any work starts, and those tokens compete with the code the model needs to read.
Rule out the dull causes first. Run /context and read the Memory files list to confirm the file loaded at all, then read the file for two rules that contradict each other.
Prune. The guide's test is one question per line: "Would removing this cause Claude to make mistakes?" Cut what Claude can infer from the code, generic advice and pasted API documentation. Move material only some tasks need into an on-demand skill, and your own cluster paths into CLAUDE.local.md, which loads after the shared file (keeping a local setting out of the team contract covers that split). Save emphasis for the one line that keeps slipping, because "If you emphasize many lines, none of them stands out."
Then test. The guide says to "test changes by observing whether Claude's behavior actually shifts." Here is a version you could defend in a writeup.
- Pick five rules you can check mechanically, such as "results go under
runs/<run-id>/" or "run the smoke test before committing." - Write tasks that each give at least one of those rules a chance to apply.
- Run every task once with the original file and once with the pruned file, each in a fresh session.
- Count the discordant pairs: tasks where only the pruned file's run followed a rule, and tasks where only the original's did.
Pairing is what makes a small test readable. Unpaired, five runs per arm separate almost nothing: even a clean 5 of 5 against 0 of 5 gives 95% Wilson intervals of 0.57 to 1.00 and 0 to 0.43, and with 10 tasks the interval on a single rate near 50% is about ±30 points. A sign test on the discordant pairs does better with the same budget. Five pairs all in one direction give a two-sided p = 0.0625, so you need at least six. Many pairs will agree, so plan on 20 or more tasks.
If adherence does not move, the pruned file still costs fewer tokens in every session. A rule that must hold every time does not belong in prose at all: turn each "never" into a test. And never put credentials in an instruction file; a file Git ignores is still a file the agent can read.
Chapter 16 derives the paired comparison, and Chapter 21 explains why more context can mean less attention to any one line.
