エージェントチームのベストプラクティス

問題: Claude Code エージェントチームが起動し、すぐにトークンを消費し始めるものの、使えるアウトプットが出てこない。チームメンバーがお互いのファイルを上書きする。リードがコーディネートではなく自ら袖をまくる。タスクが「進行中」のまま永遠に止まっている。これらはすべて修正できます。以下のパターンは、この機能がリリースされてから何ヶ月にもわたるコミュニティレポートと実際のイテレーションから生まれました。

クイックウィン: デリゲートモードをオンにして（Shift+Tab）、スポーンプロンプトで各チームメンバーに明示的なファイル境界を与えます。この 2 つの調整だけで、最も一般的なチームの失敗の大半をなくせます。

注意: このガイドはエージェントチームの概要と対になっています。まだチームを設定していない場合はそちらを先にご覧ください。コントロールと設定については、アドバンスドコントロールをご覧ください。

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

タスク固有の詳細をスポーンプロンプトに含めます。プロジェクトコンテキスト（CLAUDE.md、MCP サーバー、スキル）は自動的に届きますが、リードの会話履歴はチームメンバーには引き継がれません。具体的なファイル、受け入れ基準、制約を指し示します。明確なスポーンプロンプトは往復のやり取りを大幅に削減します。

「auth モジュールをレビューして」のような曖昧なプロンプトは、チームメンバーがコードベースを探索し、何が重要かを把握し、優先度を推測することを強います。この探索はトークンと時間を消費します。具体的なプロンプトは曖昧さを排除します。

形はシンプルです: 何をするか、どこでするか、何に集中するか、アウトプットはどうあるべきか。最初からスコープを把握しているチームメンバーは、より速く完了し、より良い成果を出します。サブエージェントのパターンから来ている場合、ルールは同じですが、リスクは高くなります。各チームメンバーが今や完全なコンテキストウィンドウだからです。

タスクをチームメンバーに合わせたサイズにする

小さすぎるとコーディネーションのコストが利益を食いつぶします。大きすぎるとチームメンバーがチェックインなしに延々と作業し、無駄な努力のリスクが高まります。適切なサイズは、明確な成果物を持つ自己完結したユニットです: 関数、テストファイル、レビュードキュメント。

チームメンバーあたり 5〜6 タスクを目安にします。これにより全員が動き続け、誰かが行き詰まった場合にリードが作業を再割り当てできます。リードが作業を十分に細かく分割していない場合は、より小さなピースに分けるよう伝えます。巨大な 1 つのタスクを抱えるチームメンバーには自然なチェックポイントがありません。5〜6 個の集中したタスクを持つチームメンバーは、各タスク後に報告し、軌道修正の余地を与えます。

ファイルコンフリクトを避ける

2 人のチームメンバーが同じファイルを編集すると、サイレントな上書きが発生します。これは実装作業における最重要ルールです。各チームメンバーが独立したファイルセットを担当するようにタスクを分割します。スポーンプロンプトでディレクトリ境界を明示します。

リポジトリが自然に独立したディレクトリに分割できない場合は、タスクの分解の中で分割を作ります。「API レイヤーのリファクタリング」を 3 人のチームメンバーで分担する代わりに、「src/api/users/ のユーザーエンドポイントをリファクタリング」を 1 人に割り当て、「src/api/billing/ の請求エンドポイントをリファクタリング」を別の 1 人に割り当てます。明示的なオーナーシップにより、チームメンバーセッション全体を台無しにするサイレントな上書きを防ぎます。

共有ファイルを避けられないプロジェクトでは、CLAUDE.md でそれらを「編集前に調整が必要」とマークし、リードがタスクリストを通じてアクセスを順番付けます。

デリゲートモードを使う

チームが起動したらすぐにデリゲートモードをオンにします（Shift+Tab）。これなしでは、リードがチームメンバー向けのタスクを横取りし、誰が何を担当するかが曖昧になることがあります。デリゲートモードはリードをコーディネーション専用ツールに制限し、実装ではなくオーケストレーションに集中させます。全体的なウォークスルーと設定オプションについては、デリゲートモードガイドをご覧ください。

調査タスクから始める

