Claude Codeオーケストレーター設計 — メインを指揮に回し、サブエージェントに実務を任せる

オーケストレーターとして使うとはどういうことか

Claude Codeのオーケストレーター運用とは、メインセッションを指揮役に固定し、調査・実装・検証といった実作業をサブエージェントへ振る使い方です。メイン側の担当はタスクの分解、担当の割り当て、返ってきた結果の統合、次の一手の決定に絞られます。ファイルを何十本も読むのも、テストを繰り返し回すのも、子側の仕事になります。

この分業が成立するのは、サブエージェントが独立したコンテキストで動くからです。子が内部でReadやGrepを何十回繰り返しても、メインに返るのは完了メッセージ1通だけ。読み込んだファイルの中身はメインのコンテキストウィンドウに載りません。

裏返して言えば、メインのコンテキストは有限の予算です。指揮役が抱えている全体の目的、採用した設計判断、まだ決めていない論点は、セッションの最後まで効き続けます。一方、調査の途中で開いた200行のファイルは、結論が出た瞬間に価値を失う情報です。前者をメインに残し、後者を子へ押し出す。オーケストレーター運用の設計原理はこの一点に集約されます。

サブエージェント自体の仕様(独立コンテキスト、ツール制限、モデル選択)はClaude Code Sub-agents完全ガイドにまとまっています。ここから先は、その仕組みを前提に「メイン側をどう組み立てるか」に絞ります。

並列調査と並列実装は別物として設計する

同じ「並列」でも、読み取りだけの並列と書き込みを含む並列では、設計の難易度が大きく違います。読み取り系はほぼ無条件に並列化できます。書き込み系は隔離を先に用意しないと壊れます。

読み取り系が安全なのは、子同士が互いの状態を一切共有しないからです。Exploreのような読み取り専用のサブエージェントを3体同時に投げても、片方が読んだ内容がもう片方の推論に混ざることはありません。副作用がないので、順序も結果に影響しません。「認証はどこで実装されているか」「テストはどう構成されているか」「設定値はどこから読まれているか」を1メッセージで同時に投げる、という使い方が典型です。

書き込み系は事情が変わります。子はそれぞれ独立したコンテキストで動くため、別の子が同じファイルを編集中であることを知る手段がありません。Writeで全体を書き換える子と別の子の編集が重なれば、片方の変更が失われます。同じ箇所への編集が重なれば、変更同士の整合も崩れます。気づくのはビルドが落ちてからになりがちです。

並列数を決めるのは、速度ではなく統合コストです。3体なら3通の報告を読んで束ねられますが、8体だとメインが報告の読み込みだけで埋まり、分割した意味が薄れます。

既定では、システム側の上限は1セッションで同時に20体までです。20体が走っている間に追加で起動するとConcurrent subagent limit reachedで失敗します。

この上限は環境変数CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS(v2.1.217以降)で指定できます。ultracodeが有効なセッションには、この上限は適用されません。ただし、上限まで走らせても報告を読んで束ねるのはメイン1人です。

書き込みを並列にするならworktree隔離が前提

ファイル衝突を根本から断つ方法は、子ごとに作業ディレクトリを物理的に分けることです。Claude Codeはgit worktreeを内蔵活用しており、サブエージェント定義のfrontmatterにisolation: worktreeを指定すると、起動時に一時的なworktreeへ作業領域が切り替わります。子が何も変更しなければworktreeは自動削除されます。

claude --bgで動かすバックグラウンドセッションでは、ファイル編集時に.claude/worktrees/<id>配下へ自動的に隔離されます。この隔離はworktree.bgIsolation: "none"で無効にできます。複数セッションが互いの作業を踏み合うのを防ぐ仕組みで、agent viewから複数本を並走させる運用と同じ設計思想の上にあります。画面側の話はagent viewの常駐プロセス設計で扱っています。

worktreeの分岐元にも注意が要ります。公式の仕様では、isolation: worktreeのworktreeは親セッションのHEADではなく、既定ブランチ(default branch)から切られます。メイン側でまだコミットしていない変更や作業ブランチの内容は、子のworktreeには入りません。子に前提を渡したいときは、先にコミットして既定ブランチへ反映するか、必要な内容を指示文に書きます。worktree.baseRefを"head"にすると、現在の作業から切らせることもできます。

隔離を入れると、指揮役の仕事に「統合」が明確に加わります。子はそれぞれのworktree内で完結し、メインが差分を確認して取り込む順序を決めます。ここで効くのが担当範囲の切り方です。ディレクトリ単位(app/とlib/とscripts/)や、レイヤー単位(API・UI・マイグレーション)で割ると、取り込み時の競合がほぼ起きません。一方、同じモジュールを機能軸で割ると、隔離していても最終的なマージで手作業が発生します。

注意点も2つあります。worktreeは.gitこそ共有しますが、チェックアウトしたファイル群は実体として増えるためディスクを食います。worktreeは新しいチェックアウトなので、開発環境の初期化が子の側で要ります。公式も、worktree内で依存関係をインストールするようClaudeに頼む運用を示しています。運用面の詳細はWorktree完全活用にまとめてあります。

