orchestrating-swarms

Claude Code Swarm Orchestration

Claude Code の TeammateTool と Task システムを使ったマルチエージェントオーケストレーションを習得しましょう。

---

プリミティブ

プリミティブ	内容	ファイルの場所
エージェント	ツールを使用できる Claude のインスタンスです。あなたもエージェントです。サブエージェントは、あなたが起動するエージェントです。	該当なし（プロセス）
チーム	一緒に作業する、名前付きのエージェントグループです。リーダーが 1 人、チームメイトが複数います。	~/.claude/teams/{name}/config.json
チームメイト	チームに参加したエージェントです。名前、色、受信トレイがあります。team_name + name を指定して Task 経由で起動します。	チーム設定に記載
リーダー	チームを作成したエージェントです。チームメイトからのメッセージを受信し、計画やシャットダウンを承認します。	設定内の最初のメンバー
タスク	件名、説明、ステータス、担当者、依存関係を持つ作業項目です。	~/.claude/tasks/{team}/N.json
受信トレイ	エージェントがチームメイトからメッセージを受信する JSON ファイルです。	~/.claude/teams/{name}/inboxes/{agent}.json
メッセージ	エージェント間で送信される JSON オブジェクトです。テキストの場合も、構造化データ（shutdown_request、idle_notification など）の場合もあります。	受信トレイファイルに保存
バックエンド	チームメイトの実行方法です。自動検出されます。in-process（同じ Node.js 内で動作し、表示されません）、tmux（別々のペインで表示）、iterm2（iTerm2 の分割ペイン）があります。起動バックエンドを参照してください。	環境に基づいて自動検出

接続の仕組み

flowchart TB
    subgraph TEAM[TEAM]
        Leader[Leader - you]
        T1[Teammate 1]
        T2[Teammate 2]

        Leader <-->|messages via inbox| T1
        Leader <-->|messages via inbox| T2
        T1 <-.->|can message| T2
    end

    subgraph TASKS[TASK LIST]
        Task1["#1 completed: Research<br/>owner: teammate1"]
        Task2["#2 in_progress: Implement<br/>owner: teammate2"]
        Task3["#3 pending: Test<br/>blocked by #2"]
    end

    T1 --> Task1
    T2 --> Task2
    Task2 -.->|unblocks| Task3

ライフサイクル

flowchart LR
    A[1. Create Team] --> B[2. Create Tasks]
    B --> C[3. Spawn Teammates]
    C --> D[4. Work]
    D --> E[5. Coordinate]
    E --> F[6. Shutdown]
    F --> G[7. Cleanup]

メッセージフロー

sequenceDiagram
    participant L as Leader
    participant T1 as Teammate 1
    participant T2 as Teammate 2
    participant Tasks as Task List

    L->>Tasks: TaskCreate (3 tasks)
    L->>T1: spawn with prompt
    L->>T2: spawn with prompt

    T1->>Tasks: claim task #1
    T2->>Tasks: claim task #2

    T1->>Tasks: complete #1
    T1->>L: send findings (inbox)

    Note over Tasks: #3 auto-unblocks

    T2->>Tasks: complete #2
    T2->>L: send findings (inbox)

    L->>T1: requestShutdown
    T1->>L: approveShutdown
    L->>T2: requestShutdown
    T2->>L: approveShutdown

    L->>L: cleanup

---

目次

1. コアアーキテクチャ
2. エージェントを起動する 2 つの方法
3. 組み込みエージェントタイプ
4. プラグインエージェントタイプ
5. TeammateTool の操作
6. Task システムとの統合
7. メッセージ形式
8. オーケストレーションパターン
9. 環境変数
10. 起動バックエンド
11. エラー処理
12. ワークフロー全体

---

コアアーキテクチャ

Swarm の仕組み

Swarm は以下で構成されます。

• リーダー（あなた）— チームを作成し、ワーカーを起動し、作業を調整します
• チームメイト（起動されたエージェント）— タスクを実行し、結果を報告します
• タスクリスト — 依存関係を含む共有作業キューです
• 受信トレイ — エージェント間のメッセージングに使用する JSON ファイルです

ファイル構成

~/.claude/teams/{team-name}/
├── config.json              # Team metadata and member list
└── inboxes/
    ├── team-lead.json       # Leader's inbox
    ├── worker-1.json        # Worker 1's inbox
    └── worker-2.json        # Worker 2's inbox

~/.claude/tasks/{team-name}/
├── 1.json                   # Task #1
├── 2.json                   # Task #2
└── 3.json                   # Task #3

チーム設定の構成

{
  "name": "my-project",
  "description": "Working on feature X",
  "leadAgentId": "team-lead@my-project",
  "createdAt": 1706000000000,
  "members": [
    {
      "agentId": "team-lead@my-project",
      "name": "team-lead",
      "agentType": "team-lead",
      "color": "#4A90D9",
      "joinedAt": 1706000000000,
      "backendType": "in-process"
    },
    {
      "agentId": "worker-1@my-project",
      "name": "worker-1",
      "agentType": "Explore",
      "model": "haiku",
      "prompt": "Analyze the codebase structure...",
      "color": "#D94A4A",
      "planModeRequired": false,
      "joinedAt": 1706000001000,
      "tmuxPaneId": "in-process",
      "cwd": "/Users/me/project",
      "backendType": "in-process"
    }
  ]
}

---

エージェントを起動する 2 つの方法

方法 1：Task ツール（サブエージェント）

結果を返す短期間で目的が明確な作業には Task を使用します。

Task({
  subagent_type: "Explore",
  description: "Find auth files",
  prompt: "Find all authentication-related files in this codebase",
  model: "haiku"  // Optional: haiku, sonnet, opus
})

特徴：

• 同期実行（完了するまでブロック）するか、run_in_background: true を指定して非同期実行します
• 結果が直接あなたに返されます
• チームへの参加は不要です
• 最適な用途：検索、分析、目的を絞った調査

権限モード： mode: "plan" のような特定のモードが必要な場合を除き、mode パラメーターは省略してください。mode: "auto" を渡すと、ユーザーが設定した権限設定（例：bypassPermissions）が上書きされます。省略すると、ユーザー自身の defaultMode が適用されます。

