agent-teams

エージェントチーム

実験的機能：エージェントチームを利用するには CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が必要です。Claude Code のバージョンによって動作が変更される場合があります。

破壊的変更（Claude Code 2.1.178）：明示的な TeamCreate ／ TeamDelete ツールは削除されました。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を設定すると、すべてのセッションに暗黙のチームが 1 つ用意されるため、作成や終了の操作は不要です。以前これらのツールで使われていた team_name パラメーター（例：Agent）は、引き続き受け付けられますが無視されるため、古い呼び出しでエラーは発生しません。新しいコードでは省略してください。調整方法は変わりません。Agent ツールでチームメイトを起動し、SendMessage で連絡を取り、TaskCreate／TaskList／TaskUpdate で作業を追跡します。

実際に動作するセットアップ例、通信の例、シャットダウン手順、ワークツリーのパス解決の復旧手順、一般的なディスパッチパターンについては、REFERENCE.md を参照してください。

このスキルを使う場面

エージェントチームを使う場合	代わりにサブエージェントを使う場合
複数のエージェントが並行して作業する必要がある	タスクが順次進行し、相互に依存している
エージェント間で継続的な連絡が必要である	1 つの集中したタスクから 1 つの結果が得られる
バックグラウンドタスクの進捗報告が必要である	エージェントの出力を次のステップに直接渡す
複雑なワークフローでタスクの調整が役立つ	シンプルで範囲が限定され、独立して実行できる
同じコードベースに対する独立した変更（ワークツリーを使用）	コンテキストを共有しても問題なく効率的である

サブエージェントに関する注意：チームはメインスレッドから起動する

Agent や関連する並列起動ツールは、親の会話で利用できる場合でも、サブエージェントのツール一覧に含まれないことがあります。自身のチームを調整するよう設計されたサブエージェントは、失敗が完了後の要約まで明らかにならないまま、逐次的な単一スレッド実行にひそかに切り替わることがあります。内容は同じでも、実時間で約 5 倍かかります。

状況	推奨パターン
メインの会話から作業を振り分ける	Agent を直接並列に呼び出す — すべてのツールを利用できます
サブエージェントが自身のチームを調整する	設計上避けてください。作業を分割し、メインスレッドから振り分けます
サブエージェントがチームを調整する必要がある	事前にツールを利用できるか確認し、逐次実行へのフォールバックを明示的な結果として報告します

調整を担当するサブエージェントには、次の検出ルールを伝えてください。Agent ツールを呼び出せることを確認します。呼び出せない場合は、ひそかにフォールバックしてはいけません。要約の 1 行目に「このサンドボックスでは並列の作業振り分けが利用できないため、逐次実行しました。」と報告してから、同じ入力条件で逐次実行を続けます。可能であれば、トップレベルの調整はメインの会話で計画してください。

ネイティブのチームツール

暗黙のチーム（2.1.178）には作成／削除の手順は不要です。これらのツールは、セッションにすでに用意されている唯一のチームに対して動作します。

ツール	用途
Agent	チームメイトを起動します（name を指定してください。team_name は受け付けられますが無視されます）
SendMessage	ダイレクトメッセージ、ブロードキャスト、シャットダウン要求、計画の承認を送信します
TaskCreate / TaskList / TaskUpdate	共有タスクの作成、確認、割り当て／進行を行います
TaskOutput	バックグラウンドエージェントの出力を取得します
TaskStop	実行中のバックグラウンドエージェントを停止します

TaskCreate → Agent ツールでチームメイトを起動（name を指定）→ TaskUpdate で割り当て → 結果を自動受信、というセットアップ手順の全コードは、REFERENCE.md → チームのセットアップワークフロー にあります。チームメイトからのメッセージはターン間にリーダーの受信トレイに届くため、ポーリングは不要です。

タスク管理

状態	意味
pending	まだ開始されていません
in_progress	割り当て済みで、実行中です（チームメイトごとに同時に 1 件）
completed	正常に完了しました
blocked	別のタスクを待っています（blocked_by フィールド）

チームメイトは TaskList と TaskUpdate を使ってID 順（最小のものから）にタスクを引き受け、ブロックしているタスクが完了するまで、ブロックされたタスクをスキップします。

コミュニケーション（SendMessage）

種類	使用する場面
message	特定のチームメイトへのダイレクトメッセージ（recipient には agentId ではなく name を指定）
broadcast	チーム全体への重要な告知（チームメイトが N 人の場合、往復が N 回発生するため、控えめに使用）
shutdown_request / shutdown_response	チームメイトが正常に終了するためのハンドシェイク
plan_approval_response	チームメイトの計画を承認または却下

DM、broadcast、discovery（Read ~/.claude/teams/<name>/config.json → members）の例は REFERENCE.md → Communicationにあります。

チームメイト向けの重要なルール

• タスクを in_progress にするのは、常にちょうど 1 件だけにしてください。
• タスクの完了報告には、SendMessage ではなく TaskUpdate を使用してください。
• 各ターン後にアイドル状態になるのは通常です。アイドル状態でも利用不可とは限りません。メッセージを受信するとチームメイトが再開します。
• すべてのコミュニケーションには SendMessage が必要です。プレーンテキストの出力はリードには表示されません。
• recipient には agentId ではなく name フィールドを使用してください。

リード向け事前確認チェックリスト

PRP の作成とエージェントの起動前に 30 秒の確認を行うことで、エージェントの作業後に複数ファイルの名前を変更する事態を防げます。