エージェントチームが初めてですか? 境界が明確でコード記述のないタスクから始めます: PR レビュー、ライブラリ調査、バグ調査、特定のチェックリストに対するモジュール監査。これらは並行実装のコーディネーション上の頭痛なしに並行探索の効果を示します。

調査タスクは寛容です。チームメンバーが非生産的な方向に進んでも、失うのはトークンであってコードではありません。実装のミスはより元に戻しにくく、特に複数のチームメンバーがお互いの上に変更を重ねてしまうと困難です。

チームのダイナミクスが自然に感じられるようになったら、実装タスクへ進みます。同じパターンが適用されますが、リスクは高くなり、ファイルオーナーシップの境界がはるかに重要になります。

積極的に監視する

Ctrl+T を使って進捗を確認し、うまく行っていないアプローチをリダイレクトします。チームを長時間放置すると無駄な作業リスクが積み重なります。特に 1 人のチームメンバーが行き詰まった場合。

エージェントチームを監督付きワークフローとして扱います。あなたがプロジェクトマネージャーです。リードはコーディネートしますが、戦略的な判断はあなたが行います: いつリダイレクトするか、いつ代替メンバーをスポーンするか、いつ行き詰まったチームメンバーをシャットダウンするか。分散した契約社員チームを管理しているようなイメージです。定期的なチェックインで問題が大きくなる前にキャッチします。

チームサイズが重要

実際には、3〜5 人のチームメンバーが本当の適正規模です。チームメンバーが増えるほどコーディネーションコストが増し、トークンの消費が増え、行き違いの可能性が増します。リードのコンテキストは 3 人ではなく 8 人のチームメンバーを追うことでより速く満杯になります。コミュニケーションコストはチームサイズに比例して増大します。すべてのブロードキャストがすべてのチームメンバーのウィンドウに届くからです。

タスクが実際に 5 人以上の並行ワーカーを必要とする場合は、フェーズに分割します。フェーズ 1 で 3 人チームを動かし、クリーンアップして、フェーズ 2 でまた 3 人チームを動かします。小規模なチームによる順次フェーズの方が、一度にすべてを抱える大規模なチームより清潔な結果を生みます。

プランモードの動作

エージェントチームのプランモードには、ドキュメントから分からない 2 つの重要な動作があります。

プランモードはターンごとに再評価されます。一度だけではありません。 チームメンバーがプランモードで動作する場合、その生存期間中そこに留まります。すべてのアクションが読み取り専用の制約でフィルタリングされます。これによりプランモードはデザイン専用の役割や初期タスク整理に適していますが、実行には向きません。

チームメンバーのモードはスポーン時に固定されます。 一度起動すると、チームメンバーをプランからデフォルトに切り替えることはできません。計画から実行への移行が必要な場合は、デフォルトモードで新しいチームメンバーをスポーンしてプランを引き渡します。既存のチームメンバーをプランモードから「切り替える」ことはしないでください。

これはチーム設計に影響します。プランモードのチームメンバーは、読み取り専用の視点がすべてであるアーキテクチャとレビューの役割に使います。コードを書いたりファイルを変更したりする役割にはデフォルトモードのチームメンバーを使います。計画してから実装するフローには、プラン承認機能を使います。これにより、デフォルトモードのチームメンバーが承認後に計画してから構築できます。

明確なルールが明確なレポートを生む

CLAUDE.md にしっかりとしたルールがあれば、チームメンバーはリードの介入なしに自分がやったことを正確に自己報告します。よく書かれた CLAUDE.md に対してクリーンアップタスクを完了したチームメンバーは、次のようなレポートを返します: 「3 ファイルにわたって 27 件の console.log を削除しました。component-page.js の 12 件の console.error と 2 件の console.warn はすべて保持しました。割り当てられたファイルに console.log が残っていないことを確認しました。」

リードの介入は不要です。明確なルールを入れれば、明確なレポートが出てきます。

このパターンは、CLAUDE.md に具体的な検証基準がリストアップされている場合に自然と発生します。「ロギングをクリーンアップ」の代わりに、チームメンバーはすでに「検証済み」が残存するインスタンスに対して grep を実行し、エラーレベルのロギングが生き残っていることを確認することを意味すると知っています。チーム向けの CLAUDE.md の整え方については、CLAUDE.md マスタリーとアドバンスドコントロールの CLAUDE.md 最適化セクションをご覧ください。

