Parallel Issue Resolver(並列Issue解決ツール)
複数のGitHub Issueを並行して解決します。各Issueは独立したgitワークツリーで隔離され、それぞれ独自のプルリクエストを通じてマージされます。**Plan(計画)→ Implement(実装)→ Review(レビュー)→ Fix(修正)→ Land(マージ)**の5フェーズで進行します。
最重要ルール:Issueは、GitHubがそのPRをMERGEDと報告した場合にのみクローズされます。 ローカルマージ、ワークツリーでのCI成功、サブエージェントの申告だけではクローズしません。クローズ時には実際に実装された内容のコメントが必ず添付されます。
作業は人間が行うのと同じ方法でmainブランチに到達します。ブランチ → PR → CI → squash-mergeです。CIが確認していないものはマージされません。
クイックスタート
ユーザーが「Resolve #12 #15 #18 in parallel」と指示した場合:
- Preflight(事前チェック):
bash <skill-dir>/scripts/preflight.sh— これを実行し、ゼロで終了するまで何も起動してはいけません。別途セットアップ手順はなく、初回実行時にリポジトリ自体を設定します。 - Plan(計画):各Issueを読み、依存関係グラフを構築し、今競合せずに実行できるIssueを選択します。
- Implement(実装):ブロックされていないIssueごとに1つのサブエージェントを
isolation: "worktree"で1つのメッセージですべて起動し、並行実行させます。各エージェントは実装、コミット、プッシュ、PR作成、ハンドオフファイルの書き込みを行います。 - Review(レビュー):各Issueに対して別のレビュアーサブエージェント(作成者以外)が、差分とIssueを照らし合わせて
approveまたはchanges-requestedを返します。 - Fix(修正):指摘事項を元の実装者に送り返し、再レビューします。最大2ラウンドまで。
- Land(マージ):承認された各Issueに対して
bash <skill-dir>/scripts/land.sh <issue> <branch> <comment-file>を1つずつ実行します。 - Loop(ループ):新たにブロックが解除されたIssueが残っている場合は、フェーズ1に戻ります。
初回実行前にREFERENCE.mdを読み、メカニクス、コマンド検出、注意点を確認してください。
フェーズ0 — Preflight(事前チェック)
毎バッチの前に実行します。これがこのスキルで唯一のセットアップコマンドです:
bash <skill-dir>/scripts/preflight.sh # --fix を追加すると安全な残存ファイルをクリア
このコマンドは、まだ設定されていないもの(gitignore対象の.env/シークレットファイルを全ワークツリーにコピーするための.worktreeinclude、無視ルール、worktree.baseRef: "head"など)をブートストラップし、実行が実際に成功することを検証します。必要なツールの存在、ツリーのクリーン状態、ghの認証状態、ベースとオリジンの同期、pull_requestでのCIトリガー設定、競合する可能性のあるagent/issue-*ブランチや孤立したワークツリーの有無を確認します。
ブートストラップは冪等であり、変更があった場合のみ出力を表示するため、2回目以降は純粋なチェックとして機能します。追跡対象ファイルは一切書き込みません — 無視ルールは.git/info/excludeに書き込まれるため、このスキルが誰かのリポジトリに差分を残すことはありません。
非ゼロで終了した場合は停止して修正してください。エージェントを起動してはいけません。 見つかった問題をユーザーに報告してください。
ベースブランチを取得します:git branch --show-current → BASE。すべてのPRはBASEをターゲットとします。
フェーズ1 — Plan(計画)(オーケストレーター、インライン)
各Issueに対して:gh issue view <id> --json number,title,body,labels,state,comments。Issueが親PRD/エピックを参照している場合は、それも読みます。
すでにCLOSED状態のIssue、またはすでにオープンPRが存在するIssue(gh pr list --search "<id> in:body")はスキップします。重複作業を避けるため、その旨を伝えてください。
依存関係グラフを構築します。以下のいずれかに該当する場合、BはAにブロックされていると判断します:
- BにAが導入するコードやインフラが必要である。
- BとAが同じファイルやモジュールを変更する(同時編集が競合する)。
- BがAで確立されるAPIの形状や決定に依存する。
Issueは、このバッチ内の他のIssueに対するブロッキング依存関係がゼロの場合にブロック解除されます。ブロック解除されたIssueのみが今回のラウンドで実行されます。すべてのIssueがブロックされている場合は、最も依存関係の弱いIssueを1つだけ実行してサイクルを断ち切ります。
各Issueに決定論的なブランチ名を割り当てます:agent/issue-<id>。エージェントを起動する前に、バッチ計画をユーザーに伝えてください — どのIssueが今実行され、どれが待機するか、その理由も含めて。
フェーズ2 — Implement(実装)(並列サブエージェント)
ブロック解除された各Issueに対して、Agentツールでisolation: "worktree"を指定して1つのサブエージェントを起動します。すべての起動を1つのメッセージにまとめて並行実行させます。
- サブエージェントタイプ:
general-purpose(編集とbashが必要) - 名前は
impl-<id>とします — フェーズ4でレビュー結果をこのエージェントに送り返すために名前が必要です。 - プロンプト:prompts/implement.mdの内容で、
{{ISSUE_ID}}、{{BRANCH}}(=agent/issue-<id>)、{{BASE}}、{{STATE_DIR}}(<repo>/.claude/pirの絶対パス)を埋め込みます。
各サブエージェントは実装、自身の差分の整理、プッシュ、PR作成を行い、{{STATE_DIR}}に2つのハンドオフファイルを書き込みます。これらのファイルは永続的な記録であり — コンテキスト圧縮やRESULT行を超えて存続します。詳細はREFERENCE.mdを参照してください。
フェーズ3 — 独立レビュー(並列サブエージェント)
実装エージェントは自身の作業をレビューしません。 completeステータスでオープンPRが返ってきた各Issueに対して、別のレビュアーを起動します — これもすべて1つのメッセージで行います。
- サブエージェントタイプ:
general-purpose。名前はreview-<id>とします。 isolation: "worktree"は不要 — レビューは読み取り専用で、ベースチェックアウトからgit diff {{BASE}}...{{BRANCH}}を実行します。ワークツリーの作成やクリーンアップは不要です。- プロンプト:prompts/review.mdの内容で、
{{ISSUE_ID}}、{{BRANCH}}、{{BASE}}、{{PR}}、{{STATE_DIR}}を埋め込みます。
レビュアーは{{STATE_DIR}}/issue-<id>.review.jsonにapproveまたはchanges-requestedの判定と所見を書き込みます。編集、プッシュ、マージ、コメントは一切行いません。報告のみ行い、判断はあなたが行います。
判定結果をPRに投稿し、人間が確認する場所に判断根拠を残します:
gh pr comment <PR> --body "$(jq -r '\"**Automated review: \(.verdict)**\n\n\(.summary)\"' .claude/pir/issue-<id>.review.json)"
フェーズ4 — Fix(修正)ラウンド(changes-requestedの場合のみ)
ブロッキングの指摘事項を元の実装者に送り返します。実装者はコードをコンテキストに保持しています:
SendMessage → to: "impl-<id>"
PR # の独立レビューで 件のブロッキング問題が見つかりました。これらだけを修正し、チェックを再実行し、同じブランチにプッシュし、ハンドオフ
.mdを最終状態に更新してください。<
blocking配列をそのまま>ある指摘が間違っていると思う場合は、正しいと信じるコードを変更する代わりに、その理由を述べてください。
その後、そのIssueに対してフェーズ3を再実行します(新しいreview-<id>エージェント — ラウンド2)。
レビューラウンドは最大2回までとします。 ラウンド2後もchanges-requestedのままのIssueがある場合は、そこで停止します。PRとIssueはオープンのままにし、ユーザーに未解決の問題とレビュアーの所見を伝えます。3ラウンド目は、そのIssueの仕様が不明確か、人間の判断が必要であることを意味し、さらなるラウンドは収束せずにトークンを消費するだけです。
実装者が修正ではなく指摘に反論した場合は、両方の主張を読み、あなた自身が判断してください。単に中継するだけではループの原因になります。
フェーズ5 — Land(マージ)(オーケストレーター、BASEチェックアウトから)
Issueは1つずつ、直列でマージします。並行してはいけません。各マージはBASEを変更し、次のPRを古くする可能性があります。land.shはGitHubが競合を報告したときにリベースを行いますが、それはすでに更新されたベースに対してのみ機能します。
ハンドオフのステータスがstatus: "complete"かつレビュー判定がapproveである各Issueに対して:
bash <skill-dir>/scripts/land.sh <issue> agent/issue-<issue> .claude/pir/issue-<issue>.md
このスクリプトは、正しい順序で後続処理全体を実行します。レビュー判定の確認 → ワークツリーの解放 → 競合があればリベース → CIがグリーンになるのを待機 → squash-merge → GitHubがMERGEDを報告することを確認 → ハンドオフコメント付きでIssueをクローズ → BASEをfast-forward → ブランチを削除 → ワークツリーを整理。
ディスク上にapprove判定がないものはマージを拒否するため、レビューは習慣ではなくゲートとして機能します。PIR_SKIP_REVIEW=1でこれを上書きできます。使用する場合は、CIが実行できない唯一のチェックを削除することになるので、その旨を明確に伝えてください。
終了コードに応じて分岐します:
| コード | 意味 | あなたの行動 |
|---|---|---|
0 | マージ完了、クローズ、クリーンアップ完了 | 次のIssueに進む |
2 | 前提条件失敗 | 修正して再実行。強行しない |
3 | スクリプトで解決できないリベース競合 | そのブランチ上で手動で解決し、プッシュ後、land.shを再実行 |
4 | CI失敗またはタイムアウト | 失敗したチェックを読み、ブランチ上で修正し、プッシュ後、land.shを再実行 |
5 | マージ/クローズ問題 | PRを調査 — Issueがオープンのままマージされている可能性あり |
0以外の場合は、PRおよびIssueを意図的にオープンにしたままにします。それらをPRリンク付きでユーザーに報告し、盲目的に再試行しないでください。
その後、ブロックされたIssueが残っている場合はフェーズ1にループバックします。
フェーズ6 — Report(報告)
Issueごとに、ユーザーに次の情報を伝えます:マージ完了(PR番号+リンク)、オープンのまま残した理由、またはスキップした理由。2ラウンドのレビュー後もオープンのままのIssueについては、レビュアーの未解決のブロッキング所見を含めてください。マージされたPR番号なしでIssueが完了したと主張しないでください。
必要条件
Claude Codeで動作します:isolation: "worktree"、SendMessage、.worktreeincludeを備えたサブエージェントに依存します。npx skills add dhiraj-verhelm/agent-skills --skill parallel-issue-resolverでインストールするか、このディレクトリを~/.claude/skills/またはリポジトリの.claude/skills/にコピーしてください。リポジトリごとのセットアップ、編集すべき設定、修正すべきパスはありません。
マシンに必要なもの:git、gh(認証済み)、jq。Preflightがこれらすべてをチェックし、不足しているものがあれば名前を表示します。
リポジトリに必要なもの:GitHubリモート、およびプルリクエストのチェックを報告するCI。PreflightはCIが見つからない場合に警告を表示します。PIR_REQUIRE_CI=0を設定すればCIゲートなしでも実行できます。これを行う場合は、スキルの主要な安全機構を削除することになるので、その旨を明確に伝えてください。
リポジトリに対して行わないこと:追跡対象ファイルの変更。無視ルールは.git/info/excludeに書き込まれるため、ブートストラップは差分を残さず、コミットに漏れ込むこともありません。
スクリプトはbash <path>として呼び出されるため、コピー中に実行可能ビットが失われても問題は発生しません。
安全性とゲート
- BASEに
git pushしてはいけません。 また、エージェント自身のブランチ以外には--forceを使用してはいけません(land.shのリベース内でのみ、--force-with-leaseを使用)。 git add -A/git add .を使用してはいけません — 明示的なパスのみをステージングしてください。- PR本文に
Closes #N/Fixes #Nを入れてはいけません。 これによりGitHubがマージ時にIssueをサイレントにクローズし、何が行われたかのコメントが残りません。Refs #Nを使用してください。クローズは明示的に行い、マージの確認とサマリーの添付を常に行います。 --adminでマージしてはいけません。また、赤いチェックをスキップしてはいけません。- Issueごとに1つのサブエージェントで、自身のIssueのみを処理します。
- Preflightが失敗した場合は停止し、ユーザーに伝えてください。ツリーがダーティな場合は停止してください — ワークツリーはHEADからブランチを作成します。