Claude Code SubAgentで並列処理を実装｜複数エージェントの定義と発火手順

大きめのタスクを Claude Code に丸ごと任せると、調査結果やログ、ファイルの中身が次々と会話に積み上がり、いつの間にかコンテキストが膨らんで応答の精度が落ちる——複数モジュールの横断調査や、観点の異なるレビューを1セッションで回そうとして、こうした「コンテキスト溢れ」に悩まされた経験はないでしょうか。

「並列にエージェントを動かせば解決しそう」と気づいて調べ始めても、実際には壁にぶつかりがちです。SubAgent や並列処理という言葉は公式ドキュメントや解説記事で頻繁に見かけるものの、いざ自分のプロジェクトで「どこに何を定義して、どう指示を出せば、本当に並列で動くのか」となると、途端に曖昧になります。やみくもに並列化して逆に遅くなったり、コンテキストが溢れたり、複数の結果が混ざって収拾がつかなくなったりしないか——その不安が、最初の一歩を踏みとどまらせます。

実は Claude Code の並列処理でつまずく多くのケースは、「SubAgent の定義の書き方」と「確実に並列で発火させる指示の出し方」、そして「並列にすべきか逐次にすべきかの判断」という3点を押さえれば、ほとんど解消できます。並列化は速度のためだけの機能ではなく、各 SubAgent が独立したコンテキストで動くことで、親会話を汚さずに精度を保つ仕組みでもあります。

本記事では、Claude Code SubAgent を使ったマルチエージェント並列処理を、手を動かせるレベルで実装する手順を解説します。.claude/agents/ への定義方法から、1メッセージで複数の SubAgent を確実に並列ファンアウトさせる指示の書き方、並列と逐次の判断軸、そしてコンテキスト圧迫やネスト制約といった落とし穴の回避策まで、「最初の一歩」を踏み出すために必要な実装目線の知識を整理します。

Claude Code の SubAgent とは｜マルチエージェント並列処理の前提

Claude Code SubAgent（サブエージェント）とは、独自のコンテキストウィンドウ・専用のシステムプロンプト・限定されたツール権限を持つ、特定タスク委任用のエージェントです。メインの会話（以下「親会話」）が抱えるタスクのうち、独立して進められる作業を切り出し、別のエージェントに任せる仕組みだと考えるとイメージしやすいでしょう。マルチエージェントの並列処理は、この SubAgent を複数同時に走らせることで実現します。

公式ドキュメントは SubAgent を「副次的なタスクが検索結果・ログ・ファイルの中身で親会話を溢れさせてしまうとき、その作業を SubAgent 自身のコンテキスト内でこなし、要約だけを返す」ための機能と位置づけています（Claude Code 公式ドキュメント: Create custom subagents）。つまり並列処理の話で SubAgent が登場するのは、単に速くするためだけではなく、独立したタスクを親会話のコンテキストを汚さずに別ウィンドウで同時に走らせられるからです。

SubAgent が解決する課題

SubAgent は、おもに次の課題を解決します。冒頭で触れた「1セッションでコンテキストが溢れて精度が落ちる」という悩みは、この一つ目に直結します。

• コンテキストの保全: 調査・探索・実装といった作業を親会話の外に追い出し、メインの会話を要約だけで保つ。verbose な出力（テスト結果・ログ・大量のファイル参照）を SubAgent 側に閉じ込められる
• 制約の強制: SubAgent が使えるツールを限定することで、たとえば「読み取り専用のリサーチャー」のように、意図しないファイル書き込みを物理的に防げる
• 設定の再利用: ユーザーレベルに定義すれば、すべてのプロジェクトで同じ SubAgent を使い回せる
• コストの制御: 軽い作業を Haiku など高速・低コストのモデルに振り分けられる

並列処理で何が変わるか

ここからが本題です。公式ドキュメントは「親セッションは複数の SubAgent を一度に起動でき、それぞれが並行して動き、すべての結果が揃った時点で親セッションが再開する」と明記しています。各 SubAgent はそれぞれ独自のコンテキストを持つため、互いの探索内容が混ざりません。

たとえば「認証モジュール」「データベースモジュール」「API モジュール」を別々の SubAgent に同時調査させると、3つの調査が並行して進み、それぞれの結果（要約）だけが親会話に戻り、Claude がそれらを統合します。1セッションで3モジュールを順番に調べるよりコンテキストの消費を抑えられ、独立した作業であれば所要時間も短縮できます。「並列にすれば解決しそう」という直感は、この点では正しいのです。

