agent-teams-guide

エージェントチームガイド

クイックリファレンス

コマンド	説明
Create an agent team...	並行作業のためにチームメイトを起動します
Clean up the team	すべてのチームメイトを正常に終了します
Delegate mode	チームの開始後に Shift+Tab を押します
Shift+Up/Down	インプロセスモードでチームメイトを選択します

エージェントチームを有効にする

エージェントチームは実験的な機能です。環境変数で有効にします。

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

または、Claude Code を実行する前に、シェルで環境変数を設定します。

チームを作成する

複数の視点が役立つ並行作業について説明し、チームを開始します。

Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

Claude は次を作成します。

• チームリーダー（メインセッション）
• チームメイト（個別の Claude Code インスタンス）
• 連携用の共有タスクリスト

表示モード

インプロセスモード（デフォルト）

• すべてのチームメイトがメインターミナルで実行されます
• Shift+Up/Down でチームメイトを選択します
• 入力して直接メッセージを送信します
• どのターミナルでも動作します

分割ペインモード

• チームメイトごとに専用のペインが割り当てられます
• tmux または iTerm2 が必要です
• settings.json で teammateMode を設定します。

{ "teammateMode": "in-process" }

• セッションごとに上書きします：claude --teammate-mode in-process

チームメイトを操作する

タスクの割り当て

• リーダーが明示的に割り当てる：どのタスクをどのチームメイトに割り当てるか、リーダーに伝えます
• 自己割り当て：チームメイトが、未割り当てでブロックされていないタスクを自動的に選びます

直接コミュニケーション

• インプロセス：チームメイトを選択し、メッセージを入力して Enter を押すと内容を表示できます。Escape で中断します
• 分割ペイン：ペインをクリックして直接やり取りします

委任モード

リーダーが自分でタスクを実装しないようにして、連携に集中できるようにします。

1. 先にチームを開始します
2. Shift+Tab を押して委任モードに切り替えます

計画の承認を必須にする

複雑なタスクの場合：

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

ベストプラクティス

チームメイトに十分なコンテキストを与える

チームメイトはリーダーの会話履歴を引き継ぎません。起動プロンプトに詳細を含めてください。

Spawn a security reviewer teammate with the prompt: "Review the authentication
module at src/auth/ for security vulnerabilities. Focus on token handling,
session management, and input validation..."

タスクの規模を適切にする

• 小さすぎる：連携のオーバーヘッドがメリットを上回ります
• 大きすぎる：チームメイトが確認を受けずに長時間作業します
• 適切な規模：自己完結した単位（関数、テストファイル、レビュー）

ファイルの競合を避ける

各チームメイトが別々のファイルを担当するように作業を分けます。2 人のチームメイトが同じファイルを編集すると、変更が上書きされます。

進捗を確認して方向を調整する

進捗を確認し、アプローチを修正し、調査結果をまとめます。チームを長時間放置しないでください。

クリーンアップ

完了したら：

Clean up the team

リーダーが共有チームリソースを削除します。クリーンアップはチームメイトではなく、必ずリーダーを使ってください。

トラブルシューティング

問題	解決策
チームメイトが表示されない	Shift+Down を押して切り替えます。タスクにチームが必要か確認してください
権限の確認が多すぎる	権限設定で操作を事前承認します
エラーでチームメイトが停止する	出力を確認し、追加の指示を与えるか、代わりのチームメイトを起動します
リーダーが早く終了する	続行してチームメイトを待つよう、リーダーに伝えます
孤立した tmux セッション	tmux ls を実行し、次に tmux kill-session -t <name> を実行します

エージェントチームを使う場面

特に適している作業：

• 調査とレビュー（複数の視点で同時に実施）
• 新しいモジュールや機能（独立した部分）
• 相反する仮説によるデバッグ（並行調査）
• レイヤーをまたぐ連携（フロントエンド、バックエンド、テスト）

あまり適していない作業：

• 順番に進めるタスク
• 同じファイルの編集
• 依存関係の多い作業

よくあるパターン

並行コードレビュー

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

相反する仮説を立てて調査する

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk
to each other to try to disprove each other's theories.

制限事項

• インプロセスのチームメイトではセッションを再開できません
• タスクのステータスが実際の完了状況より遅れることがあります
• 終了に時間がかかる場合があります（チームメイトは現在のリクエストを先に完了します）
• 1 セッションにつき 1 チームです
• チームの入れ子はできません（チームメイトは自分のチームを起動できません）
• チームの存続中、リーダーは固定されます
• 分割ペインには tmux または iTerm2 が必要です（VS Code ターミナル、Windows Terminal、Ghostty では使用できません）