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

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

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

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

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

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

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

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

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

書き込み系は事情が変わります。子はそれぞれ独立したコンテキストで動くため、別の子が同じファイルを編集中であることを知る手段がありません。2体が同じファイルにEditをかければ、後から書いた側の内容が残り、先の変更は静かに消えます。エラーも警告も出ないため、気づくのはビルドが落ちてからです。

並列数の目安は、速度ではなく統合コストで決まります。3体なら3通の報告を読んで束ねられますが、8体だとメインが報告の読み込みだけで埋まり、コンテキストを節約するために分割したはずが逆効果になります。実務上は読み取り系で3〜5体、書き込み系で2〜3体あたりが扱いやすい範囲です。

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

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

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

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

注意点も2つあります。worktreeは.gitこそ共有しますが、チェックアウトしたファイル群は実体として増えるためディスクを食います。package-lock.jsonのようなlockfileはworktreeごとに持つことが多く、ブランチ間で依存が違えば依存関係の再インストールが必要です。運用面の詳細はWorktree完全活用にまとめてあります。

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

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

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

1. 調査: 観点を分けた読み取り専用の子を3体前後で同時に投げる
2. 計画: メインが報告を統合し、担当の割り当てと共有インターフェースを決める
3. 実装: 担当ファイルを割り当てた子を2〜3体、必要ならworktree隔離を付けて並列
4. 検証: 1体に集約し、全体をまとめてテストとビルドにかける

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

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

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

指揮役の成果は指示文の質でほぼ決まります。ここでは実務で繰り返し使える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
 
返してほしいのは以下だけです。
- 各パターンの合否
- 落ちた場合のみ、例外の型と発生行
 
実行ログ全文は返さないでください。

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

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

ここまでの型は、いずれも「メインが子に委任し、結果を1通受け取る」単発の委任構造です。これに対してAgent Teamsは、複数のClaudeセッションをteammateとして束ね、同じ文脈の中で役割分担させるマルチエージェント協業を想定した機能です。v2.1.32でresearch previewとして導入され、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1の設定を要求します。

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

運用を支える足回りも入っています。teammateが待機に入る直前に発火するTeammateIdleと、タスク完了時のTaskCompletedのhookがv2.1.33で追加され、次の一手を発火させる契機を外部スクリプトのポーリングに頼らず掴めるようになりました。同じリリースで、サブエージェントのfrontmattertoolsにTask(agent_type)構文を書き、親が起動できる子の種類をホワイトリスト化する指定も入っています(このツールはv2.1.63でTaskからAgentに改名されており、Task(...)表記は現在もエイリアスとして有効です)。表示モードはteammateMode設定でauto・in-process・tmux・iterm2(v2.1.186以降)から選べます。

ただしresearch preview段階であり、トークン消費も大きい機能です。hookのイベント名や構文の細部が正式リリース時に変わる可能性は残ります。日常の並列化は単発委任で十分に回るため、Agent Teamsは「役割を持った複数エージェントが会話しながら進める必要がある」場面に絞って試す対象と捉えるのが無理のない距離感でしょう。

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

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

1つ目は、同一ファイルへの同時編集です。前述のとおり後勝ちで上書きされ、エラーも出ません。防ぐ手段は担当ファイルの明示かisolation: worktreeの2つで、どちらも指示を出す前に決めておく必要があります。走らせてから気づく類のミスではありません。

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

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

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

よくある質問

サブエージェントは同時に何体まで走らせるのが現実的ですか

読み取り系で3〜5体、書き込み系で2〜3体が扱いやすい範囲です。上限を決めているのは実行側の性能ではなく、返ってきた報告をメインで束ねるコストになります。報告フォーマットを固定して1体あたりの報告量を絞れば、扱える体数はもう少し伸びます。

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

単発の委任では、メインに見えるのは完了メッセージ1通だけです。途中で進路を修正したい作業は、そもそも委任に向きません。実行中の様子を確認しながら進めたい場合は、agent viewでバックグラウンドセッションとして起動し、画面から個別に覗く運用が近い形になります。

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

編集できますが、子と同じファイルを触ると衝突源が増えます。メイン側は差分の確認と取り込み判断に寄せ、実際の書き換えは子へ出すほうが、担当の境界がはっきりします。1〜2ツール呼び出しで済む軽い修正は、起動コストのほうが重いのでメインで直接済ませて構いません。

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

サブエージェントごとにシステムプロンプトと前提の受け渡しが発生するため、総消費量は増える方向です。特にAgent Teamsはトークン消費の大きい機能として位置付けられています。一方で、メインのコンテキストが早期に埋まって作業をやり直す事態は避けられるため、長い作業ほど差し引きの評価は変わります。

まとめ

オーケストレーター運用の核は、メインのコンテキストを「最後まで効く情報」だけで満たすことにあります。全体の目的と設計判断はメインに残し、読み込みと実行ログは子へ押し出す。この線引きが決まれば、並列化するかどうかは自然に決まります。

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