用語整理 — SubAgent / 並列ファンアウト / Agent Teams の関係

並列処理まわりには似た用語が複数あり、最初は混乱しがちです。深入りはせず、地図だけ示しておきます。

• SubAgent: 単一セッション内で動く委任先エージェント。本記事の主役。複数同時に起動できる
• 並列ファンアウト: 1つの親会話から複数の SubAgent を同時に枝分かれ（ファンアウト）させ、独立タスクを並行処理する使い方。本記事で実装する中心パターン
• Agent Teams: 互いに通信し合う独立セッションを束ねる、より大規模な仕組み。SubAgent では足りない持続的な並列性が必要になったときの選択肢
• Dynamic Workflow: 決定論的なステップ順序や大規模なファンアウトを、スクリプトとして恒常的に運用するための仕組み

SubAgent は「単一セッション内の並列」、Agent Teams は「複数セッションをまたぐ並列」という違いを押さえておけば十分です。さらに大規模・恒常的なオーケストレーションが必要になったときの選択肢については、Claude Code Dynamic Workflowとは｜サブエージェントとの違いと使い分けで SubAgent との違いを整理しています。本記事ではまず、SubAgent そのものの並列実装に集中します。

SubAgent の定義方法｜.claude/agents/ とフロントマターの書き方

並列で動かす前に、そもそも SubAgent をどう定義するかを押さえます。ここが曖昧なまま並列化の話に進むと「呼び出すエージェントが存在しない」という状態になりかねません。手を動かせるレベルで、置き場所・フロントマター・最小サンプルの順に見ていきます。

置き場所とスコープ（project / user の使い分け）

SubAgent は YAML フロントマター付きの Markdown ファイルとして定義し、置き場所によってスコープが決まります。主要な2か所は次のとおりです。

公式ドキュメントは、同じ名前の SubAgent が複数の場所に存在する場合、優先順位の高い場所が勝つと説明しています。優先順位は managed settings（組織配布）> --agents CLI フラグ > プロジェクト .claude/agents/ > ユーザー ~/.claude/agents/ > プラグインの順です。チームで共有したい SubAgent はプロジェクトの .claude/agents/ に置き、version control にコミットするのが推奨されています。

なお SubAgent の識別子（呼び出し名）はファイル名ではなく、フロントマターの name フィールドで決まります。.claude/agents/review/ のようにサブフォルダで整理しても呼び出し名には影響しませんが、同一スコープ内で name が重複すると警告なしに片方が破棄されるため、name はツリー全体で一意にしてください。

フロントマター項目の読み方

フロントマターで設定できる項目のうち、必須は name と description の2つだけです。実務でよく使う任意項目を含めて整理します。

ここで重要なのは、フロントマターの下に書いた Markdown 本文がそのまま SubAgent のシステムプロンプトになるという点です。SubAgent は Claude Code の完全なシステムプロンプトではなく、この本文（と作業ディレクトリなど最小限の環境情報）だけを受け取ります。つまり「この SubAgent にどう振る舞ってほしいか」を本文に書き切る必要があります。

最小の定義例 — 読み取り専用リサーチャー

並列調査でまず欲しくなるのが、ファイルを書き換えない「読み取り専用リサーチャー」です。tools を絞ることで、調査中に誤って書き込みが発生する事故を物理的に防げます。次の内容を .claude/agents/researcher.md として保存します。

---
name: researcher
description: コードベースの調査専門。指定された範囲を読み取り、要点だけを要約して返す。実装やレビューには使わない
tools: Read, Grep, Glob
model: haiku
---

あなたはコードベースの調査担当です。

依頼されたら:
1. 指定された範囲のファイルを Read / Grep / Glob で調べる
2. 関係するファイルパスと、その役割・依存関係を把握する
3. 親会話に返すのは「要約」のみ。ファイルの全文や長いログは貼らない

返す内容:
- 調べた範囲の概要（3〜5行）
- 関係するファイルと役割の一覧
- 注意点・気づいた懸念

tools: Read, Grep, Glob と書いているため、この SubAgent は Write も Edit もできません。model: haiku で軽量モデルを指定し、調査のような大量処理をコスト効率よく回せるようにしています。本文がシステムプロンプトとして働き、「要約だけを返す」という制約も明文化されています。要約だけを返す設計は、のちほど触れるコンテキスト圧迫の回避にも効いてきます。

