Claudeのコメントが長すぎる問題──AIが書いたコメントは、AI自身の役に立っていなかった

Claude Codeが生成する過剰なコードコメントの原因をRLHFの訓練特性から解説。「コードから復元できない情報のみ」ルールと"情報の置き場所"という発想転換で、コメント比率を21%→8.8%に改善した実践知をまとめます。

はじめに：コード1行に、コメント18行

AIが生成したコードを開いた瞬間の違和感

Claude Codeに関数の実装を依頼したとき、こんなコードが返ってきた経験はないでしょうか。

def calculate_discount(price: float, rate: float) -> float:
    # この関数は商品の割引後価格を計算します
    # price: 元の価格（浮動小数点数）。税込みまたは税抜きのどちらでも使用可能です
    # rate: 割引率（0.0〜1.0の範囲で指定。例：0.2は20%割引を意味します）
    # 戻り値: 割引後の価格（浮動小数点数）
    #
    # 使用例:
    #   calculate_discount(1000, 0.2) → 800.0
    #   calculate_discount(500, 0.1) → 450.0
    #
    # 注意: rateが0.0未満または1.0を超える場合は予期しない動作をする可能性があります
    # そのため、呼び出し元で事前にバリデーションを行うことを推奨します
    # また、浮動小数点演算の性質上、極めて小さな誤差が生じる場合があります
    # 金融計算に使用する場合はDecimalモジュールの使用を検討してください
    #
    # この実装はシンプルな乗算を使用しており、O(1)の時間計算量です
    # パフォーマンスに問題はありません
    # 将来的に複雑な割引ロジック（複数段階割引など）が必要になった場合は
    # Strategyパターンへのリファクタリングを検討してください
    #
    # 実装者注: 2024年のコードレビューで指摘されたエッジケースに対応済みです
    # 変更履歴はGitログを参照してください
    return price * (1 - rate)  # 割引後の価格を返す

コード本体は return price * (1 - rate) の1行です。それに対してコメントは18行。

「丁寧に書いてくれている」と感じる方もいるかもしれません。しかし実際に開発現場でこのコードを目にすると、多くのエンジニアは違和感を覚えます。読むべき情報がノイズに埋もれ、コードの本質が見えなくなっているのです。

Claude自身に聞いてみたら「むしろ邪魔」と答えた

ここで面白い実験をしてみましょう。このコメントを生成したClaudeに、同じセッション内でこう問いかけます。

「このコメントは、あなたが次のセッションでこのコードを読む際に役立ちますか？」

Claudeの回答はこうです。「率直に言うと、大半のコメントは私自身の理解を助けるものではありません。型情報はシグネチャから読み取れますし、使用例はdoctestとして書くべきです。変更履歴はGitログに属します。むしろこれだけのコメントがあると、本質的なWHY――なぜこの実装を選んだのか――が埋もれてしまいます」

AIが自分自身の出力を「むしろ邪魔」と評価する。この逆説こそが、本記事の核心です。

この記事で分かること

• 過剰コメントが生まれる構造的な原因（RLHFとモデルの心理）
• 実際に効果があったルールと、効果がなかったルール（実測データ付き）
• 明日から使えるプロンプトとCLAUDE.mdの具体的な書き方

そもそも「良いコードコメント」とは何か

コメントの役割はWHYであってWHATではない

コードコメントの原則は古くから言われてきました。「コメントにはWHYを書け、WHATは書くな」というものです。

from dataclasses import dataclass

@dataclass
class User:
    name: str
    is_active: bool

users = [
    User("Alice", True),
    User("Bob", False),
    User("Charlie", True),
]

# ❌ WHATコメント（コードを読めば分かる）
# userリストをループしてアクティブなユーザーを取得する
active_users = [u for u in users if u.is_active]

# ✅ WHYコメント（コードからは分からない背景）
# 退会後30日以内は"is_active=True"のままなのでここでは絞り込まない
# 詳細はIssue #892を参照
active_users = [u for u in users if u.is_active]

