エージェントチーム (Agent Teams) は複数の Claude Code セッションを 1 つのチームにまとめ、共有作業リストと相互メッセージングで協業させる実験的機能です。

情報

一行要約: サブエージェントがリーダーにだけ報告する一方向のワーカーだとすれば、エージェントチームは互いに対話し作業を自ら取りに行き、検証まで交わす同僚集団です。

注意

「エージェントチーム」の 2 つを区別してください。 このページが扱うのは Claude Code ネイティブの Agent Teams ランタイム (tmux/iTerm2 ペイン、共有 TaskList、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS)で、これは有効であり moai cg ハイブリッドモードがそのまま活用します。一方、MoAI の 静的 agent-team オーケストレーション階層 (旧 workflow.team.* 設定、--team 強制フラグ)は 引退 しました — --team を強制すると MODE_TEAM_UNAVAILABLE とともにサブエージェントモードへフォールバックします。つまりネイティブランタイムは生きており、MoAI 自身のワークフローオーケストレーションの静的チーム階層だけが消えたのです。

エージェントチームは複数の Claude Code インスタンスが一緒に働くよう調整する構造です。1 つのセッションが チームリーダー (team lead) になって作業を分配し結果を統合し、残りの チームメイト (teammate) はそれぞれ独立したコンテキストウィンドウで働きながら互いに直接通信します。

サブエージェントとの決定的な違いは通信の方向です。サブエージェントはメインエージェントにだけ結果を報告し互いに対話できませんが、エージェントチームのチームメイトは共有作業リストを見て仕事を自ら取りに行き、チームメイト同士で直接メッセージをやり取りします。リーダーを介さずユーザーが特定のチームメイトに直接指示することもできます。

エージェントチームは 並列探索 が実質的な価値を加える作業に最も強力です。

逆に順次的な作業、同じファイルを一緒に修正する作業、依存性が多い作業は単一セッションやサブエージェントがより効率的です。エージェントチームは調整コストとトークン使用量が単一セッションより大きく増えます。

速くて集中したワーカーが報告だけすればよい場合はサブエージェントを、チームメイトが発見を共有し互いを検証しながら自律的に調整する必要がある場合はエージェントチームを選びます。

チームメイト数に強制的な上限はありませんが現実的な制約があります。

• トークンコストは線形に増加 します。チームメイトごとに独立したコンテキストウィンドウを持ちトークンを別々に消費します。
• チームメイトが多くなるほど 通信と調整の負担 が大きくなり衝突の可能性も増えます。
• 一定数を超えると 収穫逓減 が発生します。追加のチームメイトが作業速度を比例して高めてくれるわけではありません。

公式ガイドはほとんどのワークフローで 3-5 名 から始めることを推奨します。チームメイトあたり 5-6 個の作業 (task) を割り当てると、過度なコンテキストスイッチングなしで全員を忙しく保てます。たとえば独立した 15 個の作業があれば 3 名が良い出発点です。集中した 3 名が散らばった 5 名より良い結果を出す場合が多いです。

エージェントチームは 4 つの構成要素で動作します。

作業は pending、in progress、completed の 3 つの状態を持ち、作業間の依存性も設定できます。依存性が解消されていない pending 作業は先行作業が完了するまで取りに行けません。あるチームメイトが先行作業を完了すると依存していた作業が自動的にロック解除されます。

作業の分配は 2 つの方式で行われます。

• リーダー割り当て: リーダーが特定の作業を特定のチームメイトに明示的に割り当てます。
• 自律クレーム (self-claim): チームメイトが作業を終えると、割り当てられておらず塞がれていない次の作業を自ら取りに行きます。

作業のクレームは ファイルロック (file locking) を使って、複数のチームメイトが同時に同じ作業を取りに行こうとするときに発生する競合状態を防ぎます。チームメイト間の通信は SendMessage で行われ、送られたメッセージは受信者に自動的に届けられます。リーダーがポーリングする必要なくメッセージが届き、チームメイトが作業を終えて止まると自動的にリーダーに知らせます。

2 人のチームメイトが同じファイルを編集すると上書きが発生します。したがって各チームメイトが 異なるファイル集合を所有 するよう作業を分割するのが核心的なベストプラクティスです。新規モジュールやレイヤー横断作業のように領域が自然に分かれる場合にエージェントチームが特にうまく動作する理由でもあります。

flowchart TD
    User[ユーザー] --> Lead[チームリーダー
作業分配・結果統合]
    Lead --> TaskList[(共有作業リスト
pending/進行中/完了)]
    Lead --> Mailbox{{メールボックス
SendMessage}}
    TaskList --> T1[チームメイト A
独立コンテキスト]
    TaskList --> T2[チームメイト B
独立コンテキスト]
    TaskList --> T3[チームメイト C
独立コンテキスト]
    T1 <--> Mailbox
    T2 <--> Mailbox
    T3 <--> Mailbox
    User -.直接指示.-> T1

