How to Reduce Verbose Claude Code Comments with WHY Rules (2026)

Long comments added by Claude Code often look like readability insurance, but they more often burn context and raise review load. Official best practices state that performance degrades as the context window fills. Community reports show verbose comments can continue even after CLAUDE.md and memory rules.

📑Table of Contents

1. Summary: problem, symptoms, decision axis
2. Why long comments often fail to help
3. Why ratio can improve while long blocks remain
4. WHY-only placement rules
5. Rollout checklist: rules, hooks, review
6. Author Perspective
7. FAQ
8. Conclusion

This article turns the problem into an operational frame: keep only non-obvious WHY comments, ban WHAT and edit-history noise, and enforce the rule with measurement, hooks, and diff review.

Learning outcomes

---

Summary: problem, symptoms, decision axis

Treat verbose comments as a placement and measurement design issue, not as a politeness deficit.

Decision snapshot

Lens	Takeaway	Practical implication
Problem	Long comments rarely help AI comprehension and pressure context	Same constraint as official context guidance
Field symptom	Verbose by default; prose rules alone do not fully stop it	GitHub #65961; unrequested comment rewrites
Metric trap	Ratio can fall while long blocks remain	Track block count and max run length
Decision axis	From “is it useful?” to “is this the right place?”	Ban-list rules beat vague style advice
Controls	Ban list, hooks, diff review, density lint	Do not stop at a single paragraph in CLAUDE.md

Sources and audience

Sources (as of August 2026):

• Claude Code best practices (EN)
• Claude Code memory / CLAUDE.md guidance
• GitHub issue #65961
• UZU Tech / Zenn measurement write-up
• KyleOndy code-comments skill

Audience: developers and tech leads who use Claude Code daily and want less comment noise in PRs without losing the few WHY notes that matter.

---

Why long comments often fail to help

Long explanatory comments behave less like comprehension aids and more like an output habit that steals limited context from code.

Official context constraints

Claude Code best practices explain that the context window fills quickly with conversation turns, files read, and command output, and that performance degrades as it fills.

The same guide tells teams to keep CLAUDE.md short and limited to instructions Claude cannot infer from code. Over-long instruction files bury real rules in noise and cause ignored guidance.

That is not a dedicated “code comments” chapter, but the same constraint applies to verbose AI-facing prose inside the codebase.

