subagent-teams

単一の Claude Code セッション内で Task ツールのサブエージェントチームをオーケストレーションします。完全な並列セッションのために worktree + ターミナルを使用する agent-teams-skill とは異なり、このスキルは Task ツールを使用して、共有コードベースアクセスを備えた軽量なセッション内並列処理を実現します。

<quick_start> リサーチのファンアウト:

Launch 3 Explore agents in parallel:
- Agent 1: Search for authentication patterns
- Agent 2: Search for database schema
- Agent 3: Search for API endpoints

実装のファンアウト:

1. Plan agent designs architecture
2. 3 general-purpose agents build components in parallel
3. code-reviewer agent validates all changes

</quick_start>

<success_criteria>

• サブエージェントが適切なモデル階層で起動される（検索/レビューには Haiku、コードには Sonnet、アーキテクチャには Opus）
• 並列エージェントがファイル編集の競合なしに独立して完了する
• ファンイン統合により、すべてのバックグラウンドエージェントから主要な知見を収集する
• コンテキストオーバーフローを避けるため、並列エージェントの総数は 5〜7 の制限内に収まる
• ライブ UI スピナーを伴う進捗トラッキングに TaskCreate/TaskUpdate を使用する </success_criteria>

- 「サブエージェントチームをセットアップ」「ファンアウト」「並列タスク」「Task ツールチーム」 - 「並列でリサーチ」「並列で探索」「並列でレビュー」 - 「サブエージェントを起動」「セッション内エージェント」

---

これと agent-teams をいつ使い分けるか

要因	subagent-teams（これ）	agent-teams
分離	共有コードベース、共有コンテキスト	完全な worktree 分離
オーバーヘッド	軽量 — Task ツール呼び出しのみ	重量級 — ターミナル、git ブランチ、ポート
最適な用途	リサーチ、レビュー、ドキュメント更新	機能開発、ファイル編集の競合
最大エージェント数	5〜7（コンテキスト制限）	2〜3（M1 8GB RAM 制限）
所要時間	数分	数時間
調整	TeamCreate + TaskList/TaskUpdate	WORKTREE_TASK.md + git ブランチ

目安: エージェントが同じファイルを編集する場合 → agent-teams（worktree 分離）を使用します。エージェントが読み取り専用、または異なるファイルを編集する場合 → subagent-teams（より高速で軽量）を使用します。

---

Task ツールのパラメーター（完全リファレンス）

コアパラメーター

{
  subagent_type: "Explore" | "general-purpose" | "Plan" | ...,
  model: "haiku" | "sonnet" | "opus",
  prompt: "...",
  description: "3-5 word summary",        // Required
  run_in_background: true,                 // For parallel execution
  team_name: "my-team",                    // Scope to a team's task list
  name: "agent-1",                         // Name for team messaging
  mode: "default"                          // Permission mode (see below)
}

エージェントのフロントマターフィールド（.md エージェントファイル用）

フィールド	型	目的
name	string	エージェント識別子
description	string	エージェントが行うこと（ルーティングで表示される）
model	string	デフォルトモデル: haiku、sonnet、opus
tools	list	許可されるツール（エージェントの機能を制限）
disallowedTools	list	明示的にブロックされるツール
permissionMode	string	default、acceptEdits、dontAsk、plan
mcpServers	list	エージェントが利用できる MCP サーバー
hooks	object	イベント駆動の自動化（PostToolUse など）
maxTurns	number	停止するまでの最大 API ラウンドトリップ数
skills	list	エージェントが利用できるスキル
memory	object	永続状態（以下のメモリスコープを参照）

メモリスコープ

memory フィールドは、エージェントにセッションをまたいだ永続状態を提供します:

# User-scoped: shared across all projects for this user
memory:
  scope: user    # Stored in ~/.claude/agent-memory/

# Project-scoped: shared across sessions within one project
memory:
  scope: project # Stored in .claude/agent-memory/

# Local-scoped: private to this machine + project combo
memory:
  scope: local   # Stored in .claude/local/agent-memory/

使用する場面: 個人の設定・パターンには user。チーム共有のナレッジには project。マシン固有のパスや認証情報には local。

バックグラウンド実行

次のアクションをブロックしないエージェントには run_in_background: true を使用します:

// Launch in background — returns immediately with output_file path
Task({
  subagent_type: "Explore",
  prompt: "Search for all auth patterns",
  run_in_background: true  // Non-blocking
})

