swarm-coordination

スウォーム調整

複数のエージェントによる開発を一貫性のある、競合のないものにするためのプロトコルとパターン。同じコードベースで他の Claude Code エージェントと作業する際は、以下のガイドラインに従ってください。

基本原則

1. 2 階層のタスク追跡：永続的な作業項目は GitHub Issues（またはコミット済みの ISSUES.md）で管理し、進行中の作業はオーケストレーターのネイティブなタスクリスト（TaskCreate/TaskUpdate/TaskList）で管理します
2. ファイルロック：フックがファイルロックを自動的に管理します。ロックを尊重してください
3. セッションの分離：追跡用に各エージェントに一意のセッション ID を割り当てます
4. 明確な引き継ぎ：別のエージェントが作業を続けられるよう、状態と成果物への参照を必ず残してください

2 階層のタスク追跡

• 階層 1 — 永続的な記録：GitHub Issues（トラッカーのないリポジトリでは ISSUES.md）に、作業項目の恒久的な履歴、つまり依頼内容、理由、最終的な処理内容を記録します。
• 階層 2 — 進行中の作業：オーケストレーターがネイティブなタスクリスト（TaskCreate/TaskUpdate/TaskList）を管理します。作業項目ごとにタスクを 1 つ作成し、それぞれに明確な受け入れ基準を設定します。ワーカーは独自のタスクリストを管理しません（共有状態を禁止するルールについては .claude/rules/agent-constraints.md を参照してください）。
• 引き継ぎ：Core Directives §7「コマンドプロトコルに従う」を参照してください。すべての引き継ぎに、検証可能な成果物への参照が必要です。

ファイルベースの出力

ワーカーはコンテキストに直接書き込まず、結果を scratchpad/<task-id>.md に書き込みます。artifacts/ に保存するのは、ADR、計画書、PRD などの永続的な成果物のみです。オーケストレーターはワーカーを起動する前に出力先を作成し、ワーカーは割り当てられたファイルに書き込みます。その後、オーケストレーターが内容を読み、統合します。

ワークフロー

作業の開始

• タスクリストを確認する：オーケストレーターは、ブロックされておらず未割り当ての項目がないか TaskList を確認します
• タスクを作成する：作業項目ごとにタスクを 1 つ作成し、それぞれに明確な受け入れ基準を設定します
• 競合を確認する：最近の編集内容について .claude/hooks/.file-tracker.log を確認します
• 割り当てる：ワーカーに、焦点を絞った自己完結型のプロンプトを送ります（agent-constraints.md を参照）

作業中

• 変更をアトミックに保つ：壊れた状態を残さない、小さく完結した変更を行います
• こまめにコミットする：マージ競合を減らすため、頻繁にコミットします
• タスクの状態を更新する：ワーカーから報告を受けたら、オーケストレーターが TaskUpdate を更新します
• ロックを尊重する：ファイルがロックされている場合は、解除を待つか、別の作業に取り組みます

作業の完了

• テストを実行する：変更によって既存の機能が壊れていないことを確認します
• タスクを完了にする：オーケストレーターは結果を添えて、ネイティブなタスクリストでタスクを完了にします
• 永続的な記録を更新する：完了したことを GitHub Issue / ISSUES.md に反映します
• 状態を整理する：すべての変更をコミットし、未コミットの作業を残しません

競合の防止

ファイルロックプロトコル

フックがロックを自動的に取得・解放します。ロックに遭遇した場合：

# Check who holds the lock
cat .claude/hooks/.locks/<filename>.lock

# Lock automatically expires after 60 seconds
# If urgent, wait or pick a different task from the task list

マージ競合への対処方針

1. こまめにプルする：ブランチを最新の状態に保ちます
2. 小規模な PR：大規模な変更よりもマージしやすくなります
3. 調整する：編集を始める前に、オーケストレーターのタスクリストでタスク（および関連ファイル）を担当します
4. 速やかに解決する：競合を検出したら、直ちに対処します

コミュニケーションのパターン

引き継ぎメッセージ

未完了の作業を残してセッションを終了する場合は、具体的な成果物を参照する引き継ぎを残します。

echo '{"message": "Continue implementing auth middleware. Tests passing but needs error handling in src/auth.ts:45", "artifact": "artifacts/plan_auth_middleware.md"}' > .claude/hooks/.state/handoff.json

マルチエージェントのパターン

オーケストレーター／ワーカーパターン

複雑なタスクでは、1 つのエージェントがオーケストレーションを行い、他のエージェントが実行します。

1. オーケストレーター：計画を立て、ネイティブなタスクリストで作業をタスクに分解し、ワーカーに割り当てます
2. ワーカー：焦点を絞ったプロンプトを受け取り、実装して結果を返します（ワーカー間で状態を共有しません。詳しくは agent-constraints.md を参照してください）
3. 同期ポイント：オーケストレーターがすべてのワーカーの結果を集め、最終的な統合の前に整合性を取ります

並列ストリーム

独立した機能を並行して開発する場合：

1. ストリームごとに、受け入れ基準を設定した個別のタスクを作成します
2. 各ワーカーは、割り当てられたタスクを通じて 1 つのストリームを担当します
3. ストリーム間で同じファイルを編集しないようにします
4. 定められた統合ポイントでストリームをマージします

予算とウェーブ

コストのサーキットブレーカーのみ：これは、後から過剰な支出を制限するものです。ステップの繰り返しやループは検出しません。これは別の障害モードであり、ここでは対象外です。

• オーケストレーターは、ワーカーのバッチをディスパッチする際にトークン数／ウェーブ数の上限を指定します。起動後ではなく、起動前に上限を設定してください
• 上限に達した場合：ディスパッチを停止し、これまでの支出額と残りの作業を報告して、続行前にユーザーに確認します
• ディスパッチするタスクのタイトルには [Wave N/M] のプレフィックスを付けます（例：[Wave 1/3] Explore auth patterns）。これにより、支出と進捗をひと目でウェーブに紐付けられます

状態ファイル

ファイル	用途
.claude/hooks/.state/session_*.json	アクティブなエージェントのセッション
.claude/hooks/.state/handoff.json	セッション間の引き継ぎメッセージ
.claude/hooks/.locks/*.lock	ファイル編集ロック
.claude/hooks/.file-tracker.log	最近のファイル変更

ベストプラクティス

1. 編集前に確認：対象ファイルにアクティブなロックがないことを必ず確認してください
2. 作業単位を完了：切り替える前に、論理的な作業単位を完了してください
3. 意図を記録：タスクリストを使って、取り組む作業とその受け入れ基準を宣言してください
4. ローカルでテスト：問題を早期に発見するため、プッシュ前にテストを実行してください
5. こまめに同期：タスクリスト、永続的な課題、Git を他のエージェントと同期した状態に保ってください

緊急時の手順

デッドロックの検出

エージェント同士が互いの完了を待っている場合：

# Check active sessions
ls -la .claude/hooks/.state/session_*.json

# Check active locks
ls -la .claude/hooks/.locks/

# Force release stale locks (use with caution)
find .claude/hooks/.locks -mmin +5 -delete

競合からの復旧

1. 現在の作業を新しいブランチに保存します
2. main と同期します：git fetch && git rebase origin/main
3. ファイルごとに競合を解決します
4. 現在の状態を反映するように、ネイティブのタスクリストと永続的な課題の記録を更新します
5. 作業を続けます