はじめに
Claude Code でサブエージェント（Subagent）を使い始めると、最初は単一のエージェントに雑多な仕事を任せがちです。調査、設計、実装、レビューを全部ひとつの research-agent に押し込む、という構成です。小さな作業では充分ですが、プロジェクトが 3 つ、5 つと並走し始めたあたりから急に破綻します。
具体的には、次のような症状が出ます。
- 会話の後半で前半の指示を忘れる
- プロジェクト A の文脈がプロジェクト B の作業に漏れる
- 同じ内容を何度も再説明している
- サブエージェントが「何を成果物として返すか」で毎回揺れる
この記事は、こうした状態になったときに有効な Agent Teams ベースの役割分担設計 をまとめたものです。具体的には、横断判断を担う Orchestrator teammate と、プロジェクト別の Project teammate、そして実装を担う Implementer teammate を並列配置し、ファイルベースで状態を共有する構造です。筆者が個人プロジェクト群を横断管理する際に使っている設計を、特定実装に依存しない形で一般化して紹介します。
対象読者は、Claude Code でサブエージェントを既に数本書いたことのある方を想定しています。初歩的な書き方には深入りしません。
前提知識：Subagent と Agent Teams の違い
設計の話に入る前に、似て非なる 2 つの機構を整理しておきます。どちらを使うべきかで設計がぶれやすいからです。
| 項目 | Subagent | Agent Teams |
|---|---|---|
| 実行形態 | 親セッションから子を起動して結果を受け取る | 複数 teammate が並列に独立セッションで動く |
| 文脈共有 | 起動時にプロンプトで渡す | teammate 間で共有メッセージングが走る |
| 子の再委譲 | Subagent は別の Subagent を起動できない（公式仕様） | teammate 同士はフラットに並び、メッセージで連携 |
| 主な用途 | 特定タスクの単発委譲、文脈遮断 | 役割分担された複数エージェントの並列運用 |
重要なのは Subagent は別の Subagent を起動できない という公式仕様です。つまり「統括 PM が子 PM を呼び、子 PM がさらに実装担当を呼ぶ」といった多段の親子委譲は、Subagent 単体では成立しません。
そこで本記事では Agent Teams を前提に、役割を分けた teammate 群をフラットに並列配置し、ファイルで状態を共有する 構造で設計します。呼び出し階層ではなく、役割分担された並列エージェントとして組み立てるのがポイントです。
なお、v2.1.63 以降では従来の Task ツールが Agent にリネームされています。本記事でもツール参照は Agent で統一します。
役割分担が必要になる 3 つのシグナル
単一エージェント運用から役割分担された Agent Teams 構成へ切り替えるタイミングは、次の 3 つのシグナルで判断できます。ひとつでも該当したら、設計を見直す価値があります。
シグナル 1：プロジェクト横断の意思決定が発生する
「プロジェクト A の作業を止めて、プロジェクト B に人員を回すか」「共通基盤の刷新を、どのプロジェクトから先にやるか」といった、複数プロジェクトにまたがる判断が頻発するようになると、単一エージェントでは扱い切れなくなります。
理由は単純で、単一エージェントが全プロジェクトのコンテキストを抱えると、トークンが破綻するからです。プロジェクトごとの詳細は Project teammate に閉じ込め、Orchestrator teammate は横断判断だけ担う構成が自然です。
シグナル 2：サブタスクが 5 つ以上に分岐する
ひとつのゴールから派生するサブタスクが 5 つを超えたあたりから、エージェントの指示書が急に読みにくくなります。目安として、1 つの teammate の指示文が 300 行を超えてきたら分割を検討するタイミングです。
分岐の数は、コードで言うところの関数の引数の数と似ています。3〜4 個までは読めますが、7 個を超えると誰も読まなくなります。
シグナル 3：中長期で状態管理が必要になる
単発の調査なら単一エージェントで問題ありません。一方で、週をまたいで継続する案件、マイルストーンが複数ある案件、外部からの入力（顧客レビュー、外部 API の変化）を取り込み続ける案件では、状態を持つ存在が必要になります。
この「状態を持つ存在」を Orchestrator teammate に置き、具体作業は Project teammate や Implementer teammate に役割ベースで割り当てる、という構成が Agent Teams の基本形です。
設計原則
役割分担を成功させるかどうかは、設計原則のありなしで決まります。以下の 4 つは最低限守りたい原則です。
原則 1：責務分離
teammate ごとの責務を、次のように切り分けます。
- Orchestrator teammate：横断の優先順位付け、プロジェクト間のリソース配分、全体進捗の把握
- Project teammate：単一プロジェクト内のタスク管理、マイルストーン追跡、リスク記録
- Implementer teammate：コードの読み書き、テスト、具体的な成果物生成
Implementer を必ず分けるわけではありません。プロジェクトが小さければ Project teammate が実装まで担うこともあります。重要なのは「ひとりの teammate に、抽象度の違うタスクを混在させない」ことです。
原則 2：委譲範囲の明示
ある teammate が別の teammate に作業を渡すとき、次の 3 点を必ず明文化します。
- ゴール：何ができたら完了か
- 制約：触ってよい範囲、触ってはいけないもの
- 成果物：どのファイルに、どの形式で返すか
この 3 点が曖昧だと、受け手の teammate は必ず「自分はもっと広い権限があるつもり」で暴走します。自分の担当プロジェクト外へ越境したり、横断判断を勝手に始めたりします。
原則 3：コンテキスト遮断
Project teammate や Implementer teammate には、Orchestrator teammate が持つ全情報を渡してはいけません。委譲範囲に必要な情報だけを渡し、残りは遮断します。
これは精神論ではなく、実用的な理由があります。各 teammate が無関係な情報を抱えると、独立コンテキストの意味が薄れ、トークンコストも増えます。そして、関係ない情報が多いほど、判断を誤る確率も上がります。
筆者の経験則では「ある teammate に渡すコンテキストは、その teammate の担当範囲に直接関係する 20% 以下に絞る」のが目安です。それ以上渡しているなら、そもそも役割分割できていないか、委譲範囲が広すぎます。
原則 4：成果物インターフェース（ファイルベース）
teammate 間のやりとりは、メモリ上の会話ではなくファイルに落とします。具体的には、次のような構造です。以下の .pm-workspace/ は本記事での呼称で、プロジェクトごとに好きなディレクトリ名に読み替えて構いません。
.pm-workspace/
projects/
project-a/
status.md # Project teammate が更新
tasks.md # 現在のタスク
decisions.md # 意思決定ログ
project-b/
...
orchestrator/
priorities.md # Orchestrator teammate の横断優先度
dashboard.md # 全プロジェクトの進捗サマリ
Agent Teams は teammate 同士がフラットに並ぶため、共有メッセージだけで状態を保つと長期運用で破綻しがちです。ファイルに落として読み書きする設計にすると、セッションをまたいでも状態が保たれ、人間が途中経過を確認・修正できます。エージェントが暴走した際のリカバリも容易です。
実装パターン
ここからは、抽象化した例として 3 つの teammate 定義を示します。実プロジェクトでは、これを自分のドメインに合わせて書き換えて使います。
Orchestrator teammate
---
name: orchestrator
description: |
全プロジェクトの窓口役。ユーザーからの相談を受け、
ファイルで状態を共有しながら該当プロジェクトの teammate と連携する。
複数プロジェクトにまたがる優先度判断・リソース配分を担当する。
tools:
- Read
- Write
- Edit
---
あなたは複数プロジェクトを横断管理する Orchestrator teammate です。
## 責務
- ユーザーからの相談窓口になる
- 該当プロジェクトの Project teammate にメッセージで依頼を回す
- プロジェクト横断の優先度を判断する
- 全プロジェクトのダッシュボードを更新する
## やらないこと
- 個別プロジェクトの詳細タスク管理（Project teammate の仕事）
- コードの読み書き（Implementer teammate の仕事）
## 依頼のルール
1. 依頼内容がどのプロジェクトに属するか判定する
2. 該当の Project teammate にメッセージを投げる
3. 依頼時に渡すのは以下 3 点のみ
- ゴール（何ができたら完了か）
- 制約（触ってよい範囲）
- 成果物パス（どこに何を書くか）
## 状態管理
- 横断優先度: .pm-workspace/orchestrator/priorities.md
- 全体ダッシュボード: .pm-workspace/orchestrator/dashboard.md
ポイントは「やらないこと」を明記している点です。これがないと、Orchestrator がうっかり個別タスクに首を突っ込み、役割分担が崩れます。
Project teammate
---
name: project-a
description: |
単一プロジェクト（project-a）内のタスク・マイルストーン・リスクを管理する。
Orchestrator から受けた依頼を、実装単位に分解して Implementer teammate に回す。
tools:
- Read
- Write
- Edit
---
あなたは project-a を担当する Project teammate です。
## 責務
- プロジェクト内のタスクリスト管理
- マイルストーン追跡
- リスク・ブロッカーの記録
- Implementer teammate への具体タスク依頼
## 参照するもの
- 自プロジェクトの CLAUDE.md
- .pm-workspace/projects/project-a/ 配下のファイル
## 触らないもの
- 他プロジェクトのディレクトリ
- .pm-workspace/orchestrator/ 配下
（ここは Orchestrator の領域）
## 依頼のルール
- Implementer teammate には最小単位のタスク（1〜2 時間で完了する粒度）のみ渡す
- 依頼結果はタスクファイルに追記し、Orchestrator から見える状態にする
「触らないもの」で他プロジェクトや Orchestrator 領域への越境を禁じるのが肝です。teammate は明示されない境界を平気で越えるので、ここは必ず書きます。
Implementer teammate
Implementer teammate の定義は、プロジェクトの性質に強く依存するため、抽象例のみ示します。
---
name: implementer
description: |
Project teammate から渡された具体タスクを実装する。
ゴール、制約、成果物パスを厳密に守る。
tools:
- Read
- Edit
- Bash
- Grep
---
あなたは Implementer teammate です。Project teammate から渡された
タスク定義に従い、コード変更・テスト・動作確認を行います。
## 守ること
- 渡されたゴール以外の改善提案を勝手にコードに反映しない
- 成果物パス以外のファイルは変更しない
- 完了時は必ずテストを走らせて結果を報告する
## 暴走防止
- タスク定義に曖昧さを感じたら、作業を止めて Project teammate に質問を返す
- 想定外の変更が必要になったら、Project teammate に報告してから着手する
Implementer teammate のポイントは「勝手に良くしない」です。改善提案は Project teammate に返すだけにして、自分の裁量で書き換えない約束にします。ここを緩めると、役割分担の意味がなくなります。
teammate 配置の俯瞰図
3 種類の teammate の関係を図にすると、次のようになります。Agent Teams は親子ではなく、役割ごとにフラットに並ぶのがポイントです。
図で確認したいのは、次の 2 点です。
- ユーザーは Orchestrator としか会話しない：Project や Implementer に直接話しかけない
-
ファイルは役割ごとの領域に分かれている：Orchestrator は
orchestrator/、各 Project teammate はprojects/<name>/と明確に住み分け
teammate 間の接続は、呼び出しの階層ではなく「共有メッセージングとファイル経由の状態共有」で成立しています。プロジェクトが少ないうちは 2 種類（Orchestrator + Implementer）で始めても構いません。プロジェクト数が増えてから Project teammate を追加する、段階的な導入がおすすめです。
通信パターン
teammate 間の通信は、3 つのパターンを組み合わせて設計します。
パターン 1：成果物ファイル受け渡し
最も基本の通信方法です。依頼側の teammate は「このパスに書いてほしい」と指示し、受け手はそのパスへファイルを書きます。依頼側は該当ファイルを読んで結果を受け取ります。
利点は、セッションをまたいでも結果が残ることと、人間が途中経過をレビューできることです。Agent Teams では teammate のセッションが独立しているため、このファイル経由の受け渡しが最も安定します。
パターン 2：Skill 呼び出しによる定型化
Skill として定義したタスクを呼び出す方法です。頻出する依頼パターン（例：「プロジェクト A の週次レポート作成」）は Skill 化しておくと、teammate のプロンプトが短くなります。
Skill は「名前付きの依頼テンプレート」と捉えると分かりやすいです。
パターン 3：Monitor による外部状態の監視
Monitor は、backgroundで走っているコマンドのログ、CI の進行状況、ファイル変更などを監視するための仕組みです。teammate 同士の結果受け取りには使いません。
Orchestrator teammate や Project teammate が、長時間走るビルド・テスト・外部 API 呼び出しの進捗を追いたいときに使うと便利です。
3 パターンの使い分けは、次の表を目安にします。
| シーン | 使うパターン |
|---|---|
| teammate 間の成果物受け渡し | 成果物ファイル |
| 定型化された依頼 | Skill 呼び出し |
| ビルド・CI・長時間コマンドの監視 | Monitor |
コンテキスト管理
Agent Teams 運用の最大のハマりどころは、コンテキスト管理です。ここを設計し忘れると、トークンコストが一気に跳ね上がります。
teammate ごとに CLAUDE.md をどう読み分けるか
プロジェクトルートに 1 枚の CLAUDE.md しかない構成は、Agent Teams と相性が悪いです。すべての teammate が同じファイルを読み込むため、役割分担の意味が薄れます。
推奨は、次のような分割です。
CLAUDE.md # ルート：Orchestrator teammate 向けの概要
.pm-workspace/
projects/
project-a/
CLAUDE.md # project-a teammate 専用
project-b/
CLAUDE.md # project-b teammate 専用
各 teammate 定義で、読み込む CLAUDE.md のパスを明示します。Orchestrator は全プロジェクトの概要のみ、Project teammate は自プロジェクトの詳細のみ、という棲み分けです。
トークンバジェットの配分
全体のコストを抑えるには、各 teammate のトークン配分を決めておくのが有効です。目安として、次のような配分がバランス良いです。
| teammate | トークン比率 | 理由 |
|---|---|---|
| Orchestrator | 10〜15% | 横断判断に必要な最小限の情報だけ |
| Project | 30〜40% | プロジェクト内の文脈をしっかり抱える |
| Implementer | 45〜60% | コードと具体タスクに最も多く使う |
Orchestrator に多く配分したくなりますが、そこが膨らむと役割分担のメリットが消えます。Orchestrator は「薄く広く」が原則です。
失敗例 2 つ
Agent Teams は強力ですが、設計を誤ると単一エージェントより悪化します。典型的な失敗を 2 つ紹介します。
失敗例 1：役割を細かく分けすぎてコスト爆発
「Orchestrator、事業部 teammate、プロジェクト teammate、機能 teammate、実装 teammate」のように、役割を 5 種類に分けたケースです。
何が起きたか。teammate 間の受け渡しのたびに独立コンテキストの初期化が走るため、1 つの作業で 5 回ぶんのセットアップコストが発生しました。結果、単一エージェントの 3 倍以上のトークン消費になり、速度も大幅に落ちました。
教訓は 「役割は 3 種類まで」 です。それ以上に分けたいときは、同じ役割の teammate を横に並べる（たとえば Implementer を複数並列で走らせる）ほうがほぼ常に安く済みます。
失敗例 2：指示の粒度ミス（抽象度バラバラ）
Orchestrator への相談に「プロジェクト A の認証周りを改善して」と、Project teammate への依頼に「auth.ts の 42 行目のバグを直して」が混在したケースです。
抽象度が違う指示を同じ teammate に投げると、受け手は自分の仕事の範囲が分からなくなります。結果、42 行目のバグ修正をしようとした teammate が、認証周り全体の設計レビューを始める、といった暴走が発生しました。
教訓は「役割ごとに、指示の抽象度を揃える」です。Orchestrator への依頼は「プロジェクト単位」、Project teammate への依頼は「機能単位」、Implementer teammate への依頼は「ファイル・関数単位」と、役割ごとの粒度を決めておきます。
Subagent との使い分け
最後に、Agent Teams と Subagent の使い分けを整理します。両者は対立するものではなく、役割が違います。
| 観点 | Agent Teams | Subagent |
|---|---|---|
| 主な効果 | 役割分担・並列運用・文脈遮断 | 特定タスクの単発委譲 |
| 向いている場面 | プロジェクト横断管理・長期運用 | 単発の調査・短時間のサブタスク |
| コストの性質 | 並列数ぶん広がる | 1 回ごとに独立 |
| 管理難易度 | 役割設計・ファイル共有の設計が必要 | 単体の起動設計で済む |
| 再委譲 | teammate 同士はフラットに連携可能 | Subagent は別の Subagent を呼べない |
筆者の感覚では、「Agent Teams = 役割分担された常駐的な運用」「Subagent = 単発の文脈遮断つきタスク」と使い分けるのがわかりやすいです。
具体的には、Orchestrator と Project を Agent Teams で常駐させておき、単発の調査・レビュー・翻訳のような使い捨てタスクだけ Subagent で起動する、というハイブリッド運用が現実的です。
まとめ
Agent Teams は、銀の弾ではありません。プロジェクト数が少ないうちは、単一エージェントのほうが素直で速いです。一方で、プロジェクト横断の判断が増えたり、状態管理が必要になった段階では、役割を分けた並列運用の恩恵が効いてきます。
この記事で紹介した要点は、次のとおりです。
- 役割分担のシグナルは「横断判断」「分岐 5 つ以上」「中長期の状態管理」の 3 つ
- 設計原則は「責務分離」「委譲範囲の明示」「コンテキスト遮断」「ファイルベース成果物」の 4 つ
- 通信は成果物ファイル、Skill 呼び出し、Monitor（外部状態監視）の 3 パターンを使い分ける
- CLAUDE.md は teammate ごとに分割し、トークン配分を 10:35:55 程度で設計する
- 役割は 3 種類までに抑え、各役割で指示の抽象度を揃える
- Agent Teams は役割分担、Subagent は単発委譲、と使い分ける
最後に、これは筆者の現時点での設計観であり、Claude Code の機能進化や自身の運用経験に応じて今後も変わっていくはずのものです。ご自身の環境に合わせて、適宜読み替えてお試しください。