方法 2：Task ツール + team_name + name（チームメイト）

Task に team_name と name を指定して、継続的に稼働するチームメイトを起動します。

// First create a team
Teammate({ operation: "spawnTeam", team_name: "my-project" })

// Then spawn a teammate into that team
Task({
  team_name: "my-project",        // Required: which team to join
  name: "security-reviewer",      // Required: teammate's name
  subagent_type: "security-sentinel",
  prompt: "Review all authentication code for vulnerabilities. Send findings to team-lead via Teammate write.",
  run_in_background: true         // Teammates usually run in background
})

特徴：

• チームに参加し、config.json に表示されます
• 受信トレイのメッセージを介して通信します
• 共有タスクリストからタスクを引き受けられます
• シャットダウンするまで稼働します
• 最適な用途：並列作業、継続的なコラボレーション、パイプラインの各段階

主な違い

項目	Task（サブエージェント）	Task + team_name + name（チームメイト）
存続期間	タスクが完了するまで	シャットダウンが要求されるまで
通信	戻り値	受信トレイのメッセージ
タスクへのアクセス	なし	共有タスクリスト
チームへの参加	いいえ	はい
調整	1 回限り	継続的

---

組み込みエージェントタイプ

これらはプラグインなしで常に使用できます。

Bash

Task({
  subagent_type: "Bash",
  description: "Run git commands",
  prompt: "Check git status and show recent commits"
})

• ツール： Bash のみ
• モデル： 親から継承
• 最適な用途： Git 操作、コマンド実行、システムタスク

Explore

Task({
  subagent_type: "Explore",
  description: "Find API endpoints",
  prompt: "Find all API endpoints in this codebase. Be very thorough.",
  model: "haiku"  // Fast and cheap
})

• ツール： 読み取り専用ツールすべて（Edit、Write、NotebookEdit、Task を除く）
• モデル： Haiku（速度を最適化）
• 最適な用途： コードベースの調査、ファイル検索、コードの理解
• 詳細度のレベル： "quick"、"medium"、"very thorough"

Plan

Task({
  subagent_type: "Plan",
  description: "Design auth system",
  prompt: "Create an implementation plan for adding OAuth2 authentication"
})

• ツール： 読み取り専用ツールすべて
• モデル： 親から継承
• 最適な用途： アーキテクチャの計画、実装戦略

general-purpose

Task({
  subagent_type: "general-purpose",
  description: "Research and implement",
  prompt: "Research React Query best practices and implement caching for the user API"
})

• ツール： すべてのツール（*）
• モデル： 親から継承
• 最適な用途： 複数ステップのタスク、調査と実行を組み合わせたタスク

claude-code-guide

Task({
  subagent_type: "claude-code-guide",
  description: "Help with Claude Code",
  prompt: "How do I configure MCP servers?"
})

• ツール： 読み取り専用ツール + WebFetch + WebSearch
• 最適な用途： Claude Code、Agent SDK、Anthropic API に関する質問

statusline-setup

Task({
  subagent_type: "statusline-setup",
  description: "Configure status line",
  prompt: "Set up a status line showing git branch and node version"
})

• ツール： Read、Edit のみ
• モデル： Sonnet
• 最適な用途： Claude Code のステータスラインの設定

---

プラグインのエージェントタイプ

compound-engineering プラグインの例：

レビューエージェント

// Security review
Task({
  subagent_type: "compound-engineering:review:security-sentinel",
  description: "Security audit",
  prompt: "Audit this PR for security vulnerabilities"
})

// Performance review
Task({
  subagent_type: "compound-engineering:review:performance-oracle",
  description: "Performance check",
  prompt: "Analyze this code for performance bottlenecks"
})

// Rails code review
Task({
  subagent_type: "compound-engineering:review:kieran-rails-reviewer",
  description: "Rails review",
  prompt: "Review this Rails code for best practices"
})

// Architecture review
Task({
  subagent_type: "compound-engineering:review:architecture-strategist",
  description: "Architecture review",
  prompt: "Review the system architecture of the authentication module"
})

// Code simplicity
Task({
  subagent_type: "compound-engineering:review:code-simplicity-reviewer",
  description: "Simplicity check",
  prompt: "Check if this implementation can be simplified"
})

compound-engineering のすべてのレビューエージェント：

• agent-native-reviewer - エージェントでも機能するようにします
• architecture-strategist - アーキテクチャへの準拠
• code-simplicity-reviewer - YAGNI とミニマリズム
• data-integrity-guardian - データベースとデータの安全性
• data-migration-expert - 移行の検証
• deployment-verification-agent - デプロイ前チェックリスト
• dhh-rails-reviewer - DHH／37signals の Rails スタイル
• julik-frontend-races-reviewer - JavaScript の競合状態
• kieran-python-reviewer - Python のベストプラクティス
• kieran-rails-reviewer - Rails のベストプラクティス
• kieran-typescript-reviewer - TypeScript のベストプラクティス
• pattern-recognition-specialist - デザインパターンとアンチパターン
• performance-oracle - パフォーマンス分析
• security-sentinel - セキュリティの脆弱性

リサーチエージェント

// Best practices research
Task({
  subagent_type: "compound-engineering:research:best-practices-researcher",
  description: "Research auth best practices",
  prompt: "Research current best practices for JWT authentication in Rails 2024-2026"
})

// Framework documentation
Task({
  subagent_type: "compound-engineering:research:framework-docs-researcher",
  description: "Research Active Storage",
  prompt: "Gather comprehensive documentation about Active Storage file uploads"
})

// Git history analysis
Task({
  subagent_type: "compound-engineering:research:git-history-analyzer",
  description: "Analyze auth history",
  prompt: "Analyze the git history of the authentication module to understand its evolution"
})

すべてのリサーチエージェント：

• best-practices-researcher - 外部のベストプラクティス
• framework-docs-researcher - フレームワークのドキュメント
• git-history-analyzer - コードの変遷の調査
• learnings-researcher - docs/solutions/ の検索
• repo-research-analyst - リポジトリのパターン

デザインエージェント

Task({
  subagent_type: "compound-engineering:design:figma-design-sync",
  description: "Sync with Figma",
  prompt: "Compare implementation with Figma design at [URL]"
})

