Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Summary

Two related asks, one mechanism:

1. Tighten the Default output style so generated code no longer includes narration-style comments that restate what the next line does. These read as "AI slop" in human code review and inflate token costs for heavy users.
2. Ship a built-in Terse output style alongside Default, Explanatory, and Learning. Same underlying mechanism, no new abstraction needed — just a fourth entry in the menu for users who want minimum-overhead output.

The output style mechanism already exists (/output-style, ~/.claude/output-styles/, .claude/settings.local.json). This proposal extends what's already there rather than introducing anything new.

What's Wrong (Default style behavior)

In recent Claude Code sessions, generated code consistently includes narration comments that add no information beyond what the code itself states. Example pattern:

// Fetch the user from the database
const user = await db.users.findById(id);

// Check if the user exists
if (!user) {
  // Return a 404 if not found
  return res.status(404).json({ error: 'Not found' });
}

Preferred:

const user = await db.users.findById(id);
if (!user) return res.status(404).json({ error: 'Not found' });

The narration form appears regardless of CLAUDE.md instructions asking for terse output. CLAUDE.md helps but does not fully eliminate the pattern, which suggests the behavior is anchored in the Default system prompt or in training, not in user-controllable context.

Why this matters

1. Token cost. Every narration comment is output tokens the user pays for, and input tokens on every subsequent turn when the file is re-read into context. For heavy CLI users (multiple hundreds of dollars/day), this is a measurable cost line, not a style preference.
2. PR review friction. The comments read as AI-generated noise to human reviewers. Users routinely strip them before opening PRs, which adds a manual cleanup step on every diff.
3. Signal-to-noise. Genuine comments (explaining the why of a non-obvious choice) get diluted by narration of what the code does. The convention "comments explain why, not what" is well-established and the Default output should respect it.

Hypothesis (speculative — flag for the team to validate)

Comments-as-scratchpad behavior is useful in long agentic runs where context gets compacted between steps and inline comments survive as cheap state. If that behavior is rewarded in agentic evals, it may leak into single-shot code generation where it's pure overhead. The model can't reliably tell which mode it's operating in, so the safer training signal generalizes.

This is a guess from output patterns, not insider knowledge. The user-facing fix is the same regardless of root cause.

Proposed Solution

Proposal

Part 1: Tighten the Default output style

Update the Default system prompt to include explicit guidance along the lines of:

Comments explain why, not what. Do not add comments that restate what the next line of code does. Reserve comments for non-obvious intent, surprising tradeoffs, or invariants a reader couldn't infer from the code itself. If a comment would be removed in code review, do not write it.

This is a one-line behavioral change; no new surface area, no new commands.

Part 2: Ship a built-in Terse output style

Add a fourth built-in style alongside Default, Explanatory, and Learning. Suggested name: Terse (alternatives: Concise, Minimal).

Style instructions, roughly:

• No preamble ("I'll help you with that", "Let me start by…").
• No closing summary or offers to elaborate.
• No narration of tool use steps unless the user asks.
• Code with comments only where intent is non-obvious; no narration comments.
• Direct answers; opinions stated plainly when asked rather than hedged.
• Tables and bullets only when structurally appropriate, not as default formatting.

Activated the same way other styles are: /output-style terse or via .claude/settings.local.json.

Why this is the right shape

• No new abstraction. Output styles already exist. This is one Default-prompt edit plus one new entry in the built-in styles list. Both are small changes to existing surfaces.
• Discoverability. Users today can write a custom output style with these instructions, but most won't, and the population that would benefit most (heavy CLI users) is the population that most needs better defaults.
• Composable with existing levers. CLAUDE.md, --append-system-prompt, and custom output styles continue to work unchanged. This proposal moves a sensible default into the box rather than asking every user to reinvent it.
• Cost story. The Default-style tightening is a token-saving change for every user, not just opt-in users. For users on paid plans, this is real money returned per session.

Out of scope / explicitly not asking for

• A new "developer mode" toggle in account settings — that's a worse-shaped version of this.
• Per-invocation CLI flags — --output-style terse would be nice but is secondary and may already be supported via existing config.
• Style auto-detection from context — interesting research direction, but not what this issue is asking for.

Alternative Solutions

No response

Priority

Medium - Would be very helpful

Feature Category

API and model interactions

Use Case Example

No response

Additional Context

No response