平行問題解決器 (Parallel Issue Resolver) 是做什麼的?
並行處理一批 GitHub Issue,每個 Issue 在獨立的 git worktree 中隔離處理,然後透過各自的 Pull Request 合併。分為五個階段:規劃 → 實作 → 審查 → 修正 → 合併 (Land)。
最重要的規則:只有當 GitHub 回報該 PR 狀態為 MERGED 時,Issue 才會被關閉。 不會因為本地合併、worktree 中測試通過或子代理的回報而關閉。每個 Issue 關閉時都會附上一則評論,說明實際實作的內容。
所有變更以與人類開發者相同的方式進入 main:建立分支 → PR → CI → squash-merge。未經 CI 驗證的程式碼不會被合併。
快速開始
使用者說:「並行處理 Issue #12 #15 #18」。
- 前置檢查 (Preflight):
bash <skill-dir>/scripts/preflight.sh— 必須在啟動任何子代理之前回傳 0。沒有單獨的設定步驟;它會在首次執行時自動設定倉庫。 - 規劃 (Plan):讀取每個 Issue,建立依賴圖,選出可以立即執行而不會衝突的 Issue。
- 實作 (Implement):為每個未受阻的 Issue 啟動一個子代理,設定
isolation: "worktree",所有子代理在單一訊息中啟動以實現並行。每個子代理會實作、提交、推送、建立 PR 並寫入交接檔案。 - 審查 (Review):為每個 Issue 安排一個獨立的審查者子代理 — 絕非原始作者 — 它會閱讀 diff 與 Issue 描述,回傳
approve或changes-requested。 - 修正 (Fix):將阻礙性意見回饋給原始實作者,然後重新審查。最多兩輪。
- 合併 (Land):對每個已核准的 Issue,執行
bash <skill-dir>/scripts/land.sh <issue> <branch> <comment-file>— 一次一個。 - 循環 (Loop):若有新解除封鎖的 Issue,則繼續執行。
在首次執行前,請閱讀 REFERENCE.md 了解運作機制、命令偵測與常見陷阱。
階段 0 — 前置檢查 (Preflight)
每次執行批量任務前都要執行此步驟。這是此技能中唯一的設定命令:
bash <skill-dir>/scripts/preflight.sh # 加上 --fix 可清除安全的殘留項目
它會設定任何尚未配置的項目 — .worktreeinclude(確保被 gitignore 的 .env/密碼檔案會複製到每個 worktree)、忽略規則、worktree.baseRef: "head" — 然後驗證執行是否會成功:所需工具是否存在、工作目錄是否乾淨、gh 是否已授權、基底分支是否與 origin 同步、CI 是否在 pull_request 上觸發,以及是否沒有殘留的 agent/issue-* 分支或孤立的 worktree 會造成衝突。
引導程序是冪等的,只會在變更內容時輸出訊息,因此從第二次執行開始,它純粹是檢查角色。它不會寫入任何受追蹤的檔案 — 忽略規則寫在 .git/info/exclude 中,因此此技能絕不會在任何人的倉庫中留下 diff。
若 exit code 非零,請停止並修正 — 不要啟動子代理。 將發現的問題回報給使用者。
擷取基底分支: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")— 告知使用者以避免重複工作。
建立依賴圖。Issue B 被 A 封鎖 如果符合以下任一條件:
- B 需要 A 引入的程式碼/基礎設施。
- B 和 A 修改重疊的檔案/模組 → 並行編輯會衝突。
- B 依賴於 A 建立的 API 形狀或決策。
某 Issue 是未受阻的,如果它對此批次中的其他 Issue 沒有阻擋性依賴。只有未受阻的 Issue 會在這一輪中執行。如果所有 Issue 都被封鎖,則只執行依賴最弱的那個來打破循環。
為每個 Issue 分配一個確定性的分支名稱:agent/issue-<id>。在啟動子代理前告知使用者批次規劃 — 哪些 Issue 現在執行、哪些等待、以及原因。
階段 2 — 實作 (Implement)(並行子代理)
對每個未受阻的 Issue,透過 Agent 工具啟動一個子代理,設定 isolation: "worktree"。將所有啟動指令放在同一則訊息中以實現並行執行。
- 子代理類型:
general-purpose(需要編輯 + bash)。 - 命名為
impl-<id>— 你需要這個名稱才能在階段 4 中將審查意見傳送回給它,讓它能保持上下文。 - 提示:使用 prompts/implement.md 的內容,並填入
{{ISSUE_ID}}、{{BRANCH}}(=agent/issue-<id>)、{{BASE}}和{{STATE_DIR}}(<repo>/.claude/pir的絕對路徑)。
每個子代理必須實作、整理其 diff、推送、建立 PR,並在 {{STATE_DIR}} 中寫入兩個交接檔案。這些檔案是持久性記錄 — 它們能在上下文壓縮後存活,RESULT 行則不行。請參閱 REFERENCE.md。
階段 3 — 獨立審查 (Independent Review)(並行子代理)
實作代理不可審查自己的工作。 對每個回傳 complete 且已建立 PR 的 Issue,啟動一個獨立的審查者 — 同樣全部放在一則訊息中。
- 子代理類型:
general-purpose。命名為review-<id>。 - 不使用
isolation: "worktree"— 審查是唯讀操作,從基本的 checkout 執行git diff {{BASE}}...{{BRANCH}}即可。無需建立或清理 worktree。 - 提示:prompts/review.md 的內容,填入
{{ISSUE_ID}}、{{BRANCH}}、{{BASE}}、{{PR}}、{{STATE_DIR}}。
審查者會在 {{STATE_DIR}}/issue-<id>.review.json 中寫入 verdict(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 Round)(僅針對 changes-requested)
將阻擋性意見回饋給原始實作者,該實作者仍保有程式碼的上下文:
SendMessage → to: "impl-<id>"
PR # 的獨立審查發現了 個阻擋性問題。請僅修正這些問題,重新執行檢查,推送到同一個分支,並更新你的交接
.md檔案以反映最終狀態。<
blocking陣列,逐字列出>如果你認為某個發現是錯的,請說明原因,而非修改你認為正確的程式碼。
然後對該 Issue 重新執行階段 3(一個全新的 review-<id> 代理 — 第二輪)。
最多兩輪審查。 如果第二輪後某 Issue 仍為 changes-requested,則停止:保留 PR 和 Issue 為開啟狀態,並告訴使用者未解決的問題及審查者的發現。三輪表示 Issue 規格不明確或分歧需要人類介入,繼續只會浪費 token 且無法收斂。
如果實作者對某一發現提出反駁而非修正,請自行閱讀雙方論點並做出裁決。不要只是轉發 — 這樣會形成無窮迴圈。
階段 5 — 合併 (Land)(協調器,從 BASE checkout 執行)
一次一個、序列化地合併 Issue — 絕不並行。每次合併都會變更 BASE,這可能使下一個 PR 過時;land.sh 會在 GitHub 回報衝突時進行 rebase,但這僅能在已經更新過的基底上運作。
對每個交接檔案中標示 status: "complete" 且審查 verdict 為 approve 的 Issue:
bash <skill-dir>/scripts/land.sh <issue> agent/issue-<issue> .claude/pir/issue-<issue>.md
該腳本以唯一正確的順序執行所有後續步驟:檢查審查 verdict → 釋放 worktree → 如有衝突則 rebase → 等待 CI 變綠 → squash-merge → 驗證 GitHub 回報 MERGED → 使用交接檔案中的內容關閉 Issue 並留言 → fast-forward BASE → 刪除分支 → 清除 worktree。
若磁碟上沒有 approve 的 verdict,腳本會拒絕合併任何內容,因此審查是一個強制關卡,而非習慣。設定 PIR_SKIP_REVIEW=1 可繞過此檢查 — 如果你使用此選項,請大聲說出來,因為它移除了 CI 無法執行的唯一檢查。
以 exit code 分支判斷:
| 代碼 | 意義 | 你該做什麼 |
|---|---|---|
0 | 已合併、關閉、清理完畢 | 繼續處理下一個 Issue |
2 | 前置條件失敗 | 修正後重新執行;不要強行跳過 |
3 | 腳本無法解決的 rebase 衝突 | 在該分支上手動解決、推送、重新執行 land.sh |
4 | CI 失敗或超時 | 閱讀失敗的檢查、在分支上修正、推送、重新執行 land.sh |
5 | 合併/關閉問題 | 檢查 PR — 可能合併了但 Issue 仍開啟 |
任何非 0 的結果會特意保留 PR 和 Issue 為開啟狀態。將這些情況連同 PR 連結回報給使用者;不要盲目重試。
如果仍有被封鎖的 Issue,則回到階段 1 繼續循環。
階段 6 — 報告 (Report)
向使用者報告每個 Issue 的結果:已合併(PR # + 連結)、保留開啟的原因,或跳過的原因。對於兩輪審查後仍保留開啟的 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。前置檢查會驗證三者是否存在,並指出缺失的項目。
倉庫需要:一個 GitHub 遠端倉庫,以及在 Pull Request 上回報檢查的 CI。如果沒有找到這樣的 CI,前置檢查會發出警告。你可以透過設定 PIR_REQUIRE_CI=0 繼續執行,這會在不經 CI 閘門的情況下合併 PR。如果你這麼做,請大聲說出來,因為這移除了技能的主要安全屬性。
此技能不會對倉庫做的事:修改任何受追蹤的檔案。忽略規則寫在 .git/info/exclude 中,因此引導程序不會留下任何 diff,也不會有任何內容意外被提交。
腳本透過 bash <path> 方式呼叫,因此複製時若遺失執行權限位元也不會造成問題。
安全性與閘門
- 永遠不要
git push到 BASE,且永遠不要對除了代理自己的分支以外的任何東西使用--force(在land.sh的 rebase 內部使用--force-with-lease)。 - 永遠不要使用
git add -A/git add .— 只暫存明確的路徑。 - 永遠不要在 PR 主體中加入
Closes #N/Fixes #N。 這會讓 GitHub 在合併時靜默關閉 Issue,而不留下關於做了什麼的評論。請使用Refs #N;關閉 Issue 是明確的動作,受已驗證的合併閘門控制,且總是附帶摘要。 - 永遠不要使用
--admin合併,也永遠不要跳過紅色檢查。 - 每個 Issue 只有一個子代理,且只處理自己的 Issue。
- 如果前置檢查失敗,請停止並通知使用者。如果工作目錄有未提交的變更,也請停止 — worktree 是從 HEAD 分支出去的。