ワークフローエージェント

Task({
  subagent_type: "compound-engineering:workflow:bug-reproduction-validator",
  description: "Validate bug",
  prompt: "Reproduce and validate this reported bug: [description]"
})

---

TeammateTool の操作

1. spawnTeam - チームを作成

Teammate({
  operation: "spawnTeam",
  team_name: "feature-auth",
  description: "Implementing OAuth2 authentication"
})

作成されるもの：

• ~/.claude/teams/feature-auth/config.json
• ~/.claude/tasks/feature-auth/ ディレクトリ
• あなたはチームリーダーになります

2. discoverTeams - 利用可能なチームを一覧表示

Teammate({ operation: "discoverTeams" })

戻り値： 参加可能なチームの一覧（すでにメンバーになっているチームを除く）

3. requestJoin - チームへの参加をリクエスト

Teammate({
  operation: "requestJoin",
  team_name: "feature-auth",
  proposed_name: "helper",
  capabilities: "I can help with code review and testing"
})

4. approveJoin - 参加リクエストを承認（リーダーのみ）

join_request メッセージを受信した場合：

{"type": "join_request", "proposedName": "helper", "requestId": "join-123", ...}

承認します：

Teammate({
  operation: "approveJoin",
  target_agent_id: "helper",
  request_id: "join-123"
})

5. rejectJoin - 参加リクエストを拒否（リーダーのみ）

Teammate({
  operation: "rejectJoin",
  target_agent_id: "helper",
  request_id: "join-123",
  reason: "Team is at capacity"
})

6. write - チームメイト 1 人にメッセージを送信

Teammate({
  operation: "write",
  target_agent_id: "security-reviewer",
  value: "Please prioritize the authentication module. The deadline is tomorrow."
})

チームメイトへの重要事項： あなたのテキスト出力はチームには表示されません。コミュニケーションには必ず write を使用してください。

7. broadcast - すべてのチームメイトにメッセージを送信

Teammate({
  operation: "broadcast",
  name: "team-lead",  // Your name
  value: "Status check: Please report your progress"
})

警告： ブロードキャストはコストがかかります。チームメイトが N 人の場合、個別のメッセージを N 件送信します。特定のチームメイトには write を使用してください。

ブロードキャストする場合：

• 即時対応が必要な重大な問題
• 全員に影響する重要なお知らせ

ブロードキャストしない場合：

• 1 人のチームメイトへの返信
• 通常のやり取り
• 一部のチームメイトだけに関係する情報

8. requestShutdown - チームメイトに終了を依頼（リーダーのみ）

Teammate({
  operation: "requestShutdown",
  target_agent_id: "security-reviewer",
  reason: "All tasks complete, wrapping up"
})

9. approveShutdown - 終了を承認（チームメイトのみ）

shutdown_request メッセージを受信した場合：

{"type": "shutdown_request", "requestId": "shutdown-123", "from": "team-lead", "reason": "Done"}

必ず呼び出してください：

Teammate({
  operation: "approveShutdown",
  request_id: "shutdown-123"
})

これにより確認が送信され、プロセスが終了します。

10. rejectShutdown - 終了を拒否（チームメイトのみ）

Teammate({
  operation: "rejectShutdown",
  request_id: "shutdown-123",
  reason: "Still working on task #3, need 5 more minutes"
})

11. approvePlan - チームメイトの計画を承認（リーダーのみ）

plan_mode_required のチームメイトから計画が送られた場合：

{"type": "plan_approval_request", "from": "architect", "requestId": "plan-456", ...}

承認します：

Teammate({
  operation: "approvePlan",
  target_agent_id: "architect",
  request_id: "plan-456"
})

12. rejectPlan - フィードバックを添えて計画を却下（リーダーのみ）

Teammate({
  operation: "rejectPlan",
  target_agent_id: "architect",
  request_id: "plan-456",
  feedback: "Please add error handling for the API calls and consider rate limiting"
})

13. cleanup - チームリソースを削除

Teammate({ operation: "cleanup" })

削除対象：

• ~/.claude/teams/{team-name}/ ディレクトリ
• ~/.claude/tasks/{team-name}/ ディレクトリ

重要： チームメイトがまだアクティブな場合は失敗します。先に requestShutdown を使用してください。

---

タスクシステムとの連携

TaskCreate - 作業項目を作成

TaskCreate({
  subject: "Review authentication module",
  description: "Review all files in app/services/auth/ for security vulnerabilities",
  activeForm: "Reviewing auth module..."  // Shown in spinner when in_progress
})

TaskList - すべてのタスクを確認

TaskList()

戻り値：

#1 [completed] Analyze codebase structure
#2 [in_progress] Review authentication module (owner: security-reviewer)
#3 [pending] Generate summary report [blocked by #2]

TaskGet - タスクの詳細を取得

TaskGet({ taskId: "2" })

説明、ステータス、blockedBy などを含むタスク全体を返します。

TaskUpdate - タスクのステータスを更新

// Claim a task
TaskUpdate({ taskId: "2", owner: "security-reviewer" })

// Start working
TaskUpdate({ taskId: "2", status: "in_progress" })

// Mark complete
TaskUpdate({ taskId: "2", status: "completed" })

// Set up dependencies
TaskUpdate({ taskId: "3", addBlockedBy: ["1", "2"] })

タスクの依存関係

ブロックしているタスクが完了すると、ブロックされているタスクのブロックが自動的に解除されます：

// Create pipeline
TaskCreate({ subject: "Step 1: Research" })        // #1
TaskCreate({ subject: "Step 2: Implement" })       // #2
TaskCreate({ subject: "Step 3: Test" })            // #3
TaskCreate({ subject: "Step 4: Deploy" })          // #4

// Set up dependencies
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })   // #2 waits for #1
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })   // #3 waits for #2
TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })   // #4 waits for #3

// When #1 completes, #2 auto-unblocks
// When #2 completes, #3 auto-unblocks
// etc.

タスクファイルの構造

~/.claude/tasks/{team-name}/1.json：

