AtsushiHashimoto/.claude/skills/review

Multi-Agent Review（多角的コードレビュー）

現在のブランチの変更内容を、6つの専門的な観点から並列にレビューします。

用途

• コミット前の品質確認
• /commit/merge 前のプリレビュー
• 設計判断の妥当性検証
• 仕様との整合性確認

Workflow

Step 1: 変更内容の収集

まず現在のブランチの変更を収集します：

# Issue番号の取得
BRANCH=$(git branch --show-current)
ISSUE_ID=$(echo "$BRANCH" | grep -oE '[0-9]+' | head -1)

# 変更の範囲を確認
git diff main --stat
git diff main --name-only
git log main..HEAD --oneline

Step 2: Issue目的と仕様ファイルの確認

# Issue内容を取得して目的を把握
gh issue view "$ISSUE_ID" --json title,body

# 仕様ファイルの確認
SPEC_FILE=$(ls .spec/issues/${ISSUE_ID}-*.md 2>/dev/null | head -1)
if [ -n "$SPEC_FILE" ]; then
  cat "$SPEC_FILE"
fi

Step 3: 6つのサブエージェントを並列実行

6つのサブエージェントを Task tool で並列に起動し、それぞれ異なる観点でレビューを行います。

各サブエージェントには以下を渡します：

• git diff main の出力（変更内容）
• Issue のタイトルと本文（目的）
• 仕様ファイルの内容（存在する場合）
• 変更されたファイルの完全な内容

3-1. アーキテクチャレビュー（Architecture Review）

Task tool で subagent_type=general-purpose を使用。

レビュー観点：

• 設計の妥当性: 変更が既存のアーキテクチャパターンと整合しているか
• 単一情報源の原則（Single Source of Truth）: 同じ情報が複数箇所で定義されていないか。修正時に複数箇所を変更する必要がないか
• 既存コードとの一貫性: 命名規則、コーディングスタイルが統一されているか
• 過度な複雑性: YAGNI原則に反した過剰設計がないか
• 依存関係: 不要な依存の追加や循環依存がないか
• ファイルサイズ: 変更ファイルが肥大化していないか（行数順にチェック）

ファイルサイズチェック:

# 変更ファイルの行数を取得（大きい順）
git diff main --name-only | xargs wc -l 2>/dev/null | sort -rn | head -20

| 閾値 | 判定 | |------|------| | 300行以下 | ✅ OK | | 300-500行 | ⚠️ 分割検討 | | 500行超過 | ❌ 分割必須 |

超過ファイルについては以下を分析：

• 肥大化の原因（複数責務、コピペ、過剰な分岐）
• 分割案（責務ごとのファイル分割提案）
• 仕様ファイルの想定行数との比較

3-2. リスクレビュー（Risk Review）

Task tool で subagent_type=general-purpose を使用。

レビュー観点：

• 対症療法的修正の検出（重要）: 想定される挙動と異なる振る舞いに対して、挙動を上書きする形での修正を検出。このような修正は保守性を低下させるため禁止
  • 例: 根本原因を修正せず、出力を後から加工する処理
  • 例: バグの原因を直さず、条件分岐で回避する処理
• セキュリティ: 機密情報の漏洩、インジェクション脆弱性、安全でないデシリアライゼーション
• エッジケース: 境界値、null/undefined、空配列、並行処理の問題
• データ保護: 重要データが data/shared/ に保存され、Worktree削除時に失われない設計か
• ハードコーディング: マジックナンバー、固定パス、環境依存値が設定に抽出されているか
• ポータビリティ: 他の環境でも動作するか
• プロジェクトルール遵守: .claude/CLAUDE.md および .claude/workflows/ で定義されたルール（コミット規則、ブランチ命名規則、開発ガイドライン等）に従っているか
• 依存関係の永続化: 新規パッケージが devcontainer rebuild 後も利用可能か（Python: pyproject.toml、システム: Dockerfile に追加されているか）

3-3. テストレビュー（Test Review）

Task tool で subagent_type=general-purpose を使用。

テストの目的原則: 自動テストの目的は、人間による手動検証を最小化することにある。人間がリアルな環境で試したときに初めて発覚する問題を、自動テストの段階で検出できるようにすることがゴールである。

