Home / Blog / Claude Code Agent Teams 完全ガイド 2026 — コスト計算から失敗パターンまで

Claude Code Agent Teams 完全ガイド 2026 — コスト計算から失敗パターンまで

Claude Code Agent Teams 完全ガイド 2026 — コスト計算から失敗パターンまで

Claude Code Agent Teamsの有効化から実践活用まで。Subagentsとの使い分け判断、Hooksでの品質ゲート、Maxプランでのコスト試算、よくある失敗と対策を網羅。

Claude CodeAgent TeamsAI開発並列処理

エンジニアのゆとです。

Claude Code v2.1.32からAgent Teamsという機能が使えるようになった。

複数のClaude Codeインスタンスを1つのチームとして動かして、共有タスクリストで作業を分担させる仕組みだ。サブエージェント（Task tool）とはアーキテクチャが根本的に違っていて、「チームメイト同士が直接通信できる」という点が本質的な差になる。

ただし実験的機能で、デフォルトは無効。「significantly more tokens（大幅に多くのトークン）を消費する」という公式注記もある。雰囲気で使い始めるとMaxプランの枠を溶かすことになるので、コスト構造から失敗パターンまで体系的に整理した。

Agent Teamsとは — 2026年の現在地

実験的機能としての位置づけ（v2.1.32以降、デフォルト無効）

Agent TeamsはClaude Code v2.1.32以降で使えるが、デフォルトは無効になっている。有効化するには環境変数 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 をセットする必要がある。

「Experimental」という名称のとおり、現在も開発中の機能で、いくつかの制限がある。セッション再開時にin-processのTeammateは復元されない、ネストチームは作れない、同時に動かせるチームは1つだけ——といった制約が残っている。

# バージョン確認
claude --version
# v2.1.32 以上が必要

利用するにはまず settings.json に1行追加する：

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

これだけで有効化される。

Subagentsとの根本的な違い

Agent Teamsを理解するためにまずSubagentsとの比較が必要だ。どちらも「並列処理」という文脈で語られるが、設計思想が違う。

比較軸SubagentsAgent Teams
コンテキスト独立。結果だけをメインに返す独立。完全に独立したセッション
エージェント間通信不可（メインとしか話せない）可能（Teammateが直接通信できる）
調整方法メインエージェントが全管理共有タスクリストで自己調整
向いているタスク結果だけ必要な集中タスク議論・議論・協調が必要な複雑作業
トークンコスト低め（結果要約をメインに返す）高め（各Teammateが独立インスタンス）

Subagentsは「研究者を外注して結果書を受け取る」感覚に近い。Agent Teamsは「チームミーティングで全員がホワイトボードを共有しながら議論する」感覚だ。

Teammateが互いに仮説を反証し合えるのがAgent Teamsの核心で、これはSubagentsには絶対できない。

Agent Teamsのアーキテクチャ

4つのコンポーネント

Agent Teamsは以下の4つで構成されている：

┌─────────────────────────────────────────────┐
│                  Team Lead                   │
│ （メインCCセッション）                        │
│ ・チーム作成 / Teammateスポーン              │
│ ・作業調整 / 結果統合                        │
└───────────────┬─────────────────────────────┘
                │
        ┌───────┴───────┐
        │  Shared Task  │  ← Task List（pending/in progress/completed）
        │     List      │
        └───────┬───────┘
                │
    ┌───────────┼───────────┐
    ▼           ▼           ▼
┌────────┐ ┌────────┐ ┌────────┐
│Teammate│ │Teammate│ │Teammate│  ← 各自が独立コンテキスト
│   A    │ │   B    │ │   C    │
└───┬────┘ └───┬────┘ └───┬────┘
    │          │          │
    └──────────┼──────────┘
               │
           Mailbox（直接通信）

各コンポーネントの役割：

  • Team Lead: メインのClaude Codeセッション。チームを作り、Teammateをスポーンして、作業を調整する。会話の入口でもある
  • Teammates: 独立したClaude Codeインスタンス。各自がタスクを実行する。互いに直接通信できる
  • Task List: 全エージェントが参照・更新できる共有タスクリスト。ファイルロックで競合を防いでいる
  • Mailbox: エージェント間のメッセージングシステム。TeammateがLeadに送ったメッセージは自動で届く（LeadがポーリングするわけではなくPush型）

