parallel-execution

並列実行パターン

読み込むタイミング

• トリガー：マルチエージェントタスク、同時実行操作、サブエージェントの起動、独立した作業の並列化
• スキップ：並列化の余地がない単一ステップのタスクや逐次ワークフロー

基本概念

並列実行では、Agent ツール（Claude Code 2.1.63 より前は Task という名前でした。現在もエイリアスとして Task を使用できます）を使って、複数のサブエージェントを同時に起動します。サブエージェントはデフォルトでバックグラウンドで実行されるため、N 個のタスクが並行して実行され、全体の実行時間を大幅に短縮できます。

重要なルール：真の並列実行を実現するには、すべての Agent 呼び出しを単一のアシスタントメッセージ内に含める必要があります。呼び出しが別々のメッセージに分かれていると、順番に起動されます。

実行手順

ステップ 1：並列化できるタスクを特定する

起動する前に、タスクが独立していることを確認します。

• あるタスクが別のタスクの出力に依存していない
• タスクごとに対象とするファイルや関心事が異なる
• 競合なく同時に実行できる

ステップ 2：動的なサブエージェント用プロンプトを準備する

各サブエージェントに、役割を定義したカスタムプロンプトを割り当てます。

You are a [ROLE] specialist for this specific task.

Task: [CLEAR DESCRIPTION]

Context:
[RELEVANT CONTEXT ABOUT THE CODEBASE/PROJECT]

Files to work with:
[SPECIFIC FILES OR PATTERNS]

Output format:
[EXPECTED OUTPUT STRUCTURE]

Focus areas:
- [PRIORITY 1]
- [PRIORITY 2]

ステップ 3：すべてのタスクを 1 つのメッセージで起動する

重要：すべての Agent 呼び出しを同じアシスタントメッセージ内で行います。

I'm launching N parallel subagents:

[Agent 1]
description: "Subagent A - [brief purpose]"
prompt: "[detailed instructions for subagent A]"

[Agent 2]
description: "Subagent B - [brief purpose]"
prompt: "[detailed instructions for subagent B]"

[Agent 3]
description: "Subagent C - [brief purpose]"
prompt: "[detailed instructions for subagent C]"

サブエージェントがデフォルトでフォアグラウンド実行される Claude Code のバージョンでは、各呼び出しに run_in_background: true を追加します。

ステップ 4：結果を収集する

各サブエージェントは、完了時に最終結果を親の会話へ自動的に返します。統合する前に、すべてのサブエージェントから報告が届くまで待ちます。ポーリングは行わず、依存する作業を早まって開始しないでください。（別途呼び出す TaskOutput は非推奨です。）

ステップ 5：結果を統合する

すべてのサブエージェントの出力をまとめ、統一された結果を作成します。

• 関連する調査結果を統合する
• 推奨事項間の矛盾を解決する
• 重大度や重要度に基づいて優先順位を付ける
• 実行可能な要約を作成する

動的なサブエージェントのパターン

パターン 1：タスクベースの並列化

実装するタスクが N 個ある場合、N 個のサブエージェントを起動します。

Plan:
1. Implement auth module
2. Create API endpoints
3. Add database schema
4. Write unit tests
5. Update documentation

Wave 1 - spawn 3 subagents (independent of each other):
- Subagent 1: Implements auth module
- Subagent 2: Creates API endpoints
- Subagent 3: Adds database schema

Wave 2 - after wave 1 has finished (these depend on its output):
- Subagent 4: Writes unit tests
- Subagent 5: Updates documentation

パターン 2：ディレクトリベースの並列化

複数のディレクトリを同時に分析します。

Directories: src/auth, src/api, src/db

Spawn 3 subagents:
- Subagent 1: Analyzes src/auth
- Subagent 2: Analyzes src/api
- Subagent 3: Analyzes src/db

パターン 3：視点ベースの並列化

複数の観点から同時にレビューします。

Perspectives: Security, Performance, Testing, Architecture

Spawn 4 subagents:
- Subagent 1: Security review
- Subagent 2: Performance analysis
- Subagent 3: Test coverage review
- Subagent 4: Architecture assessment

タスクリストとの連携

並列実行を使用する場合、タスクの追跡（TaskCreate／TaskUpdate、または古いバージョンでの TodoWrite）の方法が異なります。

逐次実行：一度に in_progress にできるタスクは 1 つのみです
並列実行：複数のタスクを同時に in_progress にできます

# Before launching parallel tasks
todos = [
  { content: "Task A", status: "in_progress" },
  { content: "Task B", status: "in_progress" },
  { content: "Task C", status: "in_progress" },
  { content: "Synthesize results", status: "pending" }
]

# As each subagent reports back, mark its task completed
todos = [
  { content: "Task A", status: "completed" },
  { content: "Task B", status: "completed" },
  { content: "Task C", status: "completed" },
  { content: "Synthesize results", status: "in_progress" }
]

並列実行を使用する場面

適したタスク：

• 複数の独立した分析（コードレビュー、セキュリティ、テスト）
• ファイルごとに独立している複数ファイルの処理
• 異なる視点で行う探索的なタスク
• 異なる項目を確認する検証タスク
• 独立したコンポーネントの機能実装

並列化を避ける場合：

• タスク間に依存関係がある（タスク B がタスク A の出力を必要とする）
• 逐次ワークフローが必要（コミット -> プッシュ -> PR）
• タスクが同じファイルを変更する（競合のリスクがある）
• 正確性を保つために順序が重要

パフォーマンス上の利点

方法	5 個のタスクを各 30 秒で実行	合計時間
逐次実行	30秒 + 30秒 + 30秒 + 30秒 + 30秒	約150秒
並列実行	5 個すべてを同時に実行	約30秒

並列実行では、独立したタスク数を N とすると、およそ N 倍高速になります。

例：機能の実装

ユーザーのリクエスト：「ログイン、登録、パスワードリセットを含むユーザー認証を実装する」

オーケストレーターが計画を作成：

1. ログインエンドポイントを実装する
2. 登録エンドポイントを実装する
3. パスワードリセットエンドポイントを実装する
4. 認証ミドルウェアを追加する
5. 統合テストを作成する

並列実行：

Wave 1 - launching 4 subagents in parallel:

[Agent 1] Login endpoint implementation
[Agent 2] Registration endpoint implementation
[Agent 3] Password reset endpoint implementation
[Agent 4] Auth middleware implementation

[Results arrive as each subagent finishes]

Wave 2 - depends on wave 1:

[Agent 5] Integration test writing

[Synthesize into cohesive implementation]

トラブルシューティング

タスクが順番に実行されていますか？

• すべての Agent 呼び出しが単一のメッセージ内にあることを確認してください
• 古いバージョンの Claude Code を使用している場合は、それぞれに run_in_background: true が設定されていることを確認してください

結果を確認できませんか？

• 結果は各サブエージェントの完了時に届きます。すべてのサブエージェントが完了するまでお待ちください
• 権限を拒否されたサブエージェントは、作業を完了せずに戻る場合があります。レポートを確認してください

出力に競合がありますか？

• タスクで同じファイルを変更しないようにしてください
• 統合の手順に競合解決を追加してください