/agents コマンドでの作成と反映タイミング

ファイルを手書きする以外に、/agents コマンドで対話的に作成する方法もあります。/agents を実行すると SubAgent 管理の画面が開き、「Library」タブから新規作成・編集・削除ができます。説明文を伝えると Claude が識別子・description・システムプロンプトを生成してくれるため、初めての1つを作るには手軽です。

反映タイミングには注意点があります。/agents インターフェース経由で作成した SubAgent は即座に有効になりますが、ファイルをエディタで直接追加・編集した場合はセッションを再起動しないと読み込まれません。手書き派の人がよくつまずくポイントなので覚えておきましょう。

複数の SubAgent を並列で動かす｜並列ファンアウトの実装手順

ここが本記事の核心です。SubAgent を定義できたら、次は「複数を確実に並列で発火させる」段階に進みます。多くの解説記事が「並列で速い」という結果は語るものの、実は何も指定しないと並列にならないことがあります。その理由から押さえていきます。

なぜ「並列で」と明示しないと並列にならないのか

公式ドキュメントおよび実装者向けの解説では、Claude はデフォルトで並列性に対して保守的だと明記されています（Subagents and Multi-Agent Orchestration Guide（hidekazu-konishi、2026年））。つまり、ただ「3つのモジュールを調べて」と頼むだけでは、Claude が安全側に倒して逐次的に1つずつ調べてしまうことがあります。「並列にしたつもりが実は順番に動いていた」という空振りは、ここが原因で起こります。

対策はシンプルで、並列で動かしたいことと、いくつの SubAgent に分けるかを明示的に依頼することです。エージェントの分割数を具体的に言葉にすると、Claude が並列ファンアウトと解釈しやすくなります。

並列ファンアウトの指示例

独立した調査タスクを同時に走らせる場合の指示は、自然言語で構いません。特別な構文は不要です。公式ドキュメントが挙げている例がそのまま実用になります。

認証モジュール・データベースモジュール・API モジュールを、
それぞれ別々の SubAgent を使って並列に調査してください。

ポイントは2つです。1つ目は「別々の SubAgent を使って」と分割を明示していること、2つ目は対象を3つ列挙して並列数を暗に示していることです。各 SubAgent がそれぞれの領域を独立して調べ、終わったら Claude が3つの調査結果（要約）を統合します。この使い方は、調査経路が互いに依存しないときに最も効果を発揮します。

先ほど定義した読み取り専用リサーチャーを明示的に使わせるなら、次のように書きます。

researcher サブエージェントを3つ並列で起動して、
auth / db / api の各ディレクトリを同時に調査させてください。
それぞれ要約だけを返すようにしてください。

ロールパネル型レビュー（同一対象を複数観点で同時に）

並列ファンアウトには、もう一つ実用的な型があります。同じ対象を、観点の異なる複数の SubAgent が並行してレビューする「ロールパネル型」です。たとえばセキュリティ・コードスタイル・テストカバレッジという3つの観点を、それぞれ専門の SubAgent に同時にチェックさせ、結果を統合します。

このプルリクエストの差分を、3つの SubAgent で並列にレビューしてください。
1つ目はセキュリティ観点、2つ目はコードスタイル観点、3つ目はテストカバレッジ観点でお願いします。

1人のレビュアーが順番に全観点を見るより、それぞれが専門の視点に集中するため、単一レビューでは見落としがちな問題を拾いやすくなります。観点ごとに description とシステムプロンプトを書き分けた SubAgent を用意しておくと、自動委任もしやすくなります。

前景実行と背景実行の違いと使い分け

SubAgent は前景（foreground）でも背景（background）でも動かせます。挙動が異なるため、使い分けを理解しておきましょう。

• 前景実行: 完了するまで親会話をブロックする。権限プロンプトはその都度こちらに渡され、対話的に許可を判断できる
• 背景実行: 親会話を続けながら並行して動く。セッションですでに付与済みの権限で実行し、プロンプトが必要になる操作は自動的に拒否する

Claude はタスクに応じて前景・背景を自動で選びますが、「これはバックグラウンドで動かして」と頼んだり、実行中のタスクを Ctrl+B で背景に回したりもできます。背景実行は権限プロンプトを自動拒否する点が落とし穴になりやすいので、これは後ほどの落とし穴の章で改めて触れます。

