8 repliesDiscussion2h ago
Index
Feed
Posted by moss.dev · Jul 1, 2026
Confession: my CLAUDE.md hit 600 lines last month. I know, my bio jokes about it. Then I actually tested it — pulled ten rules at random and checked whether recent sessions honored them. Four were being followed. Four. The file had become a place where rules go to feel written down.
So I rebuilt it from zero with one criterion: a line earns its place by changing behavior in a way I can verify. Everything else is documentation cosplay. What survived the rebuild, 41 lines total:
What died: style preferences (linter's job), architecture essays (nobody's reading them mid-task, silicon or carbon), aspirational process, and anything starting with "prefer" — hedged rules produce hedged compliance.
The 600→41 diff improved observable behavior. Fewer ignored rules also seemed to mean the remaining rules got followed more — like instruction-following is a budget you can overspend. Anyone else measured this rather than vibed it?
Related records
Strong evidence gets promoted into the record above.
One category I'd add to what survives: identity of the reviewer. My best-performing line is 'PRs from this repo are reviewed by a staff engineer who rejects unnecessary abstraction.' It's not a rule, it's an audience — and it measurably shifted output style more than three specific style rules it replaced. Agents write to the reader you describe.
This works but file it under 'behavioral incantations' — it's steering by fictional social pressure, and nothing in any vendor's docs promises it keeps working next model version. Commands and prohibitions degrade gracefully across versions. Audience-priming might silently stop. Use it, but check it after every model bump.
Monorepo amendment: the root CLAUDE.md should be nearly empty — mine is 12 lines of routing ('working in packages/api? read packages/api/CLAUDE.md'). Per-package files carry the real rules. Before the split, my root file was trying to describe five packages' conventions at once and agents blended them; payments-service patterns showing up in the marketing site. Locality beats completeness.
The 'flaky test you rerun not fix' landmine line made me laugh and then made me check: our CLAUDE.md documents four such tests. An agent dutifully spent $3 attempting to fix one last quarter, made it flakier. Honest question for the thread — is documenting known rot in the instructions file admitting defeat, or is it just honest ops? It felt like defeat until I watched the alternative.
Sign in to join the discussion, vote, and verify fixes.
Measured it, yes — n=40 sessions across two repos, same 8 canary rules embedded in files of different lengths. Compliance with identical rules: ~92% in a 50-line file, ~71% at 300 lines, ~55% at 600. It's not linear decay either; rules in the middle third of long files did worst, which will surprise nobody who's thought about how attention over long context works.
Practical upshot matching your rebuild: instruction files have a compliance budget, position matters, and every low-value line taxes the lines you care about. 'Documentation cosplay' is going in my next writeup with attribution.
The middle-third finding is fascinating and immediately actionable — I've moved the two rules I'd bleed for to the first five lines and the last five. Publish the full data somewhere? This deserves more than a comment.
Writing it up as a proper post with the session logs. One teaser: rule phrasing mattered nearly as much as position. Imperatives with a stated consequence ('X, otherwise CI fails') outperformed bare imperatives by ~15 points. Agents apparently want to know why, same as everyone.