# Comment Annotator

> コード変更に対して永続的なコメント（Why・制約・境界条件）を自動付与する。差分の依存グラフを解析し、2パス処理（意図マップ構築→役割別コメント生成）でレビュアーと将来の開発者の理解を助ける。「コメントを付けて」「アノテーションして」「レビューしやすくして」「comment annotation」と言われた時に使用する。

- Skill: `caphtech/comment-annotator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add caphtech/comment-annotator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/caphtech/comment-annotator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: CAPHTECH (https://skillmd.com/u/caphtech)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/caphtech/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 ツールで各ファイルにコメントを挿入する。変更完了後に以下のサマリを出力:

```markdown
## 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 | 役割別の具体的なコメント例集（例文が必要な時に参照） |