CLAUDE.md for an iOS Team: What to Put In It (and What to Leave Out)

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. Constraints invisible in the diff. App Store review requirements, a minimum OS version the code doesn't yet reflect, a performance budget on one screen because a past ship got rejected for jank. An agent has no way to infer any of that from the code alone. Repo-specific workflow gotchas. Which branch triggers a real deploy, which test suite is a known-flaky non-gate versus a hard one, where the actual source of truth lives when two files disagree. I run a merge gate across a few of my own repos, code only merges once CI is green and review found nothing blocking, and the single highest-value line in each CLAUDE.md is the sentence explaining that the gate exists and why a raw git merge is bypassing something on purpose. What the agent never touches unsupervised. For me that's deploy config and anything security-sensitive. Naming the boundary explicitly is cheaper than discovering