Claude Codeのサブエージェント完全活用 — Taskツールで作る並列開発パターン

要点

Claude Codeのサブエージェントは、メインの会話とは別のコンテキストウィンドウで動く子エージェントです。起動に使うのは Agent ツールで、メインに戻るのは最終報告だけ。調査の中間ログや大量のテスト出力が、メインの会話に残りません。

v2.1.63より前、このツールは Task という名前でした。タイトルの「Taskツール」はこの旧称にあたります。今も設定やエージェント定義に書かれた Task(...) は別名として動きますが、現行のツール名は Agent です。

並列に走らせるときは、次の3点が判断の軸になります。

• 何が子に渡るか: 会話履歴は渡りません。渡るのは委任メッセージと、CLAUDE.mdなどの起動時コンテキストです
• どこまで並べられるか: 同時に動かせる数と、入れ子にできる深さに上限があります
• どう戻ってくるか: フォアグラウンドかバックグラウンドかで、権限確認の出方と使えるツールが変わります

サブエージェントに何が渡り、何が渡らないか

サブエージェントは、毎回まっさらなコンテキストウィンドウで起動します。メインが読み込んだファイルも、呼び出し済みのスキルも、会話の流れも見えません。会話から引き継げるのは、メインが書いた委任メッセージだけです。

見落としやすいのは、組み込みの Explore と Plan がCLAUDE.mdを読まない点です。「vendor/ は無視する」のような規則を守らせたいなら、委任のプロンプトに書き直します。Claudeがその文面を組み立てるので、依頼するときに一言添えておくと渡ります。

会話履歴まで引き継ぎたい場合は、forkという別の種類があります。forkは親の会話をそのまま継承し、システムプロンプトも使えるツールも親と同じです。/subtask に続けてタスクを書くと、会話を分岐させてバックグラウンドで走らせられます。親とシステムプロンプトとツール定義が同一なので、最初のリクエストは親のプロンプトキャッシュを使い回せます。

claude コマンドの入口(v2.1.289の出力)

サブエージェントには、会話の中でClaudeに任せる使い方のほかに、起動時に定義を渡す入口があります。v2.1.289の claude --help には、次の記述があります。

claude --version
# 2.1.289 (Claude Code)
 
claude --help
#   --agents <json-or-file>  JSON object defining custom agents, or
#                            with --print the path to a file that
#                            holds one (e.g. '{"reviewer":
#                            {"description": "Reviews code",
#                            "prompt": "You are a code reviewer"}}')
#   --agent <agent>          Agent for the current session. Overrides
#                            the 'agent' setting.
 
claude agents --help
# Usage: claude agents [options]
#
# Manage background agents

名前が似た3つは、役割が別です。--agents はサブエージェントの定義を渡す引数、--agent は現在のセッション自体をそのエージェントとして動かす引数です。claude agents はサブエージェントではなく、バックグラウンドで動くエージェント(セッション)を管理するコマンドで、サブエージェントの並列実行とは別系統になります。

--agent で起動した本体は、tools に Agent(worker, researcher) のように書くと、起こせる子を限定できます。この許可リスト構文が効くのは、claude --agent で動くメインスレッドだけです。サブエージェントの定義の中では、括弧の中身は無視されます。

並列にするとぶつかる3つの上限

上限の20体に達すると、次の起動は Concurrent subagent limit reached で失敗します。Claudeには再試行しないよう伝わります。実行中の数が20を下回れば、また起動できます。上限は CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS で変えられ、v2.1.217以降が対象です。ultracodeを有効にしたセッションでは、この上限は適用されません。

入れ子の深さは CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で決まります。たとえば settings.json に次のように書くと、孫までに抑えられます。

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

1 を指定すると、サブエージェントが自分の子を起こせなくなります。この既定値は版で変わってきました。v2.1.172〜v2.1.216は5層まで、v2.1.217〜v2.1.218は1層、v2.1.219から3層です。古い記事やメモにある深さは、この履歴と突き合わせて読んでください。

上限より先に効いてくるのは、トークンです。公式のdocsでも、詳細な結果を返すサブエージェントを多数走らせると、メインのコンテキストを大きく消費すると注意されています。各サブエージェントも、実行中は自分のトークンを使います。サブエージェントのリクエストは、メインの会話と同じ使用量の枠に数えられます。

フォアグラウンドかバックグラウンドかで、権限確認と使えるツールが変わる

並列で走らせたのに期待どおりに動かないときは、フォアグラウンドとバックグラウンドの扱いの違いを疑います。Claude Codeは、Agentツールで起こした1体ごとに、次の順でフォアグラウンドかバックグラウンドかを決めます。

対話セッションの既定がバックグラウンドになる点は、並列パターンに直接響きます。バックグラウンドのサブエージェントは、権限が要る操作に当たると、メインのセッションに確認を出します。どのサブエージェントが求めているかも表示されます。許可すれば続行し、Escを押せばそのツール呼び出しだけを拒否できます。

バックグラウンドのサブエージェントは、使える組み込みツールも絞られます。Read / Grep / Glob / Bash / Edit / Write などは残り、定義の tools に書いたほかの組み込みツールは、通常はエラーなしで外されます。同じ定義が、フォアグラウンドとバックグラウンドで別のツールセットに解決されることがあります。

