Claude Code マルチエージェント並列実行 — Task ツールと SubAgent で開発効率を10倍にする

実装前に知っておくべきアーキテクチャの考え方

並列エージェント設計で最も重要なのは「何を分割し、何を分割しないか」の判断です。私の経験から言うと、以下の判断基準が有効です。

分割すべきもの:

• 読み取り専用の解析処理（テスト・リント・型チェックなど）
• 独立したファイル群への処理（モジュールAとモジュールBを別々にレビューなど）
• 異なるリソースへのアクセス（DB確認・API確認・ファイル確認を同時に）

分割してはいけないもの:

• 同じファイルへの書き込み処理（競合が発生します）
• 前の結果に依存する処理（ビルドの後にテスト、など順序が必要なもの）
• 共有状態を変更する操作（環境変数の書き換えなど）

この判断を誤ると、エラーは出ないのに結果が壊れるという厄介なバグになります。

実際の設定例：3エージェント並列CI

以下は、私が実際に Claude Lab のリポジトリで使っている設定です。大きなプルリクエストを作成したとき、次の3つを並列実行します。

Agent 1：TypeScript 型チェックとリント

## SubAgent: TypeScript Checker
 
あなたはコード品質チェッカーです。以下の作業を行い、結果を JSON 形式で返してください。
 
**作業内容:**
1. `npx tsc --noEmit 2>&1` を実行してエラーをリストアップ
2. `npx eslint src/ --format json 2>&1` を実行してリント結果を取得
3. エラー件数と深刻度を集計
 
**出力形式:**
{"tsc_errors": N, "eslint_errors": N, "eslint_warnings": N, "details": "..."}

Agent 2：テスト実行とカバレッジ計測

## SubAgent: Test Runner
 
あなたはテスト実行エージェントです。以下を実行してください。
 
**作業内容:**
1. `npx jest --coverage --json 2>&1 | tail -1` を実行
2. カバレッジサマリーを抽出
3. 失敗したテストのリストを作成
 
**出力形式:**
{"total_tests": N, "passed": N, "failed": N, "coverage_pct": N.N, "failed_tests": [...]}

Agent 3：依存関係のセキュリティチェック

## SubAgent: Security Auditor
 
あなたはセキュリティ監査エージェントです。
 
**作業内容:**
1. `npm audit --json 2>&1` を実行
2. 高・中リスクの脆弱性を抽出
3. 修正が必要なパッケージをリストアップ
 
**出力形式:**
{"high_risk": N, "moderate_risk": N, "affected_packages": [...], "fix_command": "..."}

親エージェントの集約ロジック

## 親エージェント指示
 
上記3つの SubAgent を同時に起動し、全ての結果が返ったら以下を行ってください。
 
1. 各エージェントの JSON 結果をパース
2. 問題があった場合は優先度付きリストを作成
3. "全クリア" か "要対応あり" かを明確に判定
4. 結果を RESULT.md に書き出す
 
**重要:** SubAgent が失敗した場合（タイムアウト・エラーなど）は、その旨を記録して他のエージェントの結果は正常扱いとする。一部失敗で全体を止めないこと。

失敗しがちなアンチパターン3選

実際に使い込んでわかった、やりがちな失敗パターンをご紹介します。

アンチパターン1: SubAgent にコンテキストを渡しすぎる

# ❌ 悪い例
「これまでの会話を踏まえて、プロジェクト全体を理解した上でリファクタリングしてください」
 
# ✅ 良い例
「src/api/users.ts の関数 getUserById を、以下の要件でリファクタリングしてください: [具体的な要件]」

SubAgent はコンテキストを引き継ぎません。「これまでの会話」は存在しないも同然です。必要な情報はすべてタスク指示に含める必要があります。

アンチパターン2: 結果の検証を省略する

# ❌ 悪い例
SubAgent の出力をそのまま次の処理に渡す
 
# ✅ 良い例
出力を受け取ったら、まず JSON として正しくパースできるか確認し、
必須フィールドが揃っているかを検証してから次へ進む

SubAgent は指定した形式で返さないことがあります。親エージェントでの検証は必須です。

アンチパターン3: タイムアウトを考慮しない

テストスイートが大きい場合、SubAgent がタイムアウトすることがあります。重要な処理を SubAgent に任せる場合は、タイムアウト時のフォールバックを必ず設計しておきましょう。

実践的なユースケース：コードレビューの自動化

私が最も効果を感じているのが、プルリクエストのコードレビュー支援です。次の構成で動かしています。

PR が作成される
  │
  ├─ Agent A: 変更ファイルリストを取得
  │
  ├─ [並列実行] ─────────────────────────────────
  │   ├─ Agent B: ロジック変更部分をレビュー
  │   ├─ Agent C: テスト充足性を確認
  │   └─ Agent D: ドキュメントとの整合性確認
  │
  └─ 親エージェント: レビューコメントを集約して GitHub に投稿

Agent B・C・D が並列で動くため、レビュー全体が1/3の時間で完了します。特に大きな変更のときに効果を実感します。

パフォーマンスを最大化するための5つのヒント

これまでの試行錯誤から得た実践的なヒントです。

1. タスクを「読み取り」と「書き込み」に分類する 読み取り専用タスクは積極的に並列化できます。書き込みが発生するタスクは依存関係を慎重に設計します。

2. SubAgent の出力は短く保つ 大量のテキストを返す SubAgent は遅くなります。必要な情報だけを JSON で返すよう指示しましょう。

3. 失敗を前提に設計する 「全エージェントが成功する」前提の設計は壊れます。一部が失敗しても結果を集約できる設計にします。

4. 反復よりも構造化を 「もし〜なら再試行して」という指示は避けます。それよりも「失敗した場合は {"error": "...理由..."} を返す」という構造化された失敗レポートを求める方が安定します。

5. 段階的に複雑さを増やす いきなり5並列は難しいです。まず2つを並列化して動作を確認し、徐々に増やしていくのが安全です。

次のステップ

マルチエージェントの基礎を理解したら、次は hooks システム（PreToolUse / PostToolUse）と組み合わせると、さらに強力な自動化が実現できます。タスク実行前の検証・実行後の通知・エラー時の自動ロールバックなど、開発ワークフロー全体を自動化できます。

まずは小さな並列化から試してみてください。「テストとリントを同時に走らせる」だけでも、毎日の開発体験が変わります。

この記事で紹介した設定例は、実際の開発環境でテスト済みです。Claude Code のバージョンや環境によって挙動が異なる場合があります。最新情報は公式ドキュメントでご確認ください。