My first CLAUDE.md for a client project ran 400 lines: architecture diagrams, the full MVVM-vs-TCA debate, a style section that just repeated SwiftLint's config in prose. Claude Code reads that file in full on every single turn, and it still missed rules buried near the bottom, because by line 340 they're competing with everything else for the model's attention. I cut it to 60 lines over two weeks. Same team, same codebase, fewer violations of the rules that actually mattered.
It's not documentation
The instinct is to treat CLAUDE.md like a README: a place to record everything true about the project. A README gets read once by a human who skims for the one section they need. CLAUDE.md gets read in full, by a model, every turn, and every line you add dilutes every other line's share of attention. That's the whole design constraint, and most CLAUDE.md files ignore it.
What earns a line
Non-obvious conventions. Not "we use MVVM," that's visible in five minutes of reading the code. "ViewModels never import UIKit" earns its place only if it's a rule someone actually broke once and it cost a day.
