Community程式設計與開發github.com

平行問題解決器 (Parallel Issue Resolver)

並行處理多個 GitHub Issue,每個 Issue 在獨立的 git worktree 中處理,並透過各自的 Pull Request 合併。支援依賴圖規劃、子代理並行實作、獨立審查、CI 驗證與自動合併。

平行問題解決器 (Parallel Issue Resolver) 是什麼?

**平行問題解決器 (Parallel Issue Resolver)** 是一個專為 Claude Code 設計的 AI 技能,允許開發者將一組 GitHub Issue 以平行的方式解決,大幅提升多工處理效率。它會根據 Issue 之間的依賴關係建立依賴圖,只對「未受阻」的 Issue 啟動工作流程,每個 Issue 在獨立的 git worktree 中實作、提交、推送並建立 PR。 此技能支援多層安全閘門:每個 PR 必須由**不同的子代理**獨立審查,最後透過 `land.sh` 腳本等待 CI 通過、進行 squash-merge,並在 Issue 中留下實作摘要。如果審查要求變更,會回饋給原始實作者進行最多兩輪修正。 此技能在 Claude Code 環境中運作,依賴 subagent 的 `isolation: "worktree"` 能力與 `SendMessage` 跨代理通訊。安裝方式為 `npx skills add dhiraj-verhelm/agent-skills --skill parallel-issue-resolver`,或在專案目錄中放置 `.claude/skills/` 資料夾。前置檢查腳本可確保環境準備就緒(git, gh, jq、遠端倉庫、CI 組態)。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dhiraj-verhelm/agent-skills/tree/HEAD/skills/parallel-issue-resolver

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

平行問題解決器 (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」。

  1. 前置檢查 (Preflight):bash <skill-dir>/scripts/preflight.sh — 必須在啟動任何子代理之前回傳 0。沒有單獨的設定步驟;它會在首次執行時自動設定倉庫。
  2. 規劃 (Plan):讀取每個 Issue,建立依賴圖,選出可以立即執行而不會衝突的 Issue。
  3. 實作 (Implement):為每個未受阻的 Issue 啟動一個子代理,設定 isolation: "worktree",所有子代理在單一訊息中啟動以實現並行。每個子代理會實作、提交、推送、建立 PR 並寫入交接檔案。
  4. 審查 (Review):為每個 Issue 安排一個獨立的審查者子代理 — 絕非原始作者 — 它會閱讀 diff 與 Issue 描述,回傳 approve 或 changes-requested。
  5. 修正 (Fix):將阻礙性意見回饋給原始實作者,然後重新審查。最多兩輪。
  6. 合併 (Land):對每個已核准的 Issue,執行 bash <skill-dir>/scripts/land.sh <issue> <branch> <comment-file> — 一次一個。
  7. 循環 (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
4CI 失敗或超時閱讀失敗的檢查、在分支上修正、推送、重新執行 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 分支出去的。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能