| name | parallel-issues |
| description | GitHub issue を sub-issue に分解し、worktree 分離した並行エージェントで実装、読み取り専用の検証ゲートを経て、コンフリクト検知とマージ順序決定まで行う並行開発オーケストレーション手順。/parallel-issues <issue番号 or タスク概要> で起動する。 |
| disable-model-invocation | true |
parallel-issues
1つの issue(または大きめのタスク)を複数の sub-issue に分解し、worktree 分離した並行エージェントで実装して安全に合流させる。あなたはコーディネーターであり、実装はすべてサブエージェントに委譲する。
なぜこの手順か
並行開発の失敗は「実装そのもの」ではなく、(1) 分解の粒度ミスによる作業衝突、(2) 完了申告と実態の乖離、(3) 合流順序の誤りによるコンフリクト連鎖、で起きる。この手順は3点それぞれに独立したゲートを置く。
Phase 0: 前提確認
作業開始前に以下を確定させる。不明なものは推測せずユーザーに確認する。
- ベースブランチとテストコマンド(プロジェクト固有のため、CLAUDE.md やタスクランナー定義から候補を挙げてユーザーに確認する)
- 作業ツリーがクリーンであること(
git status)
- 対象 issue の内容(
gh issue view などで実際に読む。タイトルだけで分解しない)
Phase 1: 分解(codebase-verified)
- issue を読み、関連コードを実際に調べたうえで sub-issue 案を作る。コードを読まずに issue 本文だけから分解しない(分解の妥当性はコードの実態が決める)。
- 各 sub-issue に対し「触るはずのファイル・モジュール範囲」を明記する。範囲が重なる sub-issue は並行させず、統合するか依存関係として直列化する。
- 分解案(sub-issue 一覧・依存関係・並行度)をユーザーに提示し、承認を得てから fan-out する。ここが人間の判断を挟む唯一の必須ポイント。
Phase 2: fan-out(worktree 分離)
- 1 sub-issue = 1 エージェントとし、それぞれを worktree 分離で起動する(Agent tool の worktree isolation など、利用中のエージェント環境が提供する分離機構を使う)。
- 各エージェントへの指示には必ず含める:
- sub-issue の完了条件と「触ってよいファイル範囲」
- テストコマンドと「テストが通るまで完了申告しないこと」
- 返答フォーマット: 変更ファイル一覧・変更概要・テスト実行結果(生ログではなく要約)
- 依存関係のある sub-issue は先行タスクの検証ゲート通過後に起動する。
Phase 3: 検証ゲート(申告を信用しない)
各エージェントの完了申告ごとに、読み取り専用の検証を通す。
verifier エージェント定義が利用可能ならそれを使う。なければ、同等の内容(変更ファイルの実読・破損チェック・git diff 照合・テスト再実行・申告との差分報告)を読み取り専用のサブエージェントに直接指示する。
- 検証には「申告された変更ファイル一覧・変更意図・テストコマンド」を明示的に渡す。
- FAIL / PARTIAL は該当エージェントに差し戻す。2回差し戻しても解消しない場合は自力で直そうとせず、ユーザーにエスカレーションする(分解の前提が崩れているサイン)。
Phase 4: 合流(コンフリクト検知とマージ順序)
- 全 worktree の変更ファイル一覧を突き合わせ、重なりを検出する。重なりがあれば、その組は同時マージせず順序を決めて後続側をリベースさせる。
- マージ順序は「依存される側が先、変更範囲が小さい側が先」を基本とする。
- 1つマージするごとにベースブランチでテストを実行する。まとめてマージしてからテストしない(失敗時に原因コミットを特定できなくなる)。
- マージ済み worktree は削除前にユーザーへ報告する(後戻りしにくい操作のため)。
Phase 5: 報告
最後に以下のダッシュボード形式で報告する。
## parallel-issues 結果
| sub-issue | 状態 | 検証 | マージ |
|-----------|------|------|--------|
| <名前> | done / blocked / needs-decision | PASS/FAIL | 済/未 |
### 要判断事項
- <ユーザーの判断が必要な項目>
- issue へのステータス反映(コメント・クローズ)を行った場合は、read-back(
gh issue view 等での再取得)で反映を確認してから完了と報告する。