リーダーは作業リストを通じて仕事を分配し、チームメイトはメールボックスで互いに直接対話し、ユーザーはリーダーを介さず個別のチームメイトにも指示できます。

エージェントチームは 実験的機能でデフォルトで無効化 されています。Claude Code v2.1.178 以上が必要で、環境変数 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を 1 に設定して有効化します。

• Implicit Teams: チーム生成がより簡単になりました。リーダーが最初のチームメイトをスポーンすると自動的にチームが形成され、セッション終了時に自動的に整理されます。
• TeamCreate/TeamDelete の除去: v2.1.178 からこのコマンドは消えました (もはや手動でチームを生成したり削除したりする必要なし)。
• team_name accepted-but-ignored: Hook payload で team_name フィールドは依然として含まれますが、実際には無視されます (レガシー互換性用)。

シェル環境に直接指定するか、settings.json に登録します。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

有効化後は自然言語でチーム生成を依頼すればよいです。Claude がチームを作りチームメイトをスポーンした後、作業を調整します。

TODO コメントをコードベース全体で追跡する CLI ツールを設計中です。
異なる観点から探索するエージェントチームを作ってください。
1 人は UX、1 人は技術アーキテクチャ、1 人は批判者の役割で。

エージェントチームは 2 つの表示モードをサポートします。

デフォルト値は in-process です (v2.1.179 から、以前は auto でした)。どこでも追加設定なしで使え、split-pane モードに切り替えるには teammateMode 設定値を変更します。

teammateMode に指定できる値は 4 つです。

~/.claude/settings.json で指定します。

{
  "teammateMode": "auto"
}

単一セッション限定で --teammate-mode auto フラグで上書きすることもできます。

split-pane モードには外部ツールが必要です。tmux はシステムパッケージマネージャーでインストールし、iTerm2 は it2 CLI をインストールした後 iTerm2 設定 (Settings → General → Magic → Enable Python API) で Python API を有効化する必要があります。

チームメイトはデフォルトではリーダーの /model 選択を継承しません。プロンプトでモデルを指定しなかったときに使うモデルは /config の Default teammate model で設定します。ただし v2.1.186 からチームメイトはリーダーの effort level を継承します (split-pane モードでは v2.1.186 から適用、以前のバージョンはリーダーの effort を伝えません)。

hook を使うと、チームメイトが作業を終えたり作業が生成・完了したりするときにルールを強制できます。

エージェントチームは実験的機能なので次の限界を認識して使います。

• セッション再開の未対応: /resume と /rewind はインプロセスのチームメイトを復元できません。再開後はリーダーに新しいチームメイトをスポーンするよう指示します。
• 作業状態の遅延: チームメイトが作業完了マークを漏らして依存作業が塞がれることがあります。
• 一度に 1 チーム: リーダーは 1 つのチームだけを管理します。新しいチームを作る前に現在のチームを整理する必要があります。
• ネストしたチーム不可: チームメイトは自分のチームやチームメイトをスポーンできません。チーム管理はリーダーだけが可能です。
• リーダー固定: チームを作ったセッションが寿命の間リーダーであり、リーダーシップを移譲できません。

チームの整理は常にリーダーを通じて行います。作業が終わったらリーダーに整理を依頼しますが、実行中のチームメイトが残っていると整理が失敗するので先に終了させる必要があります。

MoAI-ADK はこのネイティブなチームランタイムの上に CG モード (moai cg、Claude + GLM ハイブリッド) を載せてコストを最適化します。リーダーは Claude で戦略・計画・監査を調整し、チームメイトは tmux セッション単位の環境隔離を通じて GLM 環境を継承し大量の実装作業を行う方式です。「誰が何をするか」というチーム構造の問いに「どのモデルがいくら分の仕事をするか」というトークノミクスの答えを結合したもので、実装中心の SPEC・コード生成・テスト作成のようにトークン消費が大きい作業で 60-70% のコスト削減 を得ます。

1 つ区別しておくべきことがあります。MoAI-ADK は自身のワークフローオーケストレーションでは静的なエージェントチーム階層を引退させ、順次サブエージェントと動的ワークフローをデフォルトで使いますが、このページで扱った Claude Code のネイティブなチームランタイム (tmux ペイン、共有作業リスト) は CG モードがそのまま活用します。つまり「チーム」という実行形態は生きており、その用途が協業調整からコストルーティングへ移った形です。

CG モードの設定と運用方法は別のドキュメントで詳しく扱うので、以下のリンクを参考にします。

• ダイナミックワークフロー
• CG モード (Claude + GLM)

• Claude Code Docs — Orchestrate teams of Claude Code sessions

ヒント

エージェントチームが初めてなら、コードを書かない作業から始めてください。PR レビュー、ライブラリリサーチ、バグ調査のように境界が明確な作業は、並列実装の調整負担なしに並列探索の価値をすぐに体感させてくれます。