AI Code Review

AIコードレビュースキル

指定されたPull Requestを体系的にレビューし、レビュー結果をPRコメントとして投稿するスキルです。レビュー指摘は人間向けとAI向けの2パターンで併記します。初回レビューだけでなく、修正後の再レビューにも対応します。6つの観点でPRの品質を多角的に検証します。

重要な原則

+---------------------------------------------------------------+
| レビューの鉄則                                                  |
+---------------------------------------------------------------+
| 1. 推測でレビューしない - 必ずコードを読んで根拠を示す              |
| 2. 6つの観点を漏れなくチェックする                                |
| 3. 指摘には必ず根拠（該当コード・行番号）を添える                   |
| 4. 数値・事実を根拠にする場合は必ずソースを確認する                  |
| 5. 人間向けとAI向けの2形式で指摘を書く                            |
| 6. 重大度を正確に分類し、過剰な指摘を避ける                        |
| 7. 再レビュー時は前回指摘の修正確認を必ず行う                      |
+---------------------------------------------------------------+

レビュー観点（6つ）

カテゴリの細分類

指摘のcategoryフィールドには、6観点に加えてサブカテゴリを使用できる。適切なサブカテゴリがある場合はそちらを使用すること。

docs-drift と internal-consistency の使い分け:

• ファイルAの内容がファイルBと矛盾 → docs-drift
• 同一ファイル内でステータスが「SKIP」なのに受入基準が「[x]完了」→ internal-consistency
• 同一ファイル内で記載された数値が実態と不一致 → internal-consistency

各観点の詳細: references/review_guide_ja.md

このスキルを使用する場面

初回レビュー

• PRが作成され、コードレビューを依頼された場合
• 自分のPRをセルフレビューしたい場合
• マージ前のセキュリティ・品質チェックを行いたい場合

再レビュー（修正後の確認）

• 初回レビューの指摘を受けて修正が行われた場合
• 追加コミットが積まれたPRの差分を確認したい場合

再レビューの詳細: references/rereview_guide_ja.md

ワークフロー概要

初回レビュー

PR URLまたは番号を受け取る
      |
1. PR情報の取得（diff、説明文、関連ファイル一覧）
      |
2. 変更ファイルの分類と優先度付け
      |
3. 6観点でのレビュー実行
   a. セキュリティ
   b. ドキュメントとの乖離
   c. 可読性・複雑度
   d. ライブラリ選定の妥当性
   e. PR説明の適切性
   f. 既知脆弱性の検出
      |
3.5. PR内横断チェック（同一パターンの問題を他ファイルでも確認）
      |
4. 指摘の重大度分類と整理
      |
5. ★ レビュー結果の承認確認 ★（必須ゲート）
   - レビューサマリーをユーザーに提示
   - AskUserQuestionでレビュー結果投稿の承認を確認
      |
6. PRコメントの作成・投稿
   - サマリーコメント（PR全体）
   - インラインコメント（個別指摘）

再レビュー

PR URLまたは番号 + 再レビュー指示を受け取る
      |
1. PR情報の取得（最新diff、前回レビューコメント）
      |
2. 前回指摘の修正確認
   a. 各指摘に対する修正状況を確認
   b. 修正済み / 未修正 / 部分修正を分類
      |
3. 新規変更に対する6観点レビュー
   a. セキュリティ
   b. ドキュメントとの乖離
   c. 可読性・複雑度
   d. ライブラリ選定の妥当性
   e. PR説明の適切性
   f. 既知脆弱性の検出
      |
3.5. PR内横断チェック（同一パターンの問題を他ファイルでも確認）
      |
4. 指摘の重大度分類と整理（前回指摘の修正状況を含む）
      |
5. ★ レビュー結果の承認確認 ★（必須ゲート）
   - レビューサマリーをユーザーに提示
   - AskUserQuestionでレビュー結果投稿の承認を確認
      |
6. PRコメントの作成・投稿
   - 前回指摘の修正状況サマリー
   - 新規指摘（サマリー + インライン）

