What to put in CLAUDE.md
ours hit 681 KB

Put in what every session needs and nothing else: the commands, the traps, and a map to the rest.

Download for MacmacOSSend it to your Mac
What to put in CLAUDE.md: ours hit 681 KB
  • Ours grew from 8 KB to 681 KB, and every session read all of it first.
  • Keep the rules. Move the stories behind them into files read only when needed.
  • If something must always happen, make it a hook or a test, not a sentence.

Claude breaks a rule, so you tell it to write the rule down, with the story of what went wrong. Do that for two months and you get what we got.

Our CLAUDE.md grew 87 times over in eight weeks

Every session, and every scheduled job, read all of it before its first word of work: about 170,000 tokens. Claude co-wrote 577 of the 628 commits that touched the file. Each paragraph was a good idea on the day.

Each bar is what main really had that day, from GitHub’s push log. Git’s own date query got it wrong, so we stopped asking it.

Keep the rule and one line of why. Move the history.

74 lines, moved out

A chord posted while a modifier is held is a different chord: every chord, every app it broke in, and each round of fixes, with dates.

what stayed

macOS merges a held modifier into a posted chord (Ctrl+Cmd+C reached a terminal as Ctrl+C). Every synthetic chord waits for or refuses a held modifier.

The rule is what Claude needs. The history is for whoever changes that code.

Leave a map to everything else

CLAUDE.md

## Where the detail lives

Read the topic file before you change that topic.

Release-to-paste latency, measureddocs/engineering/latency.md
The mic, chunks, recording limitsdocs/engineering/audio-capture.md
Spoken filenames, slash commandsdocs/engineering/spoken-filenames-and-commands.md
Trial, referrals, Paddledocs/engineering/billing.md
Update install and quitdocs/engineering/updates-and-releases.md

8,721 lines became 595, one table and 22 topic files. Nothing was deleted. Use plain paths like these, or path-scoped rules. An @import looks tidier, but Claude Code’s docs say it still loads with the file. The catch: Claude only opens a plain path when it decides to.

If it must happen, don’t ask

  • No: “Remember to run the linter after every edit.”
  • Yes: A hook that runs it after every edit.
  • Yes: A test that fails when the rule is broken.

Claude reads CLAUDE.md as context, not as configuration. A sentence is a request. One hook worth having: turn your Mac red when Claude needs you.

What it got us

About 170,000 tokens down to under 10,000, on every session. We did not measure whether Claude now follows the rules better, so we won’t claim it. And Claude Code’s docs say to aim for under 200 lines. Ours was 595 on the day we cut it. It is 651 now.

Check yours: wc -c CLAUDE.md, then /doctor prompt-audit, which lists outdated or conflicting lines and changes nothing until you ask.

More on what an agent needs: how to write a better prompt. Running several at once? Yappr Agents shows which one needs you.

Written 3 November 2026. Every fact about another product is from its own pages, checked that day.