agent-teams について
Claude Code で 2〜3 個のエージェントを並行稼働させるスキルです。各エージェントに別のターミナル、Git worktree、コンテキストを割り当て、リーダーがタスクファイルで調整して進捗を確認し、成果を統合します。ネイティブ Teams API を使う方法も扱います。
主な機能
- 01エージェントごとに Git worktree を分離
- 02タスクファイルで作業と契約を割り当て
- 03ブランチを監視して成果を統合
- 04ネイティブ Teams API による協調
- 05ファイル分離に応じて並列方式を選択
活用シーン
- 01共通契約に基づきフロントエンドとバックエンドを並行開発
- 02独立した機能を複数エージェントに割り当て
- 03一方がテストを書き、他方が機能を実装
- 04リファクタリングとコードレビューを並行実施
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/agent-teamsを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
config.jsonreference/best-practices-full.mdcontext-engineering.mdprompt-templates.mdworkflows-detailed.mdworktree-integration.md詳細
重要な原則: 各エージェントは共有メモリを一切持たない、まっさらな Claude セッションです。すべての調整はファイル（WORKTREE_TASK.md、共有コントラクト）と git（ブランチ、PR）を通じて行われます。エージェント間の実行時の通信はありません。
<quick_start> 環境変数を設定します（初回のみ）:
export AGENT_TEAMS_MAX=3 # M1/8GB safe default
2 エージェントのチームを起動します:
"Set up a team: Agent 1 builds the API endpoints, Agent 2 builds the React components.
They share this contract: POST /api/tasks returns { id, title, status }."
何が起こるか:
- チームリードが worktree-manager を介して 2 つの worktree を作成します
- それぞれに焦点を絞ったプロンプト + コントラクトを含む WORKTREE_TASK.md を書き込みます
- 各エージェントをそれぞれ独自の Ghostty ターミナルで起動します
- エージェントは独立して作業し、チームリードが監視してマージします </quick_start>
<success_criteria> チームセッションは、次の条件を満たすときに成功です:
- 各エージェントが自身の worktree で割り当てられたタスクを完了する
- エージェントのブランチ間にマージコンフリクトがない（またはコンフリクトが簡単に解決できる）
- 各エージェントのコンテキストが焦点を保っている（肥大化せず、無関係なコードを再読込しない）
- マージ後にすべてのエージェントの作業がプロジェクトのテストスイートを通過する
- 総実時間が逐次実行よりも短い </success_criteria>
前提条件
必須スキル: worktree-manager — agent-teams は worktree の作成、ポートの割り当て、ターミナルの起動のすべてを worktree-manager に委譲します。まずこれをインストールしてください。
推奨: プロジェクトに CLAUDE.md（開発コマンド、規約）を含む .claude/ ディレクトリがあること。プロジェクトにさらに .claude/agents/（カスタムサブエージェント）や .claude/settings.json（フック／パーミッション）がある場合、これらは各エージェントの worktree に自動的に伝播されます。
環境チェック:
# Agent teams config
echo "Max agents: ${AGENT_TEAMS_MAX:-3}"
# Worktree manager available?
ls ~/.claude/skills/worktree-manager/ 2>/dev/null && echo "worktree-manager: OK" || echo "worktree-manager: MISSING"
# Running agents (approximate)
pgrep -f "claude.*--model" | wc -l | xargs echo "Active Claude processes:"
# Memory pressure
vm_stat | grep "Pages free" | awk '{print "Free pages:", $3}'
<current_state>
アクティブなエージェント:
!pgrep -f "claude.*--model" 2>/dev/null | wc -l | tr -d ' ' 個の Claude プロセスが実行中
Worktree レジストリ:
!cat ~/.claude/worktree-registry.json 2>/dev/null | jq -r '.worktrees[] | select(.status == "active") | "\(.project)/\(.branch)"' | head -5
メモリ:
!memory_pressure 2>/dev/null | head -1 || echo "Unknown"
Git ステータス:
!git status --short --branch 2>/dev/null | head -3
</current_state>
ハードウェア制約（M1/8GB）
| リソース | 予算 | エージェントあたり | システム予約 |
|---|---|---|---|
| RAM | 8 GB | 約 1.5 GB | 2 GB |
| CPU コア | 8 | 共有 | — |
| 最大エージェント数 | 3 | — | — |
経験則: memory_pressure が「WARN」以上を報告したら、2 エージェントに減らしてください。
<when_to_use>
エージェントチームをいつ使うか
次の場合に使います:
- タスクが自然に 2〜3 の独立した作業ストリームに分解できる
- 各ストリームが異なるファイルに触れる（コンフリクトのリスクが低い）
- トークン効率よりも実時間の速さが重要
- コンポーネント間に明確なコントラクト（API の形、共有型）がある
次の場合は使わないでください:
- タスクが密結合している（すべての変更が同じファイルに触れる）
- バッテリー残量が 30% 未満（エージェントは電力を急速に消費します）
- メモリプレッシャーがすでに高い（
memory_pressureを確認してください） - コードベースにテストがない（盲目的なマージはリスクが高い）
判断のヒューリスティック:
Can I describe each agent's task in <50 words?
YES → Good candidate for agent teams
NO → Break it down more, or do it sequentially
軽量な代替手段: エージェントがファイル分離を必要としないタスク（異なるファイル、読み取り専用、レビュー）には、代わりに subagent-teams を使ってください。これは Claude ネイティブの Task ツールを使い、セッション内で並行エージェントを実行します — 起動が速く、worktree は不要です。下記の ネイティブ Teams API セクションも参照してください。
</when_to_use>
アーキテクチャ
┌──────────────────────────────────────────────────┐
│ TEAM LEAD │
│ (this Claude session) │
│ │
│ Responsibilities: │
│ • Decompose task into agent assignments │
│ • Create worktrees (via worktree-manager) │
│ • Write WORKTREE_TASK.md for each agent │
│ • Monitor progress (git log, file checks) │
│ • Coordinate merges back to main │
└─────────┬───────────────┬───────────────┬────────┘
│ │ │
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ AGENT 1 │ │ AGENT 2 │ │ AGENT 3 │
│ │ │ │ │ │
│ Worktree: │ │ Worktree: │ │ Worktree: │
│ ~/tmp/wt/ │ │ ~/tmp/wt/ │ │ ~/tmp/wt/ │
│ proj/br-1 │ │ proj/br-2 │ │ proj/br-3 │
│ │ │ │ │ │
│ Terminal: │ │ Terminal: │ │ Terminal: │
│ Ghostty 1 │ │ Ghostty 2 │ │ Ghostty 3 │
└───────────┘ └───────────┘ └───────────┘
│ │ │
└───── git branches ─────────────┘
│
[main branch]
コンテキストの分離
各エージェントは完全に別個の Claude セッションです。エージェントは:
- 互いのコンテキストウィンドウを読み取ることができません
- 互いにメッセージを送信できません
- ファイルシステムと git を通じてのみ状態を共有します
- 起動時に
WORKTREE_TASK.mdから自分のタスクを読み取ります
ファイルによる連携
| ファイル | 目的 | 書き込み元 | 読み込み元 |
|---|---|---|---|
WORKTREE_TASK.md | エージェントの担当タスクとコンテキスト | チームリーダー | エージェント |
CONTRACT.md | 共有 API／インターフェース定義 | チームリーダー | すべてのエージェント |
.agent-status | エージェントによる進捗の自己報告 | エージェント | チームリーダー |
.claude/CLAUDE.md | プロジェクトの規約、開発コマンド | プロジェクト | エージェント（自動読み込み） |
.claude/settings.json | フック（自動フォーマット）、権限 | プロジェクト | エージェント（自動読み込み） |
.claude/agents/*.md | カスタムサブエージェントの定義 | プロジェクト | エージェント（ディスパッチ時） |
| Git コミット | 作業成果物 | エージェント | マージ時にチームリーダー |
<display_modes>
表示モード
| モード | ターミナル | 方法 |
|---|---|---|
in-process | 任意のターミナル | すべてのチームメイトがメインターミナルに表示されます。Shift+Down で切り替え、Ctrl+T でタスクリストを表示します。 |
split-pane | tmux または iTerm2 のみ | チームメイトごとに専用のペインが割り当てられます。ペインをクリックして操作します。 |
設定：~/.claude/settings.json で "teammateMode": "auto" を指定します。CLI：claude --teammate-mode in-process。Ghostty で分割ペインを使うには tmux ラッパーが必要です。
分割ペインの設定
tmux： $TMUX が設定されている場合、自動検出されます。チームメイトごとに分割ペインが割り当てられます。Ctrl+B + 矢印キーで移動します。
iTerm2： AppleScript による自動化を使用します。チームメイトは現在のタブ内の分割ペインで開きます。
制限事項： Ghostty はプログラムによるペイン分割に対応していません。tmux ラッパーを使用してください：ghostty -e "tmux new-session"。推奨されるペインの最大数は 4 つ（リーダー + チームメイト 3 人）です。各ペインには約 120 列が必要です。
</display_modes>
<team_hooks>
チームフック
TeammateIdle フック
チームメイトが現在のターンを終えてアイドル状態になると実行されます。settings.json で設定します：
{
"hooks": {
"TeammateIdle": [{
"hooks": [{
"type": "command",
"command": "bash -c 'echo \"Teammate idle — check TaskList for unassigned work\" >&2'"
}]
}]
}
}
使用例： 次のタスクの自動割り当て、アイドル時間の記録、クリーンアップの開始。終了コード 2 はアイドル状態への移行をブロックし、チームメイトの作業を継続させます。マッチャーには対応していません。すべてのチームメイトに対して実行されます。
TaskCompleted フック
TaskUpdate によってタスクが完了としてマークされると実行されます。自動割り当てパイプラインに使用します：
{
"hooks": {
"TaskCompleted": [{
"hooks": [{
"type": "command",
"command": "bash -c 'echo \"Task completed — assigning next unblocked task\" >&2'"
}]
}]
}
}
終了コード 2 はタスクの完了をブロックし、タスクを in_progress のままにします。マッチャーには対応していません。
プラン承認フロー
mode: "plan" で起動されたチームメイトは、実装前にプランの承認を受ける必要があります：
- チームメイトが
ExitPlanModeを呼び出す → チームリーダーにplan_approval_requestを送信 - チームリーダーがレビュー → 承認またはフィードバック付きの却下を
plan_approval_responseで送信 - 承認された場合：チームメイトはプランモードを終了し、実装を開始
- 却下された場合：チームメイトはフィードバックを受け取り、プランを修正
// Approving a teammate's plan
SendMessage({
type: "plan_approval_response",
request_id: "abc-123", // from plan_approval_request
recipient: "architect",
approve: true
})
</team_hooks>
ワークフロー
| ワークフロー | 目的 |
|---|---|
| 1. チームを起動する | 分解 → JSON ロードマップ → worktree → タスクファイル → 起動 → 監視 |
| 2. WORKTREE_TASK.md を作成する | コンテキスト、担当タスク、ファイルの境界、コントラクト、検証、完了手順 |
| 3. 進捗を監視する | ブランチごとの git log と .agent-status の確認 |
| 4. エージェントの作業をマージする | 計画した順序でマージし、都度テストして、--no-ff を使用 |
| 5. 非同期で引き継ぐ | 長時間かかるタスクには GitHub PR の @claude ボットを使用 |
| 6. プランモード | 分解を決定する前に、コードベースを読み取り専用で調査 |
| 7. ネイティブ Teams API | worktree を使わないセッション内チームに TeamCreate + TaskCreate + SendMessage を使用 |
| 8. プラン承認 | mode: "plan" のチームメイトは、実装前にリーダーの承認を受けるためプランを提出 |
ネイティブ API と Worktree の選択： 別々のファイルを扱う場合 → ネイティブ Teams API。同じファイルを扱う場合 → Worktree。リアルタイムのメッセージング → ネイティブ API。長時間実行するプロセス → Worktree。
手順ごとの説明、WORKTREE_TASK.md のテンプレート、マージ手順、ネイティブ Teams API の例については、reference/workflows-detailed.md を参照してください。
<use_cases>
チームのパターン
機能の並行開発
2～3 人のエージェントが、独立した機能を同時に開発します。競合リスクが最も低くなります。
最適な用途： スプリント形式で機能を並行開発する場合。
参照： 起動プロンプトについては reference/prompt-templates.md#feature-parallel を参照してください。
テスト／実装（TDD ペア）
エージェント 1 が最初にテストを作成し、コミットしてプッシュします。エージェント 2 がテストをプルし、テストに合格するまで実装します。
最適な用途： テストカバレッジが重要な高品質コード。
参照： エージェントの起動プロンプトについては、reference/prompt-templates.md#test-implement を参照してください。
レビュー／リファクタリング
エージェント 1 がコードをリファクタリングします。エージェント 2 がリファクタリング後のコードをレビューし、改善案を作成します。
最適な用途： 別の視点が役立つ大規模なリファクタリングタスク。
参照： エージェントの起動プロンプトについては、reference/prompt-templates.md#review-refactor を参照してください。
</use_cases>
<best_practices>
ベストプラクティス
- エージェントごとにコンテキストを分離する — WORKTREE_TASK.md には関連情報だけを記載し、タスクは 50 語未満にします
- 外部状態を使用する —
.agent-status、Git のコミット、WORKTREE_TASK.mdを使用します（エージェント間で共有メモリはありません） - 指示を最初に記載する — タスクファイルの冒頭に最も重要な情報を記載します
- コントラクトを先に定義する — エージェントを起動する前に、共有 API の構造を
CONTRACT.mdで定義します - マージの順序が重要 — 基盤（API）を利用側（UI）より先にし、各段階でテストを実行して、
--no-ffを使用します - プロジェクト設定の継承 —
.claude/ディレクトリが自動的にコピーされ、エージェントは CLAUDE.md、フック、権限、カスタムサブエージェントを利用できます - チームフック —
TeammateIdleとTaskCompletedフックは、作業の継続や完了のブロックに終了コード 2 を使用します
コンテキストエンジニアリング、セッションハーネスのパターン、権限モデル、フックの設定については、reference/best-practices-full.md を参照してください。
制限事項
M1／8GB の制約
- エージェントは最大 3 つ — これを超えると、メモリ負荷によってスラッシングが発生します
- GPU エージェントなし — すべてのエージェントは CPU バウンドの Claude セッションです
- 起動時間 — 各エージェントの初期化には 5～10 秒かかります
調整に関する制限
- リアルタイム通信なし — ワークツリーのエージェント同士はメッセージを送れません（ただし、ネイティブの Teams API エージェントは可能です。ワークフロー 7 を参照してください）
- ファイルの競合 — 2 つのエージェントが同じファイルを編集した場合、手動での解決が必要です
- コンテキストの共有なし — 各エージェントは WORKTREE_TASK.md のみを使って新たに開始します
- 順次依存 — エージェント 2 がエージェント 1 の出力を必要とする場合、エージェント 2 は待機する必要があります
ネイティブの Agent Teams に関する制約
Claude Code のネイティブ Agent Teams における既知の制約：
| 制限事項 | 詳細 |
|---|---|
| セッションの再開不可 | /resume を実行しても、プロセス内のチームメイトは復元されません。再開されるのはリードエージェントのみです。 |
| 入れ子のチーム不可 | チームメイトはサブチームを起動できません。チーム階層は 1 段階のみです。 |
| 1 セッションにつき 1 チーム | 新しいチームを開始する前に、現在のチームをクリーンアップ（TeamDelete）してください。 |
| リードは固定 | セッションの途中でチームメイトを昇格させたり、リーダーシップを移譲したりすることはできません。 |
| 起動時に権限を設定 | チームメイトの権限は起動時に設定されます。作成後はチームメイトごとに調整できますが、起動中は調整できません。 |
| シャットダウンに時間がかかる場合がある | チームメイトはシャットダウン前に現在のリクエストを完了します。余裕を持って段階的に終了してください。 |
このスキルの対象外
- CI/CD パイプラインではありません — 自動テストには GitHub Actions を使用してください
- サブエージェント用フレームワークではありません — サブエージェント（Claude に組み込まれた Task ツール）は 1 つのセッション内で実行されます。このスキルは別々のセッションを調整します。
- 自動スケーリングではありません — チームの規模と割り当ては手動で決定します
トラブルシューティング
エージェントが WORKTREE_TASK.md を読まない
原因： エージェントが --dangerously-skip-permissions なしで起動されたか、タスクファイルがワークツリーのルートにありません。
対処方法： worktree-manager がタスクファイルをワークツリーのルートディレクトリに書き込むようにしてください。
エージェント間でマージ競合が発生する
原因： ファイルの境界に関する指示があったにもかかわらず、エージェントが重複するファイルを編集しました。 対処方法：
- WORKTREE_TASK.md で境界が明確だったか確認します
- main 上で競合を手動で解決します
- 次回は、ファイルの境界をより厳密に設定します
エージェントがコンテキストを使い果たす
原因: エージェントのタスクが広範すぎて、あまりにも多くのファイルを読み込んでしまいました。 修正: タスクをより小さな単位に分割してください。各エージェントが触れるファイルは 10 個未満にしてください。
メモリ圧迫 / システムの低下
原因: 利用可能な RAM に対してエージェントが多すぎます。 修正:
- エージェントを 2 個に減らす
- 必須でないアプリケーションを閉じる
- 起動前に
memory_pressureを確認する
エージェントは完了したが作業内容が誤っている
原因: WORKTREE_TASK.md の検証ステップが不十分です。 修正: 明示的な検証コマンドを追加してください:
## Verification
1. Run: npm test -- --filter auth
2. Run: npx tsc --noEmit
3. Manually test: curl localhost:8100/api/auth/login
参照ファイル
より詳細なガイダンスが必要なときに、必要に応じて読み込んでください:
| 参照 | 読み込むタイミング |
|---|---|
reference/workflows-detailed.md | 起動、監視、マージ、非同期ハンドオフ、Native Teams API のステップバイステップ |
reference/best-practices-full.md | コンテキストエンジニアリング、セッションハーネス、コントラクトファースト、フック設定 |
reference/context-engineering.md | エージェントプロンプトの設計、コンテキスト使用量の最適化、委任パターン |
reference/worktree-integration.md | worktree-manager との連携、ポート割り当て、ターミナル戦略 |
reference/prompt-templates.md | 4 つのチームパターン向けのすぐに使える起動プロンプトが必要なとき |
結果サイドカーを出力する
最終ステップとして、~/.claude/skill-analytics/last-outcome-agent-teams.json に書き込みます:
{"ts":"[UTC ISO8601]","skill":"agent-teams","version":"1.2.0","variant":"default",
"status":"[success|partial|error]","runtime_ms":[estimated ms from start],
"metrics":{"agents_spawned":[n],"tasks_delegated":[n],"merges_completed":[n]},
"error":null,"session_id":"[YYYY-MM-DD]"}
一部のステージが失敗しても結果が生成された場合は、ステータスに "partial" を使用してください。出力が一切生成されなかった場合にのみ "error" を使用してください。