Claude Code Agent Teamsのあそびかた
Agent Teamsは2026年2月5日にOpus 4.6と同時リリースされた実験的機能で、Claude CodeのSubagentsを独立プロセス化し、双方向にメッセージングできるようにする仕組みです。
一言でいうとSubagentsを拡張してステートフルにした機能です。各エージェントが自分のインボックス（~/.claude/teams/配下のJSONファイル）をポーリングしていて、メールボックスのアナロジーで相互通信が実現されています。ファイルロックで排他制御しているので、推論＋ファイルシステムだけでメッセージングシステムが成立しているのが面白いところです。
セットアップ
環境変数を有効にして起動するだけです。試すだけなのでグローバル設定ではなく起動引数で済ませてしまいましょう。
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude --teammate-mode tmux
表示モードは--teammate-modeで指定します。
tmux（おすすめ）: tmux内で起動する。各エージェントが独立ペインでわちゃわちゃと動く。in-process: 単一ターミナルで動作。ただしプロセスをspawnせず、シングルスレッドのままsubagentsとは別のエントリポイントからループが実行される。マルチプロセス化で真の並列処理になるtmuxモードとは等価ではない点に注意
iTerm2はPython APIを有効にしてit2 CLIをインストールしておくとtmuxの代わりになります。つまりは複数のclaudeコマンドを起動して、tmuxやiTerm2経由でそのウィンドウを管理しているという関係性になります。
in-processの場合は特別でこれを擬似的に内部で行なっています。実行中にps x | grep claudeなどするとプロセスが並列になっているのか確認できます。
利用制限の対策：Opusを避ける
Agent Teamsは各エージェントが独立したコンテキストウィンドウを持つので、全員Opusで動かすとトークン消費が激しく、サブスクの数時間の利用制限枠をすぐ使い切ります。
実践的な対策はプロンプトベースでのモデル誘導です。CLAUDE_CODE_SUBAGENT_MODELなどの環境変数を試しましたが、spawnされるClaude Codeのmodel引数は推論で決まってしまうため安定しません。プロンプトに「Use Sonnet/Haiku for the teammate.」と書いて指示するのが一番確実でした。
OpenRouterやOllamaで外部モデルを使っている場合はANTHROPIC_DEFAULT_SONNET_MODELやANTHROPIC_DEFAULT_OPUS_MODELを設定のEnvとしておけば、teammateの呼び出し時にも適用されます。これは現在ディレクトリ以下に設定しておきます。
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "sk-or-v1-your-openrouter-api-key",
"ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
"ANTHROPIC_MODEL": "openrouter/pony-alpha",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "openrouter/pony-alpha",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "openrouter/pony-alpha",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "openrouter/pony-alpha",
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
実践：難しいIssueをみんなで解く
V2 Speed Optimization #56というIssueを用意しました。これはDocker 内での npm install/build がボトルネックになっているため時間がかかる、というものでまだ解決策がありません。エージェントたちに相談して取り組んでもらいましょう。このようなプロンプトを用意しました：
gh issue #56を確認し、Team「SOTA」を作成して解決してください。Teammateは
* general-purpose (agent) – General-purpose agent for researching complex questions, se…
* Plan (agent) – Software architect agent for designing implementation plans…
* Explore (agent) – Fast agent specialized for exploring codebases. Use this wh…
* Bash (agent) – Command execution specialist for running bash commands. Use…
* statusline-setup (agent) – Use this agent to configure the user's Claude Code status l…
全員Haiku
しばらくすると以下のような返答が来ました。
⏺ gh issue #56を確認してから、Teamを作成して解決を進めます。
⏺ Bash(gh issue view 56)
⎿ title: V2 Speed Optimization
state: OPEN
author: laiso
… +101 lines (ctrl+o to expand)
⏺ Issue #56の内容を確認しました。V2 Docker実行のnpm
installボトルネック最適化が必要です。では、「SOTA」Teamを作成
して進めます。
⏺ Teamを作成しました。次に、指定されたTeammateをTeamに追加しま
。
⏺ 5 agents launched (ctrl+o to expand)
├─ @researcher
│ ⎿ Wait for assignment in SOTA team (shift+↑ to manage)
├─ @architect (Plan)
│ ⎿ Wait for assignment in SOTA team (shift+↑ to manage)
├─ @explorer (Explore)
│ ⎿ Wait for assignment in SOTA team (shift+↑ to manage)
├─ @executor (Bash)
│ ⎿ Wait for assignment in SOTA team (shift+↑ to manage)
└─ @setup (statusline-setup)
⎿ Wait for assignment in SOTA team (shift+↑ to manage)
⏺ 完璧です。SOTA Teamが立ち上がりました。次に、Issue
#56解決に向けたタスクリストを作成します。
⏺ タスクリストを作成しました。次に、依存関係を設定してTeammate
割り当てます。
⏺ 完璧です。では、explorerに最初のタスク実行を指示します。
⏺ ✅ SOTA Team立ち上げ完了
5つのTeammateを配置しました：
- explorer (Haiku): Task #1 - コードベース探索を実行中
- architect (Haiku): Task #2 - 実装計画作成予定
- executor (Haiku): Tasks #3, #4, #5 - 実装とテスト担当
- researcher (Haiku): バックアップ
- setup (Haiku): その他設定
タスク構成：
1. 📊 docker-strategy.tsとV2実装の探索 → 実行中
2. 📐 npm最適化の実装計画 → 依存関係待機中
3. 🔧 npm キャッシュマウント実装 → 依存関係待機中
4. 🧹 コンテナクリーンアップ実装 → 依存関係待機中
5. ✅ テスト・検証 → 依存関係待機中
Teamからのレスポンスを待っています。
ここにリストアップしたTeammateは実はClaude Codeのビルトイン・サブエージェントたちです（Claude Code内の@agent[TAB]の補完で出てきます）。各Teammateの立ち上げ時には内部的に、次のようなコマンドが発行されています：
CLAUDECODE=1 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude \
--agent-id architect\@SOTA \
--agent-name architect \
--team-name SOTA \
--agent-color green \
--parent-session-id 0da50c86-290e-4498-b029-5ff315c71f62 \
--agent-type Plan \
--model haiku
つまりclaudeコマンドにTeammates起動用のエントリポイントが追加されています。
この--agent-typeがサブエージェントのタイプになっています。なので自分で定義したカスタムエージェントも渡せますね。
しばらくエージェントチームが動作した後、作業を終えました。
⏺ 完璧です！すべての実装が完了しています。では、Issue
#56解決のサマリーをまとめます。
⏺ Reading 1 file… (ctrl+o to expand)
────────────────────────────────────────────────────────────────
Bash command
cat > /tmp/issue56_summary.md << 'EOF'
# Issue #56: V2 Speed Optimization - 解決完了報告
## 🎯 目標
V2 Docker実行のnpm installボトルネック最適化。npm
install実行時間の5-15%短縮を目指す。
## ✅ 実装完了内容
### 1. npm キャッシュマウント機能（既に実装済み）
- **ホストキャッシュパス**: `~/.cache/ts-bench/npm`
team-lead氏へインタビューしてみます「それぞれのTeammateがどんな役割で仕事をしたのか報告してください」
⏺ SOTA Team メンバー役割報告
---
👥 Team構成と貢献
メンバー: explorer
役割: コード調査
実施内容: docker-strategy.ts、V2フロー分析
成果: npm キャッシュが既実装を発見
────────────────────────────────────────
メンバー: architect
役割: 計画設計
実施内容: 実装戦略・優先順位整理
成果: 詳細実装計画書作成
────────────────────────────────────────
メンバー: executor
役割: 実装実行
実施内容: コンテナクリーンアップ、ログレベル制御実装
成果: 3つのcommit、全機能完成
────────────────────────────────────────
メンバー: researcher
役割: 補助
実施内容: 待機中
成果: バックアップ体制整備
────────────────────────────────────────
メンバー: setup
役割: 設定
実施内容: 待機中
成果: 環境設定体制整備
ログを見るとほとんどの作業をexecutorが腕力で解決したようです。逆にresearcherとsetupはなにもしなかったようです。それもそのはずでIssue時点では筆者はリサーチを終えていましたし、setupはそもそもClaude Code statusline の設定を手助けするエージェントです。これはteam-leadが内部タスクのどこにアサインを決定しているからで、我々は下流工程に不要なエージェントをアサインしてしまったようです（社会でも往々にあることですね）。
ところでPlanを専業とする@architectが何か気になることを言っていました：
計画書は /memory/detailed-implementation-plan.md に保存されており、executorがコピー&ペースト可能なコードを含んでいます。チームリードの次の指示をお待ちしています。
.claude/projects/以下のmemory/ディレクトリに以下を保存しているようです。ここにはチームで行っている作業の進捗などのメモがありました。
❯ tree memory/
memory/
├── detailed-implementation-plan.md
├── MEMORY.md
└── npm-cache-optimization-plan.md
❯ head MEMORY.md
# Issue #56: V2 Speed Optimization - 実装計画
## 🎯 目標
V2 Docker実行のnpm installボトルネック最適化。~npm install実行時間の5-15%短縮を目指す。
## ✅ 既に実装済みの機能
- **npm キャッシュマウント**: docker-strategy.ts:21行目 で `createNpmCacheArgs()` 呼び出し
- ホスト: `~/.cache/ts-bench/npm`
- コンテナ: `/root/.npm`
- docker.ts:47-59で自動ディレクトリ作成＆パス解決
- **NPM_CONFIG_CACHE環境変数**: docker-strategy.ts:43行目で設定済み
- **コンテナ自動削除**: DOCKER_BASE_ARGS に `--rm` フラグ存在（docker.ts:5）
## 🔧 実装対象（Task #7, #8, #9）
### Task #7: docker-cleanup.ts 作成
新規ファイル: `src/utils/docker-cleanup.ts`
- `cleanupBefore()`: V2実行前に古いswelancerコンテナ削除
- `cleanupAfterError()`: エラー時の強制削除
- `getRunningContainers()`: コンテナリスト取得
- ターゲット: `swelancer/swelancer_x86_monolith:releasev1`
このタスクがチーム内で管理されて共有されているようです：
❯ tree ~/.claude/tasks/sota
.claude/tasks/sota
├── 1.json
├── 6.json
├── 7.json
├── 8.json
└── 9.json
❯ jq . < ~/.claude/tasks/sota/7.json
{
"id": "7",
"subject": "実装: docker-cleanup.ts 作成（コンテナクリーンアップユーティリティ）",
"description": "Task #2の詳細実装計画に基づいて、新規ファイル src/utils/docker-cleanup.ts を作成。\n\n実装内容：\n1. cleanupBefore() - 実行前に古いswelancerコンテナを削除\n2. cleanupAfterError() - エラー時の強制削除\n3. getRunningContainers() - 実行中のコンテナリスト取得\n4. ログ記録による可視化\n\nターゲット: swelancer/swelancer_x86_monolith:releasev1\n\n参考: architectの詳細計画書 /memory/detailed-implementation-plan.md",
"activeForm": "docker-cleanup.ts実装中",
"owner": "executor",
"status": "completed",
"blocks": [
"9"
],
"blockedBy": [
"6"
]
}
知っておくと助かること
~/.claude/teams/: ここにチームの状態がJSONで保存されています。動作の理解にも、デバッグにも役立ちます。典型的には以下のようなファイルが生成されます：
team-name/
├── config.json
└── inboxes
├── bash-runner.json
├── config-manager.json
├── explorer.json
├── general-assistant.json
└── planner.json
外部から操作できる: インボックスのJSONファイルに反応する仕組みなので、構造を解析して別のプログラムからメッセージを書き込めます。たとえば筆者はCodexなど他のエージェントにこの知識をSkillと与えることでインボックスを書き換え、会話に参加させることができました。
プロセス起動のレースコンディション問題: シェルの起動完了よりClaude Codeのコマンド送信タイミングが早く、send-keysが無視される問題があります（issue #23513）。これは環境依存のIssueで、筆者の環境ではzshの起動プロセス完了が前後すると再現します。いまのところ回避策はin-processで使うしかないです。
Subagentsとの使い分け
Agent Teamsの有効活用についてなのですが、現状はSubagentsで十分なケースも多いです。そもそもカスタムSubagentsの効果検証もいまだ感覚的です。
- （Claude Codeにおける）Agents: Messages APIを叩いてツール呼び出しを行うループ単位
- Subagents: 単発のタスクを投げて結果を回収する子Agent。親セッションのコンテキストから派生して動作する。軽い
- Agent Teams: エージェント同士が独立した判断をしながら協調する必要があるとき。ファイルシステムを使ったステートフルで、セッションをまたいで文脈を保持することができるアーキテクチャ
OSのプロセスモデルで喩えると、Agentが単一プロセス、Subagentsがその中のスレッド（親のメモリ空間を共有し、結果を返して終了する）だとすれば、Agent Teamsはforkした独立プロセス同士がファイルシステム経由のIPCで協調する構成です。計算コストは増えますが、それぞれが自律的に判断できるのが強みです。
とはいえTowards a Science of Scaling Agent Systemsにあるようにタスクとして整理した順次実行のワークフローをマルチエージェント化しても性能が上がるとは限らないので、汎用的にAgent Teamsが機能するのかは分かりません。とりあえず、わちゃわちゃエージェントたちがパネル上で動いて楽しいのが現在の価値です（お金はかかります）。