WHATコメントは「コードの翻訳」に過ぎません。コードそのものが最も正確なWHATの記述であり、それを自然言語で言い換えることは情報の重複でしかありません。しかも、コードが変更されたときにコメントが更新されなければ、ミスリードを生むデッドコードになります。

AI時代に基準が変わった点

従来のコメント論は「人間の読み手」を前提としていました。しかしAIコーディングの時代、コードのコンテキストはもうひとつ別の用途も担っています。AIが次のセッションでコードを読む際のインプットです。

AI（特にClaudeのような大規模言語モデル）にとって、コメントは構造化されたコンテキストであり、コンテキストウィンドウを消費するリソースでもあります。不要なコメントはトークンを消費し、コンテキストの品質を下げます。S/N比（シグナル対ノイズ比）の低いコードベースは、AI自身の読解精度を下げるのです。

ノイズがもたらす実害

Stack Overflow 2025年調査では、AIツールの精度への信頼が前年の40%から33%へと低下しています。開発者の66%が「ほぼ正しいが少し違うAI出力の修正」に時間を消費しており、ツール離れの最大要因として「ノイズが多すぎる出力」が挙げられています。

コメントのノイズは単なる美観の問題ではありません。AIとの協働開発における生産性を直接侵食するのです。

なぜClaudeはコメントを書きすぎるのか──3層の原因構造

原因① RLHFによる「説明的な出力」の強化

RLHF（人間のフィードバックによる強化学習）は、モデルの訓練において人間の評価者がどちらの回答を好むかによって学習方向を決定します。

問題は、人間の評価者が「詳細で丁寧な回答」を好む傾向にあることです。「このコード、型の説明もあって丁寧だな」「使用例まで書いてくれている、親切だな」という評価が積み重なると、モデルはコメントを増やす方向に強化されます。

Anthropicは評価基準として「conciseness（簡潔さ）優先」を定めているにもかかわらず、実際の挙動との乖離が指摘されています。「簡潔に書いて」と指示しても冗長になる逆説は、単純なプロンプト修正では解決しない訓練レベルの問題です。

GitHubにはこの問題を報告するIssueが存在します（#65961 「Claude verbose code comments by default」）。個人の設定ミスではなく、モデルの性質として認識することが改善への第一歩です。

原因② 視認性の錯覚──「ちゃんと考えた」を可視化したがる

AIモデルには思考過程をアウトプットとして可視化しようとする傾向があります。これは問題解決においては有用な特性ですが、コード生成においては「思考の痕跡がコメントとして残る」という副作用を生みます。

「このアルゴリズムはO(n²)だから注意が必要で、大規模データセットではnumpy化を検討すべきで……」という内部的な検討が、そのままコメントブロックとして出力されてしまうのです。説明量＝仕事量という誤った変換が起きています。

原因③ 不確実さの言語的補強

最も重要な原因がこれです。自信のない箇所ほどコメントが長くなるという傾向です。

モデルが「この実装で本当に良いのか？」と確信を持てないとき、その不確実さを言葉で補強しようとします。「なお、このアプローチには制約があり、〇〇の場合は△△を検討する必要があります。また、□□については……」という長いコメントブロックは、実は「この箇所に自信がない」というシグナルでもあるのです。

逆説的ですが、コメントが長い箇所はコードレビューの優先候補と読めます。なぜなら、コメントの量がモデルの不確実さの指標として機能しているからです。

実験：ルール導入でコメントはどこまで減ったか

第1段階：「コードから復元できない情報のみ記載」ルール

Zenn記事（uzu_tech氏）の実践報告では、まず以下のルールをプロンプトに追加しました。

# コメントポリシー
コードコメントは「コードを読んでも復元できない情報」のみ記載すること。
- コードを見れば分かる処理の説明は書かない
- 変数名・型情報の言い換えは書かない
- WHY（なぜこう実装したのか）のみをコメントする