{
  "id": "1",
  "subject": "Review authentication module",
  "description": "Review all files in app/services/auth/...",
  "status": "in_progress",
  "owner": "security-reviewer",
  "activeForm": "Reviewing auth module...",
  "blockedBy": [],
  "blocks": ["3"],
  "createdAt": 1706000000000,
  "updatedAt": 1706000001000
}

---

メッセージ形式

通常のメッセージ

{
  "from": "team-lead",
  "text": "Please prioritize the auth module",
  "timestamp": "2026-01-25T23:38:32.588Z",
  "read": false
}

構造化メッセージ（テキストフィールド内の JSON）

シャットダウン要求

{
  "type": "shutdown_request",
  "requestId": "shutdown-abc123@worker-1",
  "from": "team-lead",
  "reason": "All tasks complete",
  "timestamp": "2026-01-25T23:38:32.588Z"
}

シャットダウン承認

{
  "type": "shutdown_approved",
  "requestId": "shutdown-abc123@worker-1",
  "from": "worker-1",
  "paneId": "%5",
  "backendType": "in-process",
  "timestamp": "2026-01-25T23:39:00.000Z"
}

アイドル通知（チームメイトの停止時に自動送信）

{
  "type": "idle_notification",
  "from": "worker-1",
  "timestamp": "2026-01-25T23:40:00.000Z",
  "completedTaskId": "2",
  "completedStatus": "completed"
}

タスク完了

{
  "type": "task_completed",
  "from": "worker-1",
  "taskId": "2",
  "taskSubject": "Review authentication module",
  "timestamp": "2026-01-25T23:40:00.000Z"
}

計画の承認要求

{
  "type": "plan_approval_request",
  "from": "architect",
  "requestId": "plan-xyz789",
  "planContent": "# Implementation Plan\n\n1. ...",
  "timestamp": "2026-01-25T23:41:00.000Z"
}

参加要求

{
  "type": "join_request",
  "proposedName": "helper",
  "requestId": "join-abc123",
  "capabilities": "Code review and testing",
  "timestamp": "2026-01-25T23:42:00.000Z"
}

権限要求（サンドボックス／ツールの権限）

{
  "type": "permission_request",
  "requestId": "perm-123",
  "workerId": "worker-1@my-project",
  "workerName": "worker-1",
  "workerColor": "#4A90D9",
  "toolName": "Bash",
  "toolUseId": "toolu_abc123",
  "description": "Run npm install",
  "input": {"command": "npm install"},
  "permissionSuggestions": ["Bash(npm *)"],
  "createdAt": 1706000000000
}

---

オーケストレーションパターン

パターン 1：並列スペシャリスト（リーダーパターン）

複数のスペシャリストが同時にコードをレビューします：

// 1. Create team
Teammate({ operation: "spawnTeam", team_name: "code-review" })

// 2. Spawn specialists in parallel (single message, multiple Task calls)
Task({
  team_name: "code-review",
  name: "security",
  subagent_type: "compound-engineering:review:security-sentinel",
  prompt: "Review the PR for security vulnerabilities. Focus on: SQL injection, XSS, auth bypass. Send findings to team-lead.",
  run_in_background: true
})

Task({
  team_name: "code-review",
  name: "performance",
  subagent_type: "compound-engineering:review:performance-oracle",
  prompt: "Review the PR for performance issues. Focus on: N+1 queries, memory leaks, slow algorithms. Send findings to team-lead.",
  run_in_background: true
})

Task({
  team_name: "code-review",
  name: "simplicity",
  subagent_type: "compound-engineering:review:code-simplicity-reviewer",
  prompt: "Review the PR for unnecessary complexity. Focus on: over-engineering, premature abstraction, YAGNI violations. Send findings to team-lead.",
  run_in_background: true
})

// 3. Wait for results (check inbox)
// cat ~/.claude/teams/code-review/inboxes/team-lead.json

// 4. Synthesize findings and cleanup
Teammate({ operation: "requestShutdown", target_agent_id: "security" })
Teammate({ operation: "requestShutdown", target_agent_id: "performance" })
Teammate({ operation: "requestShutdown", target_agent_id: "simplicity" })
// Wait for approvals...
Teammate({ operation: "cleanup" })

パターン 2：パイプライン（逐次依存関係）

各ステージは前のステージに依存します：

// 1. Create team and task pipeline
Teammate({ operation: "spawnTeam", team_name: "feature-pipeline" })

TaskCreate({ subject: "Research", description: "Research best practices for the feature", activeForm: "Researching..." })
TaskCreate({ subject: "Plan", description: "Create implementation plan based on research", activeForm: "Planning..." })
TaskCreate({ subject: "Implement", description: "Implement the feature according to plan", activeForm: "Implementing..." })
TaskCreate({ subject: "Test", description: "Write and run tests for the implementation", activeForm: "Testing..." })
TaskCreate({ subject: "Review", description: "Final code review before merge", activeForm: "Reviewing..." })

// Set up sequential dependencies
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })
TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })
TaskUpdate({ taskId: "5", addBlockedBy: ["4"] })

// 2. Spawn workers that claim and complete tasks
Task({
  team_name: "feature-pipeline",
  name: "researcher",
  subagent_type: "compound-engineering:research:best-practices-researcher",
  prompt: "Claim task #1, research best practices, complete it, send findings to team-lead. Then check for more work.",
  run_in_background: true
})

Task({
  team_name: "feature-pipeline",
  name: "implementer",
  subagent_type: "general-purpose",
  prompt: "Poll TaskList every 30 seconds. When task #3 unblocks, claim it and implement. Then complete and notify team-lead.",
  run_in_background: true
})

// Tasks auto-unblock as dependencies complete

パターン 3：スウォーム（自己組織化）

ワーカーがプールから利用可能なタスクを取得します：

// 1. Create team and task pool
Teammate({ operation: "spawnTeam", team_name: "file-review-swarm" })

// Create many independent tasks (no dependencies)
for (const file of ["auth.rb", "user.rb", "api_controller.rb", "payment.rb"]) {
  TaskCreate({
    subject: `Review ${file}`,
    description: `Review ${file} for security and code quality issues`,
    activeForm: `Reviewing ${file}...`
  })
}

