Claude Code Subagents：エージェントチームをいつ、どのように実行するか

Last updated: June 28, 2026

Claude Codeのサブエージェントとは、メインのエージェントが特定のタスクのために立ち上げる独立したClaudeセッションであり、その結果をあなたの作業に折り込んでいくものです。先週は、リファクタリングをスキーマ、API、テストに分割するために3つのサブエージェントを並行して実行しました。これらは、単一の長いセッションで計画を立てるよりも早く完了しました。本記事では、サブエージェントの定義とディスパッチ方法、小規模なチームを模倣するためのオーケストレーションパターン、そしてサブエージェントが節約するコスト以上の費用がかかる正直な境界線について解説します。

クイックアンサー：Claude Codeサブエージェントとは？

サブエージェントは、独自のコンテキストウィンドウ、独自のシステムプロンプト、および限定されたツールセットを持つClaudeインスタンスです。メインセッションがサブエージェントを実行してもコンテキストを失うことはありません。なぜなら、サブエージェントは独立して作業し、要約のみを返すからです。これは、あなたの画面を遮断することのないチームメイトにタスクを委任するようなものです。

公式な仕組みはシンプルです。YAMLフロントマターを持つmarkdownファイルを.claude/agents/に配置するだけで、Taskツールがその説明と一致するタスクがある場合、Claude Codeがそれを呼び出すことができます。sub-agents documentation がフィールドの真の情報源であり、Claude Code repo が形式の変更を追跡しています。

最小限のサブエージェント定義は以下のようになります：

---
name: migration-writer
description: Writes and runs database migrations for this repo. Use for schema changes.
tools: Read, Edit, Bash
model: inherit
---
You are a migration specialist. Always check existing migrations first, never drop columns without a confirmation step, and run the migration against the local DB before reporting done.

このファイルが存在すると、私はメインエージェントに「use the migration-writer subagent to add the orders table」と尋ねます。そうすると、インラインで手間取る代わりに、スコープが限定されたワーカーをディスパッチしてくれます。model: inheritという行は、コストと品質をメインセッションと同等に保ちます。読み取りが多いサブエージェントに対して、haikuのようなより安価なモデルを固定することは、多くのサブエージェントを実行する際の大きなレバーとなります。

サブエージェントを使うべき時と単一セッションの場合の使い分けは？

タスクが長時間実行される、コンテキストを多く必要とする、またはメインセッションに含めたくないツールセットが必要な場合にはサブエージェントを使用してください。ジョブが短い、現在行っている作業と密接に関連している、またはあなたとの頻繁なやり取りが必要な場合は、単一のセッションで維持してください。

私は、ログや大量の読み込み、試行錯誤によってメインコンテキストを汚染しそうなジョブにサブエージェントを使用します。200個のファイルをgrepするようなコードベース全体の監査は完璧な候補です。なぜなら、サブエージェントがすべてを読み取り、私自身のメインセッションがクリーンなままで2パラグラフの要約を返してくれるからです。

エージェント自体が初めての場合は、サブエージェントを追加する前にClaude Code ultimate guideで基礎を学ぶことをお勧めします。

Claude Codeでサブエージェントはどのようにディスパッチするか？

ディスパッチには2つの方法があります。メインエージェントがタスクがサブエージェントの説明に合致する場合、自らTaskツールを呼び出すか、プロンプト内で明示的に名前を指定することができます。私は後者（明示的な指定）を好みます。なぜなら、暗黙的なディスパッチは、私が意図したエージェントをスキップすることがあるからです。

定期的に実行するパターンをいくつか紹介します：

• "Use the code-reviewer subagent on the diff in this branch, then apply its suggestions."
• "Dispatch migration-writer to add a users.email_verified column, and dispatch test-writer to cover it. Run both."
• "Spin up the api-docs subagent against src/routes/ and return only the OpenAPI skeleton."

サブエージェントは独自のコンテキスト内で実行されるため、プロンプトで詳細を渡さない限り、進行中の会話を見ることはできません。この隔離性がポイントです。完了すると、ストリーム状のノイズではなく、結果が返ってきます。

チームのようなワークフローのためのパターン

コツは、実際のチームがどのように作業を分割するかをコピーし、それぞれの役割をサブエージェントにマッピングすることです。私が繰り返し使うパターンを紹介します。

調査してから展開する (Research, then fan out)。 コンテキストを収集するために1つのサブエージェントをディスパッチし、その要約を読み取り、その後、共有インターフェースに対して複数の実装サブエージェントをディスパッチします。これは、テックリードがチケットを割り当てる前に作業範囲を定める状況を模倣しています。

契約に基づいて構築する (Build behind a contract)。 まずAPIまたはコンポーネントのpropsを定義し、次にその契約に対してバックエンドサブエージェントとフロントエンドサブエージェントを並行して実行します。どちらも互いをブロックすることはなく、異なるファイルを扱うため、競合が少ないのです。

別の役割としてレビューする (Review as a separate role)。 私は読み取り専用のツールのみを持つcode-reviewerサブエージェントを保持しています。非自明な変更の後には、必ずこれをdiffに対して実行します。ツールの制限をかけることで、文字通り編集できなくなり、レビューが正直になります。