各ステップの詳細

ステップ1: PR情報の取得

gh CLIを使用してPR情報を取得する。

# PR差分の取得
gh pr diff <PR番号>

# PR詳細の取得
gh pr view <PR番号>

# PRの変更ファイル一覧
gh pr diff <PR番号> --name-only

# 前回のレビューコメント取得（再レビュー時）
gh api repos/{owner}/{repo}/pulls/{PR番号}/reviews
gh api repos/{owner}/{repo}/pulls/{PR番号}/comments

ステップ2: 変更ファイルの分類

変更されたファイルをカテゴリに分類し、レビュー優先度を決定する。

ステップ3: 6観点でのレビュー実行

各観点で変更コードを精査する。指摘はすべて以下の情報を含むこと:

重大度の定義:

ステップ3.5: PR内横断チェック

指摘事項が見つかった場合、同一PR内の他のファイル・コミットにも同様の問題がないか横断的に確認する。

指摘を発見した場合の横断チェック手順:
1. 指摘のパターンを抽出する（例: 「不正確なテスト数の記載」）
2. PR内の全変更ファイルで同様のパターンを検索する
3. 別コミットで追加された関連ファイルも確認対象に含める
4. 同一パターンの問題が複数見つかった場合はまとめて指摘する

例: TASK-002のサマリーで「全31テスト」を指摘した場合、同じPR内のTASK-001の完了サマリー（別コミット）にも同様の表現がないか確認する。

ステップ4: 指摘の整理

• 重大度の高い順にソート
• 同一ファイル内の指摘はまとめる
• 重複する指摘は統合
• 過度に些細な指摘（nitpick）が多い場合は厳選する

ステップ5: レビュー結果の承認確認（必須ゲート）

PRコメントを投稿する前に、必ずユーザーの承認を得ること。

レビュー結果が確定したら、PRへの投稿前にレビューサマリーをユーザーに提示し、AskUserQuestionツールを使って投稿の承認を確認する。

手順

1. レビュー結果のサマリーをユーザーに出力する:

   • 総合判定（Approve / Request Changes / Comment）
   • 指摘件数の内訳（critical / warning / suggestion / nitpick）
   • 主要な指摘事項の概要（再レビュー時は前回指摘の修正状況も含む）

2. AskUserQuestionツールで投稿承認を確認する:

AskUserQuestion:
  question: "上記のレビュー結果をPRに投稿してよろしいですか？"
  options:
    - label: "投稿する"
      description: "レビュー結果をPRコメントとして投稿します"
    - label: "修正してから投稿"
      description: "レビュー内容を修正してから投稿します"
    - label: "投稿しない"
      description: "レビュー結果の投稿を中止します"

3. ユーザーの回答に応じて対応する:
   • 「投稿する」: ステップ6に進み、PRコメントを投稿する
   • 「修正してから投稿」: ユーザーの指示に従いレビュー内容を修正し、再度承認を確認する
   • 「投稿しない」: 投稿を中止し、レビュー結果はローカルでの参照のみとする

+---------------------------------------------------------------+
| 重要: この承認確認は省略できない                                   |
+---------------------------------------------------------------+
| - Approve / Request Changes / Comment いずれの判定でも必須       |
| - ユーザーの承認なしにPRコメントを投稿してはならない                 |
| - 承認確認前にレビューサマリーの全体像を必ず提示すること              |
+---------------------------------------------------------------+

+---------------------------------------------------------------+
| 投稿時の注意事項                                                 |
+---------------------------------------------------------------+
| - 自身のPRには APPROVE / REQUEST_CHANGES を付与できない           |
|   → 自身のPRの場合は event を "COMMENT" にフォールバックする      |
| - commit_id は gh pr view --json headRefOid で取得する          |
| - body やコメントに JSON コードブロック・特殊文字を含む場合、      |
|   -f フラグではエスケープ問題が発生しやすいため                   |
|   --input による JSON ファイル入力を使用する                      |
+---------------------------------------------------------------+

