comment-annotator

Review Comment Annotator

コード変更に永続的なコメントを付与する。レビュアーと将来の開発者が「なぜこのコードがこうなっているか」を理解できる状態を作る。

コメントの根拠は現在のコードとテストが主軸。PR説明文やコミットメッセージは補助情報として使う。

Target Resolution → Pass 1: Intent Map → Pass 2: Role-Based Comments → Finalize

Target Resolution

Supported Targets

• PR: #123
• Branch diff: main..feature/xxx
• Specific files: src/auth/handler.ts src/auth/types.ts
• No argument: auto-detect (current branch vs base)

Resolution Logic

1. 引数があればそれを使用
2. 引数なし:
   • git branch --show-current で現在のブランチ取得
   • base branch検出（main, master, develop の順）
   • コミット済み差分: git diff <base>...HEAD
   • 未コミット変更: git diff + git diff --cached
   • 両方をマージして変更ファイル一覧を取得

除外ファイル

以下のファイルはコメント対象外:

• ロックファイル（package-lock.json, yarn.lock, Gemfile.lock, Cargo.lock 等）
• 自動生成ファイル（generated, auto-generated 等のマーカーを含む）
• vendorディレクトリ配下
• スナップショットファイル（.snap, snapshots）
• コメント記法が存在しない形式（JSON 等）

---

Pass 1: Intent Map 構築

変更の全体像を軽量に把握する。コメントはまだ書かない。

1.1 変更ファイルの役割分類

各変更ファイルを以下のいずれかに分類:

役割	判定基準
entry	ルーティング定義、main関数、CLI entrypoint
controller	HTTPハンドラ、RPCハンドラ、イベントハンドラ
middleware	認証・認可・ロギング・エラーハンドリング等の横断的関心事
service	ビジネスロジック、オーケストレーション
domain	エンティティ、値オブジェクト、型定義
repository	DB/外部API/ファイルI/Oアクセス
worker	バックグラウンドジョブ、キュー消費、定期タスク
migration	DBマイグレーション、データ変換スクリプト
utility	汎用ヘルパー、共通関数
config	設定、定数、環境変数
infra	CI/CD、Dockerfile、IaC、ビルド設定
ui	UIコンポーネント、テンプレート、スタイル
test	テストファイル

言語・フレームワーク固有のパターンで判定する。複数の役割にまたがるファイルは主要な役割を選ぶ。

1.2 局所依存グラフの構築

変更ファイル + 1段階の依存先 + 1段階の呼び出し元 + 関連テスト

手順:

1. 各変更ファイルのimport/require文を解析
2. 変更されたexportシンボル（関数、クラス、型）を抽出
3. それらシンボルの呼び出し元を検出（1段階のみ）
4. 対応するテストファイルを検出

呼び出し元検出の注意:

• Grep による検出は別名import、再export、メソッド名衝突で誤検出し得る
• 疑わしい場合はファイルを読んで確認する

暗黙的依存のチェック:

• DI/サービスコンテナの登録ファイル
• イベント/メッセージのpublish-subscribe関係
• 設定ファイルによるルーティングやフィーチャーフラグ
• DBスキーマ/マイグレーションとモデルの関係

深掘り条件（2段階以上をたどる場合）:

• 公開API・インターフェース・型定義が変更されている
• 多数の呼び出し元を持つユーティリティが変更されている
• ドメインモデル・スキーマが変更されている

1.3 シンボルカード抽出

変更されたシンボルのうち、他ファイルから参照されるもの（公開シンボル）に限定して要約:

Symbol: functionName(args) -> returnType
Purpose: [1文]
Changed: [今回の変更内容]
Constraints: [前提条件・不変条件・副作用、なければ省略]

• 軽微な変更（リネーム、フォーマット、import追加のみ）のシンボルはスキップ
• 1ファイルあたりシンボルカードは最大10個。超える場合は変更の大きいものを優先

1.4 変更意図の要約

以下のソースから変更の目的を1-3文で要約:

• コードの構造変化（何が追加・削除・変更されたか）
• テストの追加・変更内容（何を守ろうとしているか）
• PR説明文 / コミットメッセージ（設計判断の背景、補助情報）

---

Pass 2: Role-Based Comment 生成

Pass 1 の意図マップを入力に、ファイルごとにコメントを付与する。

証拠ルール

コードとテストから読み取れる事実だけを書く。

• コメントの根拠は現在のコード・テスト・型定義が主軸
• PR説明文やコミットメッセージは補助的に使うが、コードと矛盾する場合はコードが正
• Issue番号やRFCはコミットメッセージやPR説明文に記載がある場合のみ参照
• 推測（「おそらく〜」「〜かもしれない」）はコメントにしない
• 根拠が不十分ならコメント自体を省略する

処理順序

