Shrink your CLAUDE.md: the 300-token rule

Anthropic's own Claude Code best practices put it bluntly: bloated CLAUDE.md files cause Claude to ignore your actual instructions. The mechanism is what the community named context rot: models have a finite attention budget, and every token of boilerplate competes with the instruction that actually matters. Community measurements back it up — one widely shared teardown cut a working config from 3,847 tokens to 312 with no quality loss. Official guidance just says keep it short; our working target is 300-600 tokens. If yours is past 2,000, it is probably storing project documentation, not rules.

Anthropic's bar for every line is whether removing it would cause mistakes. Our working version of that test:

Keep the line only if BOTH are true:
1. It encodes a DECISION that cannot be reverse-engineered from the code.
2. Removing it would make the agent do the wrong thing THIS week, not hypothetically.

"We use pnpm, never npm"            → keep (decision, invisible in any one file)
"The auth flow works like this..."  → delete (readable from code; agent can look)
"Always write tests"                → delete (empty exhortation; gate it in CI instead)

Then treat the file the way Anthropic suggests — like code: review it when something goes wrong, prune it regularly, and let it compound in value instead of weight.

Most CLAUDE.md bloat is misplaced taskmaterial: review checklists, debugging procedures, planning templates. Those aren't standing rules — they're prompts you invoke for specific jobs. Moving them out is the highest-leverage cut, and it's exactly what a prompt library is for: the rules file stays a lean constitution, and task prompts live versioned, one command away:

# instead of a 40-line "how to review" section in CLAUDE.md:
ple get pr-review --var diff="$(git diff main)" | claude -p

# the checklist lives at /zeynepaslierhan/code-review/pr-review — versioned, diffable

The same lazy-load idea appears in Anthropic's context engineering essay as just-in-time context: keep lightweight identifiers around and load the heavy material only when the task needs it. Rules always-on, prompts on-demand.

Run the decision test over every line and delete the failures. Move every task-shaped block (checklists, procedures, templates) into your prompt library. Replace prose about the codebase with nothing — the agent reads code. Re-measure; if you're under 600 tokens, stop. And resist the urge to re-add after one bad session: two failed corrections usually mean you need a fresh session with a better prompt, not a longer rules file.