CLAUDE.md is the file Claude Code reads before it starts working for you. With older models you had to spell everything out, so most of us built long lists of do's and don'ts. Newer models follow instructions much more literally, so a long list, especially one with rules that contradict each other, gets in the way. Mine went from 1,116 lines to 50.
Before: the shape to avoid
NEVER create files unless absolutely necessary
NEVER write documentation unless asked
Don't add comments
Don't refactor anything I didn't ask about
Never commit without asking
After: the shape that works
Edit the existing file when one fits.
Write documentation when I ask for it.
Keep commits to the change I asked for, and ask before committing.
I kept a couple of hard nevers for safety, like never committing secrets. Everything else says what to do.
Step 1: Back it up
Copy the file before you touch it. You'll want to compare.
Step 2: Cut
Delete every "don't" you can't explain in one sentence.
Step 3: Find the contradictions
Paste the whole file into Claude and ask:
Read this CLAUDE.md. List every pair of rules that contradict each other, and every rule vague enough to read two ways.
Step 4: Turn "don't" into "do"
"Don't write long emails" becomes "Keep emails under 100 words."
Step 5: Move reference material out
Put long reference material in separate files, and point to them from your CLAUDE.md.
Step 6: Test it
Run the same job on the old file and the new one. Keep whichever gives the better answer.