確認項目	コマンド	理由
次の ADR/PRD/PRP の連番	ls docs/blueprint/adrs/ | sort -V | tail -1	並行したドキュメント作成時の番号の衝突を防ぎます
ファイル名の競合	git ls-files | grep <filename>	対象範囲を示す表だけでは、ツリー構造についての古い認識を防げません
ハードウェアのピン数の上限（組み込み）	pin_config.h または同等のファイルを読む	フェーズ 1 の各エージェントでピン割り当てが重複するのを防ぎます

対象範囲外の調査プロトコル

エージェントに書き込み専用の範囲が割り当てられている場合は、すべてのエージェント向けプロンプトに対象範囲外の調査プロトコルを含めてください。これにより、「対象範囲外を調査 → 予算を使い切る → 要約が途中で切れる」という失敗パターンを防げます。 REFERENCE.md → Out-of-scope discovery protocolから、文面を変更せずにブロックをコピーしてください。対象範囲外の依存関係を見つけた場合、エージェントは直ちに停止し、それをOut-of-scope dependenciesという要約セクションに列挙して、リードがトリアージできるように終了します。

Worktree の分離に関する危険性

Worktree で分離されたエージェントでは、Edit／Write が相対パスを worktree ではなく親リポジトリに対して誤って解決することがあります（上流のバグ #1091）。これにより、すぐには気付かないまま、誤ったブランチにコミットが記録されます。Worktree で分離されたエージェント向けのすべてのプロンプトに絶対パスの前置き文を追加し、リードの作業後チェック（親リポジトリから git diff origin/main..HEAD と git status --porcelain を実行）を行い、cherry-pick と rebase による復旧を使用してください。詳細はすべて REFERENCE.md → Worktree path resolutionにあります。 .claude/rules/agent-coworker-detection.mdも参照してください。

Worktree で分離されたエージェントの作業再開

完了済みの worktree で分離されたエージェント（isolation: "worktree" を指定した Agent）を SendMessage で再開すると、worktree の分離が失われます。再開後の実行は worktree ではなく、オーケストレーターのメインチェックアウトで行われます。複数ファイルを並行して変更する作業では、再開するのではなく、新しい isolation: "worktree" エージェントを再度ディスパッチしてください。SendMessage による再開は、読み取り専用または単一チェックアウト内の継続作業に限定してください。詳細は parallel-agent-dispatch →「Resuming agents: SendMessage loses worktree isolation」（issue #1546）を参照してください。

サンドボックスに関する考慮事項

Web セッション（CLAUDE_CODE_REMOTE=true）では：

• サブエージェント（チームメイト）が git push で TLS エラーに遭遇することがあります。push と PR に関する操作はすべてリードに任せてください。
• 各チームメイトは、それぞれ独自のプロセスコンテキストで実行されます。
• 独立したファイルシステム変更には、worktree による分離を推奨します。

エージェント向け最適化

コンテキスト	アプローチ
素早い並列レビュー	2～4 人のチームメイトを起動し、タスクを割り当てます
大規模なコードベースの分割	ディレクトリのサブセットを個別のタスクとして割り当てます
長時間にわたる作業	チームメイトをバックグラウンドで実行し、TaskList で状態を確認します
API コストの最小化	broadcast より message を優先します
迅速な終了	各チームメイトに shutdown_request を送信します（チームの解体は不要です）

クイックリファレンス

ワークフローのチェックリスト

• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が設定されている（暗黙のチームは存在するため、作成手順は不要です）
• 各作業単位に対して TaskCreate を実行します
• name を指定して Agent ツールからチームメイトを起動します（team_name は不要です）
• TaskUpdate でタスクを割り当てます（またはチームメイトに自分で割り当ててもらいます）
• メッセージを自動的に受信し、SendMessage で返信します
• 完了したら、各チームメイトに SendMessage shutdown_request を送信します（TeamDelete は不要です）

主なパス

パス	内容
~/.claude/teams/	暗黙のチームの状態（メンバー：name、agentId、agentType）
~/.claude/tasks/	共有タスクリストの状態

チームメイトには、起動時に指定した name で連絡してください。これはディスク上の配置に依存しない、確実な識別子です。

よくある間違い

間違い	正しい方法
受信者に agentId を使う	起動時に指定した name を使います
削除された TeamCreate／TeamDelete を呼び出す	チームは暗黙的に存在します（2.1.178）。Agent で起動し、shutdown_request で終了します
team_name を渡せばルーティングされると考える	受け付けられますが無視されます。暗黙のチームは 1 つです
更新のたびに broadcast を送信する	1 人の受信者への連絡には message を使います
メッセージをポーリングする	メッセージは自動的に届くため、そのまま待ちます
JSON 形式のステータスメッセージを送信する	ステータスには TaskUpdate を使い、メッセージにはプレーンテキストを使います
サブエージェントにリモートへのプッシュをさせる	プッシュはリードオーケストレーターに委任します

関連するスキルとルール

• parallel-agent-dispatch — worktree の事前確認、スコープの予算、および各チームメイトが終了時に出力する必要がある Return Contract。チームへのディスパッチは通常の並列ファンアウトを包含するため、両方に従ってください。
• .claude/rules/agent-development.md — エージェントファイルの構成、モデルの選択、worktree の分離
• .claude/rules/agentic-permissions.md — ツール権限のきめ細かなパターン
• .claude/rules/sandbox-guidance.md — Web サンドボックスの制約とプッシュの委任