Claude Code Task tool のサブエージェント並列実行——仕組みと上限の実際

Claude Code を動かしていると、Claude 自身が Task tool を呼び出し、複数のサブエージェントを起動して並列で作業を進める場面があります。「どういう仕組みで動いているのか」「同時にいくつまで動けるのか」「失敗したらどうなるのか」——この記事は、定義・仕組み・具体例・注意点の順でそれに答えます。

Task tool とは何か

Claude Code には Bash、Read、Write、Glob、Grep などの組み込みツールが複数あります。Task tool はその一つで、親エージェント（現在のセッションの Claude）が新しいサブエージェントを起動するためのツールです。

呼び出しのイメージを示すと次のようになります。

Task(
  description="src/ 以下の TypeScript を型チェックして結果を報告",
  prompt="以下の指示に従って作業してください..."
)

Task tool はユーザーがコマンドラインから直接呼び出すものではありません。Claude が複雑な指示を受けたとき、自分の判断で「ここは並列で処理できる」と見なしてこのツールを使います。ユーザーの側にできるのは、どう分割してほしいかをプロンプトで誘導することです。

サブエージェントとコンテキストの独立性

重要なのは、サブエージェントは独立したコンテキストウィンドウを持つという点です。親セッションで積み重なってきた会話履歴は引き継がれません。サブエージェントは「親から渡されたプロンプト」だけを見て動作します。

この独立性は二つの意味を持ちます。一つは軽量に起動できること。もう一つはサブエージェントが親の文脈を知らないこと——サブエージェントが動くために必要な情報はすべて Task のプロンプトに書かなければなりません。「このリポジトリのルールで」と親セッションで共有した前提は、サブエージェントには届いていません。

並列実行の仕組みと実際の流れ

Task tool の最大の特徴は複数のサブエージェントを並列で走らせられることです。

例として「このリポジトリの TypeScript ファイルを全ディレクトリ横断で型チェックし、エラーをまとめてほしい」と指示したとします。親エージェントは次のように複数の Task を発行するかもしれません。

親エージェント
├─ Task("src/components/ を担当") → サブエージェント①
├─ Task("src/lib/ を担当")        → サブエージェント②
└─ Task("src/pages/ を担当")      → サブエージェント③
         ↓（全サブが完了するまで待機）
   結果を統合して次の処理へ

サブエージェント①〜③はそれぞれ独立して Bash（tsc --noEmit や eslint）を実行します。すべてが終わると親エージェントが結果を受け取り、整理します。

並列化が効くのは互いに依存関係がない作業に限られます。「①の出力を使って②が動く」という順序依存がある場合、②は①が終わるまで実質的に待機します。Claude がどちらの方式を選ぶかはプロンプトの内容と Claude 自身の判断によります。

外部スクリプトからの並列呼び出しとの違い

私は Claude Code CLI（claude -p）を Python の subprocess から呼び出して記事生成をバッチ化しています。これは「外部から独立したセッションを並列に立ち上げる」方式で、Task tool の仕組みとは別物です。

Task tool は Claude 自身が管理するためタスク間の調整が自然に行われます。外部スクリプトで並列化する場合は、結果の集約とエラー処理をスクリプト側で作り込む必要があります。

公式が定める上限と制約

公式ドキュメントによると、Task tool にはシステム的な上限があります。具体的な数値はバージョンアップで変わる可能性があるため、Anthropic 公式ドキュメント で最新の値を確認してください。ここでは制約の種類と傾向を整理します。

同時起動数の上限：1 つの親エージェントセッションが同時に持てるサブエージェント数には上限があります。上限に達した場合、新たな Task は実行中のサブエージェントが終わり次第処理されると考えられます。

API レートリミット：各サブエージェントは独立した API 呼び出しを行います。並列数が増えるほど短時間のリクエスト数が増え、Anthropic API のレートリミット（429 Too Many Requests）に当たる可能性があります。利用プランのレートリミットを事前に確認しておくことが重要です。

コンテキスト長の制限：各サブエージェントは独立したコンテキストウィンドウを持ちます。プロンプトが長大になるほど早く上限に達するため、Task に与える指示は役割を絞って簡潔にするのが基本です。

実際の挙動で気をつけること

ファイルの競合書き込み

サブエージェント同士は互いの状態を知りません。複数のサブエージェントが同じファイルを書き換えると、後から書いた方で上書きされます。Task tool にはロック機構が備わっていないと考えられるため、担当するファイルやディレクトリが重ならないように Task を設計するのが実質的な対策です。

たとえばコンポーネントを並列で書き換えるなら「サブエージェント①は Button.tsx、②は Form.tsx」のようにファイル単位で担当を明確に分けます。あるいは、書き換え作業は直列の一本のサブエージェントに任せ、調査・報告だけを並列化するという方針も有効です。

エラーとタイムアウト

サブエージェントがエラーを返した場合、親エージェントはその結果を受け取って次の処理を判断します。一方、外部コマンドの実行が長引いてサブエージェントが応答を返さない場合、親エージェントが長時間待ち続けることがあります。長時間かかる可能性のある Task には、プロンプト内に「〇分以内に完了しなければ途中経過を報告して終了する」といった指示を入れておくと安全です。

コスト

並列サブエージェントはそれぞれ独立したコンテキストを持つため、直列処理より合計トークン消費が増えます。速度が上がる半面、費用も増加します。まず 2〜3 個の小規模な並列 Task から始め、費用と速度のバランスを手元で確認してから規模を広げるのが無難です。

なお、Claude Code の設定ファイルまわりのトラブルが Task の挙動に影響するケースがあります。設定関連で詰まった場合は Claude Code MCP サーバー接続失敗の原因と設定ファイルの読み方 も参考にしてください。

まとめ

Task tool は親エージェントがサブエージェントを起動して並列処理を実現する仕組みです。互いに依存しない作業を複数のサブエージェントに分散させることで処理を高速化できますが、同時起動数の上限・API レートリミット・ファイル競合・費用増加という 4 つの制約があります。

次に取る行動：まず Anthropic の公式ドキュメントで現時点の並列上限と、ご自身のプランのレートリミットを確認する。そのうえで小さな並列タスク（2〜3 個）を実際に動かして挙動とコストを観察し、その結果をもとに本番のタスク設計へ進むのが最短ルートです。