ステップ6: PRコメントの投稿

サマリーコメント（PR全体に投稿）

PRのレビュー結果の全体像をサマリーコメントとして投稿する。

コメントテンプレート: assets/templates/review_comment_template_ja.md

インラインコメント（個別指摘）

各指摘は該当コードの行にインラインコメントとして投稿する。

投稿方法:

# 1. commit SHA を取得
COMMIT_SHA=$(gh pr view <PR番号> --json headRefOid --jq '.headRefOid')

# 2. JSONファイルにレビュー内容を書き出す（Write ツール推奨）
# /tmp/review_body.json に以下の構造で書き出す:
# {
#   "commit_id": "<COMMIT_SHA>",
#   "event": "APPROVE | REQUEST_CHANGES | COMMENT",
#   "body": "レビュー本文（任意）",
#   "comments": [
#     {
#       "path": "src/example.ts",
#       "line": 42,
#       "body": "インラインコメント本文"
#     }
#   ]
# }
# ※ 自身のPRの場合は event を "COMMENT" にフォールバックすること

# 3. 投稿
gh api repos/{owner}/{repo}/pulls/{PR番号}/reviews \
  --method POST --input /tmp/review_body.json

指摘の2形式（人間向け・AI向け）

すべてのレビュー指摘は、以下の2形式を併記する。情報の重複を避け、それぞれの形式が固有の価値を持つように分離する。

人間向け形式（概要・判定に集中）

• 問題の概要と推奨修正方針を簡潔に記載
• なぜ修正すべきかの文脈を提供
• 詳細なコード差分はAI向けJSONに集約し、人間向けには記載しない
• サマリーではcritical/warningの指摘タイトルとファイル名のみ列挙（suggestion/nitpickはインラインコメントのみ）

AI向け形式（機械的修正を可能にする構造化データ）

• JSON形式で全指摘を構造化
• fix.old_text / fix.new_text: Editツールにそのまま渡せる置換テキストペア
• fix_strategy: 修正方針の提案（推奨アプローチ、代替案、影響範囲、規模感を構造化して提示）
• context: 該当行の前後約3行のコード断片（行番号のズレがあっても位置特定可能）
• scope: 本PRで修正すべきか後続対応かの判定（fix-in-this-pr / fix-in-follow-up / wont-fix）
• rule: 関連ルール・パターン名

指摘コメントの書き方

個別の指摘コメント（インラインコメント）は以下の形式で書く:

**[重大度]** 観点名

問題の概要と修正方針を簡潔に説明する。
（詳細なコード差分はAI向けJSONに記載するため、ここでは重複させない）

<details>
<summary>AI向け指示</summary>

