Claude Code マルチエージェントPRレビュー完全実装ガイド｜専門レビュアー並列化・収束ループ・境界設計パターン

# 収束ループ（擬似コード）
loop (max: 5 rounds):
  1. 専門レビュアーを並列起動（context: fork）
  2. 指摘を統合テーブルに集約
  3. バリデーターが妥当性を検証（ノイズ除去）
  4. Critical/Warning のみ自動修正対象に
  5. 修正適用（スコープ: 20ファイル未満）
  6. テスト実行（失敗3回でアボート）
  7. 指摘ゼロ → break / 残存 → 次のラウンドへ

end:
  未解決の指摘をサマリーとして人間に返す

.claude/
└── skills/
    ├── code-reviewer/
    │   └── SKILL.md
    ├── security-reviewer/
    │   └── SKILL.md
    ├── test-reviewer/
    │   └── SKILL.md
    ├── design-reviewer/
    │   └── SKILL.md
    ├── readable-code-reviewer/
    │   └── SKILL.md
    ├── spec-reviewer/
    │   └── SKILL.md
    ├── review-validator/
    │   └── SKILL.md
    └── review-fixer/
        └── SKILL.md

---
name: code-reviewer
description: Logical correctness reviewer. Checks edge cases, error handling, null safety, race conditions, boundary values in changed code. Use when reviewing PR diff for correctness issues.
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob, Bash
---

あなたはロジック正確性を専門とするコードレビュアーです。

## レビュー対象
引数で渡されたPR差分ファイルを対象とします。
変更箇所だけでなく、影響する呼び出し元・呼び出し先も確認してください。

## 確認項目
- エッジケース（空配列、null、0、最大値）の処理
- エラーハンドリングの欠落・握りつぶし
- 競合状態・非同期処理の順序問題
- 境界値（off-by-one）エラー
- 型の安全性（型アサーション・as キャストの乱用）
- 早期リターンの欠落による深いネスト

## 出力形式
以下のJSONで出力してください（他の文字は一切出力しない）:
{
  "reviewer": "code-reviewer",
  "findings": [
    {
      "severity": "critical|warning|info",
      "file": "ファイルパス",
      "line": 行番号,
      "message": "指摘内容（日本語）",
      "suggestion": "修正案（コードスニペット、任意）"
    }
  ]
}

---
name: security-reviewer
description: Security vulnerability reviewer. Checks SQL injection, XSS, auth bypass, secrets exposure, input validation in code changes. Use for any PR touching auth, data access, or external input handling.
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---

あなたはセキュリティを専門とするコードレビュアーです。

## 確認項目
- SQLインジェクション（プリペアドステートメントの未使用）
- XSS（ユーザー入力のHTMLへの直接埋め込み）
- 認証・認可バイパス（ミドルウェアの欠落、権限チェック不足）
- シークレット・認証情報のハードコード
- 入力バリデーションの欠落
- パストラバーサル
- CSRF対策の欠落

## 出力形式
code-reviewer と同じJSON形式で出力してください。
reviewerフィールドは "security-reviewer" とすること。

---
name: review-validator
description: Validates review findings from multiple reviewers. Removes false positives, duplicate findings, and context-blind suggestions. Use after collecting all reviewer outputs to filter before auto-fix.
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---

あなたはコードレビューの指摘を検証するバリデーターです。

## 入力
複数のレビュアーからの指摘リスト（JSON配列）を受け取ります。

## 検証ルール
以下の条件に当てはまる指摘は "rejected" としてください：

1. **コンテキスト無視**: 既に対処済みの問題を指摘している（他のファイルや既存の処理を確認していない）
2. **重複**: 複数のレビュアーが同一の問題を指摘している（最初の1件を残す）
3. **設計方針の誤解**: このプロジェクトの既存パターンと矛盾する一般論的な指摘
4. **スコープ外**: PR差分と無関係なファイルへの指摘