結果は明確でした。コメント比率が21.1%から8.8%へと低下しました。数字だけ見れば大成功です。

なぜ「比率の改善」だけでは不十分だったのか

しかし問題が残りました。コメント比率の平均値は下がったものの、長大なコメントブロックの数はほぼ変わらなかったのです。

10行のコメントブロックが5つあったとすれば、多くが削除されて3つになったが、残った3つは依然として8〜10行のまま、という状況です。体感として「まだ重い」という感覚が残るのに、数値では改善されている。このギャップが体感と実態の乖離を生みます。

だからこそ定量測定が必須です。コメント比率という1軸だけでなく、「連続するコメント行数の最大値」という2つ目の軸を加えることで、実態が見えてきます。

# コメント行比率を測定する簡易スクリプト（Python）
import re
from pathlib import Path

def analyze_comments(filepath: str) -> dict:
    lines = Path(filepath).read_text().splitlines()
    total = len(lines)
    comment_lines = [l for l in lines if l.strip().startswith('#')]
    
    # 連続コメントブロックの最大長
    max_block = current_block = 0
    for line in lines:
        if line.strip().startswith('#'):
            current_block += 1
            max_block = max(max_block, current_block)
        else:
            current_block = 0
    
    return {
        "total_lines": total,
        "comment_ratio": len(comment_lines) / total,
        "max_consecutive_comments": max_block
    }

このスクリプトをCIに組み込むことで、継続的な品質モニタリングが可能になります。

決定打は「有用性」ではなく「情報の置き場所」だった

発想の転換：役に立つか、ではなく、どこに置くべきか

「有用なコメントを書け」という指示の問題点は、有用性の判断がモデルに委ねられることです。モデルは「これは有用かもしれない」という判断を、コメントを書く方向に傾けます。

発想を転換することで、この問題が解決します。問いを「このコメントは役に立つか？」から「この情報の正しい保管場所はどこか？」に変えるのです。

情報の置き場所は一意に決まります。判断コストがほぼゼロになります。

情報の振り分けルール

この表を見れば分かるとおり、コード内コメントに置くべき情報は「現在進行形のWHY」だけです。

「なぜこのライブラリを使っているか（代替案が使えない理由）」「なぜこの順序で処理しているか（並び順に意味がある場合）」「なぜこの値をハードコードしているか（仕様上の制約）」――これらは他の場所に移せません。コードを読んでも文脈から復元できないからです。

一方、「いつ変更したか」はGitログにあります。「どのチケットの対応か」はIssueにあります。これらをコメントに重複して書くことは、情報の分散と陳腐化を招くだけです。

Anthropic自身の動きとも一致する

2026年7月、AnthropicはClaude Codeのシステムプロンプトを約80%削減しました。公式の問題意識は「禁止指示の羅列がモデルの創造性を制限する」というものです。

禁止項目を積み重ねるより、思想を共有する。やってはいけないことのリストより、なぜそうすべきかという原則を与える。これはZenn記事の結論と完全に一致する方向性です。

実践：プロンプトとCLAUDE.mdの設計

そのまま使えるコメント方針の記述例

以下はCLAUDE.mdに追加できる、コピーして使えるルールブロックです。

## コードコメント方針

### 原則
コメントは「コードを読んでも復元できない情報」のみ記載する。
具体的には「現在進行形のWHY（なぜこの実装を選んだか）」のみをコード内に残す。

### 情報の置き場所（これを必ず守ること）
- 変更履歴・実装経緯 → Gitコミットメッセージ
- チケット・タスク参照 → Issue番号のみ（例: `# see: #892`）
- 仕様・設計背景 → このCLAUDE.mdまたは設計ドキュメント
- 現在進行形のWHY → コード内コメント（唯一ここに書くもの）

### 禁止する具体的なパターン（NG例）
以下の形式のコメントは書かない:

