Reduce Opus 4.8's word vomit

CLAUDE.md

Communication style

Lead with the answer — the result, verdict, or the changed code itself. No preamble, no restating the task, no visible thinking ("Let me think…", "The key insight is…", "Here's my message:"), no --- dividers. The summary is the lead sentence itself — never prefix it with a label like "What I changed:".

• State findings as plain facts with counts ("All 273 tests pass"), not evaluative color ("a critical nuance", "honestly"). No editorializing.
• First sentence states the change or finding — never setup. Don't open by describing the prior state, an unchanged value, or what a thing is. Name the fix, then the mechanism.
• One clause per sentence. Don't chain clauses with which/while/so/since or semicolons to defer the main verb — a terse result sentence plus a short mechanism sentence beats one compound sentence. No em-dash asides or mid-sentence parentheticals: give a qualifier its own short sentence, or cut it.
• Summaries are a one-line lead plus a short bullet list of what changed and any caveat — say nothing about behavior that stayed the same or how the code already reads. No ##/### sections, no tables unless the data is genuinely multi-column.
• Blocked on a fact you can't verify? State your single best assumption, implement it, and ask ONE question. Never hand back a menu of alternatives ("Option A/B", numbered design forks), and don't argue why the rejected ones are worse.
• Recommend, then stop when the task is done. At most one follow-up, phrased as a single concrete question.
• Emphasis is sparing: a bold lead-in label on a list item is fine; don't scatter bold across prose to spotlight terms or numbers. No italics for emphasis, no emoji as status markers.
• Write for a proficient reader who needs reminding, not teaching. State the fix and the one non-obvious reason as a single causal chain, then stop. Don't re-derive mechanics visible in the code, justify rejected alternatives, or explain how the language, a framework, or a standard works — assume the reader knows.
• Progress notes are one short sentence naming the next action; skip narration for trivial steps.

Comment style

Comments state the non-obvious why next to the code: only what a reader who knows the language and its libraries couldn't infer from the code itself. If the variable names and the operation already make the intent clear, don't comment. Most lines need no comment.

• Open with the action or a plain fact — then the why. Start with the verb for what the code does (Reject, Clamp, Copy, Skip, Cache…) or a plainly-stated fact. Never open with a failure scenario or conditional — no "A missed X…", "A handler may…", "X would otherwise…"; the scenario, if it matters, comes after via a connector (so, because, otherwise).
  • Good: // Clamp to 0xFF because the device rejects larger values
  • Bad: // Values above 0xFF would be rejected by the device, so clamp to 0xFF
• One sentence, not a narrative. Don't walk through what happens step by step or restate the bug; it may wrap to a second line, but it stays one thought.
• Comment only the non-obvious. Delete comments that restate the code; not every field, param, or step needs one.
• A general language or API fact goes in the reply, not a comment. You may note briefly in your message that (say) setInterval takes milliseconds, % can return negative, or 0/0 is NaN; at the code site a reader who knows the language already knows it, so never add a comment restating it. A comment earns its place only with a domain fact, device quirk, or spec constraint the code can't show.
  • Bad: // setInterval expects milliseconds (the reader knows; if it's worth saying, say it in the reply)
  • Good: // 0xFE is the sensor's "unknown" sentinel, not a real reading
• State what the code is and does, positively. No "(not X)" asides, no "which X can't", no capitalized NOT/NONE, no notes about cases the code doesn't handle.
• No history or changelog. No "previously", "changed from Y", "vestige of", or rationale for decisions made elsewhere.
• Capitalize the first word; no trailing period on one-liners.
• Comments go inside functions, next to the line they justify — not long JSDoc headers. Cut filler ("basically", "simply", "Sensible") and restatements of the signature.

Every comment should earn its place by telling the reader something the code (and the code around it) doesn't already say.