// Check results later
TaskOutput({ task_id: "agent-id", block: false })  // Non-blocking check
TaskOutput({ task_id: "agent-id", block: true })    // Wait for completion

フォアグラウンドとバックグラウンド:

• フォアグラウンド（デフォルト）: 先に進む前に結果が必要な場合に使用します — 次のステップの判断材料となるリサーチなど
• バックグラウンド: 並行して行う独立した作業がある場合に使用します — オブザーバー、リンター、長時間の検索など

ヒント: バックグラウンドエージェントは、observer-lite/observer-full、セキュリティスキャン、後で結果を統合できる並列リサーチに最適です。

パーミッションモード

モード	動作
default	通常の承認フロー
acceptEdits	ファイル編集を自動承認、Bash はプロンプト表示
dontAsk	すべてを自動承認（信頼できるエージェントで使用）
plan	エージェントは実装前にプランの承認を得る必要がある
delegate	エージェントはサブエージェントへの委任のみ可能

生成の制限

ツールフィールドで Task(agent_type) を使用して、エージェントが生成できるサブエージェントを制限します：

tools:
  - Read
  - Glob
  - Task(Explore)        # Can only spawn Explore subagents
  - Task(code-reviewer)  # Can also spawn code reviewers

組み込みエージェントタイプとそのツールアクセス：

エージェントタイプ	ツール	最適な用途
Explore	Glob, Grep, Read, LS, WebFetch, WebSearch	高速なコードベース検索（読み取り専用）
Plan	Glob, Grep, Read, LS, WebFetch, WebSearch	アーキテクチャ設計（読み取り専用）
general-purpose	すべてのツール	実装、フルアクセス
feature-dev:code-reviewer	Glob, Grep, Read, LS, WebFetch	コードレビュー（読み取り専用）
feature-dev:code-explorer	Glob, Grep, Read, LS, WebFetch	詳細な機能分析（読み取り専用）
feature-dev:code-architect	Glob, Grep, Read, LS, WebFetch	アーキテクチャのブループリント（読み取り専用）
observer-lite	Read, Glob, Grep, Bash, Write	迅速な品質チェック
observer-full	Read, Glob, Grep, Bash, Write	完全なドリフト検出

