# AI Code Review

> 指定されたPRを6観点（セキュリティ、ドキュメント乖離、可読性、ライブラリ選定、PR説明、既知脆弱性）でレビューし、人間向け・AI向けの2形式でPRにコメントする。初回レビューおよび修正後の再レビューに使用する。Do NOT use for レビューコメントへの修正適用（pr-comment-fixerを使用すること）。

- Skill: `windschord/ai-code-review` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds add windschord/ai-code-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/windschord/ai-code-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: windschord (https://skillmd.com/u/windschord)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/windschord/ai-code-review

---


# AIコードレビュースキル

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

## 重要な原則

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

## レビュー観点（6つ）

| # | 観点 | 概要 |
|---|------|------|
| 1 | セキュリティ | OWASP Top 10、認証・認可、入力検証、秘密情報の漏洩、暗号化、Terraform IAM権限の過不足チェック |
| 2 | ドキュメントとの乖離 | README、API仕様書、設計書、コメントと実装の不一致 |
| 3 | 可読性・複雑度 | 命名、関数の長さ、ネスト深度、循環的複雑度、コード重複、SOLID原則 |
| 4 | ライブラリ選定の妥当性 | ライセンス、メンテナンス状況、セキュリティ履歴、サイズ、代替手段 |
| 5 | PR説明の適切性 | PRタイトル・説明文が変更内容を正確に反映しているか、レビュアーに十分な情報を提供しているか |
| 6 | 既知脆弱性の検出 | 使用ライブラリのバージョンにCVE等の既知脆弱性が報告されていないか、セキュリティアドバイザリへの対応状況 |

### カテゴリの細分類

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

| 観点 | category値 | 使い分け |
|------|-----------|---------|
| セキュリティ | `security` | セキュリティ全般 |
| セキュリティ | `iam-permissions` | Terraform IAM権限の過不足（公式ドキュメントとの照合） |
| ドキュメント乖離 | `docs-drift` | **異なるドキュメント間**（設計書↔実装、README↔コード等）の不一致 |
| ドキュメント乖離 | `internal-consistency` | **同一ファイル内**のステータス↔受入基準、数値↔実データ等の論理矛盾 |
| 可読性・複雑度 | `readability` | 可読性・複雑度全般 |
| ライブラリ選定 | `library` | ライブラリ選定全般 |
| PR説明の適切性 | `pr-description` | PRタイトル・説明文と変更内容の整合性 |
| 既知脆弱性の検出 | `known-vulnerability` | CVE・セキュリティアドバイザリに報告されたバージョンの使用 |

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

**各観点の詳細**: [references/review_guide_ja.md](references/review_guide_ja.md)

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

### 初回レビュー

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

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

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

**再レビューの詳細**: [references/rereview_guide_ja.md](references/rereview_guide_ja.md)

## ワークフロー概要

### 初回レビュー

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

### 再レビュー

```text
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情報を取得する。

```bash
# 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: 変更ファイルの分類

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

| 優先度 | カテゴリ | 例 |
|--------|---------|-----|
| 高 | セキュリティ関連 | 認証、認可、暗号化、入力処理、Terraform IAMポリシー |
| 高 | API / データベース | エンドポイント、マイグレーション、スキーマ |
| 中 | ビジネスロジック | ドメインロジック、サービス層 |
| 中 | 設定・インフラ | CI/CD、Docker、依存関係 |
| 低 | UI/表示 | テンプレート、スタイルシート |
| 低 | テスト | テストコード（ただしセキュリティテストは優先度高） |
| 低 | ドキュメント | README、コメント更新 |

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

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

| 項目 | 内容 |
|------|------|
| ファイル | 対象ファイルパス |
| 行番号 | 該当行（範囲も可） |
| 重大度 | critical / warning / suggestion / nitpick |
| 観点 | security / iam-permissions / docs-drift / internal-consistency / readability / library / pr-description / known-vulnerability （※`iam-permissions`は`security`のサブカテゴリ、`internal-consistency`は`docs-drift`のサブカテゴリ。詳細は[カテゴリの細分類](#カテゴリの細分類)参照） |
| 指摘内容 | 何が問題で、なぜ問題なのか |
| 推奨修正 | どう直すべきか |

**重大度の定義:**

| 重大度 | 意味 | マージ可否 |
|--------|------|-----------|
| critical | セキュリティ脆弱性、データ損失の可能性、本番障害のリスク | 修正必須 |
| warning | バグの可能性、パフォーマンス問題、設計上の懸念 | 修正推奨 |
| suggestion | より良い実装方法の提案、リファクタリング案 | 任意 |
| nitpick | スタイル、命名、些細な改善 | 任意 |

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

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

```text
指摘を発見した場合の横断チェック手順:
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`ツールで投稿承認を確認する:

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

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

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

```text
+---------------------------------------------------------------+
| 投稿時の注意事項                                                 |
+---------------------------------------------------------------+
| - 自身の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](assets/templates/review_comment_template_ja.md)

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

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

投稿方法:

```bash
# 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`: 関連ルール・パターン名

### 指摘コメントの書き方

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

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

問題の概要と修正方針を簡潔に説明する。
（詳細なコード差分は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": "修正後に確認すべきチェックポイント（例: 関連ファイルとの整合性確認）"
}
```

</details>
```

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

```json
{
  "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. 各指摘について修正状況を確認:

| 状態 | 説明 |
|------|------|
| resolved | 指摘どおりに修正済み |
| partially-resolved | 一部修正されたが不十分 |
| unresolved | 未修正 |
| wont-fix | 修正しない判断がされた（理由を確認） |
| regressed | 修正により別の問題が発生 |

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

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

```markdown
## 再レビュー結果

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

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

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

### 新規指摘

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

**再レビューの詳細**: [references/rereview_guide_ja.md](references/rereview_guide_ja.md)

## 禁止事項

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

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

### 適用条件

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

### チーム構成例

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

## リソース

| リソース | 内容 |
|---------|------|
| [references/review_guide_ja.md](references/review_guide_ja.md) | 6観点の詳細レビューガイドライン |
| [references/rereview_guide_ja.md](references/rereview_guide_ja.md) | 再レビュー時の手順・判定基準 |
| [assets/templates/review_comment_template_ja.md](assets/templates/review_comment_template_ja.md) | PRコメント投稿テンプレート |