// 2. Spawn worker swarm
Task({
  team_name: "file-review-swarm",
  name: "worker-1",
  subagent_type: "general-purpose",
  prompt: `
    You are a swarm worker. Your job:
    1. Call TaskList to see available tasks
    2. Find a task with status 'pending' and no owner
    3. Claim it with TaskUpdate (set owner to your name)
    4. Do the work
    5. Mark it completed with TaskUpdate
    6. Send findings to team-lead via Teammate write
    7. Repeat until no tasks remain
  `,
  run_in_background: true
})

Task({
  team_name: "file-review-swarm",
  name: "worker-2",
  subagent_type: "general-purpose",
  prompt: `[Same prompt as worker-1]`,
  run_in_background: true
})

Task({
  team_name: "file-review-swarm",
  name: "worker-3",
  subagent_type: "general-purpose",
  prompt: `[Same prompt as worker-1]`,
  run_in_background: true
})

// Workers race to claim tasks, naturally load-balance

パターン 4：調査 + 実装

まず調査し、その後に実装します：

// 1. Research phase (synchronous, returns results)
const research = await Task({
  subagent_type: "compound-engineering:research:best-practices-researcher",
  description: "Research caching patterns",
  prompt: "Research best practices for implementing caching in Rails APIs. Include: cache invalidation strategies, Redis vs Memcached, cache key design."
})

// 2. Use research to guide implementation
Task({
  subagent_type: "general-purpose",
  description: "Implement caching",
  prompt: `
    Implement API caching based on this research:

    ${research.content}

    Focus on the user_controller.rb endpoints.
  `
})

パターン 5：計画承認ワークフロー

実装前に計画の承認を必須にします：

// 1. Create team
Teammate({ operation: "spawnTeam", team_name: "careful-work" })

// 2. Spawn architect with plan_mode_required
Task({
  team_name: "careful-work",
  name: "architect",
  subagent_type: "Plan",
  prompt: "Design an implementation plan for adding OAuth2 authentication",
  mode: "plan",  // Requires plan approval
  run_in_background: true
})

// 3. Wait for plan approval request
// You'll receive: {"type": "plan_approval_request", "from": "architect", "requestId": "plan-xxx", ...}

// 4. Review and approve/reject
Teammate({
  operation: "approvePlan",
  target_agent_id: "architect",
  request_id: "plan-xxx"
})
// OR
Teammate({
  operation: "rejectPlan",
  target_agent_id: "architect",
  request_id: "plan-xxx",
  feedback: "Please add rate limiting considerations"
})

パターン 6：連携した複数ファイルのリファクタリング

// 1. Create team for coordinated refactoring
Teammate({ operation: "spawnTeam", team_name: "refactor-auth" })

// 2. Create tasks with clear file boundaries
TaskCreate({
  subject: "Refactor User model",
  description: "Extract authentication methods to AuthenticatableUser concern",
  activeForm: "Refactoring User model..."
})

TaskCreate({
  subject: "Refactor Session controller",
  description: "Update to use new AuthenticatableUser concern",
  activeForm: "Refactoring Sessions..."
})

TaskCreate({
  subject: "Update specs",
  description: "Update all authentication specs for new structure",
  activeForm: "Updating specs..."
})

// Dependencies: specs depend on both refactors completing
TaskUpdate({ taskId: "3", addBlockedBy: ["1", "2"] })

// 3. Spawn workers for each task
Task({
  team_name: "refactor-auth",
  name: "model-worker",
  subagent_type: "general-purpose",
  prompt: "Claim task #1, refactor the User model, complete when done",
  run_in_background: true
})

Task({
  team_name: "refactor-auth",
  name: "controller-worker",
  subagent_type: "general-purpose",
  prompt: "Claim task #2, refactor the Session controller, complete when done",
  run_in_background: true
})

Task({
  team_name: "refactor-auth",
  name: "spec-worker",
  subagent_type: "general-purpose",
  prompt: "Wait for task #3 to unblock (when #1 and #2 complete), then update specs",
  run_in_background: true
})

---

環境変数

起動したチームメイトには、以下が自動的に渡されます：

CLAUDE_CODE_TEAM_NAME="my-project"
CLAUDE_CODE_AGENT_ID="worker-1@my-project"
CLAUDE_CODE_AGENT_NAME="worker-1"
CLAUDE_CODE_AGENT_TYPE="Explore"
CLAUDE_CODE_AGENT_COLOR="#4A90D9"
CLAUDE_CODE_PLAN_MODE_REQUIRED="false"
CLAUDE_CODE_PARENT_SESSION_ID="session-xyz"

プロンプトでの使用方法：

Task({
  team_name: "my-project",
  name: "worker",
  subagent_type: "general-purpose",
  prompt: "Your name is $CLAUDE_CODE_AGENT_NAME. Use it when sending messages to team-lead."
})

---

起動バックエンド

バックエンドは、チームメイトの Claude インスタンスを実際に実行する方法を決定します。Claude Code は 3 つのバックエンドをサポートしており、環境に基づいて最適なものを自動検出します。

バックエンドの比較

バックエンド	仕組み	表示	永続性	速度
in-process	リーダーと同じ Node.js プロセス	非表示（バックグラウンド）	リーダーの終了時に終了	最速
tmux	tmux セッション内の別個のターミナル	tmux 内で表示	リーダー終了後も存続	中
iterm2	iTerm2 ウィンドウ内の分割ペイン	横並びで表示	ウィンドウを閉じると終了	中

自動検出ロジック

Claude Code は、以下の判断ツリーを使ってバックエンドを自動選択します：

flowchart TD
    A[Start] --> B{Running inside tmux?}
    B -->|Yes| C[Use tmux backend]
    B -->|No| D{Running in iTerm2?}
    D -->|No| E{tmux available?}
    E -->|Yes| F[Use tmux - external session]
    E -->|No| G[Use in-process]
    D -->|Yes| H{it2 CLI installed?}
    H -->|Yes| I[Use iterm2 backend]
    H -->|No| J{tmux available?}
    J -->|Yes| K[Use tmux - prompt to install it2]
    J -->|No| L[Error: Install tmux or it2]

検出時の確認項目：

