はじめに
前回の記事では、コメントについて異なる考え方を持つ『Clean Code』と『A Philosophy of Software Design』の著者2人（UB・John）の論争についてみて、コメントの価値の判断基準を考えました。
前回は、「コメントの読者は人間である」ことが前提でしが、いまはLLM（ClaudeやChatGPTの中身にあたる大規模言語モデル）もコードとコメントを読みます。
この記事では以下を扱います。
- コメントは、LLMのコード理解を助けるのか
- 腐ったコメントは、LLMに何をするのか
- AI向けの設定ファイル（AGENTS.md / CLAUDE.md）には何を書くべきか
- 腐ったコメントの検出は、AIに任せられるのか
コメントはLLMの理解を助けるのか
コメントがLLMの理解を助けるかどうかを、直接測った研究があります。
効果を示す研究
MITREの研究（2025）
Claude 3・GPT-4・Llama 3・Mixtralの4モデルに対して、コメントの有無でレガシーコードの理解度がどう変わるかをクイズ形式で測定した研究。
基礎クイズでコメントあり96%・なし84%と、コメントがあるほうが正答率が高くなった（応用クイズではあり90%・なし84%。著者ら自身が「予備的な結果」としている）。
バグ自動修正の研究（ICPC 2026）
学習時と推論時の両方でコメントが与えられた場合に、LLMによるバグ自動修正の精度が最大3倍改善したと報告している。
効果を示さない研究
RepoQA（2024）
リポジトリの大量のコードをLLMに読ませて、「この説明に当てはまる関数はどれか」を探し出させるテスト。
コメントを削除したコードのほうがスコアの上がるモデルが多く見られた。論文も「モデルはコメントなしのほうがコードをよく理解できるかもしれない」と報告している。
13モデルの比較研究（2025）
汎用モデルとコード特化型モデルの計13種類に、同じコードをコメントあり・なしで読ませて、理解の成績を比較した研究。
コメントによる改善は平均+3.7%で、統計的に有意な差ではなかった。CodeLlamaなど、コードに特化したモデルに限れば、コメントなしのほうが好成績だった。
まとめると以下のようになります。
| 条件 | コメントの効果 |
|---|---|
| レガシーコードの理解 | 助ける |
| バグ自動修正 | 助ける |
| リポジトリ規模のコード検索・理解 | むしろ邪魔 |
| 13モデルでの比較 | 有意差なし。一部のモデルはコメントなしが上 |
前回の記事で紹介した人間相手の実験と同じように、読者をLLMに替えても効果は割れています。
MITREの研究（2025）
正確なコメント付きで平均73%だった理解度は、コメントをコードと無関係な説明文に全て差し替えると、61%まで下がった（対象はタイマー処理のコードなのに、バスケットボールの試合をシミュレーションするプログラムの説明文を付けた）。コメント欄に嘘があると、コードそのものの読解まで悪化する。
ただし、「コメントの20%だけを不正確に差し替える」という現実的な腐り方では、影響はほぼ出なかった。
Comment Traps（FSE 2026）
GitHub CopilotとCursorに対して、コンテキスト中に欠陥を含むコメントアウトされたコード（削除されず、コメントアウトのまま残された古いコード）が混ざっていると、生成されるコードの欠陥率が最大58.17%に達した。
自然言語のコメントではなくコメントアウトされたコードの話だが、「コメント欄に放置された古い情報が、新しいコードに欠陥を持ち込む」という点で、コメントの腐敗と同じ問題を持っている。
不整合コミットの分析（2024）
OSSのコミット履歴を調べた研究。コードを変更したのにコメントを直さないなど、コードとコメントの食い違いを作った変更は、そうでない変更に比べて、7日以内にバグの持ち込みにつながる確率が約1.5倍だった。
これらのデータは、UBとJohnのどちらの主張も支えます。
- John（書くべき）: コメントはLLMのレガシーコード理解を助ける
- UB（腐ったコメントは害）: コメント欄の嘘や、コメントアウトのまま残された古いコードは、LLMの読解と生成を悪化させる
人間は怪しいコメントを無視して読めますが、LLMはコンテキストに入ったものを無視できません。AIの登場は、「良いコメントを書く」と「腐らせない」の両方がより大事になったと思います。
AGENTS.md とコメント論争の共通点
2025年、AGENTS.md という共通フォーマットが公開されました。リポジトリ直下に置く、コーディングエージェント向けの説明ファイルで、公式サイトは「エージェントのためのREADME」と説明しています。
OpenAI（Codex）・Google（Jules）・Cursorなどのエージェント開発元が関わり、同年12月には管理がLinux Foundation傘下のAgentic AI Foundationへ移り、その時点で60,000以上のOSSリポジトリで使われていました。
すべてのツールがこのフォーマットを使うわけではなく、Claude Code の CLAUDE.md のように独自のファイルを使うツールもありますが、役割は同じです。
では、この種のファイルには何を書くべきなのでしょうか。また、AIにはどんなコメントを書かせるべきなのでしょうか。それぞれにガイドラインがあります。
- Anthropicのガイドライン（CLAUDE.mdに何を書くか）：コードから推測できないことを書く。例として、推測できないビルドコマンドや、デフォルトから外れたコードスタイルのルール。逆に "write clean code" のような自明な指示は書かない
-
GitHubの
awesome-copilot（AIにコメントをどう書かせるか）：「WHYを説明するのに必要なときだけコメントする。WHATを説明しない」。避ける例として// Increment counter by oneを挙げている
この2つは、前回の記事で見た判定基準と同じです。
| AI向けガイドライン | 前回の記事の判定基準 |
|---|---|
| コードから推測できないことを書く（Anthropic） | Don't repeat the code（John） |
| WHYを書き、WHATを書かない（GitHub） | What ではなく Why を書く（Google） |
私たちは「コードを読めば分かることを書かない。コードに載せようがないことを書く」という考え方を、AI向け設定ファイルという形でもう一度学び直しています。
そして、前回の記事の判定基準の一つ「腐るかどうか」は、AGENTS.mdやCLAUDE.mdの1行1行にも当てはまります。たとえばCLAUDE.mdに書いたビルドコマンドは、プロジェクト側でコマンドが変わっても自動では更新されず、放置すればコードと食い違った古い情報になります。これはコメントの腐敗と同じ構造です。しかも、その古くなったCLAUDE.mdを読むのは、腐った情報を無視できないLLMです。
腐ったコメントの検出はAIに任せられるか
コメントが腐るのが問題なら、腐ったコメントを見つける作業をAIに任せることはできないのでしょうか。
実際、コードとコメントの不整合を検出する研究は活発です。C4RLLaMA（ICSE 2025）は、従来ツールのDocCheckerがF1スコア74.3%だった同じ評価条件で89.0%を達成し、CCISolver（2025）は別の評価データで89.54%を報告しています。
一部のプログラミング言語は、コメントを腐らせない仕組みを持っています。RustやPythonのdoctestは、コメント内に書いた使用例のコードを実際に実行して、書かれた通りの結果になるかを確かめます。実装が変わって使用例が古くなると、テストが落ちて気付けます。
ただし、doctestが守れるのはコード例までで、「この値はミリ秒単位」のような文章のコメントがコードとズレても検出できません。
C4RLLaMAやCCISolverが検出しているのは、「文章のコメントとコードのズレ」です。doctestが守れなかった範囲も、その仕組みで守れるようになるかもしれません。
まとめ
- コメントがLLMの理解を助けるかは、研究によって結果が割れている
- 腐ったコメントの害は、LLMの読解と生成の両方で測定されている
- AGENTS.md / CLAUDE.md に書くべきものは、前回の記事の判定基準と同じ
参考