必須の2段階思考（テストレビュー時に必ず thinking で実施すること）:

1. Step 1: 人間が手動検証したとき、この変更で何が壊れうるか？ を列挙する。実環境で起きうる問題を想像力を使って洗い出す。例：

   • プロセス間・ネットワーク境界を越えた通信の問題（CORS、タイムアウト、認証ヘッダー）
   • 正常パスでは通らないエラーハンドリングの不備（例外時のログ変数名ミス、型エラー）
   • 環境差異（OS、ブラウザ、ランタイムバージョン、依存ライブラリの有無）
   • 設定値の伝播漏れ（config に定義したが実際に使われていない）
   • リネーム・移動後の参照漏れ（旧名が残っている箇所）
   • 非同期処理のタイミング依存（競合、デッドロック、タイムアウト）
   • UI/フロントエンドとバックエンドの接続（WebSocket ハンドシェイク、プロトコル不一致）

2. Step 2: 現在のテストは Step 1 の各問題を検出できるか？ を判定する。テスト手法の限界を意識し、「テストが存在する」ではなく「そのテストが主張する保証を、その実行環境で実際に提供できるか」を問う。検出できない項目があれば、どのレベルのテスト（統合テスト、プロセス間テスト、ブラウザテスト等）を追加すべきか提案する。

レビュー観点：

• テストカバレッジ: 変更された機能に対するテストが存在するか
• テスト品質: テストが実際に意味のある検証をしているか（trivialなアサーションでないか）
• 網羅性: 全ての分岐パス、境界値、エラーケースがテストされているか
• 潜在的バグの検出力: テストが以下のような細かいミスを検出できるか
  • int/float の型変換ミス
  • round/floor/ceil の使い分けミス
  • 文字列エンコーディングの問題
  • タイムゾーン関連のバグ
  • 浮動小数点の比較誤差
• エッジケーステスト: 空配列、null、0、負数、最大値でのテストがあるか
• テストの独立性: テスト間に不要な依存がないか
• Mock の品質検証（mock/patch/stub/MagicMock 等が使われている場合）:
  • 模倣対象との乖離: mock の戻り値・振る舞いが実際の模倣対象（API、クラス、関数）と一致しているか。模倣対象のソースコードやドキュメントを読み、mock が返すデータの型・構造・エッジケースが現実と矛盾していないか確認
  • 合理性: mock の設定が論理的に合理的か。例えば、ありえない組み合わせの戻り値を返していないか、side_effect が実際の例外型と一致しているか
  • mock より実物を優先（最重要）: mock は最終手段。実物でテストできるなら実物を使う。mock を見つけたら「これは実物で代替できないか？」を最初に問う
    • 実物を使うべき: 純粋関数、ユーティリティ、軽量オブジェクト、データ変換、バリデーション、自プロジェクト内のモジュール間連携
    • テスト用の軽量実装で代替: インメモリDB（sqlite :memory:）、tmpdir でのファイル操作、テスト用 HTTP サーバー（httptest, responses 等）
    • mock が正当化されるのは以下のみ: 外部 API/ネットワーク（遅い・不安定・課金）、本番データベース、時刻（datetime.now 等）、乱数、OS レベルの副作用
  • mock を使っている箇所ごとに「実物 or 軽量実装で代替可能か？」を判定し、代替可能なら具体的な書き換え案を提示すること
• テスト不要な変更の判定: 設定ファイルやドキュメントのみの変更など、テスト不要な場合は明示

3-4. Fallbackチェッカー（Fallback Checker）

Task tool で subagent_type=general-purpose を使用。

事前準備: 仕様ファイルから「承認済みFallbackホワイトリスト」を読み込む。

レビュー観点： コード内の全 if/switch/try-catch を走査し、以下をチェック：

• else でデフォルト値返却: if x: return x else: return default
• switch/match の default で無視: case _: pass or default: break
• try-except で握りつぶし: except: pass or except: return None
• Optional unwrap でデフォルト: x.unwrap_or(default) without logging
• null合体演算子: x ?? default without explicit design reason
• 空配列/空オブジェクトで続行: if not data: data = [] then continue processing

出力形式：

## Fallback検出結果

