「チームメイトが見えない」「タスクがずっとpendingのまま」「セッションを再開したらリードがおかしくなった」──
Claude Code Agent Teamsを使い始めて最初にぶつかる壁は、だいたいこのどれかです。実験的機能なので公式ドキュメントには書かれていない挙動も多く、Xや海外フォーラムの情報を漁ることになりがちです。
この記事では、Agent Teamsを実際に使った現場で出てくる疑問を Q&A 形式でまとめました。セットアップから本番運用のトラブルシューティングまで、詰まりポイントを一通り解消できるはずです。
そもそもAgent Teamsとは何か
Agent TeamsはClaude Code v2.1.32で導入された実験的機能です。複数のClaude Codeインスタンスが「チームリード」と「チームメイト」という役割で協調して動作します。
SubagentsとAgent Teamsの違いを一言で言えば、メンバー同士が直接メッセージを送り合えるかどうかです。
| 比較軸 | Subagents | Agent Teams |
|---|---|---|
| コンテキスト | 独立したコンテキストウィンドウ、結果をリードに返す | 独立したコンテキストウィンドウ、完全に独立 |
| 通信 | メインエージェントにのみ結果を報告 | メンバー同士が直接メッセージ可能 |
| 調整 | メインエージェントが全作業を管理 | 共有タスクリストで自己調整 |
| 最適な用途 | 結果だけが重要な集中したタスク | 議論・協調が必要な複雑な作業 |
| トークンコスト | 低い（結果だけがメインコンテキストに戻る） | 高い（各メンバーが独立したClaudeインスタンス） |
重要なのは、トークンコストはメンバー数に比例して増加する点です。3名チームは単独セッションの3倍以上のトークンを消費します。
何が新しいのか
従来のSubagentsが「作業を委任して結果だけもらう」モデルだったのに対し、Agent Teamsは「チームメイトが互いに議論して合意を形成できる」モデルです。これにより以下のユースケースが実現します。
- 競合仮説の並列検証: バグの原因が複数考えられる場合、各メンバーが異なる仮説を追い、互いに反論し合うことで最も確からしい原因に収束できる
- クロスレイヤー実装: フロントエンド・バックエンド・テストを別メンバーが並列実装（ファイル衝突に要注意）
- 多角的レビュー: セキュリティ・パフォーマンス・テストカバレッジを各1名が担当し、同時レビュー
具体的に何ができるようになるのか
Q1: Agent Teamsを有効にするにはどうすればいいですか？
settings.jsonに環境変数を追加するだけです。Claude Code v2.1.32以上が必要です。
// ~/.claude/settings.json
// 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
または環境変数として直接設定することもできます。
# シェルで一時的に有効化
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude
# または .zshrc / .bashrc に追記して永続化
echo 'export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1' >> ~/.zshrc
有効化後、Claudeに「チームを作って」と伝えるだけでチームが起動します。
Q2: チームメイトが見えないのですが？
in-processモード（デフォルト）では、`Shift+Down`でチームメイトのセッションに切り替えます。最後のメンバーを超えるとリードに戻ります。tmuxやiTerm2がある環境ではsplit-panesモードが使えます。
# tmuxでsplit-panesモードを強制（全メンバーが別ペインで見える）
claude --teammate-mode tmux
# in-processを強制（任意のターミナルで動作）
claude --teammate-mode in-process
# ~/.claude.json でグローバル設定
# { "teammateMode": "tmux" }
チームメイトがそもそもスポーンされていない場合は、与えたタスクが並列作業の価値がないとClaudeが判断した可能性があります。「3名のチームメイトで作業してください」と明示的に人数を指定すると確実です。
Q3: タスクがpendingのまま進まないのですが？
タスクのスタックは最も頻繁に起きる問題の一つです。チームメイトがタスクを「完了」マークし忘れると、依存タスクが永遠にブロックされます。
// 解決方法1: リードに確認を指示する
「researcher チームメイトのタスク2が完了しているかどうか確認して、
もし完了していたら手動でタスクを更新してください」
// 解決方法2: 直接チームメイトに話しかける（Shift+Downで切り替えてから）
「あなたのタスクは完了しましたか？タスクリストを更新してください」
// 解決方法3: タスクを分割してリスタート
「現在のチームを解散して、より小さなタスク（1タスクあたり30分以内）
に分割し直してください」
予防策: タスク設計時は「明確な完了条件」を含めることが重要です。「実装する」ではなく「src/auth.py を実装し、全テストがパスしたら完了とする」のように条件を明示します。
Q4: ファイル競合が起きた場合どう対処すればいいですか？
Agent Teamsの最大の落とし穴がファイル競合です。2名のメンバーが同じファイルを編集すると、後から保存した方が上書きします。
# git worktreeを使うと各メンバーに独立したブランチ・作業ディレクトリを与えられる
# これがファイル競合の根本解決策
# メンバー用のworktreeを事前に作成
git worktree add ../project-feat-auth feat/auth
git worktree add ../project-feat-api feat/api
git worktree add ../project-feat-ui feat/ui
# チーム起動時に各メンバーに担当ディレクトリを指定する
「3名のチームメイトを起動してください:
- auth担当: ../project-feat-auth で認証モジュールを実装
- api担当: ../project-feat-api でAPIエンドポイントを実装
- ui担当: ../project-feat-ui でUIコンポーネントを実装」
worktreeを使わない場合は、少なくともファイルの所有権を明確に分担してください。同じファイルを2名が触ることは避けます。
Q5: セッション再開後にチームメイトがいなくなった
これはAgent Teamsの既知の制限です。`/resume` や `/rewind` はin-processチームメイトを復元しません。再開後にリードが存在しないチームメイトにメッセージを送ろうとするエラーが起きます。
// 対処法
「前のセッションのチームメイトは存在しません。
新しいチームメイトを同じ役割でスポーンし直してください。
前の作業状況は [ファイル名] を参照してください」
長時間の作業では、定期的にチームの進捗をファイルに記録させておくことで、セッション断のリスクを軽減できます。
よくある誤解
誤解1: チームメイトはリードの会話履歴を引き継ぐ
実際は引き継ぎません。チームメイトはプロジェクトのCLAUDE.md・MCPサーバー・スキルはロードしますが、リードとの会話履歴は持ちません。スポーン時のプロンプトに必要なコンテキストを全て含める必要があります。
誤解2: ネストしたチームが作れる
チームメイトは自分のチームやチームメイトをスポーンできません。リードだけがチームを管理できます。階層的なエージェント構造が必要な場合は、Subagentsを組み合わせる設計を検討してください。
誤解3: 権限をメンバーごとに細かく設定できる
スポーン時点では、全チームメイトはリードの権限設定を引き継ぎます。スポーン後に個別変更は可能ですが、細粒度の権限設計は現時点では限定的です。危険な操作が含まれる場合は、`plan approval`（リードの承認後に実装開始）機能を活用してください。
// plan approval の使い方
「security担当のチームメイトをスポーンし、変更を開始する前に
計画を承認するよう要求してください」
結局どうすればいいのか
Agent Teamsを使うかSubagentsで十分かを判断する基準を整理します。
- Agent Teamsを使う: メンバー同士が知見を共有・議論する必要がある、独立したコードモジュールを並列実装したい、競合仮説を同時に検証したい
- Subagentsで十分: 調査・リサーチなど結果だけを返せばいいタスク、順次依存が多いタスク、同じファイルを複数人が触る作業
初めてAgent Teamsを使うなら、まず読み取り専用タスク（PRレビュー・コードインスペクション・リサーチ）から始めることを強くすすめます。書き込みを伴わないタスクならファイル競合が起きないため、チームの仕組みを安全に学べます。
あわせて読みたい:
- AIエージェント構築完全ガイド — マルチエージェント設計の基礎からリードとサブエージェントの設計パターンまで
- AIエージェントツール比較 — Agent Teamsと組み合わせて使えるフレームワーク横断選定ガイド
参考・出典
- Agent Teams公式ドキュメント（Anthropic） — code.claude.com（参照日: 2026-04-11）
- Building a C compiler with a team of parallel Claudes（Anthropic Engineering Blog） — anthropic.com（参照日: 2026-04-11）
- 30 Tips for Claude Code Agent Teams（John Kim） — getpushtoprod.substack.com（参照日: 2026-04-11）
- Claude Code Git Worktree Architecture（Morph） — morphllm.com（参照日: 2026-04-11）
著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー10万人超。
100社以上の企業向けAI研修・導入支援。著書累計3万部突破。
SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。
ご質問・ご相談は お問い合わせフォーム からお気軽にどうぞ。