カスタムエージェント： フロントマターを使用して .claude/agents/*.md で定義します。ファイル名（.md を除く）で参照します。

モデル選択ガイド

タスク	モデル	理由
ファイル検索、パターンマッチング	haiku	高速、低コスト、十分
コードレビュー、バグ発見	haiku	生成ではなくパターンマッチング
コード生成、リファクタリング	sonnet	コードには品質が重要
アーキテクチャの決定	opus	複雑な推論が必要
ドキュメント作成	sonnet	コンテキストの理解が必要

---

チームパターン

1. リサーチチーム（3 つの Explore エージェント）

3 つの検索戦略をファンアウトし、ファンインして統合します：

Task 1 (Explore, haiku): "Search for [pattern] in src/"
Task 2 (Explore, haiku): "Search for [pattern] in tests/"
Task 3 (Explore, haiku): "Search for [pattern] in docs/"
→ Fan-in: Synthesize findings into summary

使用場面： 慣れていないコードベースを調査するとき、機能がレイヤーをまたいでどのように動作するかを理解するとき。

2. 実装チーム（architect → builders → reviewer）

並列ビルドフェーズを含むシーケンシャルパイプライン：

Phase 1: Plan agent designs architecture (1 agent)
Phase 2: 2-3 general-purpose agents build components (parallel)
Phase 3: code-reviewer validates (1 agent)

使用場面： 複数の独立したコンポーネントを持つ機能を構築するとき。

3. レビューチーム（3 つの reviewer を並列で）

Task 1 (code-reviewer, haiku): "Review src/auth/ for security"
Task 2 (code-reviewer, haiku): "Review src/api/ for consistency"
Task 3 (code-reviewer, haiku): "Review src/db/ for performance"
→ Fan-in: Aggregate findings, deduplicate

使用場面： 大規模な変更セットの PR 前レビュー。

4. 探索チーム（3 つの検索戦略）

Task 1 (Explore, haiku): Glob for file patterns
Task 2 (Explore, haiku): Grep for code patterns
Task 3 (Explore, haiku): Read key entry points
→ Fan-in: Build mental model of codebase area

使用場面： コードベースの新しい領域で初めて作業するとき。

5. ドキュメントチーム（N 個の独立したファイル更新担当）

Task 1 (general-purpose, haiku): "Update README.md with new API"
Task 2 (general-purpose, haiku): "Update CHANGELOG.md"
Task 3 (general-purpose, haiku): "Update API docs"
→ No fan-in needed (independent files)

使用場面： 複数の独立したドキュメントファイルを更新するとき。

---

進捗のレンダリング

ネイティブ進捗（TaskCreate/TaskUpdate）

実行中にライブ UI スピナーを表示するには、activeForm を指定して TaskCreate を使用します：

// Create tasks for each agent's work
TaskCreate({ subject: "Search auth patterns", activeForm: "Searching auth patterns" })
TaskCreate({ subject: "Search DB schema", activeForm: "Searching DB schema" })
TaskCreate({ subject: "Search API endpoints", activeForm: "Searching API endpoints" })

// Track status transitions
TaskUpdate({ taskId: "1", status: "in_progress" })  // → shows spinner
TaskUpdate({ taskId: "1", status: "completed" })     // → shows checkmark

タスク依存関係（シーケンシャルフェーズ）

addBlockedBy を使用してフェーズを順序付けます：

// Phase 1: Architecture (runs first)
TaskCreate({ subject: "Design architecture" })  // → task #1

// Phase 2: Implementation (blocked by Phase 1)
TaskCreate({ subject: "Build backend" })   // → task #2
TaskCreate({ subject: "Build frontend" })  // → task #3
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
TaskUpdate({ taskId: "3", addBlockedBy: ["1"] })

// Phase 3: Review (blocked by Phase 2)
TaskCreate({ subject: "Code review" })  // → task #4
TaskUpdate({ taskId: "4", addBlockedBy: ["2", "3"] })

サマリーのレンダリング（Markdown）

すべてのエージェントが完了したら、markdown サマリーをレンダリングします：

## Research Complete: 3/3 agents finished

| Agent | Scope | Findings | Time |
|-------|-------|----------|------|
| Auth search | src/auth/ | 12 files, JWT + session | 8s |
| DB search | src/db/ | 8 tables, RLS policies | 5s |
| API search | src/api/ | 15 endpoints, REST | 6s |

### Key Insights
- [Synthesized finding 1]
- [Synthesized finding 2]

---

チーム調整（ネイティブ Agent Teams API）

複雑なマルチエージェント作業には、ネイティブ Teams API を使用します：

// Create a team with shared task list
TeamCreate({ team_name: "research-sprint" })

// Spawn teammates into the team
Task({ subagent_type: "Explore", team_name: "research-sprint", name: "searcher-1" })
Task({ subagent_type: "Explore", team_name: "research-sprint", name: "searcher-2" })

// Teammates coordinate via shared TaskList
// Send messages between teammates
SendMessage({ type: "message", recipient: "searcher-1", content: "Focus on auth/" })

// Shutdown when done
SendMessage({ type: "shutdown_request", recipient: "searcher-1" })

---

プロンプトテンプレート

リサーチの生成

Search the codebase for [PATTERN]. Look in [SCOPE].
Report: file paths, line numbers, and a 2-sentence summary of each match.
Do NOT modify any files.

ビルドの生成

Implement [COMPONENT] in [FILE_PATH].
Requirements: [SPEC]
Follow existing patterns in [EXAMPLE_FILE].
Write code only — do not run tests.

レビューの生成

Review [FILE_PATH] for [CONCERN: security|performance|consistency].
Report only HIGH confidence issues.
Format: file:line — issue — suggestion

---

制約

• 並列エージェントは最大 5～7 個 — これを超えるとコンテキストウィンドウが埋まります
• ファイル編集の競合を避ける — エージェントが同じファイルを編集する可能性がある場合は、代わりに agent-teams を使用してください
• ファンインは手動 — あなた（チームリード）がバックグラウンドエージェントの結果を統合します
• バックグラウンドエージェントは互いを認識できません — 独立して完了できるようにタスクを設計してください

詳細解説： reference/task-tool-guide.md、reference/team-patterns.md、reference/prompt-templates.md を参照してください

結果サイドカーの出力

最終ステップとして、~/.claude/skill-analytics/last-outcome-subagent-teams.json に書き込みます：

{"ts":"[UTC ISO8601]","skill":"subagent-teams","version":"1.1.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"agents_spawned":[n],"tasks_completed":[n],"tasks_failed":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

一部のステージが失敗しても結果が生成された場合は、ステータスに「partial」を使用します。出力がまったく生成されなかった場合にのみ「error」を使用します。