```json
{
  "id": "F-001",
  "file": "ファイルパス",
  "line": "[行番号]",
  "severity": "critical | warning | suggestion | nitpick",
  "category": "security | iam-permissions | docs-drift | internal-consistency | readability | library | pr-description | known-vulnerability",
  "title": "問題の端的な説明",
  "fix": {
    "old_text": "置換対象のコードテキスト",
    "new_text": "置換後のコードテキスト",
    "description": "補足説明（任意）"
  },
  "fix_strategy": {
    "approach": "推奨する修正アプローチの説明",
    "alternatives": ["代替案1の説明", "代替案2の説明"],
    "impact": "修正による影響範囲（他ファイル、依存コンポーネント等）",
    "effort": "small | medium | large"
  },
  "context": "該当行の前後3行程度のコード断片",
  "scope": "fix-in-this-pr | fix-in-follow-up | wont-fix",
  "rule": "関連するルールやパターン名（例: OWASP-A03, SRP, etc.）",
  "verification_hint": "修正後に確認すべきチェックポイント（例: 関連ファイルとの整合性確認）"
}

fix_strategy の書き方:

• approach: 推奨する修正アプローチを具体的に記載する。fix.old_text/fix.new_textが単純な置換で済む場合でも、修正の意図・方針を明記する
• alternatives: 代替案がある場合に記載する。トレードオフ（パフォーマンス、可読性、互換性等）を簡潔に添える。代替案がない場合は空配列 []
• impact: 修正が他のファイルやコンポーネントに波及する場合、その範囲を記載する。影響がない場合は "なし"
• effort: 修正の規模感。small（1ファイル内の軽微な変更）、medium（複数ファイルにまたがる変更）、large（設計変更を伴う大規模な変更）
• 例:

{
  "approach": "文字列結合をパラメータ化クエリに置換する。プロジェクト内の既存パターン（src/repositories/baseRepository.ts）に合わせる",
  "alternatives": [
    "ORMのクエリビルダーを使用する方法もあるが、現在のプロジェクトでは生SQLを使用する方針"
  ],
  "impact": "同リポジトリ内の他のRepository（orderRepository.ts, productRepository.ts）にも同様の文字列結合パターンがある可能性",
  "effort": "medium"
}

verification_hint の書き方:

• 修正Claudeが修正後に確認すべき具体的なチェックポイントを記載する
• 関連ファイルとの整合性、同一PR内の類似箇所、上位ドキュメントとの一貫性など
• 例: 「修正後、index.mdのTASK-007のステータスとも整合しているか確認」
• 例: 「同じPR内のTASK-001完了サマリーにも同様の表現がないか確認」

再レビュー時の追加手順

再レビュー時は、通常の6観点レビューに加えて以下を行う。

前回指摘の修正確認

1. 前回のレビューコメントをすべて取得
2. 各指摘について修正状況を確認:

3. 修正状況をサマリーコメントに含める

再レビューサマリーの形式

## 再レビュー結果

### 前回指摘の修正状況

| # | 指摘内容 | 重大度 | 状態 | コメント |
|---|---------|--------|------|---------|
| 1 | [指摘概要] | critical | resolved | 適切に修正済み |
| 2 | [指摘概要] | warning | unresolved | 未修正 - 対応をお願いします |

- resolved: X件
- partially-resolved: X件
- unresolved: X件

### 新規指摘

（通常の6観点レビュー結果）

再レビューの詳細: references/rereview_guide_ja.md

禁止事項

- 推測に基づくレビュー（コードを読まずに指摘する）
- 個人の好みだけを根拠にした指摘（明確な理由なしの「こう書くべき」）
- 裏取りなしに数値・事実を断定する指摘（例: 「テスト数は243件」と述べる前に
  実際のテスト数をカウントする。不確実な場合は「〜の可能性がある」と表現する）
- 変更範囲外のコードへの指摘（ただしセキュリティ問題は例外）
- 過剰な nitpick（レビュー全体が些細な指摘で埋まる状態）
- 人間向け・AI向けのどちらか一方だけの記載
- 再レビュー時に前回指摘の修正確認を省略すること
- ユーザーの承認なしにPRコメントを投稿すること（承認確認ゲートの省略）

エージェントチームによる並列レビュー（条件を満たす場合は使用）

適用条件

1. 変更ファイル数が10以上
2. 変更が3つ以上の独立したモジュール/ディレクトリにまたがる
3. 各モジュールの変更が独立してレビュー可能

チーム構成例

チームリーダー（レビュー統合・サマリー作成に専念）
    |
    +-- レビュアーA: セキュリティ・既知脆弱性観点担当
    |   - コードのセキュリティ問題（認証・認可、入力検証、秘密情報管理）と
    |     依存パッケージの既知脆弱性（CVE）を一貫してチェック
    |   - 両観点を同一レビュアーが担当することで、コード側の脆弱性と
    |     依存パッケージ側の脆弱性を統合的に評価できる
    |
    +-- レビュアーB: 可読性・複雑度観点担当
    |   - 命名、関数長、ネスト、複雑度を集中チェック
    |
    +-- レビュアーC: ドキュメント乖離・ライブラリ・PR説明観点担当
        - 仕様との整合性、依存関係の妥当性、PRタイトル・説明文の適切性を集中チェック

リソース