並列処理 — Subagents と Agent Teams

7.1なぜ並列処理が必要か

Claude Codeの通常の動作はシングルスレッドだ。メインの会話が1本のコンテキストウィンドウ（AIモデルが一度に「読める」情報量の上限）の中で、調査→実装→検証を順番に回していく。このモデルは多くの場面で十分に機能するが、次の3つの壁にぶつかる場面がある。

壁①：コンテキストウィンドウの枯渇

大量のファイルを読んだり、テストスイート全体を実行したりすると、そのログだけでコンテキストの大半を消費してしまう。たとえばテスト結果が数千行に及ぶ場合、本来やりたかった「原因分析→修正→再テスト」のための余地が残らない。

壁②：大規模タスクの効率

10個のモジュールをリファクタリングする場合、1つずつ順番に処理するのは非効率だ。各モジュールが独立しているなら、同時に複数のモジュールを処理したほうが圧倒的に速い。

壁③：専門化による品質向上

コードレビューを例に取ると、1人のレビュアーはセキュリティの問題を見つけ始めると、パフォーマンスの問題を見落としがちになる。セキュリティ専門、パフォーマンス専門、テストカバレッジ専門のレビュアーが同時に動けば、各領域を深く分析できる。

Claude Codeはこの3つの壁を突破するために、2つの並列処理メカニズムを提供する。軽量なサブエージェント（Subagent）と、重量級のAgent Teamsだ。以降のセクションでそれぞれを詳しく見ていく。

7.3Agent Teams — 複数セッションの協調

Agent Teamsは、サブエージェントとは根本的に異なるアプローチだ。サブエージェントが「メインセッション内の作業員」であるのに対し、Agent Teamsは完全に独立した複数のClaude Codeセッションがチームとして協調する仕組みだ。

チームは3つの要素で構成される。チームリード（タスクの作成・割り当てを行うメインセッション）、チームメイト（それぞれが独立したClaude Codeインスタンス）、そして共有タスクリスト（全メンバーが参照・更新できる作業一覧）だ。加えて、メールボックス（Mailbox）によるエージェント間のメッセージ通信も備える。

有効化と起動

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

有効化した後は、自然言語でチームの作成を指示するだけでよい。

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage

タスクリスト共有と自己協調

Agent Teamsの中核メカニズムは共有タスクリストだ。リードが作業をタスクに分解し、チームメイトがそれを自発的に取得（セルフクレーム）する。タスクには3つの状態がある — 待機中（pending）、進行中（in progress）、完了（completed）。タスク間に依存関係を設定でき、依存先が完了するまでブロックされる仕組みだ。

複数のチームメイトが同じタスクを同時に取得しようとする競合状態を防ぐため、ファイルロックが使われている。

ピアツーピアメッセージング

サブエージェントとの最大の違いがここにある。サブエージェントはメインにしか結果を返せないが、Agent Teamsのチームメイトは互いに直接メッセージを送り合える。たとえば、セキュリティレビュアーが認証ロジックの問題を発見したとき、パフォーマンスレビュアーに「この認証処理、N+1クエリ問題も起きてない？」と直接確認できる。

メッセージの種類はmessage（特定の1人に送信）とbroadcast（全員に一斉送信）の2つ。broadcastはチームサイズに比例してコストが増えるため、使用は控えめにすべきだ。

表示モード

品質ゲートの適用

Hookを使って、チームメイトの作業完了時に自動検証を挟める。TeammateIdleフック（チームメイトがアイドル状態になるとき発火）で終了コード2を返すと、フィードバックを送って作業を続行させる。TaskCompletedフック（タスク完了マーク時に発火）で終了コード2を返すと、完了を阻止してやり直しを指示できる。

7.5実践的な設計パターン

パターン①：調査タスクの委任（Subagent）

最も頻出するパターンだ。大量のファイルを読んで要約だけ返させる。

テストスイートの全ログはサブエージェントのコンテキスト内に閉じ込められ、メインには失敗テストのリストと原因だけが返る。メインのコンテキストは数千トークンの節約になる。

同様に「認証モジュール、データベースモジュール、APIモジュールを別々のサブエージェントで同時に調査」と指示すれば、3つの調査が並列で走り、それぞれの要約がメインに集約される。

パターン②：並列コードレビュー（Agent Teams）

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

各レビュアーが同じPRを異なる視点でレビューする。単一のレビュアーだと、セキュリティの問題を見つけ始めるとパフォーマンスの問題を見落としがちになるが、専門化されたチームメイトはそれぞれの領域を深く分析し、リードが結果を統合する。

パターン③：競合仮説デバッグ（Agent Teams）

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses.
Have them talk to each other to try to disprove each other's theories,
like a scientific debate.

これがAgent Teamsの最も強力な使い方だ。各チームメイトが異なる仮説を持ち、互いの理論に反論しながら検証する。反証に耐えた仮説が真の原因である確率が格段に高くなる。

パターン④：新機能の分担開発（Agent Teams）

フロントエンド、バックエンドAPI、テストをそれぞれ別のチームメイトが担当するパターン。各チームメイトが担当ファイルを持ち、ファイル競合が起きないように分担する。チーム規模は3〜5人が最適とされ、これ以上増やしても協調コストが増えるだけで効率は上がらない。各チームメイトに5〜6タスクを割り当てるのが理想的なバランスだ。

パターン⑤：サブエージェントのチェーン（Subagent）

サブエージェントはネストできないが、メインの会話から順番に呼び出す「チェーン」は可能だ。最初のサブエージェントが問題を特定し、その結果をメインが受け取り、次のサブエージェントに修正を委任する。各フェーズの詳細なログはそれぞれのサブエージェントのコンテキストに閉じ込められる。

設計時のチェックリスト

並列処理を導入する前に、以下の観点で検討するとよい。

Series Navigation

他シリーズの関連ガイド