チームのデータは以下のパスにローカル保存される：

~/.claude/teams/{team-name}/config.json   # チーム設定（ランタイム状態）
~/.claude/tasks/{team-name}/              # タスクリスト

config.json はClaudeが自動更新する。手動で編集すると状態が壊れるので触らないこと。

タスクのライフサイクル（pending → in progress → completed）

タスクには3つの状態がある：

pending → in progress → completed

依存関係も持てる。依存先のタスクが completed になるまで、そのタスクは pending 状態のまま claim できない仕組みだ。

依存関係の解決は自動で、Teammateがタスクを完了させると、依存していたタスクが自動でunblockされる。

Teammateのタスククレーム（taking ownership）はファイルロックで排他制御している。複数のTeammateが同じタスクを同時にclaimしようとしてもrace conditionは起きない。

ファイルロックによる同時Claim防止

ファイルロック機構は公式の説明では「task claiming uses file locking to prevent race conditions」とある。複数Teammateが並走するときでも、同じタスクを2人が同時にやり始めることはない。

ただし「タスクステータスの更新が遅延する」というバグは現状ある。Teammateが作業を終えても completed に更新し忘れることがあって、これが依存タスクのブロックを引き起こす。後述の失敗パターン3で詳しく扱う。

セットアップ手順

有効化（settings.jsonに1行追加）

最小構成のセットアップ：

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

プロジェクト固有で有効化したい場合は .claude/settings.json でも同様に設定できる。

表示モード選択（in-process vs split-pane）

Agent Teamsには2つの表示モードがある：

in-process モード: Teammateが全員メインターミナル内で動く。Shift+Down でTeammateを切り替えて直接メッセージを送れる。どんなターミナルでも動く。追加設定なし。

split-pane モード: 各TeammateがそれぞれのペインをVになる。全員の出力を同時に見られて、クリックしてTeammateに直接話しかけられる。tmux か iTerm2 が必要。

デフォルトは "auto" で、tmuxセッション内で起動していればsplit-pane、そうでなければin-processになる。

強制指定したい場合は settings.json に追加：

{
  "teammateMode": "in-process"
}

または起動フラグで一時的に指定：

claude --teammate-mode in-process

tmux/iTerm2のセットアップ

split-paneモードを使いたい場合のセットアップ：

# tmux のインストール（macOS）
brew install tmux

# tmux内でClaude Codeを起動する
tmux new-session
claude  # tmuxセッション内なので自動でsplit-paneになる

iTerm2を使う場合：

# it2 CLI のインストール
npm install -g it2

# iTerm2 → Settings → General → Magic → Enable Python API をオンにする
# その後 Claude Code を起動

注意: split-paneモードはVS Codeの統合ターミナル、Windows Terminal、Ghosttyでは動かない。

実践ユースケース3選

ユースケース1: PRレビューの3視点同時分析（セキュリティ/パフォーマンス/テスト網羅性）

単一レビュアーはどうしても「今気になってる問題」を深堀りしがちで、他の観点がおろそかになる。3つのTeammateに独立したレンズを持たせることで、全観点が確実にカバーされる。

PR #142を3視点でレビューしてほしい。

Teammateを3人スポーンして：
- セキュリティTeammate: SQL injection / auth bypass / sensitive data exposure 中心に
- パフォーマンスTeammate: N+1クエリ / メモリリーク / 不必要なネットワーク呼び出し中心に
- テストTeammate: カバレッジ不足 / エッジケース / テストの質中心に

全員のレビュー完了後、Leadが findings を統合してください

このパターンが効くのは、各Teammateが「自分のレンズ以外は意識しなくていい」からだ。セキュリティTeammateはパフォーマンスの話をしない。代わりに、セキュリティに関して徹底的に調べる。

ユースケース2: フルスタック機能開発（フロント/バック/テスト各Teammate担当）

機能開発を独立したモジュールごとにTeammateに担当させる。ファイルスコープが分離している前提が成立するなら、Subagentsより効率的だ。

ユーザー認証機能（OAuth 2.0対応）を実装してほしい。