# ❌ 型・引数の説明（シグネチャで分かる）
# price: 商品価格（float）
# rate: 割引率（float, 0〜1）

# ❌ 処理の言い換え（コードを読めば分かる）
# リストをループしてフィルタリングする

# ❌ 使用例（doctestまたはテストコードに書く）
# 例: calculate_discount(1000, 0.2) → 800.0

# ❌ 変更履歴・担当者（Gitログに書く）
# 2024-03-01 〇〇対応のため修正

抽象的な原則と具体的なNG例をセットで提示することがポイントです。

抽象的な原則より「具体的なNG例」が効く理由

「コメントを簡潔にしてください」という指示は機能しません。「簡潔」の基準がモデルの判断に委ねられるからです。

一方、「この形式は禁止」と具体例を示すと効果が上がります。モデルは例示からパターンを学習します。「型の説明はシグネチャで分かる→書かない」「処理の言い換えはコードを読めば分かる→書かない」という具体的なパターンマッチングが機能するのです。

技術的に正確な表現を心がけるなら、ルールは「〇〇してはいけない」より「〇〇はXに書く、コメントにはYのみ書く」という振り分け形式が最も明確です。

CLAUDE.md運用のベストプラクティス

実際の開発現場でのベストプラクティスとして、以下が広く共有されています。

追記のタイミング: ClaudeがClaude同じミスを2回したときに初めてルールを追記します。1回目はプロンプトで対応し、パターン化したと確認できてからCLAUDE.mdに昇格させます。

ルール数の上限: 目安として150〜200のルールを上限意識として持ちましょう。それ以上増えると競合や矛盾が生まれ、どのルールが優先されているか把握できなくなります。

定期的な剪定: 月1回、CLAUDE.md全体を見直す習慣が肥大化を防ぎます。「このルールはまだ有効か？」「最初に想定した問題はもう起きていないか？」を確認します。

グローバル設定の優先: プロジェクト固有の設定より、グローバル設定（~/.claude/CLAUDE.md）への統一を優先します。複数プロジェクトで同じルールを重複管理するより、一箇所で管理する方が保守性が高まります。

やってはいけないアンチパターン

段階的に理解を深めていただくため、陥りやすい罠も明示しておきます。

• 禁止事項を積み増し続ける: 問題が起きるたびに「〇〇するな」を追記し続けると、CLAUDE.mdがブラックリストの集積所になります。禁止より思想の共有を優先してください
• 書いたルールを検証せず放置する: ルール追加後、実際にコメントが変化したか測定しないまま運用すると、機能していないルールが残り続けます
• ルール同士の矛盾を放置する: 「詳細なコメントを書け」と「コメントを最小化せよ」が共存すると、モデルは混乱します。定期的な整合性チェックが必要です

コンテキスト管理という、より大きな課題

すべての新セッションはゼロスタートである

コメント問題を深く掘り下げると、より根本的な課題に行き着きます。コンテキスト管理です。

Claudeとの新しいセッションを開始するたびに、前回の会話は引き継がれません。「なぜこのライブラリを採用したか」「廃止したAPIの代替は何か」「このモジュールのアーキテクチャ上の役割は何か」──こうした設計判断はすべてリセットされます。

コメント問題は、このコンテキスト設計問題の一部に過ぎません。

2026年の差別化要因は「コンテキストエンジニアリング」

AI協働開発において、2026年の差別化要因はコンテキストエンジニアリングにシフトしつつあります。「どのモデルを使うか」より「どのようなコンテキストをモデルに供給するか」が品質を左右する時代です。

CLAUDE.mdやCursor Rulesによる「構造的コンテキスト供給」が標準的なプラクティスになりつつあります。コードベース自体を「AIへの入力」として設計する視点が求められています。

優れたコードベースとは、人間にとって読みやすいだけでなく、AIが正確に解釈できるS/N比の高いものでもあるのです。

コメント削減がコンテキストに効く理由