### ✅ 承認済み（ホワイトリストにマッチ）
- `ファイル:行` - `パターン`

### 🔴 未承認（要修正）
- `ファイル:行` - `パターン`
  - ホワイトリストに該当なし
  - 推奨: [修正案]

### 🟡 新規fallback（要判断）
- `ファイル:行` - `パターン`
  - 計画時に想定されていなかった分岐
  - 許可する場合はホワイトリストに追加

3-5. 仕様充足チェッカー（Spec Compliance Checker）

Task tool で subagent_type=general-purpose を使用。

事前準備: 仕様ファイルから「検証チェックリスト」を読み込む。

レビュー観点： 仕様ファイルの各チェック項目について、実装が満たしているか検証。

出力形式：

## 仕様充足チェック結果

### ✅ 充足
- [x] チェック項目

### ❌ 未充足
- [ ] チェック項目
  - **現状**: [実装の状態]
  - **修正案**: [具体的な修正方法]

### ⚠️ 検証不能
- [ ] チェック項目
  - **理由**: [検証できない理由]
  - **推奨**: [検証可能にするための提案]

3-6. ロジック検証チェッカー（Logic Verification Checker）

Task tool で subagent_type=general-purpose を使用。

レビュー観点：

• ループの必要十分性: for/while の対象が過不足なく処理されるか
  • 処理対象の範囲は正しいか
  • 必要なデータが漏れていないか
  • 不要なデータを処理していないか
• 条件分岐の網羅性: if/switch/match で全ケースが考慮されているか
  • 抜けているケースはないか
  • 到達不能なコードはないか
• off-by-oneエラー: < vs <=、range(n) vs range(n+1) の検証
• 型変換の正確性: int/float/round、文字列変換で精度が失われないか
• 空・境界の処理: 空配列、0件、最大値でループが正しく動くか
• 早期終了の正当性: break/continue/return が意図通りか
• インデックスアクセス: 配列/リストへのアクセスが範囲内か

出力形式：

## ロジック検証結果

### 🔴 問題あり
- `ファイル:行` - [問題の説明]
  - **コード**: `該当コード`
  - **問題**: [具体的な問題点]
  - **修正案**: [修正方法]

### 🟡 要確認
- `ファイル:行` - [確認が必要な点]

### ✅ 問題なし
- ループ処理: N箇所確認済み
- 条件分岐: M箇所確認済み

3-7. Best Practice チェッカー（Pattern Compliance Review）

Task tool で subagent_type=general-purpose を使用。

目的: 変更された各部品（関数、クラス、モジュール）が、その言語・フレームワークの best practice パターンに沿っているかを個別に検証する。逸脱がある場合、プロジェクト固有の正当な理由があるかを確認する。

レビュー手順：

1. 部品の列挙: git diff main から変更・追加された関数、クラス、モジュールを列挙
2. 各部品ごとに best practice との照合:
   • その言語・フレームワークで確立されたパターン（公式ドキュメント、広く認知された慣習）と比較
   • 例: Python なら PEP 8, typing, contextmanager の使い方、TypeScript なら公式 handbook のパターン等
3. 逸脱の検出と理由の検証: パターンから外れている場合、以下のいずれかに該当するか確認:
   • プロジェクト内の一貫性: 他のモジュールが同じパターンを使っており、統一のために合わせている
   • パフォーマンス要件: best practice に従うとパフォーマンスが著しく劣化する
   • 既存 API との互換性: 外部 API やプロジェクト内の既存インターフェースに合わせる必要がある
   • 仕様ファイルの明示的指示: 仕様で特定のパターンが指定されている
4. 正当な理由がない逸脱は「要修正」

出力形式：

## Best Practice チェック結果

### 部品一覧
変更された関数/クラス/モジュール: N件

### 🔴 要修正（正当な理由なく best practice から逸脱）
- `ファイル:行` - `関数名/クラス名`
  - **Best Practice**: [推奨パターンの説明]
  - **現状**: [実際の実装]
  - **修正案**: [具体的な修正方法]