このような反復的なワークフローの場合、サブエージェントとClaude Code skillsを組み合わせて使用するのが効果的です。スキルはステップをエンコードし、サブエージェントが隔離された作業を行います。また、サブエージェントが外部データにアクセスする必要がある場合は、Claude Code MCP integration guideで説明されているようにMCPサーバーに接続します。

実例：注文と支払い

先月、私は「注文＋支払い」の機能を3つのサブエージェントに分割し、型付けされた契約に基づいて作業を行いました。その契約は、status、totalCents、およびpaymentIdを持つOrderのための単一のTypeScriptインターフェースでした。私がディスパッチしたのは以下の通りです：注文の作成とステータス遷移を実装するためのバックエンドサブエージェント、Stripe呼び出しを接続しpaymentIdを保存する支払いサブエージェント、そしてハッピーパスと払い戻しのエッジケースをカバーするためのテストサブエージェント。すべてが異なるファイルを扱ったため、マージは競合解決セッションではなく、3回のクリーンなコピー＆ペースト操作で済みました。全体の実行時間は14分でしたが、同じ作業を前の週の単一のシリアルセッションで行うと41分かかってしまい、それは単一のコンテキストがStripeドキュメントを再読み込みし続けたためでした。

コンテキストを失わずに並行作業を行うには？

メインセッションはコーディネーターです。その仕事は、作業を分割し、スコープが限定されたプロンプトを配布し、結果を再びつなぎ合わせることです。コーディネーターをスリムに保ち、重い読み込み作業はサブエージェントに任せましょう。

私にとって典型的な並行実行の流れは以下の通りです：

1. メインセッションで契約とファイル境界を記述する。
2. それぞれが1つのスライスと明確な成功条件を持つ2〜4つのサブエージェントをディスパッチする。
3. 実行中にではなく、結果が返ってくるたびに各要約を読み取る。
4. メインセッションでマージを行い、シーム（継ぎ目）は自分で解決する。
5. 最後にテストサブエージェントを実行し、統合された結果に対して検証を行う。

並行処理が効果を発揮するのは、スライスが真に独立している場合のみです。もし2つのサブエージェントが両方ともschema.prismaを編集する場合、それは作業の分割ではなく、マージの問題を生み出しています。ファイルと契約で境界線を引き、プロンプト内でそれを強制してください。

サブエージェントが節約するコスト以上のオーバーヘッドとなるのはどんな時か？

サブエージェントは、レイテンシ（遅延）、トークン、および調整のコストを発生させます。要約による引き渡しでは詳細が失われるため、深い継続性が必要なものは不向きです。それらを使用する前に、トレードオフについて正直である必要があります。

以前、ある機能ブランチに対してベンチマークを実行しました。マイクロサービスごとにサブエージェントを立てる場合と、単一セッションで順番に処理する場合を比較したところ、5つの緩やかに結合されたサービスでは、並行処理がウォールクロック時間で約40%優位でした。しかし、データモデルを共有する3つのサービスの場合、単一セッションの方が速かったのですが、それはマージと再説明のプロセスが並行処理による利益を食い潰したためです。

教訓：並列性は独立性を報い、結合度が高いものを罰します。スライスが状態を共有している場合は、並列化しないでください。

よくある間違いは？

• サブエージェントが多すぎること。 私は1回の実行を3〜5個に制限しています。それ以上になると、調整コストが並行処理による利益を上回ります。
• プロンプトがあいまいなこと。 「Fix the auth」では失敗します。「Add a JWT refresh endpoint at /auth/refresh, returning { token }, with a test」は成功します。
• 成功基準がないこと。 何が「完了」を意味するのかを明記してください。「Migration applied locally and rollback tested」は、「handle the schema」よりも優れています。
• ツールセットが間違っていること。 レビュアーには読み取り専用のツールだけを与えてください。デプロイエージェントには、より広範なものではなく、必要な正確なコマンドを与えてください。
• 失敗を無視すること。 サブエージェントがエラーを返した場合、それを読んでください。盲目的に再試行するとトークンを浪費し、真の問題を隠蔽します。
• マージをスキップすること。 サブエージェントは結果を返しますが、統合の責任は依然としてあなたにあります。これに実際の時間を割り当ててください。

最も高価な間違いは、サブエージェントを何事にも無料の並列処理だと扱うことです。それらは要約という境界線の背後にあるスコープが限定されたワーカーであり、その境界線にはコストがかかります。

まとめ

サブエージェントは、Claude Codeを小規模なチームのようなものに変えます。それは、独自のコンテキストを持ち、結果を報告するスコープが限定されたワーカーをディスパッチするスリムなコーディネーターです。それらを.claude/agents/で定義し、Taskツールでディスパッチし、重い読み込み作業や反復的な役割をサブエージェントに押し付けることで、メインセッションをクリーンに保ちます。

作業が長く、コンテキストを多く必要とする、または制限されたツールセットが必要な場合にそれらを使用してください。要約による引き渡しで情報が失われすぎるような、短く結合度の高い対話的なタスクではスキップしてください。ファイルと契約で境界線を引き、実行回数を数個のエージェントに抑え、常に結果を自分でマージするための時間を予算化してください。

唯一の注意点：サブエージェントはスループットを増やすだけで、判断力そのものを増やすわけではありません。それらは4つの隔離されたコンテキストで間違ったものを並行して構築することに快