Claude Code over-comments. It narrates loops, restates signatures, leaves change-log notes addressed to a PR reviewer who'll never see them, and points at spec sections that have already moved. Two layers fix it and compound: a pre-hoc layer in CLAUDE.md that steers the model as it writes, and a post-hoc cleanup skill that reclaims the residue — plus everything verbose you inherited from past work and other contributors. Use both; neither is sufficient alone.
The whole thing is one principle applied twice. Code shows how. A comment earns its place only by carrying why — a non-obvious constraint, a deliberate deviation, a gotcha, a workaround, the reason a tempting simpler version is wrong. Everything else is restatement, and restatement rots: it drifts out of sync, adds diff noise, and trains readers to skim past comments entirely.
The block I use:
