Claude Codeを1人で使い慣れた人で、並列に動く複数のClaudeセッションを役割分担して動かしたい場面が出てきた人向け
Claude Codeを使っていて、PRレビューを「セキュリティ・パフォーマンス・SEO・アクセシビリティ」の4観点で同時にやらせたい場面、書き直しを「UI層・DB層・認証層・テスト層」のように領域別で同時並行で進めたい場面、謎のバグで5つの仮説をぶつけ合って原因を絞り込みたい場面で、leadのClaudeに「Agent Teamを作って」と自然な日本語で頼むと内部でTeamCreateが呼ばれてチームが発足する。終わったら同じlead側で「チーム解散して」と頼むとTeamDeleteが呼ばれて掃除される
Claude Codeを1人で使ってる時の「もう1人のClaudeに別観点で同時に見てほしい」を、別プロセスのClaudeを4人並走させて実現する仕組みが Agent Teams で、その発足と解散を担当する2つの内蔵ツールが TeamCreate と TeamDelete です。発足側が TeamCreate、解散側が TeamDelete、間に並列作業が挟まる。
実験機能扱いで、v2.1.32以降のClaude Codeで、かつ CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 という設定値をsettings.jsonかターミナル側に通してある状態でしか呼べません。設定なしでlead側に「チーム作って」と言っても、ツール自体が存在しないので無視されます。
噛み砕くと
会議室のホワイトボードを真ん中に置いて、4人のClaudeが別々の専門担当で同じプロジェクトを並行で触る、というイメージです。TeamCreate は会議室の予約とメンバー召集、TeamDelete は終わった後にホワイトボードを消して全員退出させる作業に相当します。
1人のClaudeを4回起動して並べるのとは違って、4人の間で直接メッセージが飛ばせる構造になっている。leadを経由しなくても、フロント担当からSEO担当に「このh1の文言これでいい？」と直接聞ける。ここがsubagentとの一番の違いです。
大事な前提：設定値を通していないとツール自体が存在しない
このツールは、Claude Codeのバージョンが v2.1.32 以降で、かつ CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 という設定値がパソコン側に通っている時しか呼び出せません。設定がない状態で「チーム作って」と頼んでも、Claudeは「そんなツール持ってない」と言って単発で進めます。
通し方は2つあります。1つ目は ~/.claude/settings.json の env 欄に書く方法、2つ目はターミナル側で export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 と打ってからClaude Codeを起動する方法です。前者は永続、後者はそのターミナルが開いてる間だけ有効。
「料理ブログのモバイル対応リニューアル」で4チームを立ち上げる手順を見る
料理ブログを運営していて、PCで作った既存サイトをスマホで読みやすくリニューアルしたい、という想定で進めます。やりたい作業は4つあって、それぞれ別の専門知識が要る。1人のClaudeに順番にやらせてもいいんですが、4人並走させた方がだいぶ速いし、互いの判断にツッコミも入る。
ステップ1: 設定値を通してClaude Codeを起動する
まずはターミナルで設定値を通します。
$ export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
$ claude --version
2.1.32
$ claudeバージョンが v2.1.32 未満だとツール自体が古いClaude Codeに入ってないので、先に npm install -g @anthropic-ai/claude-code でアップデートを済ませる。
ステップ2: leadに自然な日本語でチーム発足を頼む
立ち上がったClaudeに、ホワイトボードに書くような口語で頼みます。スラッシュコマンドではなく、普通の会話文でOK。
料理ブログをスマホ向けにリニューアルしたい。Agent Teamを作って、
4人のteammateで並行で動かしてほしい。それぞれの担当はこう:
- フロントエンドCSS担当: スマホでの見栄え、フォントサイズ、余白
- SEOメタタグ担当: title、description、OGP、構造化データ
- レシピDBスキーマ担当: 材料・手順・カテゴリのテーブル設計
- 批判的レビュー担当: 他の3人の成果物に厳しめにツッコミを入れる役
Sonnetで全員回してほしい。タスクごとにplan approvalは不要。ステップ3: leadが TeamCreate を呼ぶ瞬間を見届ける
頼み終わると、lead側のClaudeが内部で TeamCreate を呼んで、4人のteammateを別プロセスとして立ち上げます。ホームフォルダ内の .claude/teams/{チーム名}/config.json という書類が自動で書き出されて、4人の名前・役割・各セッションIDが記録されます。
ここで初心者がやりがちな勘違いがあって、この config.json を「先に手で書いておけば設定がカスタマイズできる」と思って事前に書こうとする人がいます。これはNGで、ツール側が毎回上書きするので書いたものは消えます。ここは自動生成に任せる。
ステップ4: 4人が同時並行で動くのを眺める
in-processモードだと、4人のteammateが同じターミナル内で動きます。Shift+Down で「次の人の画面」に切り替えできる。tmuxかiTerm2を入れてあれば split-pane モードで全員の作業を同時に見られます。
共有のタスクリストがホームフォルダ内の .claude/tasks/{チーム名}/ フォルダで裏で動いていて、誰が何のタスクを担当中か、誰が空いてるかが自動更新されます。Ctrl+T でタスクリスト表示の切り替え。
ステップ5: teammate同士のやりとりを発生させる
批判的レビュー担当が、フロントCSS担当の成果物に異論を出してくる場面がきます。
批判担当 → CSS担当（SendMessage経由）
「タップ領域が44px未満の箇所がある。Apple HIG違反。」
CSS担当 → 批判担当
「了解、ボタンpaddingを8pxから12pxに広げた。」このやりとりは lead を経由しません。teammate同士が直接 mailbox で会話します。leadは結果報告だけ受け取る形。
ステップ6: 全員の作業が終わったら TeamDelete で解散
4人が「タスク全部終わりました」とleadに idle通知を返してきたら、leadに解散を頼みます。
みんな終わったみたいだから、チーム解散して。leadが内部で TeamDelete を呼びます。動いているteammateがまだ残っていると失敗するので、その時は「全員にshutdownを頼んでから解散して」と追加で頼む。成功すると、ホームフォルダ内の .claude/teams/{チーム名}/ と .claude/tasks/{チーム名}/ が掃除されて、4人のプロセスも止まります。
TeamCreate / TeamDelete でできること・できないこと
- できること: 別プロセスのClaude Codeを複数体まとめて立ち上げ、それぞれに役割と作業を割り当て、共有のタスクリストとメッセージ箱を用意する。終わったら全部まとめて掃除する
- できないこと: 既存のClaudeセッションを途中からチーム化することはできない。チームを作った瞬間のセッションがそのままleadに固定されて、別のセッションに役を渡すこともできない
- 意味が薄い場面: 1ファイルだけのちょっとした書き直し、同じファイルを順番に編集する作業、依存関係が直列で並んでいる作業。teammateが互いの作業を待つだけになるので、トークン代だけ余分にかかって速くならない
使いどころ3シナリオ（具体題材で再現）
シナリオ1: 料理ブログのリニューアル前にPRを4観点で同時レビューしてほしいとき
セキュリティ・パフォーマンス・SEO・アクセシビリティの4つを、4人のteammateに同時に見てもらう。1人ずつ順番に頼むと「セキュリティの観点で見て」「次はパフォーマンスで」と切り替えるたびに最初の答えに引っ張られて視野が狭まりますが、4人並走なら最初から独立した観点で動きます。仕上がりが速いだけじゃなくて、見落としが減る。
シナリオ2: 家計簿アプリの書き直しを領域別に同時に進めたいとき
UI層・DB層・認証層・テスト層をそれぞれ別のteammateに任せる。同じファイルを2人が同時に触ると上書き合戦になるので、leadに「ファイル所有を割り当てて」と頼んで、お互いのファイルには手を出さないルールにしてから走らせる。完成したらPR1本にまとめる。
シナリオ3: 「謎のバグの原因が分からない」で5つの仮説を競争させたいとき
「タイムアウト説」「メモリリーク説」「ライブラリのバージョン違い説」「設定値の不一致説」「サーバー側の設定変更説」の5つを、5人のteammateに別々に検証させる。さらに「お互いの仮説に反証を試みろ」と頼んでおくと、最後まで反証されずに残った説が本物の原因である可能性が高まる。1人で順番に検証すると最初に見つけたそれっぽい説で止まってしまう問題を、構造で潰せる。
初心者が踏みやすい落とし穴
- 設定値を通し忘れて「チーム作って」と頼んでも何も起きない。
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1がないとTeamCreateもSendMessageもTeamDeleteもClaudeの手元に存在しません。先にsettings.jsonかターミナル側で必ず通す - teammateが動いている状態で TeamDelete を叩くと失敗する。leadは「アクティブな子がいるよ」と返してきます。先に全員shutdownを頼んでから、もう一度「解散して」と言うのが正しい順番
- subagentとごっちゃにする。subagentは親に結果を返したら消える下請け、teammateは互いに直接やりとりする独立メンバー。トークン代もteammateの方がかなり高い。4人なら単純に4倍の記憶領域を食うので、並列で議論させたい時だけteammateを使う
/resumeでセッションを復活させてもteammateは戻ってこない。in-processモードのteammateはセッション再開に未対応で、leadだけが復活した状態で「○○さんに頼んで」と言っても本人は存在しません。teammateは立ち上げ直すしかない- leadを後から差し替えできない。チームを作った瞬間のセッションがlifetime全期間でlead役に固定されます。teammateを昇格させたり、別のターミナルで開いてるセッションにleadを移したりはできない。leadを終わらせたい時はチームごと解散して作り直す
- 同じファイルを2人が同時に触ると上書き合戦になる。teammate同士のファイルロックは存在しません。leadに「フロントCSS担当はstyle.cssだけ、SEO担当はindex.htmlのhead部分だけ」とファイル所有を割り当ててから走らせる
- split-paneモードはVS Codeの内蔵ターミナルでは動かない。Windows TerminalやGhosttyでも非対応。tmuxかiTerm2が要る。動かない環境ではin-processモードに自動で落ちます
- チームは同時に1つしか持てない。leadが管理できるチームは1つまで。前のチームが残ったまま新しいチームを作ろうとしても失敗するので、先に「チーム解散して」で既存チームを片付けてから次を立ち上げる
- teammateにさらにチームを作らせることはできない。チームが作れるのはlead側のみ。「バグ仮説担当のteammateに検証用のサブチームを作らせたい」という構造は動かない。入れ子チームは非対応
書き方
1) 先にCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を settings.json の env 欄か、ターミナル側のexportで通す → 2) Claude Code（v2.1.32以降）を起動して、自然な日本語で「○○の作業を、△△担当と□□担当と××担当の3人のteammateで並列で動かして」と頼む（leadが内部でTeamCreateを呼ぶ） → 3) 作業が終わったらleadに「Clean up the team（チーム解散して）」と頼む（leadが内部でTeamDeleteを呼ぶ）やってみるとこうなる
入力
（leadのClaudeに自然な日本語で）料理ブログをスマホ向けにリニューアルしたい。Agent Teamを作って、4人のteammateで並行で動かしてほしい。それぞれの担当はこう: フロントエンドCSS担当、SEOメタタグ担当、レシピDBスキーマ担当、批判的レビュー担当。Sonnetで全員回してほしい出力例
（発足時）Team 'recipe-blog-mobile' created with 4 teammates: frontend-css, seo-meta, db-schema, critical-reviewer. Task list initialized at ~/.claude/tasks/recipe-blog-mobile/. Use Shift+Down to cycle through teammates.（解散時）Team 'recipe-blog-mobile' cleaned up. Removed 4 teammate processes and shared resources.このページに出てきた言葉
- 実験機能
- 公式が「正式版ではない、まだ仕様や挙動が変わる可能性がある」と明言している機能。デフォルトでオフにされていて、設定で明示的に有効化する必要がある
- CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
- パソコンが起動時に覚えている設定値の名前。Claude Codeが起動時にこの値を確認して、1ならAgent Teams機能を有効化する
- lead（リード）
- チームを立ち上げた本人のClaudeセッション。チーム全体の司令塔役で、teammate全員に指示を出したり最後に解散させたりするのが仕事。チームの寿命の間ずっとlead役は固定で、別セッションに役を移せない
- teammate（チームメイト）
- leadから呼び出された別プロセスのClaude Code。それぞれが独立した記憶領域を持って、別々の作業を同時並行で進める。teammate同士で直接メッセージのやりとりもできる
- subagent（サブエージェント）
- 親のClaudeが裏で「これ調べてきて」と一時的に呼び出す下請けのClaude。teammateと違って親に結果を返したら消える。並列に議論させる用途には向かない
- tmux（ティーマックス）
- ターミナルを縦横に分割して複数の画面を同時表示できるツール。Agent Teamsの画面分割モードで使われる。macOSとLinuxで動く
- iTerm2（アイタームツー）
- macOS用の高機能ターミナルアプリ。tmuxの代わりにAgent Teamsの画面分割を担当できる
- mailbox（メールボックス）
- teammate同士がメッセージをやりとりする仕組み。郵便受けのイメージで、相手がいま忙しくても投函しておけば後で読まれる