1. テスト → 意図の確認
2. エントリポイント / コントローラー / ミドルウェア → 全体フローの理解
3. サービス / ドメイン / ワーカー → コアロジック
4. リポジトリ / ユーティリティ / マイグレーション → 実装詳細
5. 設定 / UI / インフラ → 環境・表示

役割別コメント戦略

各役割で焦点を変える。コードの翻訳は書かない。

役割	コメントの焦点
entry / controller	この要求が何を達成するか、責務の切り替え点
middleware	適用条件、順序依存、スキップ条件
service	処理順序の理由、トランザクション境界、再試行・冪等性の前提
domain	不変条件、状態遷移ルール、禁止される状態
repository	クエリの意図、パフォーマンス特性、障害時の挙動
worker	実行頻度、リトライ戦略、冪等性、障害復旧
migration	可逆性、データ変換ルール、ロック・ダウンタイムの有無
utility	境界条件、暗黙の前提、スレッドセーフ性
config	環境差異、変更時の影響範囲
infra	依存関係、実行順序、環境前提
ui	状態管理、ユーザー操作フロー、アクセシビリティ
test	検証するシナリオ、何を保証し何を保証しないか、回帰防止の対象

コメントの書き方ルール

1. Why を書く — 「なぜこのコードがこうなっているか」をコードから読み取って言語化する
2. 制約を書く — コードに表れている不変条件、前提条件を明示する
3. 参照リンク — コミットメッセージやPR説明文に記載がある場合のみ含める
4. 既存コメントとの整合 — コードと既存コメントが矛盾する場合、コードが正。既存コメントを更新する
5. コメント記法 — 対象言語の標準的なコメント記法を使う。特殊なプレフィックスは付けない

コメント配置ルール

• 関数・メソッド単位の説明 → 関数宣言の直上に通常コメントで記述。デコレータ・属性・アノテーションがある場合はそのまとまり全体の直上に置く。doc commentは外部公開APIの契約情報にのみ使い、内部実装の判断理由はdoc commentに入れない
• ロジック内の判断理由 → 該当コード行の直上
• ファイル全体の役割 → 既存の先頭特殊行（シェバング、エンコーディング宣言、ライセンスヘッダー、言語ディレクティブ）の後ろに配置
• 条件分岐の中 → 分岐条件の直上に理由を書く。分岐本体の中には原則書かない
• コメントは説明対象のコードに密着させる。離れた場所に置かない

既存コメントとの共存

• 対象ファイルの既存コメントを読み、重複するコメントは書かない
• 既存コメントがコードの現状と矛盾していれば更新する
• 人間が書いたコメントの意図を尊重し、表現を大きく変えない

各ファイル処理時の入力

ファイル処理時にコンテキストとして渡す情報:

1. 差分（何が変わったかの把握）
2. 変更ハンク周辺のコード + 対象シンボル定義 + 既存コメント近傍（全文は大きいファイルでは不要。必要時のみ読む）
3. 変更意図の要約（Pass 1.4から）
4. このファイルが使う/使われるシンボルカード（Pass 1.3から）
5. ファイルの役割（Pass 1.1から）

---

Finalize

整合性チェック

1. 用語の揺れ — 同じ概念に異なる用語を使っていないか
2. 重複 — 複数ファイルで同じ内容を繰り返していないか（共通部分は最も関連の深いファイルに集約）
3. 密度 — コメント過多になっていないか

コメント密度ガイド

• PR全体で最大20コメント程度を目安とする
• 自明なフォーマット変更、リネーム、import追加にはコメント不要
• 複雑なロジック変更には密に、単純な変更には疎に
• 密度が高すぎると感じたら、最も価値の高いものだけ残す

構文検証

コメント挿入後、以下を確認する:

• 対象言語のコメント記法が正しいか
• doc comment形式を使った場合、言語の規約に沿っているか
• 行長制限があるプロジェクトでは遵守しているか

出力

Edit ツールで各ファイルにコメントを挿入する。変更完了後に以下のサマリを出力:

## Review Annotation Summary

### 変更意図
[1-3文の要約]

### 注目ポイント
- [レビュアーが特に確認すべき箇所と理由]

### 追加・更新したコメント一覧
| ファイル:行 | 役割 | コメント内容 |
|------------|------|-------------|
| src/auth/handler.ts:42 | controller | [コメント本文] |
| src/auth/rate-limit.ts:15 | service | [コメント本文] |

---

大規模変更への対応

変更ファイルが20以上の場合:

1. 変更をサブグラフに分割（各サブグラフ = 起点ファイル + 関連依存 + テスト）
2. サブグラフごとにPass 1→Pass 2を実行
3. 最後にFinalize で全体の整合性チェック

---

Reference

Reference	Purpose
references/comment-templates.md	役割別の具体的なコメント例集（例文が必要な時に参照）