目次
エージェントチーム調整
概要
Claude Code Agent Teams は、ファイルシステムベースの調整プロトコルを通じて、複数のClaude CLIプロセスが共有作業に協力できるようにします。各チームメンバーは tmux ペイン内で独立した claude プロセスとして実行され、fcntl ロックで保護されたJSONファイルを介して通信します。データベース、デーモン、ネットワーク層は不要です。
このスキルは、エージェントチームを効果的に調整するためのパターンを提供します。
使用するタイミング
- 複数のファイルやモジュールにわたる並行実装
- マルチエージェントコードレビュー(あるエージェントがレビューし、別のエージェントが修正を実装)
- サブシステム間での調整が必要な大規模リファクタリング
- 並行エージェントの恩恵を受けられる自然な並列性を持つタスク
使用しないタイミング
- 単一ファイルの変更や小規模タスク(オーバーヘッドがメリットを上回る)
- 密な逐次推論が必要なタスク(エージェントは緩く調整される)
claudeCLIが利用できない、または tmux がインストールされていない場合
前提条件
# Claude Code CLIの確認
claude --version
# tmuxの確認(分割ペインモードに必要)
tmux -V
# 実験的機能の有効化(スポナーによって自動設定)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
プロトコルアーキテクチャ
~/.claude/
teams/<team-name>/
config.json # チームメタデータ + メンバー名簿
inboxes/
<agent-name>.json # エージェントごとのメッセージキュー
.lock # fcntl 排他ロック
tasks/<team-name>/
1.json ... N.json # 自動インクリメントのタスクファイル
.lock # fcntl 排他ロック
設計原則:
- ファイルシステムがデータベース: JSONファイル、
tempfile+os.replaceによるアトミック書き込み - fcntl ロック: インボックスとタスクへの同時読み取り/書き込みの破損を防止
- 番号付きタスク: 連続したファイル命名による自動インクリメントID
- 疎結合: エージェントは自身のインボックスをポーリングし、プッシュ通知はなし
クイックスタート
1. チームを作成する
# プログラムによるチームセットアップ(MCPまたは直接API経由)
# チーム設定は ~/.claude/teams/<team-name>/config.json に書き込まれます
チーム設定には以下が含まれます:
name,description,created_at(ミリ秒タイムスタンプ)lead_agent_id,lead_session_idmembers[]— 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": "APIエンドポイントの実装",
"description": "ユーザー管理用のRESTエンドポイントを作成する",
"status": "pending",
"owner": null,
"blocks": ["3"],
"blocked_by": [],
"metadata": {}
}
ステートマシンと依存関係管理については modules/task-coordination.md を参照してください。
4. メッセージで調整する
{
"from": "team-lead",
"text": "APIエンドポイントの準備ができました。統合テストの準備をしてください。",
"timestamp": "2026-02-07T22:00:00Z",
"read": false,
"summary": "API準備完了"
}
メッセージタイプとインボックス操作については modules/messaging-protocol.md を参照してください。
調整ワークフロー
agent-teams:team-created— チーム設定とディレクトリを初期化agent-teams:teammates-spawned— tmux ペインでエージェントを起動agent-teams:tasks-assigned— 依存関係を持つタスクを作成し、所有者を割り当てagent-teams:coordination-active— エージェントがタスクを要求し、メッセージを交換し、完了をマークagent-teams:team-shutdown— 承認プロトコルによるグレースフルシャットダウン
クルーロール
各チームメンバーには、その能力とタスクの互換性を決定する role があります。5つのロールが定義されています: implementer(デフォルト)、researcher、tester、reviewer、architect。ロールはエージェントが処理できるリスク階層を制限します。完全な能力マトリックスとロール-リスク互換性テーブルについては modules/crew-roles.md を参照してください。
健全性監視
チームメンバーの健全性は、ハートビートメッセージと要求期限を通じて監視できます。リーダーは60秒ごとにチームの健全性をポーリングし、2段階のストール検出プロトコル(health_check プローブ + 30秒待機)を実行します。ストールしたエージェントのタスクは解放され、「待つよりも置き換える」 doctrine に従って再起動または置き換えられます。完全なプロトコルとステートマシンについては 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) を使用して、タスクがマルチエージェント調整とシングルサービス委譲のどちらに適しているかを判断します。
ワークツリー分離の代替案 (Claude Code 2.1.49+)
ファイルを変更する並行エージェントの場合、isolation: worktree はファイルシステムベースの調整に代わる軽量な選択肢を提供します。各エージェントは自身の一時的な git ワークツリーで実行されるため、共有ファイルに対する fcntl ロックやインボックスベースの競合回避が不要になります。
- エージェントチームのメッセージングよりもワークツリーを優先する場合: エージェントが重複するファイルで作業するが、実行途中の通信は不要な場合
- エージェントチームのメッセージングを優先する場合: エージェントが互いの進捗に基づいて発見事項を調整したり計画を変更したりする必要がある場合
- 両方を組み合わせる: 調整にはエージェントチームを、ファイルシステムの安全性には
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 を参照してください。
終了条件
- 設定とディレクトリを持つチームが作成された
- チームメイトがスポーンされ、設定に登録された
- 依存関係グラフ(サイクルなし)を持つタスクが作成された
- エージェントがインボックスメッセージを介して調整している
- グレースフルシャットダウンが完了した