agent-teams

エージェントチームの連携

概要

Claude Code Agent Teams を使用すると、複数の Claude CLI プロセスがファイルシステムベースの連携プロトコルを通じて、共有作業を協調して進められます。各チームメンバーは tmux のペインで独立した claude プロセスとして実行され、データベース、デーモン、ネットワーク層を介さず、fcntl ロックで保護された JSON ファイルを通じて通信します。

このスキルでは、エージェントチームを効果的にオーケストレーションするためのパターンを紹介します。

使用する場面

• 複数のファイルやモジュールにまたがる並列実装
• 複数エージェントによるコードレビュー（1 つのエージェントがレビューし、別のエージェントが修正を実装する）
• サブシステムをまたいで調整が必要な大規模リファクタリング
• 並列性があり、エージェントの同時実行が有効なタスク

使用しない場面

• 単一ファイルの変更や小規模なタスク（オーバーヘッドがメリットを上回る場合）
• 厳密に逐次的な推論が必要なタスク（エージェント間の連携は緩やかなため）
• claude CLI を利用できない場合、または tmux がインストールされていない場合

前提条件

# Verify Claude Code CLI
claude --version

# Verify tmux (required for split-pane mode)
tmux -V

# Enable experimental feature (set by spawner automatically)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

プロトコルのアーキテクチャ

~/.claude/
  teams/<team-name>/
    config.json            # Team metadata + member roster
    inboxes/
      <agent-name>.json    # Per-agent message queue
      .lock                # fcntl exclusive lock
  tasks/<team-name>/
    1.json ... N.json      # Auto-incrementing task files
    .lock                  # fcntl exclusive lock

設計原則：

• ファイルシステムをデータベースとして使用：JSON ファイルと、tempfile + os.replace によるアトミックな書き込み
• fcntl ロック：受信箱とタスクでの同時読み書きによる破損を防止
• 番号付きタスク：自動採番 ID と連番のファイル名
• 疎結合：エージェントはそれぞれの受信箱をポーリングし、プッシュ通知は行わない

クイックスタート

1. チームを作成する

# Programmatic team setup (via MCP or direct API)
# Team config written to ~/.claude/teams/<team-name>/config.json

チーム設定には次の情報が含まれます。

• name、description、created_at（ミリ秒単位のタイムスタンプ）
• lead_agent_id、lead_session_id
• members[]：LeadMember オブジェクトと TeammateMember オブジェクトの配列

2. チームメンバーを起動する

各チームメンバーは、ID フラグを付けて起動する個別の claude CLI プロセスです。

claude --agent-id "backend@my-team" \
       --agent-name "backend" \
       --team-name "my-team" \
       --agent-color "#FF6B6B" \
       --parent-session-id "$SESSION_ID" \
       --agent-type "general-purpose" \
       --model sonnet

tmux ペインの管理と色の割り当てについては、modules/spawning-patterns.md を参照してください。

3. 依存関係を設定してタスクを作成する

{
  "id": "1",
  "subject": "Implement API endpoints",
  "description": "Create REST endpoints for user management",
  "status": "pending",
  "owner": null,
  "blocks": ["3"],
  "blocked_by": [],
  "metadata": {}
}

状態マシンと依存関係の管理については、modules/task-coordination.md を参照してください。

4. メッセージで連携する

{
  "from": "team-lead",
  "text": "API endpoints are ready for integration testing",
  "timestamp": "2026-02-07T22:00:00Z",
  "read": false,
  "summary": "API ready"
}

メッセージの種類と受信箱の操作については、modules/messaging-protocol.md を参照してください。

連携ワークフロー

1. agent-teams:team-created：チーム設定とディレクトリを初期化する
2. agent-teams:teammates-spawned：tmux ペインでエージェントを起動する
3. agent-teams:tasks-assigned：依存関係を設定してタスクを作成し、担当者を割り当てる
4. agent-teams:coordination-active：エージェントがタスクを引き受け、メッセージをやり取りし、完了を記録する
5. agent-teams:team-shutdown：承認プロトコルに従って正常にシャットダウンする

チームメンバーの役割

各チームメンバーには、その能力とタスクとの適合性を決定する role があります。役割は 5 種類です。implementer（デフォルト）、researcher、tester、reviewer、architect です。役割によって、エージェントが対応できるリスクレベルが制限されます。能力マトリックスと役割・リスクの適合表については、modules/crew-roles.md を参照してください。

チーム編成

ミッション単位でのチーム規模の決定には、references/team-formation.md のチーム編成ルールを使用してください。以下を定義しています。

• 役割の定義：Coordinator（ミッションリード）、Agents（タスク担当者）、Reviewer（批判的な立場で検証する担当者）
• チーム規模のルール：Simple（1）、Moderate（2-4）、Complex（5-7）、Critical（5-10）
• チームの最大規模：エージェント 10 人（連携オーバーヘッドの上限）
• ファイルの所有権ルール：明確な所有権を定めて競合を防止