バックグラウンドで動くものは、実行中でも /tasks で見られます。完了したバックグラウンドのサブエージェントの行は、30秒間だけ /tasks に残ります。Ctrl+Bを押せば、実行中のタスクをバックグラウンドへ回せます。

5つの実用パターン

ここからは、並列と分離が効く場面を5つに分けます。

パターン1: 独立した観点を並列のExploreで調べる

認証・データベース・APIのように、互いに依存しない領域を調べるときに向きます。公式のdocsにある依頼文は、次のとおりです。

Research the authentication, database, and API modules in parallel using separate subagents

Explore は読み取り専用で、WriteとEditが拒否されます。並べても書き込みが衝突しません。調べる深さは、Claudeが呼び出し時に quick / medium / very thorough の3段階から選びます。

注意したいのは、結果の戻り方です。1体ごとの報告が長いと、戻ってきた要約がメインのコンテキストをふくらませます。観点を増やす前に、依頼文で「要約は何行以内」「結論とファイルパスだけ」のように、返す量を指定しておくと抑えられます。

パターン2: 出力が大量の作業を隔離する

テストの全件実行、ドキュメントの取得、ログの解析は、出力が長くなる作業です。サブエージェントに任せると、長い出力は子の中に留まり、メインには要約が返ります。

Use a subagent to run the test suite and report only the failing tests with their error messages

APIレスポンスの変種を何通りも試す検証も、同じ型です。向かないのは、途中経過を見ながら進路を直したい作業です。中間の出力はメインから見えないためです。

パターン3: 担当が分かれた実装を同時に進める

フロントエンド、APIエンドポイント、マイグレーションのように、触るファイルが分かれる実装は並行できます。担当ファイルが重なりそうなときは、定義の isolation に worktree を指定する選択肢があります。サブエージェントが、一時的なgit worktreeの中で、リポジトリの隔離コピーを使って作業します。

forkなら、Claudeが呼び出しで isolation: "worktree" を渡すと、forkの編集が別のworktreeに書かれます。ここで見落としがちなのは、worktreeの派生元です。既定では、親セッションのHEADではなく、既定ブランチから作られます。

パターン4: 調べる役と実装する役を分ける

大きな変更では、いきなり実装に入ると見落としが出やすくなります。調査は読み取り専用の子に任せ、実装は general-purpose に渡す分担があります。general-purpose は、サブエージェントが使えるすべてのツールを持つ汎用型です。

Plan は、実装計画を書き出す役ではありません。プランモードの間にコードベースを調べ、計画の材料を集める調査役です。計画を人間が確認してから実装に進む流れは、プランモードそのものが担います。実装を渡す段になったら、公式のdocsにある連鎖の形が使えます。

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

1体目の結果をClaudeが受け取り、必要な文脈を2体目に渡します。

パターン5: 読み取り専用のレビュアーを置く

実装を書いた本人より、独立したコンテキストの子に読ませると、書いた側が気づかなかった点が見つかることがあります。レビュアーはEditとWriteを持たせず、tools で絞ります。公式のdocsにある例の定義は、次のとおりです。

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

この定義は .claude/agents/ などに置きます。本文には、手順とチェックリストを書きます。description はClaudeが委任先を選ぶ根拠になるため、「いつ使うか」まで書いてあるのが肝です。判定基準を具体的に書かないと、観点が散漫になります。

3つのアンチパターン

アンチパターン1: 会話の流れを前提にした作業

サブエージェントは、呼び出しごとに新しいインスタンスです。ただし、終わった子は再開できます。Claudeが SendMessage ツールに、完了時に受け取ったエージェントIDか名前を渡すと、前の会話履歴ごと続きから動きます。

注意点は2つあります。Explore と Plan は一度きりで、エージェントIDを返さないため、再開できません。続きが要る作業には、general-purpose かカスタムのサブエージェントを使います。また、x キーで自分で止めた子は自動では再開されず、Claudeが送ったメッセージは拒否されます。

アンチパターン2: 軽い単発の作業

数行を直す、ファイルを1つ読むだけの作業では、起動の手間が作業そのものを上回ります。公式のdocsも、素早く的を絞った変更はメインの会話で行うよう挙げています。forkでない子は、ゼロから文脈を集めるため、遅延も出ます。

既に会話の中にある事柄への質問なら、/btw が向きます。/btw は会話全体を見られますが、ツールは使えず、答えは履歴に残りません。

アンチパターン3: 試しながら進路を決める作業

「書いてみて、見て、次を決める」ような対話的な探索は、メインの会話が向きます。複数の段階が文脈を共有する、計画・実装・テストのような流れも同じ扱いです。

どの形で任せるか

状況別に、向く形を並べます。

まとめ

並列にするか迷ったら、まず「子に渡すのは委任文だけでよいか」を考えると、使いどころが絞れます。会話の流れが要るならfork、要らないなら通常のサブエージェントです。

数十〜数百のサブエージェントを束ねて検証まで自動で回す規模なら、ダイナミックワークフロー(Dynamic Workflows)が段取りをスクリプトに委ねる発展形になります。

メインのClaude Codeから離れた実行の形は、Claude Code Routines完全実践ガイドやAgent SDKでSlack botを作るが参考になります。