Community编程与开发github.com

并行问题解析器

将多个 GitHub Issue 并行解决,每个 Issue 在独立的 Git Worktree 中处理,然后通过各自的 Pull Request 合并。支持依赖图规划、子代理并发实现、独立审查,以及 CI 验证后的合并。

并行问题解析器 是什么?

Parallel Issue Resolver 是一个专为 Claude Code 等 AI 代理工具设计的技能,用于并行处理 GitHub Issue。它通过创建独立的 git worktree 隔离每个 Issue 的工作,避免了文件冲突。该技能支持自动检测 Issue 间的依赖关系,规划实现顺序,并利用子代理并发执行无依赖的 Issue。每个实现都由独立的审查代理审核,确保代码质量。最终,每个 Issue 通过独立的 PR 提交,等待 CI 通过后 squash-merge,并自动关闭 Issue 并添加实现注释。该技能适用于需要同时处理多个 Issue 的场景,显著提升开发效率。

兼容平台✓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 的新对话。

文档

并行问题解析器 是做什么的?

并发解决一批 GitHub Issue,每个 Issue 在独立的 Git Worktree 中处理,然后通过各自的 Pull Request 合并。共五个阶段 —— 规划 → 实现 → 审查 → 修复 → 合并。

关键规则:只有当 GitHub 报告其 PR 状态为 MERGED 时,Issue 才被视为已关闭。 本地合并、Worktree 中的测试通过或子代理的断言均不视为关闭依据。每个关闭操作都会附带一条评论,说明实际实现的内容。

工作进入 main 分支的方式与人类开发者相同:分支 → PR → CI → squash-merge。未经 CI 验证的代码不会合并。

快速开始

用户说:"并行解决 #12 #15 #18"。

  1. 预检:bash <skill-dir>/scripts/preflight.sh — 必须先退出代码 0 才能执行后续操作。没有单独的设置步骤;首次运行时它会自动配置仓库。
  2. 规划:读取每个 Issue,构建依赖图,选出可以 立即 运行且不会冲突的 Issue。
  3. 实现:为每个无阻塞的 Issue 创建一个子代理,隔离模式为 isolation: "worktree",所有代理在单条消息中生成以实现并发运行。每个代理实现、提交、推送、创建 PR,并写入交接文件。
  4. 审查:为每个 Issue 指定一个 独立的 审查子代理(非实现者本人),审查代理读取针对 Issue 的差异,返回 approve(批准)或 changes-requested(请求变更)结果。
  5. 修复:将阻塞性问题反馈给原始实现者,然后重新审查。最多两轮。
  6. 合并:对于每个已批准的 Issue,执行 bash <skill-dir>/scripts/land.sh <issue> <branch> <comment-file> — 一次合并一个。
  7. 循环:如果仍有新解除阻塞的 Issue,则进入循环。

首次运行前,请阅读 REFERENCE.md 了解机制、命令检测和注意事项。

阶段 0 — 预检

每次批量处理前都执行此操作。这是本技能中唯一的设置命令:

bash <skill-dir>/scripts/preflight.sh        # 添加 --fix 清理安全的残留文件

它会引导完成所有尚未配置的内容 — .worktreeinclude(确保 .gitignore 中的 .env/密钥文件被复制到每个 Worktree 中)、忽略规则、worktree.baseRef: "head" — 然后验证运行是否会成功:所需工具是否存在、工作区是否干净、gh 是否已认证、基础分支是否与远端同步、CI 是否在 pull_request 上触发,以及是否没有残留的 agent/issue-* 分支或孤立的 Worktree 会导致冲突。

引导过程是幂等的,仅在有变更时打印信息,因此从第二次运行开始,它仅作为检查。它不会修改任何已跟踪文件 — 忽略规则写入 .git/info/exclude,因此该技能永远不会在任何人的仓库中留下差异。

如果预检退出代码非零,请停止并修复 — 不要生成代理。 向用户报告发现的问题。

捕获基础分支:git branch --show-current → BASE。所有 PR 都针对 BASE。

阶段 1 — 规划(协调器,内联)

对于每个 Issue:gh issue view <id> --json number,title,body,labels,state,comments。如果 Issue 引用了父 PRD/Epic,也一并阅读。

跳过任何状态为 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 — 实现(并行子代理)

对于 每个 已解除阻塞的 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)。

每个子代理实现代码、整理差异、推送、创建 PR,并将两个交接文件写入 {{STATE_DIR}}。这些文件是持久记录 — 它们会在上下文压缩后存活,而 RESULT 行不会。请参阅 REFERENCE.md。

