team-composition-patterns

チーム構成パターン

Claude Code の Agent Teams 機能において、マルチエージェントチームを構成し、チームサイズを選択し、エージェントタイプを選び、表示モードを設定するためのベストプラクティスです。

このスキルを使用する場面

• タスクに対して何人のチームメイトを起動するかを決める場合
• プリセットのチーム構成から選択する場合
• 各役割に適したエージェントタイプ(subagent_type)を選ぶ場合
• チームメイトの表示モード(tmux、iTerm2、インプロセス)を設定する場合
• 非標準のワークフロー向けにカスタムのチーム構成を構築する場合

チームサイズの目安

複雑さ	チームサイズ	使用する場面
シンプル	1-2	単一観点のレビュー、独立したバグ、小規模な機能
中程度	2-3	複数ファイルの変更、2〜3 の関心事、中規模な機能
複雑	3-4	横断的な関心事、大規模な機能、深いデバッグ
非常に複雑	4-5	フルスタック機能、包括的なレビュー、システム全体の問題

経験則: 必要なすべての観点をカバーする最小のチームから始めてください。チームメイトを追加すると、調整のオーバーヘッドが増加します。

プリセットのチーム構成

レビューチーム

• サイズ: レビュアー 3 名
• エージェント: 3x team-reviewer
• デフォルトの観点: セキュリティ、パフォーマンス、アーキテクチャ
• 使用する場面: コード変更に多次元の品質評価が必要な場合

デバッグチーム

• サイズ: 調査担当 3 名
• エージェント: 3x team-debugger
• デフォルトの仮説: 3 つの競合する仮説
• 使用する場面: バグに複数のもっともらしい根本原因がある場合

機能チーム

• サイズ: 3 名(リード 1 名 + 実装担当 2 名)
• エージェント: 1x team-lead + 2x team-implementer
• 使用する場面: 機能を並列のワークストリームに分解できる場合

フルスタックチーム

• サイズ: 4 名(リード 1 名 + 実装担当 3 名)
• エージェント: 1x team-lead + 1x フロントエンド team-implementer + 1x バックエンド team-implementer + 1x テスト team-implementer
• 使用する場面: 機能がフロントエンド、バックエンド、テストの各レイヤーにまたがる場合

リサーチチーム

• サイズ: リサーチャー 3 名
• エージェント: 3x general-purpose
• デフォルトの領域: それぞれに異なるリサーチ課題、モジュール、トピックを割り当て
• 機能: コードベース検索(Grep、Glob、Read)、Web 検索(WebSearch、WebFetch)
• 使用する場面: コードベースを理解したり、ライブラリを調査したり、アプローチを比較したり、コードと Web の情報源から並列で情報を収集したりする必要がある場合

セキュリティチーム

• サイズ: レビュアー 4 名
• エージェント: 4x team-reviewer
• デフォルトの観点: OWASP/脆弱性、認証/アクセス制御、依存関係/サプライチェーン、シークレット/設定
• 使用する場面: 複数の攻撃対象領域をカバーする包括的なセキュリティ監査

マイグレーションチーム

• サイズ: 4 名(リード 1 名 + 実装担当 2 名 + レビュアー 1 名)
• エージェント: 1x team-lead + 2x team-implementer + 1x team-reviewer
• 使用する場面: 並列作業と正確性の検証を必要とする大規模なコードベースのマイグレーション(フレームワークのアップグレード、言語の移植、API バージョンの更新)

エージェントタイプの選択

Agent ツールでチームメイトを起動する際は、チームメイトが必要とするツールに基づいて subagent_type を選択します。

エージェントタイプ	利用可能なツール	用途
general-purpose	すべてのツール（Read、Write、Edit、Bash など）	実装、デバッグ、ファイル変更を伴うあらゆるタスク
Explore	読み取り専用ツール（Read、Grep、Glob）	調査、コード探索、分析
Plan	読み取り専用ツール	アーキテクチャ設計、タスクの分解
agent-teams:team-reviewer	Read/search/Bash に加えて TaskList/TaskGet/TaskUpdate/SendMessage	構造化された指摘を伴うコードレビュー
agent-teams:team-debugger	Read/search/Bash に加えて TaskList/TaskGet/TaskUpdate/SendMessage	仮説駆動型の調査
agent-teams:team-implementer	Read/Write/Edit/search/Bash に加えて TaskList/TaskGet/TaskUpdate/SendMessage	ファイルの所有範囲内での機能構築
agent-teams:team-lead	Read/search/Bash に加えて Agent Teams の調整ツール	チームのオーケストレーションと調整

重要な違い: 読み取り専用エージェント（Explore、Plan）はファイルを変更できません。読み取り専用エージェントに実装タスクを割り当てないでください。

表示モードの設定

~/.claude/settings.json で設定します。

{
  "teammateMode": "tmux"
}

モード	動作	最適な用途
"tmux"	各チームメイトを tmux ペインで	開発ワークフロー、複数エージェントの監視
"iterm2"	各チームメイトを iTerm2 タブで	iTerm2 を好む macOS ユーザー
"in-process"	すべてのチームメイトを同一プロセスで	シンプルなタスク、CI/CD 環境

カスタムチームのガイドライン

カスタムチームを構築する際は、次の点に留意してください。

1. すべてのチームにコーディネーターが必要 — team-lead を指名するか、ユーザーが直接コーディネートします
2. 役割をエージェントタイプに合わせる — 利用可能な場合は専門エージェント（reviewer、debugger、implementer）を使用します
3. 役割の重複を避ける — 2 つのエージェントが同じことをするとリソースの無駄になります
4. 境界を事前に定義する — 各チームメイトには、ファイルまたは責任範囲の明確な所有権が必要です
5. 小さく保つ — 2～4 人のチームメイトが最適です。5 人以上は大幅な調整のオーバーヘッドが必要になります

トラブルシューティング

チームメイトが Explore として起動されたが、ファイルを書き込む必要がある。 Explore と Plan は読み取り専用のエージェントです。subagent_type を general-purpose または適切な専門エージェントタイプに変更してください。読み取り専用エージェントに実装タスクを割り当てないでください。

チームが大きくなりすぎて、調整に時間がかかり全体が遅くなっている。 チームメイトが増えるたびにコミュニケーションのオーバーヘッドが増加します。役割を統合しましょう。1 つのエージェントで 2 つの領域をカバーできますか？ 6 つの独立したタスクを行う 4 人のチームよりも、2 つのタスクずつを担当する 3 つのエージェントのほうが通常はうまく機能します。

tmux モードでペインが表示されない。 チームメイトを起動する前に、tmux がインストールされ、セッションがすでに実行されていることを確認してください。in-process モードは tmux なしで動作し、CI やスクリプト環境に適しています。

2 人のレビュアーが同じ問題を指摘している。 レビューの領域が重複しています。各レビュアーのフォーカス領域を再定義してください。1 人は正確性/ロジック、1 人はセキュリティ、1 人はパフォーマンス/スケーラビリティを担当します。カバレッジが重複するとトークンを浪費し、重複した指摘が発生します。

team-lead がチームメイトを起動しているが、タスクを受け取っていない。 リードが Agent ツールを使用してチームメイトを起動し、プロンプトで完全なコンテキストを渡していることを確認してください。チームメイトは以前の会話履歴なしで新規に開始されます。初回のプロンプトにすべての関連情報を含める必要があります。

関連スキル

• parallel-feature-development — チーム編成後にワークストリームを分解し、ファイルの所有権を割り当てます
• team-communication-protocols — 編成されたチームのメッセージング規範とシャットダウン手順を確立します