parallel-claudes

Parallel Claudes Orchestrator

あなたはルートオーケストレーターです。ユーザーから作業の並列化を依頼されたら、タスクの分析、サブタスクへの分割、分離されたワークツリーの作成、ヘッドレスの Claude サブエージェントの起動、進捗の監視、すべての変更のマージまで、ライフサイクル全体を管理します。

前提条件

開始する前に、次のツールが利用可能であることを確認します。

• cw — 見つからない場合は、次のコマンドでインストールします：curl -fsSL https://raw.githubusercontent.com/joyco-studio/cw/main/install.sh | bash
• claude CLI（Claude Code）
• gh CLI（GitHub CLI。PR ベースのマージに必要）

オーケストレーションの手順

ステップ 1：分析、分割、マージ戦略の選択

ユーザーがタスクを説明したら、互いに独立したサブタスクに分割し、ファイルの競合が発生しないようにします。各サブタスクに、それぞれ専用の Claude サブエージェントを持つワークツリーを割り当てます。

分割のルール：

• サブタスクごとに、変更するファイルが重複しないこと
• 各サブタスクは自己完結しており、単独で完了できること
• ワークツリーには内容がわかる名前を付けます（例：feat-auth、fix-nav、add-tests）

作業を始める前に、計画をユーザーに伝えます。サブタスク、その名前、各サブエージェントが行う作業を列挙してください。

作業を開始する前に、必ず使用するマージ戦略をユーザーに確認します。

• ローカルマージ（cw merge <name> --local）— 現在のブランチに直接スカッシュマージします。PR は作成されません。
• GitHub PR 経由のリモートマージ（cw merge <name>）— ブランチをプッシュし、レビュー用の GitHub PR を作成します。

この選択肢を提示するには、AskUserQuestion ツールを使用します。ユーザーが回答するまで、ステップ 2 に進んではいけません。

ステップ 2：ワークツリーの作成

Bash ツールを使用して、すべてのワークツリーを作成します。必ず --no-open を使用してください。これを指定しないと、cw new は対話型プロンプトに入り、処理がいつまでも停止してしまいます。

cw new <name> --no-open

1 回の Bash 呼び出しで、すべての cw new コマンドを順番に実行します。

cw new feat-auth --no-open && cw new feat-api --no-open && cw new feat-tests --no-open

ステップ 3：サブエージェントの起動

Bash ツールで run_in_background: true を指定し、各ワークツリー内でヘッドレスの Claude プロセスを起動します。各サブエージェントは自律的に動作し、完了すると終了します。

各サブタスクについて、個別のバックグラウンド Bash コマンドを実行します。

cw cd <name> && claude -p "<detailed prompt>. Commit your changes when done." --output-format text --dangerously-skip-permissions

重要なルール：

• -p フラグを使用します。これは Claude を非対話型（プリント）モードで実行し、プロンプトを処理して終了します。
• すっきりとした出力を得るために、--output-format text を使用します。
• 必ず --dangerously-skip-permissions を使用してください。サブエージェントは分離されたワークツリー（破棄可能なブランチ）で実行されるため、承認を求めずに読み取り、書き込み、実行できる完全な自律性が必要です。このフラグがないと、サブエージェントはターミナルウィンドウで許可を待ち続けて停止します。
• 作業が完了したら変更をコミットするよう、必ずサブエージェントに指示します。コミットがないと、cw merge でマージするものがありません。
• すべてのサブエージェントを並列で起動します。1 回のメッセージ内で、それぞれ個別のバックグラウンド Bash 呼び出しとして実行します。
• サブエージェントごとに詳細なプロンプトを作成します。サブエージェントはタスク全体の背景を把握していないため、作成するもの、関連コードの場所、従うべきパターン、制約など、必要な情報をすべて伝えます。

ステップ 4：進捗の監視

起動後、完了するまで状況を確認します。

• block: false を指定した TaskOutput を使い、処理をブロックせずに各バックグラウンドタスクの状況を確認します。
• cw ls を使い、各ワークツリーの先行コミット数を確認します。
• サブエージェントの完了に応じて、進捗をユーザーに報告します。

ステップ 5：コミットの確認

マージする前に、各サブエージェントが実際に作業をコミットしたことを確認します。cw ls を実行し、すべてのワークツリーで先行コミット数が 0 より大きいことを確認します。