1. $TMUX 環境変数 → tmux 内で実行中
2. $TERM_PROGRAM === "iTerm.app" または $ITERM_SESSION_ID → iTerm2 内で実行中
3. which tmux → tmux が利用可能
4. which it2 → it2 CLI がインストール済み

in-process（tmux 以外でのデフォルト）

チームメイトは同じ Node.js プロセス内で非同期タスクとして実行されます。

仕組み：

• 新しいプロセスは起動されません
• チームメイトは同じ Node.js イベントループを共有します
• メモリ内キューを介して通信します（高速）
• チームメイトの出力は直接確認できません

使用される条件：

• tmux セッション内で実行していない
• 非対話モード（CI、スクリプト）
• CLAUDE_CODE_SPAWN_BACKEND=in-process で明示的に設定されている

特性：

┌─────────────────────────────────────────┐
│           Node.js Process               │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐ │
│  │ Leader  │  │Worker 1 │  │Worker 2 │ │
│  │ (main)  │  │ (async) │  │ (async) │ │
│  └─────────┘  └─────────┘  └─────────┘ │
└─────────────────────────────────────────┘

メリット：

• 起動が最速（プロセスを起動しない）
• オーバーヘッドが最小
• どこでも動作

デメリット：

• チームメイトの出力をリアルタイムで確認できない
• リーダーが終了すると、すべて終了する
• デバッグが難しい

// in-process is automatic when not in tmux
Task({
  team_name: "my-project",
  name: "worker",
  subagent_type: "general-purpose",
  prompt: "...",
  run_in_background: true
})

// Force in-process explicitly
// export CLAUDE_CODE_SPAWN_BACKEND=in-process

tmux

チームメイトは、tmux のペイン／ウィンドウ内で別々の Claude インスタンスとして実行されます。

仕組み：

• チームメイトごとに専用の tmux ペインが割り当てられます
• チームメイトごとに別のプロセスが実行されます
• ペインを切り替えてチームメイトの出力を確認できます
• 受信トレイのファイルを介して通信します

使用される条件：

• tmux セッション内で実行されている（$TMUX が設定されている）
• tmux が利用可能で、iTerm2 内ではない
• CLAUDE_CODE_SPAWN_BACKEND=tmux で明示的に設定されている

レイアウトモード：

1. tmux 内（ネイティブ）： 現在のウィンドウを分割します

┌─────────────────┬─────────────────┐
│                 │    Worker 1     │
│     Leader      ├─────────────────┤
│   (your pane)   │    Worker 2     │
│                 ├─────────────────┤
│                 │    Worker 3     │
└─────────────────┴─────────────────┘

2. tmux 外（外部セッション）： claude-swarm という名前の新しい tmux セッションを作成します

# Your terminal stays as-is
# Workers run in separate tmux session

# View workers:
tmux attach -t claude-swarm

メリット：

• チームメイトの出力をリアルタイムで確認できます
• リーダーの終了後もチームメイトが動作し続けます
• セッションをアタッチ／デタッチできます
• CI／ヘッドレス環境で動作します

デメリット：

• 起動が遅くなります（プロセスの起動）
• tmux のインストールが必要です
• リソースの使用量が増えます

# Start tmux session first
tmux new-session -s claude

# Or force tmux backend
export CLAUDE_CODE_SPAWN_BACKEND=tmux

便利な tmux コマンド：

# List all panes in current window
tmux list-panes

# Switch to pane by number
tmux select-pane -t 1

# Kill a specific pane
tmux kill-pane -t %5

# View swarm session (if external)
tmux attach -t claude-swarm

# Rebalance pane layout
tmux select-layout tiled

iterm2（macOS のみ）

チームメイトは、iTerm2 ウィンドウ内の分割ペインとして実行されます。

仕組み：

• it2 CLI を介して iTerm2 の Python API を使用します
• 現在のウィンドウをペインに分割します
• 各チームメイトを横並びで確認できます
• 受信トレイのファイルを介して通信します

使用される条件：

• iTerm2 内で実行されている（$TERM_PROGRAM === "iTerm.app"）
• it2 CLI がインストールされ、動作している
• iTerm2 の環境設定で Python API が有効になっている

レイアウト：

┌─────────────────┬─────────────────┐
│                 │    Worker 1     │
│     Leader      ├─────────────────┤
│   (your pane)   │    Worker 2     │
│                 ├─────────────────┤
│                 │    Worker 3     │
└─────────────────┴─────────────────┘

メリット：

• 視覚的にデバッグできます。すべてのチームメイトを確認できます
• macOS のネイティブな操作環境です
• tmux は不要です
• ペインを自動的に管理します

デメリット：

• macOS と iTerm2 でのみ利用できます
• セットアップが必要です（it2 CLI と Python API）
• ウィンドウを閉じるとペインも終了します

セットアップ：

# 1. Install it2 CLI
uv tool install it2
# OR
pipx install it2
# OR
pip install --user it2

# 2. Enable Python API in iTerm2
# iTerm2 → Settings → General → Magic → Enable Python API

# 3. Restart iTerm2

# 4. Verify
it2 --version
it2 session list

セットアップに失敗した場合： チームメイトを初めて起動するときに、Claude Code から it2 のセットアップを求められます。次のいずれかを選択できます。

1. it2 を今すぐインストールする（ガイド付きセットアップ）
2. 代わりに tmux を使用する
3. キャンセルする

バックエンドの指定

# Force in-process (fastest, no visibility)
export CLAUDE_CODE_SPAWN_BACKEND=in-process

# Force tmux (visible panes, persistent)
export CLAUDE_CODE_SPAWN_BACKEND=tmux

# Auto-detect (default)
unset CLAUDE_CODE_SPAWN_BACKEND

チーム設定内のバックエンド

バックエンドの種類は、config.json にチームメイトごとに記録されます。

{
  "members": [
    {
      "name": "worker-1",
      "backendType": "in-process",
      "tmuxPaneId": "in-process"
    },
    {
      "name": "worker-2",
      "backendType": "tmux",
      "tmuxPaneId": "%5"
    }
  ]
}

バックエンドのトラブルシューティング