工程は直列に、工程内は並列に

並列化するかどうかは、作業単位ではなく工程単位で判断すると破綻しにくくなります。調査・計画・実装・検証という工程の間には順序の依存があり、ここを並列にすると前段の結論が出る前に後段が走り出します。同じ工程の中は独立していることが多く、並列の旨味はそちらに集中します。

実際の運用は4段構えになります。

計画だけは並列にしません。ここは全体を1つの頭で見る必要がある工程で、分割すると担当割りが噛み合わなくなります。実装方針を固めてから動きたい場合は、Planモードで計画を確定させてから実装の並列に入る流れが噛み合います。

検証を最後に1体へ集約するのも同じ理由です。実装を3体で並列に進めると、それぞれの単位ではテストが通っていても、統合した状態は誰も確認していません。3体それぞれに検証させると、各自が自分の担当範囲だけを見て「問題なし」と返してきます。統合後の状態を見る役は、必ず1つに絞ります。この最後の1体に、テストの合否ではなく実際にビルド・起動して確認させる/verifyを割り当てると、統合漏れを検出しやすくなります。

そのまま使える指示文の型

指揮役の成果は指示文の質でほぼ決まります。ここでは実務で繰り返し使える5つの型を、そのまま貼れる形で置きます。

型1: 独立した観点の同時調査

以下の3つを独立したサブエージェントで同時に調べてください。
それぞれ読み取り専用で構いません。
 
A. 認証処理の入口と実装ファイル(パス:行番号で)
B. テストの構成(どのランナー、どこに置かれ、どう起動するか)
C. 環境変数の読み込み箇所と、その一覧
 
各エージェントは「結論3行 + 根拠のファイルパス」だけを返してください。
ファイルの中身は貼らないでください。

最後の2行が要点です。報告に「何を含めないか」まで書くと、メインへ戻る情報量を指揮側でコントロールできます。ファイルの中身をそのまま貼り返されると、子に逃がしたはずのコンテキストがメインへ戻ってきてしまいます。

型2: 報告フォーマットを固定した調査

このリポジトリで使われている日付処理を洗い出してください。
報告は次の表形式のみで返してください。前置きと総括は不要です。
 
| ファイル:行 | 使っているAPI | タイムゾーン指定の有無 |
 
該当が0件なら「該当なし」とだけ返してください。

表形式を先に決めておくと、複数体から返ってきた報告をメイン側でそのまま連結できます。「前置きと総括は不要」を添えるのは、要約文が入るほどメインが読む量が増えるためです。

型3: 担当ファイルを明示した並列実装

次の2つを別々のサブエージェントで並行して実装してください。
担当外のファイルには触れないこと。
 
エージェント1: lib/date.ts のみ。UTC固定の整形関数を追加。
エージェント2: components/ArticleCard.tsx のみ。上の関数を使う前提で
              表示側を書き換え(関数のシグネチャは
              formatDate(iso: string): string とする)。
 
先に共有するインターフェースを固定してあるので、
互いの実装を待たずに進めて構いません。

依存がある実装を並列化するときは、インターフェースを指揮側で先に確定させると直列待ちを外せます。ここではformatDateのシグネチャがその役割です。担当ファイルの明示は、衝突を防ぐ最小のコストで効く指定になります。

型4: 視点を分けた同時レビュー

現在の差分を、観点を分けた3体で同時にレビューしてください。
 
- エージェント1: セキュリティ(入力検証、秘密情報の混入、権限)
- エージェント2: 既存挙動との互換性(呼び出し元への影響)
- エージェント3: 可読性と命名
 
各エージェントは指摘を Must / Want / Nit の3段階に分類し、
該当箇所を ファイル:行 で示してください。指摘0件なら「なし」と返す。

1体に「品質を確認して」と投げると観点が散り、毎回違うところを拾います。観点を分けて同時に走らせると、指摘の粒度が揃い、メイン側でMustだけを抜き出す処理も機械的にできます。

型5: 検証ログの隔離実行

このAPIクライアントを、次の4パターンで実行して結果を確認してください。
(1) 正常系 (2) 401 (3) タイムアウト (4) 不正なJSON
 
返してほしいのは以下だけです。
- 各パターンの合否
- 落ちた場合のみ、例外の型と発生行
 
実行ログ全文は返さないでください。

検証は出力ログが最も膨らむ工程です。合否と失敗箇所だけを受け取る形にすれば、メインのコンテキストはほとんど消費されません。パターン別の並列パターン全般はサブエージェント完全活用で扱っています。

フォークと入れ子で、委任の形を変える

ここまでの子は、指示文に書いた前提だけを持って始まる通常のサブエージェントです。前提の説明が長くなる作業には、会話全体を引き継ぐ「フォーク」という選択肢があります。インタラクティブセッションではフォーク機能が既定でオンで、/subtask <作業内容>で手動起動もできます(v2.1.161〜v2.1.211では/fork)。

