并行问题解析器 是做什么的?
并发解决一批 GitHub Issue,每个 Issue 在独立的 Git Worktree 中处理,然后通过各自的 Pull Request 合并。共五个阶段 —— 规划 → 实现 → 审查 → 修复 → 合并。
关键规则:只有当 GitHub 报告其 PR 状态为 MERGED 时,Issue 才被视为已关闭。 本地合并、Worktree 中的测试通过或子代理的断言均不视为关闭依据。每个关闭操作都会附带一条评论,说明实际实现的内容。
工作进入 main 分支的方式与人类开发者相同:分支 → PR → CI → squash-merge。未经 CI 验证的代码不会合并。
快速开始
用户说:"并行解决 #12 #15 #18"。
- 预检:
bash <skill-dir>/scripts/preflight.sh— 必须先退出代码 0 才能执行后续操作。没有单独的设置步骤;首次运行时它会自动配置仓库。 - 规划:读取每个 Issue,构建依赖图,选出可以 立即 运行且不会冲突的 Issue。
- 实现:为每个无阻塞的 Issue 创建一个子代理,隔离模式为
isolation: "worktree",所有代理在单条消息中生成以实现并发运行。每个代理实现、提交、推送、创建 PR,并写入交接文件。 - 审查:为每个 Issue 指定一个 独立的 审查子代理(非实现者本人),审查代理读取针对 Issue 的差异,返回
approve(批准)或changes-requested(请求变更)结果。 - 修复:将阻塞性问题反馈给原始实现者,然后重新审查。最多两轮。
- 合并:对于每个已批准的 Issue,执行
bash <skill-dir>/scripts/land.sh <issue> <branch> <comment-file>— 一次合并一个。 - 循环:如果仍有新解除阻塞的 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 |
4 | CI 失败或超时 | 读取失败的检查、在分支上修复、推送、重新运行 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 分支。