## 重要な制約
- 確信がない場合は "accepted" として残してください（誤却下のリスクを避ける）
- Critical severity の指摘は原則 accepted とすること

## 出力形式
{
  "validated_findings": [
    {
      ...元の指摘フィールド,
      "validation_status": "accepted|rejected",
      "rejection_reason": "却下理由（rejectedの場合のみ）"
    }
  ]
}

---
name: review-fixer
description: Applies validated review findings automatically. Only fixes critical and warning severity issues. Skips architectural decisions and design-choice changes. Use after validation step with filtered findings list.
context: fork
allowed-tools: Read, Edit, Bash
---

あなたは検証済みの指摘に基づいてコードを修正するエージェントです。

## 修正の原則
1. **最小限の変更**: 指摘された箇所のみを修正する。周辺のリファクタリングは一切しない
2. **設計判断はスキップ**: 「このクラスの責務が広すぎる」「アーキテクチャを変更すべき」
   など設計判断が必要な指摘は修正せず、スキップリストに追加する
3. **テストは必ず実行**: 修正後に `npm test` または `pytest` を実行し、失敗したら修正を巻き戻す
4. **1ファイルずつ**: 複数ファイルの連鎖的な変更が必要な場合はスキップする

## 安全弁（必ず守ること）
- 変更対象が20ファイルを超える場合: 全件スキップして人間に委譲
- テスト失敗が3回続いた場合: 修正を全て巻き戻してアボート
- 修正前後でテスト結果が変わった場合: 差分を必ず記録する

## 出力形式
{
  "fixed": ["修正したfile:line の説明"],
  "skipped": ["スキップした指摘とその理由"],
  "test_result": "passed|failed|aborted",
  "abort_reason": "アボート理由（あれば）"
}

# PRレビュー収束ループ

## /review-pr コマンド

`/review-pr` が呼ばれたら以下のループを実行する：

### 事前準備
1. `git diff main...HEAD --name-only` でPR差分ファイルを取得
2. ファイルをカテゴリ別に分類（src/, tests/, config/ など）

### 収束ループ（最大5ラウンド）
ラウンドごとに以下を実行：

**Step 1: 並列レビュー**
以下のSkillsを並列起動（context:forkにより独立実行）：
- /code-reviewer [diff_files]
- /security-reviewer [diff_files]
- /test-reviewer [diff_files]
- /design-reviewer [diff_files]
- /readable-code-reviewer [diff_files]
- /spec-reviewer [diff_files]

**Step 2: 指摘統合**
全レビュアーの出力JSONを統合し、findings テーブルを作成

**Step 3: 妥当性検証**
/review-validator [findings_json] を実行

**Step 4: 修正**
accepted かつ critical/warning の指摘のみ /review-fixer に渡す

**Step 5: 評価**
- fixer の test_result が "failed" or "aborted" → ループ中断
- accepted findings が0件 → ループ終了（成功）
- ラウンド5完了 → ループ終了（未解決あり）

### 終了時出力
- 解決済み指摘の一覧
- 未解決（スキップ・人間委譲）指摘の一覧
- 各ラウンドの指摘数推移

import { exec, execSync } from 'child_process';
import { promisify } from 'util';
import * as fs from 'fs';

const execAsync = promisify(exec);

interface Finding {
  reviewer: string;
  severity: 'critical' | 'warning' | 'info';
  file: string;
  line: number;
  message: string;
  suggestion?: string;
  validation_status?: 'accepted' | 'rejected';
}

interface RoundResult {
  round: number;
  totalFindings: number;
  acceptedFindings: number;
  fixedCount: number;
  skippedCount: number;
  testResult: string;
}

const REVIEWERS = [
  'code-reviewer',
  'security-reviewer',
  'test-reviewer',
  'design-reviewer',
  'readable-code-reviewer',
  'spec-reviewer',
];
const MAX_ROUNDS = 5;