Teammateを3人スポーン：
- フロントTeammate: src/components/auth/ 以下のUI実装担当
- バックTeammate: src/api/auth/ 以下のAPIエンドポイント担当
- テストTeammate: tests/auth/ 以下のe2eテスト担当（フロント・バックが完了後に着手）

フロントとバックは並列進行。テストは両方が完了してから開始。
インターフェース（APIスキーマ）はLeadが先に定義してTeammateに共有してください

フロントとバックを並列で走らせるにはインターフェースの事前合意が必要だ。LeadにAPIスキーマを先に定義させてから両方をスポーンすると、「お互いの実装を待つ」待ち時間がなくなる。

ユースケース3: バグ調査の仮説検証レース

原因不明のバグを調査するとき、単一エージェントは「最初に見つけた仮説に引っ張られる」という認知バイアスを持つ。複数Teammateに異なる仮説を持たせて、互いに反証させる。

ユーザーから「セッションが突然切れる」という報告が複数件入っている。
5人のTeammateを使って並列調査してほしい。

Teammate A: メモリリークの仮説 — profilerデータと heap dump を分析
Teammate B: タイムアウト設定の仮説 — nginx / load balancer の設定を確認
Teammate C: トークン期限切れの仮説 — JWTの有効期限処理を確認
Teammate D: DB接続プールの枯渇仮説 — DB接続ログを分析
Teammate E: 競合他社製ライブラリのバグ仮説 — 使用ライブラリのissueトラッカーを確認

各Teammateは調査完了後、他のTeammateの仮説を反証できないか試みてください。
最終的な合意はfindings.md に書いてください

「互いに反証を試みる」という指示が重要だ。自分の仮説を証明するだけでなく、他の仮説を崩しに行く動きをさせることで、生き残った仮説の信頼度が上がる。

Hooks品質ゲートの実装（他サイト未カバー）

Agent Teams専用のHooksが3つある。既存のPreToolUse/PostToolUseとは別のイベントで、チームの品質管理に使える。

TeammateIdleフック — Teammateが暇になったらフィードバックを返す

TeammateIdleはTeammateがアイドル状態になる直前に実行される。exit code 2を返すとTeammateはアイドル化せず、stderrの内容がTeammateへのフィードバックとして送られる。

入力JSONのスキーマ：

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/transcript.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "TeammateIdle",
  "agent_type": "Explore",
  "agent_id": "agent-456"
}

「タスクリストに未完了タスクがまだある場合はアイドルさせない」フックの実装例：

#!/bin/bash
# ~/.claude/hooks/teammate-idle-check.sh

input=$(cat)
agent_id=$(echo "$input" | jq -r '.agent_id')
cwd=$(echo "$input" | jq -r '.cwd')

# タスクリストを確認して未完了タスクがないかチェック
# タスクは ~/.claude/tasks/ に保存される
team_name=$(ls ~/.claude/tasks/ 2>/dev/null | head -1)

if [ -n "$team_name" ]; then
  pending=$(find ~/.claude/tasks/"$team_name"/ -name "*.json" \
    -exec jq -r 'select(.status == "pending") | .name' {} \; 2>/dev/null | wc -l | tr -d ' ')

  if [ "$pending" -gt 0 ]; then
    echo "タスクリストにpendingタスクが${pending}件あります。次のタスクをclaimしてください" >&2
    exit 2
  fi
fi

exit 0

settings.json への登録：

{
  "hooks": {
    "TeammateIdle": [
      {
        "type": "command",
        "command": "~/.claude/hooks/teammate-idle-check.sh"
      }
    ]
  }
}

TaskCreatedフック — タスク粒度をチェックして品質管理

TaskCreatedはタスクが作成される際に実行される。タスク名が空だったり、説明が短すぎるタスクをブロックできる。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/transcript.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "TaskCreated",
  "task_name": "Database migration",
  "task_description": "Migrate to new schema",
  "agent_id": "agent-789"
}

タスク品質を強制するフックの例：

#!/bin/bash
# ~/.claude/hooks/validate-task.sh

input=$(cat)
task_name=$(echo "$input" | jq -r '.task_name')
task_description=$(echo "$input" | jq -r '.task_description')

