Agent Teamsのチームサイズとタスク粒度の決め方

Agent Teamsは何人から始めるか

Agent Teamsの人数に上限は決められていません。何人でもスポーンできます。ただし公式ドキュメントは、ほとんどのワークフローで3〜5人から始めることを勧めています。トークンコストが人数にほぼ比例して増える一方、人数を増やしても速度は比例して伸びないからです。

チームを組むと、リード役のセッションに加えて各チームメイトが独立したコンテキストウィンドウを持ちます。5人のチームなら5人分のコンテキストが同時に走り、リード単体よりトークン消費が大きく増えます。コスト管理のページでは、人数にほぼ比例すると説明されています。実務上の制約は、トークンコストの線形増加、調整コストの増加、人数に見合わない速度向上の3点です。

ドキュメントの言い方は「3人の集中したチームは、5人の散らばったチームをしばしば上回る」です。人数を先に決めるのではなく、独立して進められる観点がいくつあるかを数えるほうが、適正値に早く着地します。コードレビューなら、セキュリティ・パフォーマンス・テストカバレッジの3観点がそのまま3人になります。

タスクの粒度は「1つの明確な成果物」を基準に切る

タスクが大きすぎても小さすぎても、Agent Teamsは機能しません。基準は、1つの関数、1つのテストファイル、1件のレビューのように、単独で完結した成果物を生む大きさです。

タスクの数が足りないと感じたら、リードに「もっと細かく分けて」と頼めます。タスクはリードが切って割り当てるのが基本で、自分で切り直す必要はありません。

割り当て方は2通りです。リードが「このタスクはこのチームメイトに」と名指しする方法と、チームメイトが1つ終えるたびに、未着手で依存関係が解消済みのタスクを自分で拾う方法です。

タスクには未着手・進行中・完了の3状態があり、依存先が終わるまで着手できないタスクもあります。同時に取り合ったときの競合は、ファイルロックで防がれます。

チームサイズをタスク数から逆算する

「3〜5人」と「1人あたり5〜6タスク」は、別々の設計変数ではありません。2つを組み合わせると、次の手順で人数を導けます。この割り算はドキュメントの記述からの導出で、式そのものは載っていません。

階層構造がない点も、設計に効きます。チームメイトは自分のチームメイトを持てず、リードだけがチームを管理します。1セッションにつきチームは1つで、別名のチームを増やしたり、セッション間で共有したりもできません。リード役の移譲も不可です。「サブチームに投げる」設計は選べないので、フラットなタスクリストの中で粒度をそろえる以外の道はありません。

人数が増えたときの画面と、タスクが詰まったとき

チームメイトはリードの端末の下にあるエージェントパネルに並びます。選択してEnterを押すと、その人のやり取りを開いて直接メッセージを送れます。

4人以上が同時にアイドルになると、4人目以降の行は「2 idle agents」のような1行にまとまります。全員がアイドルになって30秒たつと、アイドルの行は隠れ、次のターンで戻ります。隠れた行は停止ではなく、そのまま動いています。人数を増やしたぶん、パネルで1人ずつ追う負担も増えます。

粒度に直結する制約もあります。チームメイトがタスクを完了済みにし忘れると、そのタスクに依存するタスクが進まなくなります。止まって見えるときは、作業が実際に終わっているかを見て、状態を手で更新するか、リードに促してもらいます。依存関係を深く張ったタスク設計ほど、この影響を受けやすくなります。

v2.1.287の claude --help に出ないフラグ

分割ペインで試すときの --teammate-mode は、公式ドキュメントが実験的なフラグとして紹介しています。ただし claude --help には載りません。v2.1.287で確かめると、次のとおりです。

claude --version
claude --help | grep -ci "teammate"

2.1.287 (Claude Code)
0

出力は0件で、ドキュメントの説明と一致します。フラグは --help に載らないだけで、指定は有効です。人数の多いチームでは、各自の出力を同時に眺められる分割ペイン(tmuxかiTerm2が必要。VS Codeの統合ターミナルなどでは使えません)が向く場面もあります。設定ファイルの teammateMode に "auto" を入れておけば、tmux内か it2 を入れたiTerm2のときだけ分割ペインになります。

コンテキストを渡すときのチェックリスト

チームメイトはプロジェクトのCLAUDE.md、MCPサーバー、Skillsを自動で読み込みますが、リードの会話履歴は引き継ぎません。渡せる情報は、起動時のプロンプトに書いた内容だけです。

そのため、チームメイトを起動する指示には次を含めます。

• 対象範囲(どのディレクトリ・どのモジュールか)
• 重点的に見る観点(セキュリティなら何を、パフォーマンスなら何を)
• 前提となる技術的な事実(認証方式、使用しているライブラリなど)
• 期待する報告の形式(重要度付きの一覧か、Yes/No判定か)

