| name | ai-code-review |
| description | 指定されたPRを6観点（セキュリティ、ドキュメント乖離、可読性、ライブラリ選定、PR説明、既知脆弱性）でレビューし、人間向け・AI向けの2形式でPRにコメントする。初回レビューおよび修正後の再レビューに使用する。Do NOT use for レビューコメントへの修正適用（pr-comment-fixerを使用すること）。 |
| metadata | {"version":"1.1.0"} |
AIコードレビュースキル
指定されたPull Requestを体系的にレビューし、レビュー結果をPRコメントとして投稿するスキルです。レビュー指摘は人間向けとAI向けの2パターンで併記します。初回レビューだけでなく、修正後の再レビューにも対応します。6つの観点でPRの品質を多角的に検証します。
重要な原則
+---------------------------------------------------------------+
| レビューの鉄則 |
+---------------------------------------------------------------+
| 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
このスキルを使用する場面
初回レビュー
- 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情報を取得する。
gh pr diff <PR番号>
gh pr view <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内の他のファイル・コミットにも同様の問題がないか横断的に確認する。
指摘を発見した場合の横断チェック手順:
1. 指摘のパターンを抽出する（例: 「不正確なテスト数の記載」）
2. PR内の全変更ファイルで同様のパターンを検索する
3. 別コミットで追加された関連ファイルも確認対象に含める
4. 同一パターンの問題が複数見つかった場合はまとめて指摘する
例: TASK-002のサマリーで「全31テスト」を指摘した場合、同じPR内のTASK-001の完了サマリー（別コミット）にも同様の表現がないか確認する。
ステップ4: 指摘の整理
- 重大度の高い順にソート
- 同一ファイル内の指摘はまとめる
- 重複する指摘は統合
- 過度に些細な指摘（nitpick）が多い場合は厳選する
ステップ5: レビュー結果の承認確認（必須ゲート）
PRコメントを投稿する前に、必ずユーザーの承認を得ること。
レビュー結果が確定したら、PRへの投稿前にレビューサマリーをユーザーに提示し、AskUserQuestionツールを使って投稿の承認を確認する。
手順
-
レビュー結果のサマリーをユーザーに出力する:
- 総合判定（Approve / Request Changes / Comment）
- 指摘件数の内訳（critical / warning / suggestion / nitpick）
- 主要な指摘事項の概要（再レビュー時は前回指摘の修正状況も含む）
-
AskUserQuestionツールで投稿承認を確認する:
AskUserQuestion:
question: "上記のレビュー結果をPRに投稿してよろしいですか？"
options:
- label: "投稿する"
description: "レビュー結果をPRコメントとして投稿します"
- label: "修正してから投稿"
description: "レビュー内容を修正してから投稿します"
- label: "投稿しない"
description: "レビュー結果の投稿を中止します"
- ユーザーの回答に応じて対応する:
- 「投稿する」: ステップ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
インラインコメント（個別指摘）
各指摘は該当コードの行にインラインコメントとして投稿する。
投稿方法:
COMMIT_SHA=$(gh pr view <PR番号> --json headRefOid --jq '.headRefOid')
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観点レビューに加えて以下を行う。
前回指摘の修正確認
- 前回のレビューコメントをすべて取得
- 各指摘について修正状況を確認:
| 状態 | 説明 |
|---|
| resolved | 指摘どおりに修正済み |
| partially-resolved | 一部修正されたが不十分 |
| unresolved | 未修正 |
| wont-fix | 修正しない判断がされた（理由を確認） |
| regressed | 修正により別の問題が発生 |
- 修正状況をサマリーコメントに含める
再レビューサマリーの形式
## 再レビュー結果
### 前回指摘の修正状況
| # | 指摘内容 | 重大度 | 状態 | コメント |
|---|---------|--------|------|---------|
| 1 | [指摘概要] | critical | resolved | 適切に修正済み |
| 2 | [指摘概要] | warning | unresolved | 未修正 - 対応をお願いします |
- resolved: X件
- partially-resolved: X件
- unresolved: X件
### 新規指摘
（通常の6観点レビュー結果）
再レビューの詳細: references/rereview_guide_ja.md
禁止事項
- 推測に基づくレビュー（コードを読まずに指摘する）
- 個人の好みだけを根拠にした指摘（明確な理由なしの「こう書くべき」）
- 裏取りなしに数値・事実を断定する指摘（例: 「テスト数は243件」と述べる前に
実際のテスト数をカウントする。不確実な場合は「〜の可能性がある」と表現する）
- 変更範囲外のコードへの指摘（ただしセキュリティ問題は例外）
- 過剰な nitpick（レビュー全体が些細な指摘で埋まる状態）
- 人間向け・AI向けのどちらか一方だけの記載
- 再レビュー時に前回指摘の修正確認を省略すること
- ユーザーの承認なしにPRコメントを投稿すること（承認確認ゲートの省略）
エージェントチームによる並列レビュー（条件を満たす場合は使用）
適用条件
- 変更ファイル数が10以上
- 変更が3つ以上の独立したモジュール/ディレクトリにまたがる
- 各モジュールの変更が独立してレビュー可能
チーム構成例
チームリーダー（レビュー統合・サマリー作成に専念）
|
+-- レビュアーA: セキュリティ・既知脆弱性観点担当
| - コードのセキュリティ問題（認証・認可、入力検証、秘密情報管理）と
| 依存パッケージの既知脆弱性（CVE）を一貫してチェック
| - 両観点を同一レビュアーが担当することで、コード側の脆弱性と
| 依存パッケージ側の脆弱性を統合的に評価できる
|
+-- レビュアーB: 可読性・複雑度観点担当
| - 命名、関数長、ネスト、複雑度を集中チェック
|
+-- レビュアーC: ドキュメント乖離・ライブラリ・PR説明観点担当
- 仕様との整合性、依存関係の妥当性、PRタイトル・説明文の適切性を集中チェック
リソース