# タスク名が空の場合はブロック
if [ -z "$task_name" ] || [ "$task_name" = "null" ]; then
  echo "タスク名が設定されていません。具体的な名前を付けてください" >&2
  exit 2
fi

# タスク説明が短すぎる場合はブロック（20文字未満）
desc_length=${#task_description}
if [ "$desc_length" -lt 20 ]; then
  echo "タスク説明が短すぎます（${desc_length}文字）。完了条件を含む説明を書いてください" >&2
  exit 2
fi

# タスク名が「TODO」「Fix」「Update」だけの場合はブロック（具体性なし）
if echo "$task_name" | grep -qiE '^(todo|fix|update|misc|temp)$'; then
  echo "タスク名「${task_name}」は具体性が低すぎます。対象ファイルや機能名を含めてください" >&2
  exit 2
fi

exit 0

TaskCompletedフック — テストパスを確認してからComplete許可

TaskCompletedはタスクが completed にマークされる直前に実行される。exit code 2を返すと完了がブロックされる。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/transcript.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "TaskCompleted",
  "task_name": "Implement login endpoint",
  "task_description": "POST /api/auth/login の実装",
  "agent_id": "agent-789",
  "completion_status": "success"
}

テストを通過していなければ完了させないフックの実装：

#!/bin/bash
# ~/.claude/hooks/require-tests-pass.sh

input=$(cat)
task_name=$(echo "$input" | jq -r '.task_name')
cwd=$(echo "$input" | jq -r '.cwd')

# テストファイルが存在するプロジェクトか確認
if [ ! -f "$cwd/package.json" ] && [ ! -f "$cwd/pyproject.toml" ] && [ ! -f "$cwd/go.mod" ]; then
  # テストが不要なプロジェクト構成の場合はスルー
  exit 0
fi

# タスク名に "test" や "spec" が含まれている場合はスキップ（テスト自体のタスクだから）
if echo "$task_name" | grep -qiE '(test|spec|テスト)'; then
  exit 0
fi

# 簡易テスト実行チェック（Node.jsプロジェクトの場合）
if [ -f "$cwd/package.json" ]; then
  test_script=$(cd "$cwd" && cat package.json | jq -r '.scripts.test // ""')
  if [ -n "$test_script" ] && [ "$test_script" != "null" ]; then
    # テストが失敗したら完了をブロック
    if ! cd "$cwd" && npm test --silent 2>/dev/null; then
      echo "テストが通過していません。タスクを完了にする前にテストをパスさせてください" >&2
      exit 2
    fi
  fi
fi

exit 0

全フックをまとめて設定する場合：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "hooks": {
    "TeammateIdle": [
      {
        "type": "command",
        "command": "~/.claude/hooks/teammate-idle-check.sh"
      }
    ],
    "TaskCreated": [
      {
        "type": "command",
        "command": "~/.claude/hooks/validate-task.sh"
      }
    ],
    "TaskCompleted": [
      {
        "type": "command",
        "command": "~/.claude/hooks/require-tests-pass.sh"
      }
    ]
  }
}

Hooksは非同期ではなくブロッキングで動く。重いスクリプトを仕込むとTeammateの応答が遅くなるので注意。

Subagent Definitionsとの組み合わせ（他サイト未カバー）

Subagent Definitionsは .claude/agents/ または ~/.claude/agents/ に定義ファイルを置く機能で、Agent Teamsのテンプレとしても使える。

.claude/agents/ に役割定義を書く

Subagent DefinitionはMarkdownファイルでYAMLフロントマターを持つ：

---
name: security-reviewer
description: セキュリティ脆弱性のレビュー専門エージェント。auth/暗号化/input validation中心に調査する
model: claude-sonnet-4-6
tools:
  - Read
  - Glob
  - Grep
  - Bash
---

あなたはセキュリティエンジニアとしてコードレビューを行います。

## 調査の優先順位
1. 認証・認可のバイパス可能性
2. SQLインジェクション・XSS等のインジェクション脆弱性
3. センシティブデータの平文保存・ログ出力
4. JWTトークン・セッションの管理不備
5. 外部入力のバリデーション漏れ

## 出力形式
- 重大度（Critical/High/Medium/Low）
- 脆弱性の種類
- 対象ファイル:行番号
- 具体的な修正例