トラブルシューティング

よくある問題とその解決策です。コミュニティレポートとリリースノートからまとめました。

問題	解決策
チームメンバーが表示されない	Shift+Down でアクティブなチームメンバーを循環します。タスクがチームに必要なほど複雑かどうか確認します。スプリットペインモードの場合、tmux または iTerm2 のセットアップを確認します。
許可プロンプトが多すぎる	チームメンバーをスポーンする前に、権限設定でよくある操作を事前承認します。各チームメンバーはリードの権限を継承するため、一度設定すればチーム全体に適用されます。
チームメンバーがエラーで停止する	直接指示します（Shift+Up/Down で選択してから入力）。または代替メンバーをスポーンして作業を継続します。
作業が完了する前にリードがシャットダウンする	リードに継続を指示します。「チームメンバーがタスクを完了するまで待ってください」と伝えます。
孤立した tmux セッション	`tmux ls` でセッションをリストし、`tmux kill-session -t <session-name>` でクリーンアップします。
チームメンバーがお互いのファイルを踏み合う	スポーンプロンプトで明示的なファイル境界を定義します。ディレクトリレベルのオーナーシップを使います。上の「ファイルコンフリクトを避ける」セクションをご覧ください。
タスクステータスが止まって見える	チームメンバーがタスク完了のマークを忘れることがあります。Ctrl+T で手動確認し、チームメンバーにステータス更新を促します。
Bedrock/Vertex/Foundry 上のチームメンバーが失敗する	v2.1.45 以降にアップデートしてください。以前のバージョンではモデル識別子と tmux チームメンバー向けの API プロバイダー環境変数の欠落に問題がありました。
エージェントチーム設定の切り替え時にクラッシュ	v2.1.34 以降にアップデートしてください。レンダリング間でエージェントチーム設定が変わった際のクラッシュが修正されました。
tmux チームメンバーがメッセージを送受信できない	v2.1.33 以降にアップデートしてください。tmux でのエージェントチームメンバーセッションがメッセージを正しく送受信する問題が修正されました。

あなたの問題がリストにない場合は、実行中の Claude Code のバージョンを確認してください。初期の多くの問題は v2.1.33 から v2.1.45 のリリースにわたって解決されています。

現在の制限事項

エージェントチームは実験的な機能です。チームベースのワークフローにコミットする前に知っておく価値のある制約があります。

セッションの再開なし: インプロセスのチームメンバーは /resume または /rewind 使用時には復元されません。再開後、リードはもう存在しないチームメンバーにメッセージを送ろうとすることがあります。代替メンバーをスポーンするよう伝えます。
タスクステータスの遅延: チームメンバーがタスクを完了としてマークし忘れ、依存する作業をブロックすることがあります。止まっているように見えたら手動で確認します。
シャットダウンが遅い: チームメンバーは現在のリクエストやツール呼び出しを完了してからシャットダウンします。チームメンバーが実装の途中であれば時間がかかることがあります。
セッションごとに 1 チーム: リードは一度に 1 つのチームを管理します。別のチームを始める前に現在のチームをクリーンアップします。
ネストされたチームなし: チームメンバーは独自のチームをスポーンできません。チームの階層を管理するのはリードだけです。
固定されたリード: チームを作成したセッションがその生存期間中リードのままです。チームメンバーを昇格させたりリーダーシップを移譲したりすることはできません。
スポーン時に権限が設定される: すべてのチームメンバーはリードの権限設定でスタートします。スポーン後に個別のモードを変更できますが、スポーン時には変更できません。
スプリットペインには tmux または iTerm2 が必要: スプリットペインモードは VS Code の統合ターミナル、Windows Terminal、Ghostty ではサポートされていません。

これらの粗い部分についての正直な説明は重要です。エージェントチームは強力な機能ですが、目に見えるつなぎ目があります。今回避策を習得した開発者が、Anthropic がそれらを磨き上げたときに準備できた状態になります。