Claude Code の agent teams とサブエージェントの違い：使い分けとチームの作り方

Agent teams とサブエージェントの違い

どちらも別々のコンテキストウィンドウで並列に仕事をします。違いは誰が調整するかです。サブエージェントではメインのエージェントがすべてを管理し、チームではチームメイトが共有リストからタスクを引き受け、互いに話し合います。

Agent teams を使うべきとき（使うべきでないとき）

• 調査とレビュー：チームメイトが別々の角度から問題を調べ、互いの結論に異議を唱えます。
• 新しいモジュールや機能：フロントエンド、バックエンド、テストのように、チームメイトごとに別の部分を担当します。
• 仮説が競合するデバッグ：複数のチームメイトがそれぞれ自分の仮説を証明し、他の仮説を反証しようとします。
• 順番に進める仕事、同じファイルの編集、依存関係の多いタスクには向きません。その場合は 1 つのセッションかサブエージェントを使いましょう。
• 日常的な作業にも向きません。アクティブなチームメイトが増えるほどトークン使用量も増えます。

Claude Code の agent team を設定する方法

1. Agent teams をオンにする

   環境変数、または settings.json の env ブロックで CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を 1 に設定します。チームには対話型セッションが必要です。-p（および Agent SDK）では、Claude はチームメイトを起動しません。

   // settings.json: agent teams are experimental and off by default
   {
     "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }
   }
   
   // Optional: give each teammate its own split pane (tmux or iTerm2)
   {
     "teammateMode": "auto"
   }

2. チームを普通の言葉で説明する

   チームメイトの人数と、それぞれの担当を伝えます。Claude が共有タスクリストを作り、チームメイトを起動し、終わったら結果をまとめます。

   Spawn three teammates to review PR #142:
   - One focused on security implications
   - One checking performance impact
   - One validating test coverage
   Have them each review and report findings.

3. 表示モードを選ぶ

   デフォルトはインプロセスモードで、どのターミナルでも動きます。チームメイトはプロンプトの下のパネルに表示され、矢印キーと Enter で開いてメッセージを送れます。タスクリストは Ctrl+T で表示します。分割ペインモードではチームメイトごとに専用のペインが使われ、tmux か、it2 CLI を入れた iTerm2 が必要です。teammateMode を auto または tmux に設定するか、claude --teammate-mode auto で起動します。

4. 定義済みのロールを再利用する

   「using the security-reviewer agent type」でチームメイトを頼むと、.claude/agents/ のサブエージェント定義を、そのツール・モデル・指示ごと再利用できます。

5. 舵を取り、最後に終了する

   チームメイトの様子を確認し、方向を修正しましょう。リーダーがチームメイトの仕事を自分で始めたら「wait for your teammates」と伝えます。終えるときは、リーダーにチームメイトを名前で指定して終了させます。チームのディレクトリはセッション終了時に片付けられます。

出典：Claude Code のドキュメント「Agent teams」

ベストプラクティスと制限

• まずはチームメイト 3〜5 人、1 人あたり 5〜6 タスク程度から始めましょう。焦点の定まった 3 人は、ばらばらな 5 人に勝ることがよくあります。
• チームメイトごとに別のファイル群を割り当てます。2 人が同じファイルを編集すると、互いに上書きしてしまいます。
• タスクの詳細は起動時のプロンプトに書きます。チームメイトは CLAUDE.md、MCP サーバー、skills を読み込みますが、リーダーの会話は引き継ぎません。
• hooks を品質ゲートに使えます。TeammateIdle、TaskCreated、TaskCompleted は終了コード 2 で仕事を差し戻せます。
• 制限：1 つのセッションにチームは 1 つ、入れ子のチームは不可、リーダーは交代できない、/resume でインプロセスのチームメイトは戻らない、タスクのステータスが遅れることがある。
• 分割ペインは VS Code の統合ターミナル、Windows Terminal、Ghostty では使えません。インプロセスモードはどこでも動きます。
• Agent teams をオンにすると、Claude が名前で呼んだサブエージェントがチームメイトとして起動することがあります。通常のサブエージェントに戻したい場合は、変数を 0 にしましょう。

Agent teams と、Claude Code を並列で動かすほかの方法

Agent teams は、あなたが見守っている 1 つのタスクを 1 つのセッションの中で分担するものです。独立したタスクなら、git worktrees で別々のセッションを動かすか、バックグラウンドエージェントとして動かしましょう。全体の比較は複数の Claude Code エージェントを、コストを抑える方法はClaude Code のトークン使用量を減らす方法をご覧ください。

セッションが終わっても働き続けるチーム

Agent team は 1 つのセッションの中にしか存在せず、閉じれば止まります。Crewmark は Claude Code、Codex、DeepSeek Harness、OpenCode のセッションを、続いていく職種・目標・勤務時間を持つ AI 社員に変えます。社員はハートビートで起き、共有ボードから次の issue を取り、判断が必要なときはメッセージを送ってきます。

1. 社員ごとに職種を与える

   ソフトウェアエンジニア、レビュアー、SEO スペシャリスト：チームメイトとして起動していたロールを、ずっと残しておけます。

2. 1 つのボードで働く

   セッションのタスクリストの代わりに issue を使います。issue は再起動しても、何日、何週間たっても残ります。

3. ハートビートで仕事を始める

   勤務時間中、15分、30分、60分ごとに。AI 社員とはをご覧ください。

Claude Code の agent teams に関するよくある質問