このファイルを .claude/agents/security-reviewer.md として保存する。

Teammateスポーン時に「security-reviewer」等のAgent Typeを指定

Agent Typeを指定してTeammateをスポーンする：

セキュリティレビューTeammateをスポーンして。
"security-reviewer" エージェントタイプを使ってsrc/auth/モジュールを監査してください。

Teammateはそのsubagent definitionの tools 制限と model を引き継ぐ。定義の本文はTeammateのシステムプロンプトに追記される（置き換えではなく追記）。

toolsの限定とmodelの指定

Subagent Definitionでツール制限を使うと、Teammate単位でアクセスを絞れる：

---
name: test-runner
description: テスト実行専門。コードの変更は行わず、テストのみ実行して結果を報告する
model: claude-haiku-4-5
tools:
  - Read
  - Bash
---

テストのみを実行します。コードを変更する権限はありません。
...

model: claude-haiku-4-5 にすることで、テスト実行のような単純タスクをHaikuで処理してコストを抑えられる。

1点注意: Subagent DefinitionのフロントマターにあるSkillsとMCPServersの設定はTeammate動作時には引き継がれない。Teammateはプロジェクト設定（.claude/settings.json と ~/.claude/settings.json）からSkillsとMCPを読み込む。

実装例（セキュリティレビュアー + テストランナー + ドキュメント生成）

3つの役割定義をプロジェクトに置く構成：

.claude/
├── agents/
│   ├── security-reviewer.md   # セキュリティ監査専門
│   ├── test-runner.md         # テスト実行専門（Haiku使用）
│   └── doc-generator.md       # ドキュメント生成専門
└── settings.json

security-reviewer.md:

---
name: security-reviewer
description: セキュリティ脆弱性レビュー専門。PRレビューや新機能のセキュリティ監査を依頼するときに使う
model: claude-sonnet-4-6
tools:
  - Read
  - Glob
  - Grep
  - Bash
---

セキュリティエンジニアとしてコードを審査します。
OWASP Top 10 を基準に重大度を評価してください。

test-runner.md:

---
name: test-runner
description: テストスイートを実行して結果を報告する専門エージェント
model: claude-haiku-4-5
tools:
  - Read
  - Bash
---

テストを実行して、失敗したテストの原因分析と修正提案を行います。
コードの変更は行いません。テスト実行と分析のみです。

doc-generator.md:

---
name: doc-generator
description: JSDoc / Pythonドックストリング / README 等のドキュメント生成専門
model: claude-sonnet-4-6
tools:
  - Read
  - Write
  - Edit
  - Glob
---

実装を読んでドキュメントを生成します。
既存のコメントスタイルに合わせて書いてください。

これらを使ったチーム作成の例：

新機能 (src/payments/) の品質チェックチームを作ってほしい。

- "security-reviewer" タイプのTeammateでsrc/payments/を監査
- "test-runner" タイプのTeammateでtests/payments/を全実行
- "doc-generator" タイプのTeammateでsrc/payments/のJSDocを補完

3人を並列で動かして、完了後にLeadが統合レポートをREPORT.mdに書いてください

コスト試算 — Maxプランでどこまで使えるか

トークン消費の構造（Teammate数 × コンテキストウィンドウ独立消費）

Agent Teamsのコスト構造を理解しておかないと、Maxプランの枠をあっという間に消費する。

各Teammateが独立したコンテキストウィンドウを持つ。つまり3人チームを作ると、同じプロジェクトコンテキスト（CLAUDE.md、MCP設定、etc.）が3回ロードされる。

消費トークン（概算）= リードのセッション分
                   + Teammate数 × (起動時コンテキスト + スポーンプロンプト + 作業中の会話)

公式ドキュメントでは「plan modeで動かしたAgent Teamsは通常セッションの約7倍のトークンを消費する」という記述がある。通常作業では7倍ほどにはならないが、それでも3Teammateなら3倍以上は見ておく必要がある。

実測データ: 3Teammate × 30分作業 = 約何トークン

公式は具体的な数字を出していないが、社内での実測感覚では以下のような感じ：

構成作業内容消費トークン目安
1セッションPRレビュー（中程度のPR）50K〜100K
3Teammate チーム同じPRを3視点でレビュー200K〜400K
5Teammate チームバグ調査（30分並列）400K〜800K