チーム規模の決め方とチーム編成例の詳細については、references/team-formation.md を参照してください。

ヘルスモニタリング

チームメンバーのヘルスは、ハートビートメッセージとタスク引き受けの期限切れによって監視できます。リードは 60 秒ごとに、2 段階の停止検出プロトコル（health_check プローブと 30 秒の待機）でチームのヘルスを確認します。停止したエージェントのタスクは解放され、「待たずに交代する」という原則に従って、エージェントを再起動または交代します。プロトコルと状態マシンの詳細については、modules/health-monitoring.md を参照してください。

モジュールリファレンス

• team-management.md：チームのライフサイクル、設定形式、メンバー管理
• messaging-protocol.md：メッセージの種類、受信トレイの操作、ロックパターン
• task-coordination.md：タスクの CRUD、状態遷移、依存関係の循環検出
• spawning-patterns.md：tmux での起動、CLI フラグ、ペイン管理
• crew-roles.md：役割の分類、機能マトリックス、役割とリスクの適合性
• health-monitoring.md：ハートビートプロトコル、停滞の検出、自動復旧

Conjure との統合

Agent Teams は Conjure の委任モデルを拡張します。

Conjure のパターン	Agent Teams での相当機能
delegation-core:task-assessed	agent-teams:team-created
delegation-core:handoff-planned	agent-teams:tasks-assigned
delegation-core:results-integrated	agent-teams:team-shutdown
外部 LLM の実行	チームメイトエージェントの実行

まず Skill(conjure:delegation-core) を使用して、タスクが単一サービスへの委任よりもマルチエージェント連携に適しているかを判断します。

ここでは委任がデフォルトで有効なため、チーム形成で判断するのは、委任するかどうかではなく、どの形の委任が適切かです。実行作業を担当するチームメイトは、単一セッションと同じ方法で作業を委任します。設計作業を担当するチームメイトは、同じ Keep Local 条項に従って、その作業を自分で行います。

チームメイトによる委任で fallback_reason が返された場合、そのチームメイトが自分で作業し、試したプロバイダーを報告します。再割り当てを求めてクルーにメッセージを送ることはありません。レジストリはマシン全体で共有されているため、ほかのチームメイトがこのチームメイトにはないプロバイダーを持っていることはないからです。

Worktree による分離の代替手段（Claude Code 2.1.49+）

ファイルを変更する並列エージェントには、isolation: worktree が、ファイルシステムベースの調整に代わる軽量な手段を提供します。各エージェントは一時的な独自の git worktree で実行されるため、共有ファイルでの fcntl ロックや受信トレイを使った競合回避が不要になります。

• エージェントチームのメッセージングより worktree を優先する場合：エージェントが重複するファイルを扱うものの、実行中の相互通信は必要としない場合
• worktree よりエージェントチームのメッセージングを優先する場合：エージェント同士で発見事項を共有したり、互いの進捗に応じて計画を調整したりする必要がある場合
• 両方を組み合わせる場合：調整にはエージェントチームを使い、ファイルシステムの安全性を確保するために、各チームメイトに isolation: worktree を設定します

トラブルシューティング

よくある問題

tmux が見つからない パッケージマネージャーからインストールします：brew install tmux / apt install tmux

古いロックファイル エージェントが操作の途中でクラッシュすると、ロックファイルが残る場合があります。~/.claude/teams/<team>/inboxes/ または ~/.claude/tasks/<team>/ から .lock ファイルを手動で削除してください。

孤立したタスク クラッシュしたエージェントが取得したタスクは、in_progress のままいつまでも残ります。ハートビートによる停滞の検出とタスクの自動解放には、modules/health-monitoring.md を使用してください。ヘルスモニタリングプロトコルは、応答のないエージェントを 60 秒以内に検出し、30 秒のプローブ時間を経て、そのエージェントのタスクを再割り当てできるよう解放します。

メッセージの順序 ファイルシステムのタイムスタンプの精度は環境によって異なります（HFS+ は 1 秒単位です）。短時間に大量のメッセージが送信された際の衝突を避けるには、番号付きファイル名または UUID 順の名前を使用してください。

Bedrock／Vertex／Foundry でのモデルエラー（2.1.39 より前） チームメイトエージェントがエンタープライズプロバイダーで誤ったモデル識別子を使用し、400 エラーが発生する場合がありました。すべてのプロバイダーでモデル ID が正しく修飾されるよう、Claude Code 2.1.39 以降にアップグレードしてください。

ネストされたセッションのガード（2.1.39 以降） 既存のセッション内で claude の起動が拒否される場合は、 サブシェルから起動するのではなく、tmux のペイン分割を使用していることを確認してください。このガードは意図的なものです。詳細は modules/spawning-patterns.md を参照してください。

完了条件

• 設定とディレクトリを含むチームが作成されている
• チームメイトが起動され、設定に登録されている
• 依存関係グラフを含むタスクが作成されている（循環なし）
• エージェントが受信トレイのメッセージを介して連携している
• 正常なシャットダウンが完了している