実用的な観点から言えば、コメントの削減はコンテキストウィンドウの最適化に直結します。

不要なコメントを削減することで、限られたコンテキストウィンドウをより重要な情報が占有できます。コードベースのS/N比が上がれば、AIの読解精度が上がります。コメント整理は、そのままAIとの協働品質への投資になるのです。

よくある質問（FAQ）

Q: なぜClaudeはコメントを書きすぎるのですか？

A: RLHF訓練において、詳細で丁寧な出力が人間評価者に高く評価される傾向があるためです。「説明的であること＝良い出力」という強化が積み重なり、「簡潔に」という指示とモデルの挙動が乖離する逆説が生まれています。

Q: 「役立つコメント」の基準は何ですか？

A: 「コードを読んでも復元できない情報」が唯一の基準です。より具体的には「現在進行形のWHY（なぜこの実装を選んだか）」のみをコードに残し、他の情報は適切な置き場所（Git、Issue、設計ドキュメント）に移します。

Q: ルール化すれば本当に改善しますか？

A: 比率は改善しますが、「塊（長大コメントブロック）」は残ります。有用性ルールだけでは不十分で、「情報の置き場所」という発想転換が必要です。また、定量測定なしでは改善の実態が掴めません。

Q: CLAUDE.mdには何を書くべきですか？

A: 抽象的な原則と具体的なNG例をセットで書きます。「〇〇するな」より「この情報はXに書く、コードにはYのみ書く」という振り分け形式が最も効果的です。

Q: なぜ定量測定が重要なのですか？

A: 体感と実態が乖離するためです。コメント比率が下がっても長大ブロックが残れば、体感の改善は限定的です。「コメント比率」と「連続コメント行数の最大値」の2軸で測定することで、実態が正確に把握できます。

まとめ：コメント量は、AIの自信のなさを映す鏡

この記事の要点3つ

1. 過剰コメントの正体はRLHF由来の「不確実さの言語的補強」: 長いコメントブロックは品質の証明ではなく、モデルの不確実さのシグナルです。コメントが多い箇所をレビューの優先候補として読む視点が有効です

2. 効いたのは禁止の列挙ではなく「情報の置き場所」という思想: 「役立つか」という問いをやめ、「この情報の正しい保管場所はどこか」に変えることで判断が一意になります

3. 体感ではなく比率と最大ブロック長で測る: 定量測定なしでは改善の実態は見えません。2軸での継続計測をCI/CDに組み込みましょう

長いコメントを見たら、まずそのコードを疑う

ベストプラクティスとして提案したいのは、コメント量を品質シグナルとして活用する読み方です。「このコメントブロックが長いということは、この実装に不確実な要素があるのかもしれない」という視点でコードレビューに臨むことで、隠れたリスクを早期に発見できます。

次の一歩

まず自分のリポジトリで実際のコメント比率と最大連続コメント行数を測定してみてください。体感とのギャップに驚くはずです。

次に、CLAUDE.mdに「情報の置き場所」ルールを1行追加します。

## コメントポリシー
コード内コメントには「現在進行形のWHY」のみを書く。
変更履歴はGitに、チケット参照はIssueに、設計背景はこのファイルに書く。

たったこれだけから始められます。AIとの協働開発の品質は、モデルを変えることより、コンテキストを整えることで大きく変わります。コメント整理はその最初の一歩です。

参考リンク

• Claude が書く長いコメントは、Claude 自身の役に立っていなかった（Zenn）
• Claude verbose code comments by default（GitHub Issue #65961）
• RLHF trained Claude to be verbose. Here's the proof（DEV Community）
• Claude Codeのシステムプロンプトを80%削減（ITmedia AI+）
• Context Engineering Best Practices for AI-Powered Dev Teams（Packmind）
• CLAUDE.md運用のベストプラクティス（Zenn）
• AIコーディングのコンテキスト管理術（Zenn）
• AI Coding Productivity Paradox 2026（ecorpit）