Field reports (GitHub #65961)

Field evidence points the same way. Issue #65961 on anthropics/claude-code reports:

• default verbose comments
• lots of restating adjacent code
• incomplete control even with required CLAUDE.md rules or memory

Follow-ups argue for commenting only non-obvious constraints and for keeping chat history and plan-phase banners out of the codebase.

Unrequested rewrites (verbose comment replacement)

Independent coverage on explainx.ai lists verbose comment replacement—short precise comments silently rewritten into long paragraph prose without a request—as a concrete failure mode.

It tells reviewers to inspect diffs specifically for unrequested comment rewrites. Those rewrites are easy to miss because they rarely change runtime behavior.

Measurement origin takeaway

The origin measurement write-up from UZU Tech on Zenn also reports asking Claude whether long comments help; the answer was effectively no, and often obstructive.

When uncertainty rises, models may pad with words. Comment volume can become a signal of uncertainty rather than of care.

Bottom line: long comments are a cost center for context and human attention, not automatic proof of quality.

---

Why ratio can improve while long blocks remain

“Write only information the code cannot recover” is a good rule. It is not enough.

Measured gap after the usefulness rule

UZU Tech measured 27 PRs (auto-generated noise excluded) after introducing that rule:

• Added-comment ratio: 21.1% → 8.8%
• Continuous blocks of 4+ comment lines: 52 → 50 (almost unchanged)
• Max block length: 17 → 18 lines

Ratio looked better. Review friction from multi-line blocks did not. The 18-line case still contained client-implementation dependencies, library internals, and OOMKill history—each “irrecoverable from code alone”—so a usefulness-only rule could not delete a single line.

Three metrics to track together

That is the metric design lesson. Comment ratio catches scattered WHAT comments. It under-detects the long blocks that force reviewers to stop scrolling.

Track at least:

1. Comment ratio on added lines
2. Count of 4+ line comment blocks
3. Maximum consecutive comment lines

Community discussion around #65961 matches the operational shape: comment only complex non-obvious spots; keep edit-history phrasing and phase banners out of committed code. Do not declare victory from a single ratio drop. Re-measure block counts in the next sprint.

---

WHY-only placement rules

Move the decision axis from “is this useful?” to “is this the right place?” Keep only non-obvious WHY in code comments.

Keep (WHY)

• Hidden constraints and workaround rationale
• Durable external causes: protocols, hardware, upstream issues
• Surprising behavior, units/boundaries, nil meaning, ownership, invariants

Ban list

• WHAT narration readable from the next few lines
• Edit history (“old implementation…”, “added…”, NEW / UPDATED / FIXED)
• Bare task IDs (promote the needed fact into the comment body if required)
• Chat history and plan-mode phase banners

Placement table

Information type	Code comment	Better home
Non-obvious WHY / constraints	Yes, keep short	—
WHAT narration	No	The code itself
Edit history / migration story	No	git log / PR description
Task ID only	No	Issue tracker (promote needed facts)
Chat / phase notes	No	Session logs (do not persist)
Long procedures / domain essays	No (also bloats CLAUDE.md)	Skills / conditional rules

Sources for this section

• Qiita kkaattoo on CLAUDE.md keep/drop
• Claude Code best practices (JA)
• KyleOndy commit
• UZU Tech / Zenn

Mapping the same axis onto CLAUDE.md

Map the same axis onto CLAUDE.md. The Qiita analysis treats AI-facing notes like human code comments: keep only what Claude cannot infer; excess text burns context and buries rules.

The official memory docs recommend keeping each CLAUDE.md under 200 lines and moving long procedures into skills or path-scoped rules. CLAUDE.md is context guidance, not hard enforcement; use a PreToolUse hook or another check when a comment rule must be enforced. The same keep/drop test still applies to code comments.

Public implementation example

A public practitioner implementation from KyleOndy defaults to no comments, forbids transition narration (now uses, no longer, NEW:), and keeps durable causes rather than edit stories.

Ban lists work better when they name concrete phrases instead of relying on “be concise” vibes.

Source

---

Rollout checklist: rules, hooks, review

Prose rules alone are not enough. Ship ban list + metrics + automation + human review together.

Policy text in CLAUDE.md

1. Put an explicit WHY-only / WHAT-history-task-ID ban section in global or repo CLAUDE.md. Prefer concrete banned phrases over vague tables alone.
2. Append real violations you observe: history comments, phase references, unsolicited long rewrites.

Density lint and cleanup

3. Add a PostToolUse-style comment density lint. If language-specific ceilings are exceeded, re-run a deletion pass. Avoid asking the same model “is this too much?”—that invites self-justification (called out in the KyleOndy approach via related issue discussion).
4. Provide a /code:comments-style cleanup: Pass 1 strip narration, Pass 2 rewrite edit stories into current reasons, Pass 3 add missing WHY only. Revert accidental executable code changes.

Measurement and human review

5. Measure before/after merge: ratio and 4+ line block count and max run length.
6. Make unrequested comment rewrites a required human diff check (explainx checklist).
7. Put uncertainty in the PR description, not in padded comments.

Adoption caveat

First-week vibes lie. If ratio falls but block count stays flat, review load probably did not change.

Re-run the same three metrics next sprint and only extend the ban list with newly observed stock phrases.

---

Author Perspective

No private author production log is used here. The practitioner takeaways below stay inside public evidence.

• Do not treat “lots of polite comments” as a quality proxy. Context burn and review stop-time matter first.
• A new paragraph in CLAUDE.md is not a control system. Ban list, density hook, block metrics, and diff review need to travel together.
• Code comments and CLAUDE.md share one keep/drop test. Slimming only one surface leaves the same failure mode on the other.
• Keep long WHY when it is truly irrecoverable. Delete history, play-by-play, and unrequested rewrites.

---

FAQ

Q1. Is “write fewer comments” in CLAUDE.md enough?

Often no. #65961 reports verbose comments continuing despite required rules and memory.

Pair a ban list with hooks and metrics.

Q2. Can I rely only on “comment what code cannot recover”?

Ratio may improve while long useful blocks remain (UZU: 52 → 50).

Add placement rules and history bans.

Q3. What do official docs say about code comments specifically?

There is no dedicated code-comment chapter. The official memory docs instead say to keep each CLAUDE.md under 200 lines and move long procedures into skills or path-scoped rules. That is behavioral guidance, not hard enforcement; use a PreToolUse hook or another control when the rule must be enforced.

Apply that to AI-facing prose broadly.

Q4. What should reviewers look for?

Focus on:

• unrequested comment rewrites
• chat/phase references
• NEW/old-implementation narration
• bare task-ID lines

Use the explainx diff check and #65961 follow-ups as a checklist.

Q5. Which metrics should we track?

Comment ratio plus 4+ line block count plus max consecutive comment lines.

Ratio alone misreads perceived improvement.

---

Conclusion

• Long AI comments are rarely proof of care; they are often a tax on context and review.
• Official docs warn about context degradation and over-specified instructions; community trackers keep reporting default verbosity and partial rule failure.
• Usefulness-only rules do not remove long blocks. Cut by placement (WHY vs git/PR) and explicit bans.
• Do not stop at policy text. Ship density hooks, cleanup commands, block metrics, and diff review together.

Next actions

1. Baseline this week’s PRs on ratio, 4+ line blocks, and max run length.
2. Freeze a single WHY-only / ban-list section in CLAUDE.md.
3. Re-measure the same three numbers in one week and extend the ban list only with phrases that still appear.

Related reading

• Sync Claude Code and Codex configs without CLAUDE.md / AGENTS.md drift
• CLAUDE.md design patterns for personal, team, and monorepo setups
• codebase-memory-mcp: cut agent tokens with a code graph