agent-teams

エージェントチーム

同じコードベースで同時に作業する複数の Claude Code セッションを調整します。

有効化

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude  # starts as team lead

最初のセッションがチームリーダーになります。同じリポジトリ内の後続セッションは、チームメイトとして参加します。

アーキテクチャ

Team Lead (coordinates, delegates, reviews)
  ├── Teammate 1 (owns task A, messages lead + peers)
  ├── Teammate 2 (owns task B, messages lead + peers)
  └── Teammate 3 (owns task C, messages lead + peers)
      │
      └── Shared: task list + mailbox + file locks

サブエージェントとの主な違い： チームメイトは完全な Claude Code セッションです。それぞれ独自のコンテキストウィンドウを持ち、すべてのツールを使えるほか、親に報告するだけでなく、互いに直接メッセージを送れます。

チームの規模

チームの規模	最適な用途
2	一方が構築し、もう一方がレビュー
3-5	レイヤー（API、UI、テスト）をまたぐ機能の並行作業
> 5	調整のオーバーヘッドが並列作業の利点を上回る

生産性を高められるチームメイトの人数は3～5人です。それ以上になると、チームが節約する時間より、リーダーが調整に費やす時間のほうが長くなります。

タスクの粒度： チームメイト1人あたり5～6件のタスクを目安にします。少なすぎると能力を活用できず、多すぎるとコンテキストの切り替えが頻繁になります。

表示モード

プロセス内での切り替え：

• Shift+Down — チームメイトを順番に切り替えます（末尾から先頭に戻ります）
• 各チームメイトの現在のタスクと出力を確認できます

ペイン分割（チームメイトが2人を超える場合に推奨）：

• tmux：チームメイトごとに tmux split-window -h
• iTerm2：Cmd+D で縦に分割
• 各ペインでそれぞれの claude セッションを実行します

タスク管理

タスクは次の状態を遷移します。

pending → in-progress → completed
              │
              └── blocked (waiting on dependency)

タスクの分解

次の条件を満たす単位に作業を分割します。

• 互いに重複しないファイルを変更する
• 個別に検証できる
• 完了条件が明確である

適切な分解：

Task 1: Add rate limiting middleware (src/middleware/rate-limit.ts)
Task 2: Add rate limit tests (tests/rate-limit.test.ts)
Task 3: Update API docs for rate limit headers (docs/api.md)
Task 4: Add Redis config for rate limit store (src/config/redis.ts)

不適切な分解：

Task 1: Implement rate limiting
Task 2: Fix rate limiting bugs
Task 3: Improve rate limiting

依存関係

タスクには依存関係を設定できます。

Task 3 (API docs) → depends on Task 1 (middleware)
Task 2 (tests) → depends on Task 1 (middleware)
Task 4 (Redis config) → no dependencies

チームメイトは、ブロックされていないタスクを自動的に引き受けます。

ファイルロックによる確保

チームメイトは競合を防ぐため、編集前にファイルを確保します。

1. チームメイトがファイルにロックがかかっているか確認します
2. ロックされていない場合、ファイルロック方式で確保します
3. ファイルを編集します
4. タスク完了時にロックを解除します

2人のチームメイトが同じファイルを必要とする場合、一方が待機するか、リーダーが割り当てを変更します。

計画の承認

チームメイトは実装前に計画を立てます。

1. チームメイトがタスクを受け取ります
2. 簡潔な計画（変更するファイル、アプローチ）を作成します
3. リーダーが計画をレビューします
4. リーダーが承認するか、方向を修正します
5. チームメイトが実装します

これにより、要件の誤解による無駄な作業を防げます。

委任モード

Shift+Tab で、リーダーの委任モードを切り替えます。

• リーダーは調整のみを行い、コードを直接編集しません
• 実装はすべてチームメイトに委任します
• リーダーはレビュー、計画の承認、タスクの進行管理を行います

フックイベント

フック	発生するタイミング
TeammateIdle	チームメイトがタスクを完了し、未処理の作業がないとき
TaskCreated	共有リストに新しいタスクが追加されたとき
TaskCompleted	チームメイトがタスクを完了としてマークしたとき

これらを使って、通知の送信、次のタスクの自動割り当て、またはすべてのタスク完了時の統合テスト実行を行えます。

チームと代替手段の使い分け

シナリオ	使用するもの
重複しないファイルでの並行作業	エージェントチーム
短時間のバックグラウンド調査	サブエージェント
分離された機能ブランチでの作業	Worktree（claude -w）
同じ問題に対する複数のアプローチの比較	Worktree（結果を比較）
複数レイヤー（API + UI + テスト）にまたがる変更	エージェントチーム
単発の委任	isolation: worktree を指定したサブエージェント
大規模な移行（20ファイル以上）	/batch コマンド

アンチパターン

• チームメイトが5人を超える — 調整のオーバーヘッドが大きくなります
• 可変状態や同じファイルを共有するタスク
• 計画の承認を省略する — 手戻りにつながります
• リーダーが調整ではなく実装を行う（委任モードを使用します）
• 依存関係を設定しない — 依存するタスクでチームメイト同士が競合します

セッションの例

Lead: "We need rate limiting. Breaking into 4 tasks."

  Task 1: middleware implementation → Teammate 1
  Task 2: Redis config → Teammate 2 (no deps)
  Task 3: tests → Teammate 1 (after Task 1)
  Task 4: API docs → Teammate 2 (after Task 1)

Teammate 1 plans → Lead approves → implements Task 1
Teammate 2 plans → Lead approves → implements Task 2
Task 1 completes → unblocks Tasks 3 and 4
Teammate 1 picks up Task 3, Teammate 2 picks up Task 4
All complete → Lead runs integration tests → commits

ドキュメント

https://code.claude.com/docs/agent-teams