問題	原因	解決策
"No pane backend available"	tmux も iTerm2 も利用できない	tmux をインストールします：brew install tmux
"it2 CLI not installed"	iTerm2 内にいますが、it2 がありません	uv tool install it2 を実行します
"Python API not enabled"	it2 が iTerm2 と通信できない	iTerm2 の「Settings」→「General」→「Magic」で有効にします
ワーカーが表示されない	インプロセスバックエンドを使用している	tmux または iTerm2 内で起動します
ワーカーが予期せず終了する	tmux の外でリーダーが終了した	永続化には tmux を使用します

現在のバックエンドの確認

# See what backend was detected
cat ~/.claude/teams/{team}/config.json | jq '.members[].backendType'

# Check if inside tmux
echo $TMUX

# Check if in iTerm2
echo $TERM_PROGRAM

# Check tmux availability
which tmux

# Check it2 availability
which it2

---

エラー処理

よくあるエラー

エラー	原因	解決策
"Cannot cleanup with active members"	チームメイトがまだ実行中	まずすべてのチームメイトに requestShutdown を呼び出し、承認を待ちます
"Already leading a team"	チームがすでに存在する	先に cleanup を実行するか、別のチーム名を使用します
"Agent not found"	チームメイトの名前が間違っている	実際の名前は config.json で確認します
"Team does not exist"	チームが作成されていない	先に spawnTeam を呼び出します
"team_name is required"	チームのコンテキストが不足している	team_name パラメーターを指定します
"Agent type not found"	subagent_type が無効	適切なプレフィックスを付けて利用可能なエージェントを確認します

グレースフルシャットダウンの手順

必ず次の手順に従ってください：

// 1. Request shutdown for all teammates
Teammate({ operation: "requestShutdown", target_agent_id: "worker-1" })
Teammate({ operation: "requestShutdown", target_agent_id: "worker-2" })

// 2. Wait for shutdown approvals
// Check for {"type": "shutdown_approved", ...} messages

// 3. Verify no active members
// Read ~/.claude/teams/{team}/config.json

// 4. Only then cleanup
Teammate({ operation: "cleanup" })

クラッシュしたチームメイトへの対処

チームメイトのハートビートタイムアウトは 5 分です。チームメイトがクラッシュした場合：

1. タイムアウト後、自動的に非アクティブとしてマークされます
2. そのタスクはタスクリストに残ります
3. 別のチームメイトがそのタスクを引き継げます
4. タイムアウトの経過後、クリーンアップが可能になります

デバッグ

# Check team config
cat ~/.claude/teams/{team}/config.json | jq '.members[] | {name, agentType, backendType}'

# Check teammate inboxes
cat ~/.claude/teams/{team}/inboxes/{agent}.json | jq '.'

# List all teams
ls ~/.claude/teams/