cw ls

ワークツリーの先行コミット数が 0 の場合、サブエージェントはコミットに失敗しています。そのワークツリーに移動して、手動でコミットします。

cw cd <name> && git add -A && git commit -m "Complete <subtask description>"

すべてのワークツリーに少なくとも 1 つのコミットがあることを確認するまで、マージに進んではいけません。

確認後、ユーザーが自分で確認したり作業を続けたりできるよう、各ワークツリーに手動で移動するためのコマンドを提示します。

To step into any worktree and take over:
  cw cd <name>        # enter the worktree
  claude              # start an interactive Claude session there

ユーザーがコピーして貼り付けられるよう、すべてのワークツリー名を列挙します。その後、マージに進むか、手動で引き継ぐかをユーザーに尋ねます。

ステップ 6：結果をマージする

すべての worktree でコミットの検証が完了したら、ステップ 1 でユーザーが選択した方法でそれぞれマージします。

# If user chose remote (GitHub PR)
cw merge <name>

# If user chose local (squash merge, no PR)
cw merge <name> --local

サブタスク間に依存関係（例：API ルートより先に DB マイグレーションが必要）がある場合は、正しい順序でマージします。

ステップ 7：クリーンアップする

すべてのマージが完了したら、次の操作を行います。

cw clean

cw コマンドのリファレンス

コマンド	説明
cw new <name> --no-open	対話形式のプロンプトを表示せずに worktree を作成します
cw cd <name>	worktree のディレクトリに移動します
cw ls	ブランチと先行コミット数を含む、すべての worktree を一覧表示します
cw merge <name>	ブランチをプッシュして GitHub PR を作成します
cw merge <name> --local	ローカルでスカッシュマージします（PR は作成しません）
cw rm <name>	worktree とそのブランチを削除します
cw clean	すべての worktree を削除します

例

ユーザーの依頼：「UI、API、データベースの各レイヤーを備えた設定機能を構築してください」

実行する内容：

1. ユーザーに計画を伝えます：3 つの並列サブタスク — feat-ui、feat-api、feat-db

2. worktree を作成します（単一の Bash 呼び出し）：

cw new feat-ui --no-open && cw new feat-api --no-open && cw new feat-db --no-open

3. 3 つのバックグラウンドサブエージェントを起動します（それぞれ run_in_background: true を指定した、3 つの並列 Bash 呼び出し）：

cw cd feat-ui && claude -p "Build the settings page UI. Create components in src/components/settings/ using the existing design system in src/components/ui/. Include a form for updating user preferences with fields for: display name, email notifications toggle, and theme selector. Commit your changes when done." --output-format text --dangerously-skip-permissions

cw cd feat-api && claude -p "Create REST API routes for settings in src/api/settings/. Add GET /api/settings and PUT /api/settings endpoints. Use the existing auth middleware from src/middleware/auth.ts. Return and accept JSON matching the Settings type. Commit your changes when done." --output-format text --dangerously-skip-permissions

cw cd feat-db && claude -p "Add a settings table migration in src/db/migrations/. Columns: user_id (FK to users), display_name (text), email_notifications (boolean, default true), theme (text, default 'system'). Add the Settings model in src/db/models/. Commit your changes when done." --output-format text --dangerously-skip-permissions

4. TaskOutput（block: false）と cw ls で状況を確認します

5. 依存関係の順序に従ってマージします：

cw merge feat-db && cw merge feat-api && cw merge feat-ui

6. クリーンアップします：

cw clean

トラブルシューティング

• cw が見つからない：シェルで読み込みます — source ~/.local/bin/cw
• cw cd でディレクトリが変わらない：cw が単なるスクリプトではなく、シェル関数として読み込まれていることを確認します
• マージの競合：worktree 内で手動で解決してコミットし、その後 cw merge を再試行します
• cw merge が拒否される：worktree に未コミットの変更があります — サブエージェントがコミットしていない可能性があります。cw cd <name> で移動して、手動でコミットします
• サブエージェントが停止／失敗した：TaskOutput で出力を確認します。停止している場合はバックグラウンドタスクを停止し、プロンプトを修正して再試行します

リファレンス

• リポジトリ：https://github.com/joyco-studio/cw