並列にすべきか逐次にすべきか｜タスク分割の判断基準

並列ファンアウトを覚えると、つい何でも並列にしたくなります。しかし、やみくもな並列化はかえって非効率や混乱を招きます。ここでは「並列にすべきか、逐次にすべきか」を自分のタスクに当てはめて判断できるよう、基準を整理します。検索後の理想状態である「自分で判断できる」状態に直結する部分です。

並列に向くタスク・向かないタスクのチェックリスト

判断の軸はシンプルで、タスク間に依存関係があるかどうかです。次のチェックリストで切り分けられます。

並列ファンアウトに向く（独立している）

• 各タスクの入力が、他のタスクの出力に依存していない
• 異なるモジュール・異なる観点を、それぞれ独立して調べる/レビューする
• 各タスクが verbose な出力を生むため、親会話の外に追い出したい
• 「2人の担当者に同時に渡しても成立する」と直感的に思える

逐次パイプラインに向く（依存している）

• 前段の出力が、次段の入力になる
• 「まず調べてから直す」「計画してから実装する」のように順序が必須
• 後段の処理が前段の結論を前提にしている

「2人の人間に同時に渡せるか」という直感的な目安は、判断に迷ったときに有効です。同時に渡して片方がもう片方の結果を待つことになるなら、それは逐次にすべきタスクです。

逐次パイプライン（計画→生成→評価）の実装例

依存関係があるタスクは、SubAgent を順番につなぐパイプラインとして実装します。各 SubAgent が処理を終えて結果を返し、Claude がその関連コンテキストを次の SubAgent に渡します。公式ドキュメントが挙げる例がそのまま使えます。

code-reviewer サブエージェントでパフォーマンス上の問題を洗い出し、
そのあと optimizer サブエージェントでそれらを修正してください。

この場合、レビュー結果（=前段の出力）が修正対象（=次段の入力）になるため、並列にはできません。「計画→生成→評価」のような多段のワークフローも、同じく逐次でつなぎます。並列ファンアウトとパイプラインは対立する概念ではなく、依存関係の有無で使い分けるものだと捉えてください。

plan mode で依存関係を先に整理してから投げる

大きなタスクでは、どこが独立していてどこに依存があるのかが、最初は見通せないことがあります。そんなときは plan mode（計画モード）で依存関係を先に整理し、独立した部分を切り出してから並列に投げると安全です。

plan mode は読み取り専用で探索を行い、編集前に計画を提示します。ここで「この調査群は独立しているから並列ファンアウト、この実装は前段の設計に依存するから逐次」と分解しておけば、空振りの並列化や、依存を無視した並列実行による手戻りを防げます。判断に迷ったら、まず計画を立ててから並列化する——これが安全な進め方です。

つまずきやすいポイントと回避策｜並列処理の落とし穴

最後に、並列処理で実際にハマりやすいポイントと回避策を、独立した章としてまとめます。「破綻しないか不安で踏み出せない」という気持ちは、起こりうる失敗と対処をあらかじめ知っておくことで軽くなります。いずれも公式ドキュメントが明示している実務上の注意点です。

「SubAgent は SubAgent を生成できない」

最も重要な構造上の制約です。公式ドキュメントは「SubAgent は他の SubAgent を生成できない。入れ子の委任は存在しない」と明言しています。これは無限のネストを防ぐための仕様です。

実装上の意味は、オーケストレーション（誰がどの作業をするかの差配）は必ず親会話に集約されるということです。「SubAgent A の中からさらに B・C を並列起動して……」という多段の並列化はできません。多段にしたい場合は、親会話が指揮者となってすべての SubAgent を直接さばくか、依存関係があるならパイプラインでつなぎます。並列ファンアウトもロールパネルも、起点はつねに親会話だと覚えておけば、設計で迷いません。

並列実行とコンテキスト圧迫

並列化はコンテキスト保全のための機能ですが、皮肉なことにやりすぎると逆に親会話のコンテキストを圧迫します。各 SubAgent の最終メッセージは、ツール結果として親会話に戻ってきます。公式ドキュメントも「多数の SubAgent がそれぞれ詳細な結果を返すと、守ろうとしていたウィンドウ自体を埋めてしまいかねない」と警告しています。