# Check task states
cat ~/.claude/tasks/{team}/*.json | jq '{id, subject, status, owner, blockedBy}'

# Watch for new messages
tail -f ~/.claude/teams/{team}/inboxes/team-lead.json

---

ワークフロー全体

ワークフロー 1：専門家が並行して行う完全なコードレビュー

// === STEP 1: Setup ===
Teammate({ operation: "spawnTeam", team_name: "pr-review-123", description: "Reviewing PR #123" })

// === STEP 2: Spawn reviewers in parallel ===
// (Send all these in a single message for parallel execution)
Task({
  team_name: "pr-review-123",
  name: "security",
  subagent_type: "compound-engineering:review:security-sentinel",
  prompt: `Review PR #123 for security vulnerabilities.

  Focus on:
  - SQL injection
  - XSS vulnerabilities
  - Authentication/authorization bypass
  - Sensitive data exposure

  When done, send your findings to team-lead using:
  Teammate({ operation: "write", target_agent_id: "team-lead", value: "Your findings here" })`,
  run_in_background: true
})

Task({
  team_name: "pr-review-123",
  name: "perf",
  subagent_type: "compound-engineering:review:performance-oracle",
  prompt: `Review PR #123 for performance issues.

  Focus on:
  - N+1 queries
  - Missing indexes
  - Memory leaks
  - Inefficient algorithms

  Send findings to team-lead when done.`,
  run_in_background: true
})

Task({
  team_name: "pr-review-123",
  name: "arch",
  subagent_type: "compound-engineering:review:architecture-strategist",
  prompt: `Review PR #123 for architectural concerns.

  Focus on:
  - Design pattern adherence
  - SOLID principles
  - Separation of concerns
  - Testability

  Send findings to team-lead when done.`,
  run_in_background: true
})

// === STEP 3: Monitor and collect results ===
// Poll inbox or wait for idle notifications
// cat ~/.claude/teams/pr-review-123/inboxes/team-lead.json

// === STEP 4: Synthesize findings ===
// Combine all reviewer findings into a cohesive report

// === STEP 5: Cleanup ===
Teammate({ operation: "requestShutdown", target_agent_id: "security" })
Teammate({ operation: "requestShutdown", target_agent_id: "perf" })
Teammate({ operation: "requestShutdown", target_agent_id: "arch" })
// Wait for approvals...
Teammate({ operation: "cleanup" })

ワークフロー 2：調査 → 計画 → 実装 → テストのパイプライン

// === SETUP ===
Teammate({ operation: "spawnTeam", team_name: "feature-oauth" })

// === CREATE PIPELINE ===
TaskCreate({ subject: "Research OAuth providers", description: "Research OAuth2 best practices and compare providers (Google, GitHub, Auth0)", activeForm: "Researching OAuth..." })
TaskCreate({ subject: "Create implementation plan", description: "Design OAuth implementation based on research findings", activeForm: "Planning..." })
TaskCreate({ subject: "Implement OAuth", description: "Implement OAuth2 authentication according to plan", activeForm: "Implementing OAuth..." })
TaskCreate({ subject: "Write tests", description: "Write comprehensive tests for OAuth implementation", activeForm: "Writing tests..." })
TaskCreate({ subject: "Final review", description: "Review complete implementation for security and quality", activeForm: "Final review..." })

// Set dependencies
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })
TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })
TaskUpdate({ taskId: "5", addBlockedBy: ["4"] })

// === SPAWN SPECIALIZED WORKERS ===
Task({
  team_name: "feature-oauth",
  name: "researcher",
  subagent_type: "compound-engineering:research:best-practices-researcher",
  prompt: "Claim task #1. Research OAuth2 best practices, compare providers, document findings. Mark task complete and send summary to team-lead.",
  run_in_background: true
})

Task({
  team_name: "feature-oauth",
  name: "planner",
  subagent_type: "Plan",
  prompt: "Wait for task #2 to unblock. Read research from task #1. Create detailed implementation plan. Mark complete and send plan to team-lead.",
  run_in_background: true
})

Task({
  team_name: "feature-oauth",
  name: "implementer",
  subagent_type: "general-purpose",
  prompt: "Wait for task #3 to unblock. Read plan from task #2. Implement OAuth2 authentication. Mark complete when done.",
  run_in_background: true
})

Task({
  team_name: "feature-oauth",
  name: "tester",
  subagent_type: "general-purpose",
  prompt: "Wait for task #4 to unblock. Write comprehensive tests for the OAuth implementation. Run tests. Mark complete with results.",
  run_in_background: true
})

Task({
  team_name: "feature-oauth",
  name: "reviewer",
  subagent_type: "compound-engineering:review:security-sentinel",
  prompt: "Wait for task #5 to unblock. Review the complete OAuth implementation for security. Send final assessment to team-lead.",
  run_in_background: true
})

// Pipeline auto-progresses as each stage completes

ワークフロー 3：自己編成型コードレビューのスウォーム

// === SETUP ===
Teammate({ operation: "spawnTeam", team_name: "codebase-review" })

// === CREATE TASK POOL (all independent, no dependencies) ===
const filesToReview = [
  "app/models/user.rb",
  "app/models/payment.rb",
  "app/controllers/api/v1/users_controller.rb",
  "app/controllers/api/v1/payments_controller.rb",
  "app/services/payment_processor.rb",
  "app/services/notification_service.rb",
  "lib/encryption_helper.rb"
]

for (const file of filesToReview) {
  TaskCreate({
    subject: `Review ${file}`,
    description: `Review ${file} for security vulnerabilities, code quality, and performance issues`,
    activeForm: `Reviewing ${file}...`
  })
}

// === SPAWN WORKER SWARM ===
const swarmPrompt = `
You are a swarm worker. Your job is to continuously process available tasks.

LOOP:
1. Call TaskList() to see available tasks
2. Find a task that is:
   - status: 'pending'
   - no owner
   - not blocked
3. If found:
   - Claim it: TaskUpdate({ taskId: "X", owner: "YOUR_NAME" })
   - Start it: TaskUpdate({ taskId: "X", status: "in_progress" })
   - Do the review work
   - Complete it: TaskUpdate({ taskId: "X", status: "completed" })
   - Send findings to team-lead via Teammate write
   - Go back to step 1
4. If no tasks available:
   - Send idle notification to team-lead
   - Wait 30 seconds
   - Try again (up to 3 times)
   - If still no tasks, exit

Replace YOUR_NAME with your actual agent name from $CLAUDE_CODE_AGENT_NAME.
`

// Spawn 3 workers
Task({ team_name: "codebase-review", name: "worker-1", subagent_type: "general-purpose", prompt: swarmPrompt, run_in_background: true })
Task({ team_name: "codebase-review", name: "worker-2", subagent_type: "general-purpose", prompt: swarmPrompt, run_in_background: true })
Task({ team_name: "codebase-review", name: "worker-3", subagent_type: "general-purpose", prompt: swarmPrompt, run_in_background: true })

// Workers self-organize: race to claim tasks, naturally load-balance
// Monitor progress with TaskList() or by reading inbox

---

ベストプラクティス

1. 必ずクリーンアップする

孤立したチームを残さないでください。作業が終わったら、必ず cleanup を呼び出してください。

2. 意味のある名前を使う

// Good
name: "security-reviewer"
name: "oauth-implementer"
name: "test-writer"

// Bad
name: "worker-1"
name: "agent-2"

3. 明確なプロンプトを書く

ワーカーに何をすべきかを正確に伝えます。

// Good
prompt: `
  1. Review app/models/user.rb for N+1 queries
  2. Check all ActiveRecord associations have proper includes
  3. Document any issues found
  4. Send findings to team-lead via Teammate write
`

// Bad
prompt: "Review the code"

4. タスクの依存関係を使う

ブロックの解除はシステムに任せます。

// Good: Auto-unblocking
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })

// Bad: Manual polling
"Wait until task #1 is done, check every 30 seconds..."

5. 結果を確認するために受信箱をチェックする

ワーカーは受信箱に結果を送ります。受信箱を確認します。

cat ~/.claude/teams/{team}/inboxes/team-lead.json | jq '.'

6. ワーカーの失敗に対処する

• ワーカーのハートビートタイムアウトは5分です
• クラッシュしたワーカーのタスクは再取得できます
• ワーカーへのプロンプトに再試行ロジックを組み込みます

7. broadcastよりwriteを優先する

broadcastはチームメイトがN人の場合、N件のメッセージを送信します。特定の相手に連絡するにはwriteを使います。

8. タスクに合ったエージェントタイプを選ぶ

• 検索や読み取りにはExplore
• アーキテクチャの設計にはPlan
• 実装にはgeneral-purpose
• 特定の種類のレビューにはSpecialized reviewers

---

クイックリファレンス

サブエージェントを起動する（チームなし）

Task({ subagent_type: "Explore", description: "Find files", prompt: "..." })

チームメイトを起動する（チームあり）

Teammate({ operation: "spawnTeam", team_name: "my-team" })
Task({ team_name: "my-team", name: "worker", subagent_type: "general-purpose", prompt: "...", run_in_background: true })

チームメイトにメッセージを送る

Teammate({ operation: "write", target_agent_id: "worker-1", value: "..." })

タスクパイプラインを作成する

TaskCreate({ subject: "Step 1", description: "..." })
TaskCreate({ subject: "Step 2", description: "..." })
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })

チームをシャットダウンする

Teammate({ operation: "requestShutdown", target_agent_id: "worker-1" })
// Wait for approval...
Teammate({ operation: "cleanup" })

---

Claude Code v2.1.19に基づく — 2026-01-25にテストおよび検証済み