MaxプランはAPIトークンの月次上限が存在する（プランごとに異なる）。集中的にAgent Teamsを使うと1セッションで月間予算の数%を使いきることがある。特にplan modeを組み合わせると消費が跳ね上がる。

/usage コマンドで現在のセッションのトークン使用量を確認できる：

/usage

コスト最適化: TeammateのモデルをSonnetに下げるパターン

もっとも効果的な節約策はTeammateのモデルをOpusからSonnetにすることだ。

コードレビューチームを作ってほしい。
3人のTeammateを全員Sonnetで起動してください。

または /config の「Default teammate model」を設定しておく：

/config
# → Default teammate model を Sonnet に設定

Subagent Definitionを使う場合はDefinitionのフロントマターで model を指定するのが確実だ。

単純なタスク（テスト実行、ドキュメント生成、ファイル収集）はHaikuを使ってもいい。速いし安い。

「Agent Teamsが割に合うタスク」の判断基準

コスト的に割に合うのはこういうタスクだ：

  • 並列探索の価値が明確（競合仮説を同時に検証、独立したモジュールを同時開発）
  • タスクが大きい（小粒なタスクは起動コストのほうが高い）
  • エージェント間の議論が必要（Subagentsでは実現できない）
  • ファイルスコープが明確に分離できる（ファイル競合リスクがない）

逆に割に合わないのは：

  • 逐次実行でも時間がかからない（1時間の作業をSubagentsで30分にできるなら十分）
  • 同じファイルを複数Teammateが触る可能性がある
  • タスクが細かすぎる（「README に1行追加」にTeam Teamsは不要）
  • 結果の統合が複雑すぎる（LeadのコンテキストもTeammateの結果を統合するために膨らむ）

よくある失敗パターンと対策

失敗1: Leadが自分でタスクを実行し始める → 「Wait for teammates」指示

よくある症状: チームを作ったのに、Leadがプロンプトに返答するついでに自分でコードを書き始める。Teammateに振るべきタスクをLeadが直接やっている。

原因: LeadはどのClaude Codeセッションと同じく、自分でタスクを完了させようとする傾向がある。Teammateに振るという指示が曖昧だと自分でやってしまう。

対策: 明示的に委任を強制する指示を入れる。

このタスクはTeammateを使って並列実行してほしい。
Leadは自分でコードを書かず、Teammateのコーディネーションと結果統合だけを担当してください。
Teammateの作業完了を待ってから次のステップに進んでください。

実行中にLeadが自分でやり始めたら：

待って。自分でやらずにTeammateに任せてください。
まずTeammateが全員のタスクを完了するのを待ってください

失敗2: ファイル競合でお互いの変更を上書き → ファイルスコープの分離設計

よくある症状: 2人のTeammateが同じファイル（たとえば App.tsx や config.ts）を並列で編集して、後から変更したほうが前の変更を上書きする。コンフリクトではなくサイレントな上書きになるので気づきにくい。

原因: ファイルレベルのロック機構はない。Task Listのロックはタスクのclaimだけを保護していて、ファイル編集の排他制御はしていない。

対策: スポーン前にファイルスコープを明確に設計する。

Teammateのファイル担当を明確に分けてほしい：
- Frontend Teammate: src/components/ と src/pages/ のみ編集可
- Backend Teammate: src/api/ と src/services/ のみ編集可
- Shared設定（src/config.ts, src/types.ts等）はLeadが担当

お互いのスコープを侵食しないように指示してください

複数Teammateが package.json や tsconfig.json 等の設定ファイルを同時に触ろうとするケースも要注意。こういう共有設定はLeadが担当するか、タスクに明示的な依存関係を設定して逐次実行させる。

失敗3: タスクステータスが更新されず依存タスクがブロック → 手動介入

よくある症状: Teammateの作業は終わっているのに、タスクリスト上のステータスが in progress のままで、依存タスクが pending から進めない。

原因: これは公式が認めている既知のバグだ。「Task status can lag: teammates sometimes fail to mark tasks as completed, which blocks dependent tasks.」とドキュメントに明記されている。

対策: Leadを介してTeammateに手動でステータス更新を促す。

