Claude Code が足す長いコメントは、読みやすさの保険に見えて、実際にはコンテキストを食い、レビュー負荷を上げることが多いです。公式のベストプラクティスは、コンテキストが埋まるほど性能が落ちると明記しています。コミュニティの報告では、CLAUDE.md や memory を書いても冗長コメントが止まらないケースが続いています。この記事では、「有用か」だけでなく「置き場所として正しいか」で切る基準と、禁止リスト・計測・フック・diff レビューまで含めた運用手順を整理します。
📑目次
サマリー：問題・症状・判断軸
まず全体像です。長いコメント問題は「丁寧さ不足」ではなく、出力の置き場所と計測の設計問題として扱う方が実務に効きます。
判断の全体像
| 観点 | 要点 | 実務での含意 |
|---|---|---|
| 問題 | 長いコメントは AI 読解を助けず context を圧迫する | 公式 best practices の context 制約と同型 |
| 現場症状 | デフォルトで冗長、ルール文章だけでは半減しきれない | GitHub #65961、unrequested comment rewrite |
| 計測の落とし穴 | 比率は下がっても長いブロックは残る | ブロック数・最大行数を必須指標にする |
| 判断軸 | 有用か → 置き場所か（WHY / 履歴は git・PR） | 禁止リスト型のルールが効く |
| 実行手段 | 禁止リスト、hooks、diff レビュー、密度 lint | 文章ルール単体で終わらせない |
出典（2026年8月時点）:
- Claude Code best practices (EN)
- Claude Code memory / CLAUDE.md guidance (公式)
- GitHub issue #65961
- UZU Tech / Zenn 実測記事
- KyleOndy code-comments skill
対象読者は、Claude Code やコーディングエージェントを日常利用し、PR のコメントノイズと context 劣化を抑えたい開発者・テックリードです。
長いコメントが「役に立たない」と分かる根拠
結論から言うと、長い説明コメントは理解補助ではなく出力癖になりやすく、限られたコンテキストをコードから奪います。
公式が示すコンテキスト制約
Claude Code の公式ベストプラクティス（日本語） は、コンテキストウィンドウが会話・読んだファイル・コマンド出力で急速に埋まり、満杯に近いほど性能が落ちると説明しています。
同じ文書は CLAUDE.md についても、コードから推測できない指示だけを短く残し、肥大すると重要ルールがノイズに埋もれて無視されると警告しています。
コードコメント専用の章ではない一方で、「AI 向けの長い文章が増えるほど効きが落ちる」という制約は、コード内コメントにもそのまま当てはまります。
現場報告（GitHub #65961）
現場側の証拠も揃っています。anthropics/claude-code の Issue #65961 は、次を報告しています。
- デフォルトで冗長なコードコメントが付き、隣接コードの自明な言い換えが多い
CLAUDE.mdの必須ルールや memory でも確実には止まらない
追記では、複雑な非自明箇所だけに絞るべき、チャット経緯や plan phase の参照をコードに残すべきでない、といった運用上の指摘が続いています。
依頼なき書き換え（verbose comment replacement）
独立記事の explainx.ai は、短い精密なコメントが依頼なく長段落に置き換わる verbose comment replacement を失敗モードとして切り出しています。
同記事は「unrequested comment rewrites を diff で確認せよ」とチェックリスト化しています。依頼していない書き換えは、機能差分より目立ちにくく、レビューで見逃しやすい点に注意が必要です。
計測元の実感
UZU Tech の Zenn 記事 では、Claude 自身に「長いコメントは助かっているか」を確認したところ、「助かっていない。邪魔が多い」という趣旨の回答だったと報告されています。
自信がない箇所ほど言葉で埋める傾向があり、分量そのものが不確実さの指標になり得る、という読み方も実務では有用です。
要するに、長いコメントは「説明が厚いほど安全」ではなく、「限られた context と人間の注意を奪うコスト」として扱う方が妥当です。
比率は下がっても長いブロックが残る理由
「コードから復元できない情報だけ書け」というルールは有効です。ただし、それだけでは長いブロックは消えません。
実測で見えるギャップ
UZU Tech の計測（PR 27件、自動生成除外）では、ルール導入後に次の変化が報告されています。
- 追加コメント比率: 21.1% → 8.8%
- 4行以上の連続ブロック: 52 → 50（ほぼ不変）
- ブロック最大行数: 17 → 18
比率だけ見ると改善に見えます。一方で、レビュー中にスクロールを止める十数行ブロックの数はほぼ減っていません。最大18行の例は、クライアント実装依存・ライブラリ内部仕様・OOMKill 経緯など、いずれも「コードから復元不能」に該当する情報を含んでいたため、有用性ルールでは1行も消せなかった、と説明されています。
追うべき3指標
ここが計測設計の要点です。コメント比率は散発 WHAT コメントの削減を拾えますが、長い WHY ブロックや長い説明段落の体感負荷は拾いにくい。
チーム指標には、少なくとも次をセットで入れます。
- 追加行に対するコメント比率
- 4行以上の連続コメントブロック数
- 最大連続コメント行数
コミュニティ側でも同型の指摘があります。#65961 の議論では、全行説明は不要で非自明制約に絞るべき、変更履歴型コメントや phase バナーはコードベースに残すべきでない、といった運用ルールが共有されています。比率改善を「効いた」と即断せず、次スプリントでブロック数を再集計する方が安全です。
WHYのみ・置き場所で切るコメント基準
判断軸を「有用か」から「そこが正しい置き場所か」へ移します。コードコメントに残すのは、非自明な WHY だけです。
書いてよいもの（WHY）
- 隠れた制約や workaround の理由
- 外部仕様、ハードウェア、upstream issue など耐久性のある原因
- 読み手が驚く挙動、units / boundary / nil の意味、ownership、invariant
書かないもの（禁止リスト）
- WHAT（コードを読めば分かる実況）
- 変更履歴（「旧実装では」「〜を追加した」「NEW / UPDATED / FIXED」）
- タスク ID だけの参照（必要な内容は本文に直書きする）
- チャット履歴や plan mode の phase バナー
置き場所の対応表
| 情報の種類 | コードコメント | より良い置き場所 |
|---|---|---|
| 非自明な WHY・制約 | ○ 短く残す | — |
| WHAT 実況 | × | コード自体 |
| 変更履歴・移行経緯 | × | git log / PR 説明 |
| タスク ID のみ | × | issue（必要内容はコメントへ昇格） |
| チャット / phase メモ | × | セッションログ（永続化しない） |
| 長い手順・ドメイン知識 | ×（CLAUDE.md 肥大化） | skills / 条件付き rules |
この節の出典
CLAUDE.md への写像
CLAUDE.md への写像も同じ軸です。Qiita の整理 は、「これを削除すると Claude がミスするか？」を1行テストにし、推測不能な Bash・固有決定・落とし穴だけを残すよう勧めています。
公式の memory docs は、各 CLAUDE.md を200行未満に保ち、長い手順は skills や path-scoped rules へ移すよう勧めています。CLAUDE.md はコンテキストに読み込まれる指示であり、ハードな強制設定ではありません。コメント生成を確実に止める境界が必要なら、PreToolUse hook などの検査・拒否を使います。コメント規約と CLAUDE.md 規約は別物ではなく、同じ keep/drop テストで管理できます。
公開実装例（禁止語の固定）
公開実装例として、KyleOndy の Claude Code skill は次を明文化しています。
- デフォルト no comments
- 状態を述べ、遷移を述べない
- 制約は編集経緯ではなく durable cause
禁止リストを文章の雰囲気ではなく、具体語（NEW: / no longer / phase banner など）で固定すると、エージェントが守りやすくなります。
導入チェックリスト：ルール・フック・レビュー観点
文章ルールだけでは不十分です。禁止リスト、計測、自動フック、diff レビューをセットにします。
ルールと自動化
- グローバルまたはリポジトリの
CLAUDE.mdに、「WHY のみ / WHAT・履歴・タスクID禁止」を名指しで書く。表形式の曖昧な方針より、禁止語リストを優先する。 - 実際に出た違反（履歴コメント、phase 参照、丁寧な長段落置換）を項目として追記する。
- PostToolUse などで comment density lint を入れる。言語別 ceiling を超えたら削除パスを再実行する。書いたモデルに「多すぎ？」と聞く正当化ループは避ける（KyleOndy が #61305 を踏まえて注意している点）。
/code:comments相当の cleanup を用意する。Pass1 で叙述削除、Pass2 で編集叙述を現在理由へ変換、Pass3 で欠落 WHY のみ追加。実行コード変更は revert する。
計測と人間レビュー
- PR マージ前後で測る。コメント比率に加え、4行以上ブロック数と最大行数を必須にする。
- 人間レビューの観点に、unrequested comment rewrites を入れる（explainx のチェックリスト）。
- 不確実さはコメント分量で隠さず、PR description や回答本文で「未確認」と明示する。
採用時の注意
ルール追加直後の体感判断は誤りやすいです。比率が下がってもブロック数が残るなら、レビュー負荷はほぼ変わっていない可能性があります。
次のスプリントで同じ指標を再集計し、禁止リストの穴（新しい定型句）だけを更新する運用が現実的です。
筆者の観点
著者本人の個別運用ログは本記事では使いません。公開ソースから見える実務判断だけを整理します。
- 「丁寧なコメントが多い PR」を品質の代理指標にしない。context 消費とレビュー停止時間の方が先に効く。
- ルール文章の追加だけで安心しない。禁止リスト、密度フック、ブロック数計測、diff 観点の4点が揃って初めて再現性が出る。
CLAUDE.mdとコードコメントは別問題に見えて、keep/drop テストは同じ。片方だけ痩せていても、もう片方が肥大すれば同じ失敗が起きる。- 長い WHY が本当に必要なら残してよい。消すべきなのは、履歴・実況・依頼されていない言い換えである。
よくある質問（FAQ）
Q1. CLAUDE.md に「コメントを減らして」と書けば十分ですか？
不十分なことが多いです。#65961 は、必須ルールや memory でも冗長コメントが続くと報告しています。
禁止リスト、hooks、計測をセットにしてください。
Q2. 「コードから復元できない情報」ルールだけでもよいですか？
比率は下がっても、長い有用ブロックは残り得ます（UZU 計測では 52→50）。
置き場所基準と履歴禁止を追加してください。
Q3. 公式ドキュメントはコードコメントについて何と言っていますか？
コードコメント専用の章ではありません。公式の memory docs は、コンテキストを圧迫する長文を避け、各 CLAUDE.md を200行未満にし、長い手順を skills や path-scoped rules へ分けるよう説明しています。これは行動の助言であり、強制には PreToolUse hook など別の制御が必要です。
AI 向け長文全般に適用できます。
Q4. レビューでどこを見ればよいですか？
次を重点的に見ます。
- 依頼していない comment rewrite
- chat/phase 参照
- NEW/旧実装叙述
- タスクIDだけの行
explainx の diff チェックと #65961 の追記が観点になります。
Q5. 計測はどの数字を追うべきですか？
コメント比率に加え、4行以上ブロック数と最大連続行数です。
比率だけだと体感改善を取り違えます。
関連記事:
まとめ
- 長い AI コメントは丁寧さの証拠ではなく、context とレビューを削るコストになりやすい。
- 公式は context 劣化と over-specified 指示の失敗を警告し、コミュニティはデフォルト冗長と rules 無効化を継続報告している。
- 有用性ルールだけでは長いブロックは消えない。置き場所（WHY vs git/PR）と禁止リストで切る。
- 導入はルール文章で終わらせず、density hook・cleanup・ブロック数計測・diff レビューまでセットにする。
次アクション
- 今週マージする PR で、コメント比率・4行以上ブロック数・最大行数のベースラインを取る。
CLAUDE.mdに WHY のみ／禁止リストを1節で固定する。- 1週間後に同じ3指標で再計測し、残った定型句だけ禁止リストへ追加する。
著者
krona23
IT業界20年以上の実務経験を持ち、日本国内有数のPVを誇る大規模Webサービスで事業部長・CTOを複数社で歴任。Windows/iOS/Android/Webと技術の変遷を経験し、現在はAIネイティブへの変革に注力。DevGENTでは、AIコードエディタ・自動化ツール・LLMの実践的な使い方を日英西3言語で発信中。
コメントを残す