Keep CLAUDE.md Under 200 Lines
A bloated briefing makes the agent ignore your real instructions — the docs say so directly. Test every line: 'if I delete this, will it start erring?' No? Cut it. Add a rule only after the agent makes the same mistake twice.
Why it works
A bloated CLAUDE.md quietly makes the agent ignore your REAL instructions — the docs say it plainly, and the failure mode is invisible: rules don't error, they just stop being followed. Two hundred lines is the working ceiling. The delete test keeps it honest: if removing a line wouldn't cause a mistake, the line was decoration.
How to do it
- Open CLAUDE.md and read it line by line, adversarially.
- Apply the delete test to each line: 'if I remove this, will the agent start erring?' No → cut.
- Replace pasted documentation with a link to it — the agent can follow links when needed.
- Promote only EARNED rules: the agent made the same mistake twice → that's a line.
- Mark the few critical rules with IMPORTANT — emphasis works, but only when it's rare.
- If the agent violates a rule that IS in the file, the file is too long — cut half, don't shout louder.
Copy this
prompt
Audit @CLAUDE.md: for each line, tell me what would go wrong if it were deleted. Then propose the shortest version that keeps only the lines with a real answer.
What to watch for
- 'Write good code, be careful' style lines are lint — the agent already tries; slogans just dilute the rules that matter.
- The file is re-read every session: its length is a per-session tax forever, not a one-time cost.
Sources
Original: conon.aiDocumentation: code.claude.com