フォーク機能がオンのときは、Claudeが起動するサブエージェントは(フォアグラウンドに固定される例外を除き)すべてバックグラウンドで動き、結果は完了通知として後続のターンで届きます。バックグラウンドの子は使える組み込みツールも絞られるため、同じ定義でもフォアグラウンドとは解決されるツールが変わりえます。

入れ子の深さにも上限があります。

子がさらに孫を並列で走らせる構成も取れ、インタラクティブセッションでは最上位の子の要約だけがメインへ返ります。読み取り専用に保ちたい子は、toolsからAgentを外すかdisallowedToolsに入れます。

Agent Teamsとサブエージェントはどう違うか

ここまでの型は、いずれも「メインが子に委任し、結果を1通受け取る」単発の委任構造です。これに対してAgent Teamsは、複数のClaudeセッションをteammateとして束ね、teammate同士がメッセージを直接やり取りしながら役割分担する機能です。実験的機能で既定は無効のため、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1を設定して有効にします。

両者の違いは、往復があるかどうかに集約されます。

運用を支える足回りも入っています。teammateが待機に入る直前に発火するTeammateIdleと、タスク完了時のTaskCompletedのhookがv2.1.33で追加され、次の一手を発火させる契機を外部スクリプトのポーリングに頼らず掴めるようになりました。同じ時期に、親が起動できる子の種類をtoolsのTask(agent_type)構文で絞る指定も入りました。現在の表記はAgent(agent_type)で、claude --agentでメインスレッドとして動かすエージェントにだけ効きます。サブエージェント定義の中に書いても、かっこ内の種類リストは無視されます。表示モードはteammateMode設定でauto・in-process・tmux・iterm2(v2.1.186以降)から選べます。4値の違いとtmux/iTerm2が必要になる条件はteammateModeでAgent Teamsの表示方法を切り替えるで扱っています。

実験的機能であり、公式ドキュメントも単独セッションより大幅にトークンを使うと説明しています。セッションの再開などには既知の制限もあります。日常の並列化は単発委任で十分に回るため、Agent Teamsは「役割を持った複数エージェントが会話しながら進める必要がある」場面に絞って試す対象と捉えるのが無理のない距離感でしょう。

指揮が空回りする4つのパターン

オーケストレーター運用がうまくいかないときは、だいたい次のどれかに当たります。

1つ目は、同一ファイルへの同時編集です。前述のとおり、各子は互いの編集を知らないため、書き込みが重なると片方の変更が失われます。防ぐ手段は担当ファイルの明示かisolation: worktreeの2つで、どちらも指示を出す前に決めておく必要があります。走らせてから気づく類のミスではありません。

2つ目は、子に状態の引き継ぎを期待することです。サブエージェントは結果を1通返したら終了し、新しく起動した子は前回の中間状態を持ちません。同じ子を再開(resume)すれば続きから動けますが、通常は指示文に前提を書き切るほうが確実です。「さっき調べた件の続きを」という指示は通らないので、必要な前提は毎回プロンプトへ書き切ります。この性質は、逆に言えば毎回まっさらな目で見てくれるという利点でもあります。

3つ目は、指示が抽象的すぎて報告が使えないケースです。「調べて」「レビューして」だけでは、返ってくる形式が毎回変わります。前節の型2・型4のように、報告フォーマットと判定の粒度を先に固定するだけで、統合の手間は大きく減ります。

4つ目は、並列数を増やしすぎることです。体数を倍にしても、報告を読んで矛盾を解消するのはメイン1人です。体数が増えるほど、統合の労力が時間短縮を食いつぶします。数十以上を束ねたい規模になると、段取り自体をスクリプトへ委ねる仕組みが別途必要になります。

よくある質問

子エージェントの途中経過を見る方法はありますか

実行中の子はプロンプト下のパネルに並びます。フォークした子はEnterで会話記録を開いて指示を送れ、xで停止できます。Ctrl+EnterかCtrl+X Ctrl+Sで送ると、子が待っている作業の完了前にメッセージを読ませられます(v2.1.286以降)。通常の子の行は、完了するとすぐ消え、失敗や停止した行は30秒残ります。数十本の別セッションを並べて見張りたいなら、agent viewでバックグラウンドセッションとして起動する運用が近い形です。

指揮役のメインでもファイルを編集していいですか

編集できますが、子と同じファイルを触ると衝突源が増えます。メイン側は差分の確認と取り込み判断に寄せ、実際の書き換えは子へ出すほうが、担当の境界がはっきりします。ごく軽い修正なら、子を起動する手間のほうが大きくなりがちで、メインで直接済ませる選択もあります。

トークン消費は単独セッションより増えますか

サブエージェントごとにシステムプロンプトと前提の受け渡しが発生するため、総消費量は増える方向です。特にAgent Teamsは、各teammateが別のClaudeインスタンスなのでトークン消費が大きくなります。

まとめ

メインに残すのは最後まで効く判断だけで、読み込みと実行ログは子に出します。まずは読み取り系の並列調査から始め、報告フォーマットの固定に慣れてから、worktree隔離を挟んだ書き込み系の並列へ進む流れが無理がありません。どのサブエージェントを作り、何をどう返させるかという設計側の判断軸はエージェント設計パターンで扱っています。