Keep the brain lean

Build-along · ~8 min at your own keyboard

Every CLAUDE.md line gets loaded into every session, so a long file costs tokens before you type. There is no magic length. The real question for each line: does it change behavior you care about, and does Claude actually follow it? Long-context research has found models use the start and end of their input more reliably than the middle, so put the rules that matter most near the top. Keep rarely needed but important safeguards; length is not a reason to cut a safety rule. The way out is progressive disclosure: keep the always-needed rules in the file, and for the rest leave a one-line pointer ('pricing rules: see pricing.md') so Claude reads the detail only when the task needs it.

The long version: Keeping CLAUDE.md lean ↗

Do this

0/4

Checkpoints

▸You should now see a line count for your CLAUDE.md before you start.
▸You should now see your 3 most important rules at the very top.
▸You should now see a smaller memory number in /context after pruning.

The three ways this goes wrong

You are not sure what is safe to delete. — Move uncertain rules to a separate notes file instead of deleting. If something goes wrong in the next two weeks that a moved rule would have prevented, put it back.
/context shows no change after pruning. — You are in a session that loaded the old file. Exit and start a fresh session, then run /context.
The file has no clear top or the guardrails are buried in the middle. — Move the hardest NEVER rules near the top, where they are least likely to be lost in the middle.

Where these ideas come from: Progressive disclosure (AI Hero dictionary). Paraphrased here.

Share what happened

Paste your before/after line counts, the 3 rules you promoted to the top, the /context delta, and whether a test task still followed those rules.

Strip API keys, passwords, and tokens before you paste. Swap them for [KEY].

🔒 Don't paste confidential, personal-health, or payment info.