阶段 3 — 独立审查(并行子代理)

实现代理不得审查自己的工作。 对于每个状态为 complete 且已创建开放 PR 的 Issue,生成一个 独立的 审查代理 — 同样 所有生成命令放在一条消息中。

  • 子代理类型:general-purpose。将其命名为 review-<id>。
  • 无需 isolation: "worktree" — 审查是只读操作,基于基础检出目录中的 git diff {{BASE}}...{{BRANCH}} 进行。无需创建或清理 Worktree。
  • 提示内容: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 '"**自动化审查: \(.verdict)**\n\n\(.summary)"' .claude/pir/issue-<id>.review.json)"

阶段 4 — 修复轮次(仅针对 changes-requested)

将阻塞性发现发送回 原始实现者,其上下文中仍保留着代码:

SendMessage → to: "impl-<id>"

对 PR # 的独立审查发现了 个阻塞问题。请仅修复这些问题,重新运行检查,推送到同一分支,并更新您的交接 .md 文件以反映最终状态。

<blocking 数组,照原样>

如果您认为某个发现是错误的,请说明原因,而不是更改您认为正确的代码。

然后对该 Issue 重新运行阶段 3(一个全新的 review-<id> 代理 — 第二轮)。

最多两轮审查。 如果第二轮后 Issue 状态仍为 changes-requested,则停止:保持 PR 和 Issue 开放,并向用户报告哪些问题未解决,同时附上审查者的发现。三轮意味着 Issue 定义不清或分歧需要人工介入,继续轮次只会浪费 Token 而无法收敛。

如果实现者反驳发现而不是修复它,请阅读双方的论点并自行裁定。不要只是将信息来回传递 — 那样会形成死循环。

阶段 5 — 合并(协调器,从 BASE 检出目录执行)

一次一个,串行合并 Issue — 切勿并行处理。每次合并都会更改 BASE,这可能导致下一个 PR 过时;land.sh 会在 GitHub 报告冲突时执行变基,而这只适用于已更新的基础分支。

对于每个交接文件状态为 status: "complete" 且 审查判决为 approve 的 Issue:

bash <skill-dir>/scripts/land.sh <issue> agent/issue-<issue> .claude/pir/issue-<issue>.md

该脚本按唯一正确的顺序执行所有尾随操作:检查审查判决 → 释放 Worktree → 如有冲突则变基 → 等待 CI 变绿 → squash-merge → 验证 GitHub 报告状态为 MERGED → 使用交接评论关闭 Issue → 快进 BASE → 删除分支 → 清理 Worktree。

它拒绝合并任何没有磁盘上 approve 判决的内容,因此审查是一个严格的门禁而非习惯。PIR_SKIP_REVIEW=1 可覆盖此规则 — 如果你使用此选项,请明确说明,因为这将移除 CI 无法执行的唯一检查。

根据其退出代码进行分支处理:

代码含义你的操作
0已合并、关闭并清理继续处理下一个 Issue
2前提条件失败修复后重新运行;不要强制跳过
3脚本无法解决的变基冲突手动在该分支上解决、推送、重新运行 land.sh
4CI 失败或超时读取失败的检查、在分支上修复、推送、重新运行 land.sh
5合并/关闭问题检查 PR — 可能已合并但 Issue 仍开放

任何非 0 的退出码都会 特意 保持 PR 和 Issue 开放。向用户报告这些情况并附上 PR 链接;不要盲目重试。

然后,如果仍有被阻塞的 Issue,循环回到阶段 1。

阶段 6 — 报告

按 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,因此引导过程不会留下差异,也不会泄露任何内容进入提交。

脚本作为 bash <path> 调用,因此复制过程中丢失的可执行位不会导致问题。

安全与门禁

  • 永远不要 git push 到 BASE,并且绝不对除代理自身分支以外的任何内容使用 --force(--force-with-lease,仅限于 land.sh 的变基操作内部)。
  • 永远不要使用 git add -A / git add . — 仅暂存显式路径。
  • 永远不要在 PR 正文中放置 Closes #N / Fixes #N。 这会导致 GitHub 在合并时静默关闭 Issue,而不附带任何关于处理内容的注释。请使用 Refs #N;关闭操作是显式的,在已验证合并之后进行,并且始终附带摘要。
  • 永远不要使用 --admin 合并,也永远不要跳过红色(失败)的检查。
  • 每个 Issue 对应一个子代理,且仅处理其自己的 Issue。
  • 如果预检失败,停止并告知用户。如果工作区不干净,停止 — Worktree 从 HEAD 分支。

Individual skills in this repo

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

相关技能