Teammate Aのタスク「認証APIの実装」は完了しているように見えます。
タスクステータスをcompletedに更新してください

または、Leadに状況確認を依頼する：

現在のタスクリストの状態を確認して、completedになっていないが実は完了済みのタスクがあれば更新してください

TeammateIdleフックを使ってこのバグを緩和することもできる（前述のフック実装を参照）。

失敗4: Teammateが同じ調査を重複実行 → タスク粒度の設計指針（5-6タスク/Teammate）

よくある症状: 3人のTeammateが全員 src/ 以下を grep して同じことを調べている。並列のはずが並列の意味をなしていない。

原因: タスクが大きすぎるか、抽象的すぎる。「このプロジェクトのセキュリティ問題を調べて」というタスクを3人に振ると、全員が同じ調査をする。

対策: 1 Teammateあたり5-6タスクになる粒度で設計する。タスクは「何を調べる」より「どのファイル/コンポーネントを担当する」という形にする。

悪い設計：

全Teammateで src/ のセキュリティ問題を調べてください

良い設計：

タスクを以下の単位に分割してチームを作ってください：
- Teammate A: src/auth/, src/session/ の担当（4タスク）
- Teammate B: src/api/, src/middleware/ の担当（5タスク）
- Teammate C: src/database/, src/models/ の担当（4タスク）
各Teammateのタスクは明確なファイルスコープを持たせてください

失敗5: tmux orphanedセッションの掃除忘れ → tmux ls + tmux kill-session

よくある症状: チームを終了したつもりなのにtmuxセッションが残り続ける。次回起動時に古いセッションが邪魔をする。

原因: cleanupが正常に完了しなかった場合、tmuxセッションが残ることがある。

確認と掃除：

# 現在のtmuxセッション一覧
tmux ls

# 出力例:
# claude-team-1748320000: 4 windows (created Mon May 26 12:00:00 2026)
# my-project: 1 windows (created Mon May 26 10:00:00 2026)

# 不要なセッションを削除
tmux kill-session -t claude-team-1748320000

Agent Teamsのセッション名には claude-team- というプレフィックスが付くことが多い。定期的に確認して掃除する習慣をつけておくといい。

チームの正規の終了手順：

# 1. 全Teammateにシャットダウンを依頼
チームの全Teammateに順番にシャットダウンをリクエストしてください

# 2. Leadにcleanupを依頼
チームをクリーンアップしてください

公式の注意書きにあるとおり、cleanupは必ずLeadから実行する。Teammateがcleanupを実行すると共有リソースが不整合な状態になる可能性がある。

Subagents vs Agent Teams — 判断フローチャート

Subagentsを選ぶべきケース

以下に当てはまるならSubagentsが適切：

  • 結果だけが欲しい（中間の調査プロセスはどうでもいい）
  • タスクが順次実行でも十分速い
  • 同一ファイルを複数エージェントが触る可能性がある
  • チームのセットアップオーバーヘッドを払う価値がない小タスク
  • コスト最優先（Subagentsのほうがトークン消費は少ない）

Subagentsに向いているタスクの例：

  • 大量ファイルの一括レビュー（読んで要約するだけ）
  • 外部APIのドキュメント収集
  • テストの自動実行と結果収集
  • ログの分析

Agent Teamsを選ぶべきケース

以下に当てはまるならAgent Teamsが価値を発揮する：

  • エージェント同士が互いの作業を参照して議論する必要がある
  • 競合する仮説を並列検証して収束させたい
  • 独立したモジュールを同時開発できる（ファイル競合なし）
  • 複雑な調査で「複数の専門家が会議する」形が有効

判断フローをシンプルにまとめると：

エージェント同士の直接通信が必要？
├── Yes → Agent Teams
└── No → タスクが独立している？
           ├── Yes → Subagents（並列）
           └── No → 単一セッション（逐次）

「Teammateが互いの結果を読んでフィードバックを出し合う」という動きが必要な場面がAgent Teamsのトリガーだ。それが不要なら、Subagentsのほうが設定が簡単でコストも低い。

よくある質問（FAQ）

Q. Agent TeamsはいつClaude Code正式機能になりますか？