### 🟡 許容（正当な理由あり）
- `ファイル:行` - `関数名/クラス名`
  - **Best Practice**: [推奨パターン]
  - **逸脱理由**: [プロジェクト一貫性 / パフォーマンス / API互換性 / 仕様指示]
  - **根拠**: [具体的にどのモジュール/仕様と合致するか]

### ✅ Best Practice 準拠
- N件の部品が best practice に準拠

3-8. UI/UX レビュー（UI/UX Review）【条件付き】

GUI/フロントエンド変更がある場合のみ実行。

Task tool で subagent_type=general-purpose を使用。

発動条件（いずれかに該当）：

• 変更ファイル: **/*.html, **/*.css, **/*.js, **/templates/**, **/static/**
• CLIメッセージ、ログ出力、ユーザー向けメッセージの変更
• print(), logger.*(), console.*() の追加・変更

レビュー観点：

• 一貫性: 他の UI 要素と表示形式が統一されているか
• 直感性: ユーザーが誤解しない表現か
  • オプショナル機能の無効状態がエラーに見えないか（例: "disabled" vs "not running"）
  • 状態表示が現在の状態を正確に伝えているか
• メリハリ: 重要度に応じた視覚的優先順位が付いているか
  • 起動成功メッセージは目立つべき
  • オプション機能の状態は控えめに
• エラー状態: エラーと正常状態が明確に区別できるか

出力形式：

## UI/UX レビュー結果

### 🔴 問題あり
- `ファイル:行` - [問題の説明]
  - **現状**: `現在の表示`
  - **問題**: [問題点]
  - **修正案**: `改善後の表示`

### 🟡 要確認
- `ファイル:行` - [確認が必要な点]

### ✅ 問題なし
- UI/UX チェック: N箇所確認済み

Step 4: レビュー結果の統合

8つのサブエージェントの結果を統合し（UI/UX レビューは条件付き）、以下の形式で報告：

## 🔍 Multi-Agent Review Results

### 📐 Architecture Review
[結果サマリー]
- ✅ / ⚠️ / ❌ 各項目の判定

### 🛡️ Risk Review
[結果サマリー]
- ✅ / ⚠️ / ❌ 各項目の判定

### 🧪 Test Review
[結果サマリー]
- ✅ / ⚠️ / ❌ 各項目の判定

### 🚫 Fallback Check
[結果サマリー]
- ✅ 承認済み: N件
- ❌ 未承認: M件
- 🟡 新規: K件

### 📋 Spec Compliance
[結果サマリー]
- ✅ 充足: N件
- ❌ 未充足: M件
- ⚠️ 検証不能: K件

### 🔄 Logic Verification
[結果サマリー]
- ✅ / ⚠️ / ❌ 各項目の判定

### 🏗️ Best Practice Check
[結果サマリー]
- ✅ 準拠: N件
- 🟡 許容（理由あり）: M件
- 🔴 要修正: K件

### 🎨 UI/UX Review（該当する場合）
[結果サマリー]
- ✅ / ⚠️ / ❌ 各項目の判定

### 📋 Summary
- **Critical Issues**: [即座に修正が必要な問題]
- **Warnings**: [改善を推奨する問題]
- **Approved**: [問題なしの項目]

### 💡 Recommendations
[具体的な改善提案]

Step 5: ユーザーへの提示

レビュー結果を提示し、以下を確認：

• Critical Issues がある場合: 修正を提案
• Warnings のみの場合: 修正するか進めるか確認
• 問題なしの場合: /commit/merge への進行を提案

Implementation

1. git diff main で変更内容を取得
2. gh issue view でIssue目的を取得
3. 仕様ファイル .spec/issues/{issue_id}-*.md を読み込み
4. Task tool を7回並列に呼び出し（+ UI/UX は条件付き）、各サブエージェントにレビュー指示を渡す
5. 結果を統合してユーザーに提示

重要: サブエージェントは必ず並列（同一メッセージ内で複数のTask tool呼び出し）で起動すること。

Note

• /commit/merge のPhase 0（品質チェック）とは独立して実行可能
• より詳細なレビューが必要な場合にこのコマンドを使用
• /commit/merge は単体でも品質チェックを行うため、両方を実行する必要はない
• 仕様ファイルが存在しない場合、Fallbackチェッカーと仕様充足チェッカーは「仕様ファイルなし」と報告する