async function runReviewLoop(): Promise<void> {
  const diffFiles = getDiffFiles();
  if (diffFiles.length === 0) {
    console.log('差分なし。レビューをスキップします。');
    return;
  }

  const history: RoundResult[] = [];

  for (let round = 1; round <= MAX_ROUNDS; round++) {
    console.log(`\n=== ラウンド ${round}/${MAX_ROUNDS} ===`);

    // Step 1: 並列レビュー（各Skillを個別プロセスで起動）
    const allFindings = await runParallelReviewers(diffFiles);
    console.log(`  レビュー指摘数: ${allFindings.length}`);

    if (allFindings.length === 0) {
      console.log('指摘なし。ループを終了します。');
      break;
    }

    // Step 2: 妥当性検証
    const validatedFindings = await runValidator(allFindings);
    const accepted = validatedFindings.filter(f => f.validation_status === 'accepted');
    console.log(`  妥当と判定された指摘: ${accepted.length}/${allFindings.length}`);

    const actionable = accepted.filter(f => f.severity !== 'info');
    if (actionable.length === 0) {
      console.log('自動修正対象なし。ループを終了します（infoのみ）。');
      outputSummary(history, accepted);
      return;
    }

    // Step 3: 修正
    const fixResult = await runFixer(actionable);
    const roundResult: RoundResult = {
      round,
      totalFindings: allFindings.length,
      acceptedFindings: accepted.length,
      fixedCount: fixResult.fixed.length,
      skippedCount: fixResult.skipped.length,
      testResult: fixResult.test_result,
    };
    history.push(roundResult);

    if (fixResult.test_result === 'aborted' || fixResult.test_result === 'failed') {
      console.log(`テスト${fixResult.test_result}。ループを中断します。`);
      outputSummary(history, accepted);
      return;
    }
  }

  outputSummary(history, []);
}

function getDiffFiles(): string[] {
  try {
    const output = execSync('git diff main...HEAD --name-only').toString();
    return output.trim().split('\n').filter(Boolean);
  } catch {
    return [];
  }
}

async function runParallelReviewers(files: string[]): Promise<Finding[]> {
  // 実際の実装では claude -p でヘッドレス実行
  // ここでは並列実行のコンセプトを示す
  const promises = REVIEWERS.map(reviewer =>
    runSkill(reviewer, files)
  );
  const results = await Promise.all(promises);
  return results.flat();
}

async function runSkill(skillName: string, files: string[]): Promise<Finding[]> {
  // ファイル一覧はファイル経由で渡す（ARGMAXを避けるため直接埋め込まない）
  const tmpFile = `/tmp/review-files-${skillName}.txt`;
  fs.writeFileSync(tmpFile, files.join('\n'));
  const prompt = `/${skillName} $(cat ${tmpFile})`;
  // execAsync で真の非同期実行（Promise.all での並列実行に対応）
  const { stdout } = await execAsync(
    `claude -p "${prompt}" --output-format json --max-turns 5`,
    { timeout: 120000 }
  );
  try {
    const result = JSON.parse(stdout);
    return result.findings || [];
  } catch {
    return [];
  }
}

async function runValidator(findings: Finding[]): Promise<Finding[]> {
  const tmpFile = '/tmp/review-findings.json';
  fs.writeFileSync(tmpFile, JSON.stringify(findings));
  const { stdout } = await execAsync(
    `claude -p "/review-validator $(cat ${tmpFile})" --output-format json --max-turns 3`,
    { timeout: 60000 }
  );
  const result = JSON.parse(stdout);
  return result.validated_findings || findings;
}

async function runFixer(findings: Finding[]): Promise<any> {
  const tmpFile = '/tmp/review-actionable.json';
  fs.writeFileSync(tmpFile, JSON.stringify(findings));
  const { stdout } = await execAsync(
    `claude -p "/review-fixer $(cat ${tmpFile})" --output-format json --max-turns 10`,
    { timeout: 300000 }
  );
  return JSON.parse(stdout);
}