公式はタイムラインを明言していない。現時点（2026年5月）では「Experimental」の扱いで、セッション再開時のTeammate復元など、既知の制限が残っている。本番プロジェクトでの使用は計画的に。重要なタスクにはSubagentsか単一セッションを使うほうが安全だ。

Q. VS Codeの統合ターミナルでAgent Teamsを使えますか？

in-processモードは使える。split-paneモード（各TeammateがそれぞれのペインVになる）はVS Codeの統合ターミナルでは動かない。開発中にAgent Teamsを多用するならiTerm2かtmux環境を整えておくといい。

Q. Teammateの数はいくつまで動かせますか？

公式の上限はないが、推奨は3-5人だ。それ以上になるとコーディネーションのオーバーヘッドが増えて、Leadのコンテキストも膨らむ。「10人チームで爆速開発」みたいな発想は現時点では割に合わない。

Q. Agent Teamsでclaudeのモデルは途中で変えられますか？

スポーン後に個別TeammateのモデルをLeadから変更することは現状できない。Subagent Definitionの model フロントマターか、スポーン時のプロンプトで指定する（「Sonnet で起動してください」等）のが確実だ。/config でデフォルトTeammateモデルを設定しておく方法もある。

Q. Teammateが止まってしまったら（エラーで停止した場合）どうすればいいですか？

Shift+Down でTeammateのセッションに移動して状況確認する。エラーが出ていれば直接指示を送って復帰できる。復帰不可能なら、Leadに「Teammate Aは停止しました。代わりの新しいTeammateをスポーンして同じタスクを引き継いでください」と伝えると新しいTeammateに作業を引き継げる。

Q. ネストチームは使えますか？

使えない。Teammateが自分のチームを作ることはできない。チームを管理できるのはLeadだけで、「Lead → Teammates」のフラットな1階層のみ。

Q. Agent Teamsのログはどこで確認できますか？

Leaderのセッショントランスクリプトは ~/.claude/projects/ 以下に保存される。タスクリストの状態は ~/.claude/tasks/{team-name}/ に、チーム設定は ~/.claude/teams/{team-name}/config.json にある。デバッグ時はこれらを直接確認するといい（config.jsonは編集しないこと）。

まとめ

Agent TeamsはSubagentsとは別物だ。「Teammateが互いに通信して議論できる」という点が唯一かつ本質的な差で、これが必要ないならSubagentsで十分だ。

実験的機能なので、既知の制限（セッション再開時のTeammate消滅、タスクステータスのラグ）は把握した上で使う。本番のクリティカルなタスクには向かない。

コストは3〜5倍に膨らむことを前提に使う。Teammateのモデルを明示的にSonnetにする、Subagent Definitionで役割を固定化する、無駄なTeammateを起動しない——この3つが節約の基本だ。

最初に試すなら「PRを3視点でレビューさせる」が一番わかりやすくて失敗しにくい。ファイルの競合がなく、タスクの粒度も自然に決まる。慣れてきたらHooksで品質ゲートを追加すると、手放しで動かしても品質が下がらない仕組みになる。

記事が見つかりません:

記事が見つかりません:

記事が見つかりません:

記事が見つかりません:

記事が見つかりません:

記事が見つかりません:

// 関連記事

Claude Codeを初めて動かした日、僕は5分で固まった — 始め方と「あの日知りたかったこと」全部書く

Claude Codeを初めて動かした日、僕は5分で固まった — 始め方と「あの日知りたかったこと」全部書く
Claude Code × VSCode 完全ガイド 2026 — CLI経験者が生産性を3倍にする実務ワークフロー

Claude Code × VSCode 完全ガイド 2026 — CLI経験者が生産性を3倍にする実務ワークフロー
フリーランスエンジニアの Claude Code Subagents 活用術 2026 — 1人運営で並列処理を最大化する設計パターン

フリーランスエンジニアの Claude Code Subagents 活用術 2026 — 1人運営で並列処理を最大化する設計パターン
Claude Code Skills 完全ガイド 2026年5月版 — 公式仕様・自作の作り方・おすすめ10選を実装視点で

Claude Code Skills 完全ガイド 2026年5月版 — 公式仕様・自作の作り方・おすすめ10選を実装視点で
← 記事一覧に戻る