「認証まわりを見て」ではなく、「src/auth/ のトークン処理・セッション管理・入力検証を確認し、重要度付きでissueを報告して。JWTはhttpOnly cookieに保存している前提」まで書くと、追加の質問なしに動き出せます。スポーンプロンプトに書いた内容は、各チームメイトのコンテキストに最初から載ります。長い指示を全員に配ると、人数ぶんだけトークンが増えます。

モデルの使い分けもチーム設計の一部

コストは人数だけでなく、チームメイトごとのモデル選択でも調整できます。コスト管理のページは、チームメイトにSonnetを使う構成を勧めています。「4人チームでリファクタリングして、各チームメイトはSonnetを使って」のように、プロンプトでモデルまで指定できます。

Claude Codeがチームメイトのモデルを決める順序は、v2.1.251で変わりました。現在は次のとおりです。

1. スポーンプロンプトで、そのチームメイトに名指ししたモデル
2. Sub-agent定義から起動した場合は、その定義の model(inherit ならリードのモデル)
3. CLAUDE_CODE_SUBAGENT_MODEL 環境変数が inherit 以外に設定されていれば、その値
4. どれも指定がなければ、リードの現在のモデル

v2.1.250までは環境変数が最優先でした。環境変数で全員を固定したい場合は、v2.1.257以降の CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 を使います。上の1と2が無効になり、環境変数(未設定ならリードのモデル)が全員に効きます。teammateDefaultModel はv2.1.234で削除されており、残っていても無視されます。

組織の availableModels 許可リストで弾かれた場合、Anthropic APIとClaude Platform on AWSでは、opus のようなファミリー名は許可リスト内の最新版に置き換わります。プロバイダ固有のモデルIDを使う面ではこの置き換えが働かず、リードのモデルにフォールバックします。

effort(思考の深さ)は、チームメイトがリードのeffortを引き継ぎます。閲覧中のチームメイトの以降のターンにも /effort が効きます。見積もりの前提になるので、設定はeffortレベルの設定で確かめておきます。

in-processチームメイトのリクエストは、メイン会話のプロンプトキャッシュTTLバケットから外れ、既定では5分でキャッシュが切れます。subagentPromptCacheTtl を 1h にすると1時間保てますが、1時間キャッシュの書き込みはAPIでは高い料金になります。

待つこと・見守ることも設計の一部

チームサイズとタスク粒度を決めても、運用を誤ると効果は薄れます。典型的な失敗は3つあります。

リードが待たずに自分で実装を始めてしまうことがあります。チームメイトの作業と競合するので、「チームメイトの完了を待ってから進めて」と明示して止めます。

2人が同じファイルを編集すると、片方の変更が上書きされます。タスクを切る段階で、担当するファイル群が重ならないようにします。

放置しすぎると、うまくいっていないアプローチが積み上がります。エラーのあとに回復せず止まるチームメイトもいるので、パネルで出力を確かめ、追加の指示を出すか、後任のチームメイトを立てます。初めてAgent Teamsを使うなら、コードを書かせる前に、PRレビューやライブラリ調査のように境界の明確な調査タスクから試すと、実装の衝突なしに感覚をつかめます。

粒度の基準を機械で守らせたいなら、Hooksが使えます。終了コード2で理由を返すと、次のように動きを止められます。

たとえば TaskCompleted で、テストファイルが存在しなければ完了させない検査を入れると、「成果物を生むタスク」という粒度の基準が機械的に効きます。

意図しないチームの形成にも注意

Agent Teamsを有効にしていると、Claudeが名前を付けたサブエージェントはチームメイトとして起動します。頼んでいない場面でもチームが形成され、確認も出ません。人数もトークンも想定外に増える原因になります。アクティブなチームメイトは、終了するかセッションが終わるまでトークンを消費し続けます。作業が済んだチームメイトは終了させます。サブエージェントのままにしたいときは CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を 0 にします。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

保存すればセッションを開き直す必要はなく、次に名前の付くサブエージェントから反映されます。ユーザー設定で 0 にしても、プロジェクト設定や管理設定が 1 なら、そちらが優先されます。

Sub-agentsで足りるときは無理にチームを組まない

順番に進めるタスクや、同じファイルを触るタスクは、Sub-agentsや並列サブエージェントのほうが調整コストなく終わります。Sub-agentsは1セッション内で動き、独立したコンテキストウィンドウで作業して結果だけを返します。

Agent Teamsが優位に立つのは、複数の観点が本当に独立して進められる場面です。新機能の別々のモジュールを別のチームメイトに任せる、フロントエンド・バックエンド・テストを同時並行で進める、といったケースが当たります。ドキュメントの例では、原因不明の不具合に5人のチームメイトを立て、互いの仮説を反証し合わせる使い方もあります。

まとめ

人数は「3〜5人」を丸暗記するより、独立した観点の数と、総タスク数を5〜6で割った値の両方で決めると外しにくくなります。タスクは単独で完結する成果物の大きさに切り、チームメイトには会話履歴が渡らない前提でスポーンプロンプトに文脈を書き込みます。