function outputSummary(history: RoundResult[], remaining: Finding[]): void {
  console.log('\n=== レビューサマリー ===');
  history.forEach(r => {
    console.log(`ラウンド${r.round}: 指摘${r.totalFindings}件 → 修正${r.fixedCount}件 スキップ${r.skippedCount}件 [${r.testResult}]`);
  });
  if (remaining.length > 0) {
    console.log(`\n未解決（人間レビュー推奨）: ${remaining.length}件`);
    remaining.forEach(f => console.log(`  [${f.severity}] ${f.file}:${f.line} - ${f.message}`));
  }
}

runReviewLoop().catch(console.error);

# アーキテクチャ上の設計判断を記録
docs/architecture-decisions.md

# このプロジェクトで使うコーディングパターン
.claude/project-patterns.md

# 意図的に採用していない（しない）パターン
.claude/excluded-patterns.md

# 自動修正スキップの基準

## 設計判断が必要なもの
- クラス/モジュールの責務分割
- インターフェースの変更
- データ構造の変更
- 外部APIの呼び出し方法の変更

## リスクが高いもの
- テスト以外のファイルとの連鎖変更（2ファイル超）
- データベーススキーマへの影響
- 設定ファイルの変更

## コンテキスト依存のもの
- パフォーマンスのトレードオフ
- 「〇〇パターンに変更すべき」という提案
- ビジネスロジックの解釈が必要な変更

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "scripts/validate-review-command.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# Review Fixerが実行しようとするコマンドを検証

COMMAND="$CLAUDE_TOOL_INPUT_COMMAND"

# git reset --hard, git checkout -- などの巻き戻し系は禁止
if echo "$COMMAND" | grep -E "git (reset --hard|checkout -- |clean -f)" > /dev/null 2>&1; then
  echo "ERROR: 破壊的なgitコマンドは自動修正で使用禁止です" >&2
  exit 1
fi

# npmスクリプト以外のシェルコマンドは制限
if echo "$COMMAND" | grep -E "^(rm -rf|chmod 777|curl.*\|.*sh)" > /dev/null 2>&1; then
  echo "ERROR: 危険なコマンドパターンが検出されました" >&2
  exit 1
fi

exit 0

name: Claude Multi-Agent Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  code-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Code Logic Review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            /code-reviewer
            対象ファイル: $(git diff origin/main...HEAD --name-only | head -30 | tr "\n" " ")
          claude_args: "--max-turns 5 --model claude-sonnet-4-6"
          timeout-minutes: 10

  security-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Security Review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            /security-reviewer
            対象ファイル: $(git diff origin/main...HEAD --name-only | head -30 | tr "\n" " ")
          claude_args: "--max-turns 5 --model claude-sonnet-4-6"
          timeout-minutes: 10

  test-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Test Coverage Review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            /test-reviewer
            対象ファイル: $(git diff origin/main...HEAD --name-only | head -30 | tr "\n" " ")
          claude_args: "--max-turns 5 --model claude-sonnet-4-6"
          timeout-minutes: 10

  review-summary:
    needs: [code-review, security-review, test-review]
    runs-on: ubuntu-latest
    if: always()
    steps:
      - name: Summarize Review Results
        run: |
          echo "## レビュー完了" >> $GITHUB_STEP_SUMMARY
          echo "- Code Review: ${{ needs.code-review.result }}" >> $GITHUB_STEP_SUMMARY
          echo "- Security Review: ${{ needs.security-review.result }}" >> $GITHUB_STEP_SUMMARY
          echo "- Test Review: ${{ needs.test-review.result }}" >> $GITHUB_STEP_SUMMARY

name: Claude Interactive Review

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude-review:
    if: |
      (github.event_name == 'issue_comment' || github.event_name == 'pull_request_review_comment')
      && contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # コメント内容をそのままプロンプトとして渡す
          prompt: ${{ github.event.comment.body }}
          claude_args: "--max-turns 8"