| name | comment-annotator |
| context | fork |
| description | コード変更に対して永続的なコメント（Why・制約・境界条件）を自動付与する。差分の依存グラフを解析し、2パス処理（意図マップ構築→役割別コメント生成）でレビュアーと将来の開発者の理解を助ける。「コメントを付けて」「アノテーションして」「レビューしやすくして」「comment annotation」と言われた時に使用する。 |
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
- 引数があればそれを使用
- 引数なし:
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段階の呼び出し元 + 関連テスト
手順:
- 各変更ファイルのimport/require文を解析
- 変更されたexportシンボル（関数、クラス、型）を抽出
- それらシンボルの呼び出し元を検出（1段階のみ）
- 対応するテストファイルを検出
呼び出し元検出の注意:
- 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説明文に記載がある場合のみ参照
- 推測（「おそらく〜」「〜かもしれない」）はコメントにしない
- 根拠が不十分ならコメント自体を省略する
処理順序
- テスト → 意図の確認
- エントリポイント / コントローラー / ミドルウェア → 全体フローの理解
- サービス / ドメイン / ワーカー → コアロジック
- リポジトリ / ユーティリティ / マイグレーション → 実装詳細
- 設定 / UI / インフラ → 環境・表示
役割別コメント戦略
各役割で焦点を変える。コードの翻訳は書かない。
| 役割 | コメントの焦点 |
|---|
| entry / controller | この要求が何を達成するか、責務の切り替え点 |
| middleware | 適用条件、順序依存、スキップ条件 |
| service | 処理順序の理由、トランザクション境界、再試行・冪等性の前提 |
| domain | 不変条件、状態遷移ルール、禁止される状態 |
| repository | クエリの意図、パフォーマンス特性、障害時の挙動 |
| worker | 実行頻度、リトライ戦略、冪等性、障害復旧 |
| migration | 可逆性、データ変換ルール、ロック・ダウンタイムの有無 |
| utility | 境界条件、暗黙の前提、スレッドセーフ性 |
| config | 環境差異、変更時の影響範囲 |
| infra | 依存関係、実行順序、環境前提 |
| ui | 状態管理、ユーザー操作フロー、アクセシビリティ |
| test | 検証するシナリオ、何を保証し何を保証しないか、回帰防止の対象 |
コメントの書き方ルール
- Why を書く — 「なぜこのコードがこうなっているか」をコードから読み取って言語化する
- 制約を書く — コードに表れている不変条件、前提条件を明示する
- 参照リンク — コミットメッセージやPR説明文に記載がある場合のみ含める
- 既存コメントとの整合 — コードと既存コメントが矛盾する場合、コードが正。既存コメントを更新する
- コメント記法 — 対象言語の標準的なコメント記法を使う。特殊なプレフィックスは付けない
コメント配置ルール
- 関数・メソッド単位の説明 → 関数宣言の直上に通常コメントで記述。デコレータ・属性・アノテーションがある場合はそのまとまり全体の直上に置く。doc commentは外部公開APIの契約情報にのみ使い、内部実装の判断理由はdoc commentに入れない
- ロジック内の判断理由 → 該当コード行の直上
- ファイル全体の役割 → 既存の先頭特殊行（シェバング、エンコーディング宣言、ライセンスヘッダー、言語ディレクティブ）の後ろに配置
- 条件分岐の中 → 分岐条件の直上に理由を書く。分岐本体の中には原則書かない
- コメントは説明対象のコードに密着させる。離れた場所に置かない
既存コメントとの共存
- 対象ファイルの既存コメントを読み、重複するコメントは書かない
- 既存コメントがコードの現状と矛盾していれば更新する
- 人間が書いたコメントの意図を尊重し、表現を大きく変えない
各ファイル処理時の入力
ファイル処理時にコンテキストとして渡す情報:
- 差分（何が変わったかの把握）
- 変更ハンク周辺のコード + 対象シンボル定義 + 既存コメント近傍（全文は大きいファイルでは不要。必要時のみ読む）
- 変更意図の要約（Pass 1.4から）
- このファイルが使う/使われるシンボルカード（Pass 1.3から）
- ファイルの役割（Pass 1.1から）
Finalize
整合性チェック
- 用語の揺れ — 同じ概念に異なる用語を使っていないか
- 重複 — 複数ファイルで同じ内容を繰り返していないか（共通部分は最も関連の深いファイルに集約）
- 密度 — コメント過多になっていないか
コメント密度ガイド
- 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以上の場合:
- 変更をサブグラフに分割（各サブグラフ = 起点ファイル + 関連依存 + テスト）
- サブグラフごとにPass 1→Pass 2を実行
- 最後にFinalize で全体の整合性チェック
Reference
| Reference | Purpose |
|---|
| references/comment-templates.md | 役割別の具体的なコメント例集（例文が必要な時に参照） |