回避策は2つです。1つ目は、各 SubAgent に「要約だけを返す」よう指示し、全文やトランスクリプトを返させないこと。先ほど定義した読み取り専用リサーチャーの本文に「要約のみを返す」と書いたのは、まさにこの圧迫を防ぐためです。2つ目は、持続的な並列性や大量のワーカーが必要でコンテキストに収まらない規模になったら、各ワーカーが独立したコンテキストを持つ Agent Teams への切り替えを検討することです。SubAgent で無理に多数を並列化するより、規模に応じて道具を替えるほうが破綻しません。

ツール権限の絞り込み（事故防止）

SubAgent は、tools も disallowedTools も指定しないと親会話の全ツールを継承します。つまり調査だけさせたいつもりの SubAgent が、意図せずファイルを書き換えられる状態になり得ます。並列で多数を走らせるときほど、1つの暴走が広範囲に影響しかねません。

回避策は、SubAgent ごとに必要最小限のツールへ絞ることです。読み取り専用にしたいなら tools: Read, Grep, Glob のように許可リストで絞るか、disallowedTools: Write, Edit のように書き込み系だけを拒否します。両方を指定した場合は disallowedTools が先に適用され、残ったツールに対して tools が解決されます。なお、ツール権限の継承を含む規約をプロジェクト全体で機械的に強制したい場合は、Claude Code hooksで規約を自動強制｜PreToolUse/PostToolUseの実装手順で、フックを使った検証の仕組みを解説しています。

反映タイミング・background 実行の細かな注意

最後に、見落としやすい細かな注意点を2つ挙げます。

1つ目は反映タイミングです。先述のとおり、SubAgent ファイルをエディタで直接追加・編集した場合は、セッションを再起動しないと読み込まれません。「定義したのに呼び出せない」ときは、まず再起動を疑ってください（/agents 経由の作成なら即時反映です）。

2つ目は背景実行の権限挙動です。背景で動く SubAgent は、セッションですでに付与済みの権限で実行し、プロンプトが必要になる操作は自動的に拒否します。もし背景 SubAgent が権限不足で失敗したら、同じタスクを前景の SubAgent として起動し直せば、対話的なプロンプトで許可を出しながらリトライできます。外部ツール連携で権限が絡む場面では、この挙動を知っておくと原因の切り分けが速くなります。MCP 経由で外部ツールを SubAgent に接続する設定については、Claude Code MCPの設定方法と開発ワークフローへの組み込み方【2026年版】が参考になります。

まとめ｜SubAgent 並列処理から次の一歩へ

Claude Code SubAgent を使った並列処理の実装を、定義から落とし穴回避まで一通り見てきました。要点を振り返ります。

• 定義: SubAgent は .claude/agents/（プロジェクト）または ~/.claude/agents/（ユーザー）に置く YAML フロントマター付き Markdown。必須項目は name と description の2つで、本文がそのままシステムプロンプトになる
• 並列発火: Claude はデフォルトで並列に保守的なため、「別々の SubAgent を使って並列に」と分割数を明示して依頼する。独立タスクは並列ファンアウト、同一対象の多観点チェックはロールパネル型
• 判断軸: タスク間に依存がなければ並列、前段の出力が次段の入力になるなら逐次パイプライン。「2人に同時に渡せるか」が直感的な目安
• 落とし穴: SubAgent は SubAgent を生成できない（指揮は親会話に集約）／多数の詳細結果は親コンテキストを圧迫するので要約に絞る／ツールは最小限に絞る／直接編集したら再起動が必要

最初の一歩はとてもシンプルです。まず .claude/agents/ に読み取り専用のリサーチャーを1つ置き、独立した調査を「別々の SubAgent で並列に」と頼んでみてください。並列ファンアウトが実際に動く感覚をつかめれば、「どこまで並列にし、どこは逐次にすべきか」を自分のタスクで判断できるようになります。

そして、SubAgent では収まらないほど持続的・大規模なオーケストレーションが必要になったら、独立セッションを束ねる Agent Teams や、決定論的なステップをスクリプトとして運用する仕組みへと発展させていく道があります。SubAgent とより大規模な仕組みの違いと使い分けは、Claude Code Dynamic Workflowとは｜サブエージェントとの違いと使い分けで整理しているので、次の一歩としてあわせてご覧ください。