build-feature

分阶段构建功能

一个阶段对应一个 PR，在合并前经过多轮审查和修复。在一个分支上构建的功能无法试用，而只经过一轮审查就合并的代码，其修复也未经审查。

main
 └─ integrate/<plan>                         cut once, before the first phase
     ├─ <plan>-phase-1 ──PR──▶ integrate     build, verify, review x2-3, fix, merge
     ├─ <plan>-phase-2 ──PR──▶ integrate
     ├─ <plan>-phase-N ──PR──▶ integrate
     └──────────────────PR──▶ main           demo, then the user merges

one phase: feat/<plan> ──PR──▶ main          no integrate branch

从计划文件开始，切勿依赖记忆。 从参数中获取路径，或在 plans/ 下查找；若有多个匹配项，则询问用户。每个阶段都重新阅读计划。如果任何决策仍为 _open_，就停下并请用户返回规划阶段。第 1 阶段开始前，检查每一条 Verify 项和 ## Demo：没有验证依据且未延期的阶段，是规划疏漏，最好现在就提出。

按照图示创建分支。 从最新的 main 创建 integrate/<plan-name> 并推送；如果该分支已存在，则直接复用。每个阶段都从该分支创建分支，并将其作为目标分支，这样 main 就不会包含未完成的功能。如果计划只有一个阶段，则跳过该分支：从 main 创建 feat/<plan-name>，演示完成后停在已通过检查的 PR，留给用户合并。

每个阶段都从未勾选的任务开始，这些任务的 Blocked by: 阶段必须已合并；并且只完成该阶段的任务。 Solo 模式下，按计划顺序逐项完成。绝不要提前处理尚未开始阶段的工作，哪怕只有三行；明确的阶段边界能让 PR 更易审查。无关的 bug 和诱人的重构都只需在计划中记一行备注。在完成工作的同一提交中勾选任务，并更新 ## Progress。Active: 列出所有进行中的阶段，例如 Active: 2a, 2b · 7/15 tasks。

继续已有工作，不要重新开始。 首先查找目标分支为集成分支的未关闭 PR。尚未合并阶段的 PR 仍处于进行中；其提交和审查评论能表明已进行到哪一轮。Solo 模式以外，如果运行时仍保留该阶段的 worker，就继续使用它。否则，说明情况，并根据计划和 PR 向新的 worker 交代背景。

开始任何工作前，先展示流程。 确认当前进度后，根据计划中的阶段、已合并的 PR 和未关闭的 PR，以纯文本图示打印流程。将每一步标记为已完成、进行中或待处理，让用户看到剩余工作。如果有 Blocked by: 行，就将阶段分组为若干波次：每个波次包含其所有阻塞项都位于更早波次的阶段。列出每个阶段的阻塞项，因为某个阶段只需等自己的阻塞项合并后即可开始，不必等整个前序波次完成。如果没有阻塞项，则按顺序列出阶段。使用计划中的阶段 ID，例如 2a。只有一个阶段的计划应显示 feat/<plan>，而不是集成分支。

plans/<plan>.md
main
 └─ integrate/<plan>
     ├─ wave 1
     │   └─ [x] phase 1  <title>   merged #12
     ├─ wave 2
     │   ├─ [~] phase 2a <title>   PR #14, review round 2
     │   └─ [~] phase 2b <title>   building
     ├─ wave 3
     │   └─ [ ] phase 3  <title>   blocked by 2a, 2b
     ├─ [ ] demo
     └─ [ ] final PR ──▶ main      user merges

第 1 阶段开始前，使用 AskUserQuestion 询问如何构建。 将答案记录在 Decisions 下的 **Build mode** 中，以便恢复工作时保留设置。只有一个阶段的计划跳过此步骤，直接使用 Solo 模式构建。

• Orchestrator (Recommended) —— 每个阶段都使用全新的 worker 子 Agent，这样第 6 阶段就不会沿用第 1 阶段的上下文。Blocked by: 阶段均已合并的阶段会同时运行，每个 worker 都在自己的 git worktree 中。如果没有 Blocked by: 行，则按顺序逐个运行。并行 worker 只勾选各自的任务；每次合并时由你更新 ## Progress。
• Solo —— 每个阶段都由你构建，每轮都使用全新的审查者子 Agent。后续阶段的上下文会越来越繁杂。

在每个选项的 preview 中展示对应模式的流程图。如果提问工具不支持 preview，则在提问前打印两种模式的流程图。

Orchestrator
you ─┬─ worker 1 ── phase 1 ── reviewers
     ├─ worker 2 ── phase 2 ── reviewers
     └─ worker 3 ── phase 3 ── reviewers
fresh context per phase; unblocked
phases run in parallel

Solo
you ─┬─ phase 1 ── reviewers
     ├─ phase 2 ── reviewers
     └─ phase 3 ── reviewers
one context, grows each phase

不要询问子 Agent 使用什么模型。 除非用户的参数另有说明，否则两者都使用你的模型。如果设置了 effort 参数，审查者使用你的 effort，worker 使用低一级的 effort（high→medium）。在 Claude Code 中读取 $CLAUDE_EFFORT；切勿猜测。如果无法查到，就不设置 effort。将每个角色的模型和 effort 与构建模式一并记录。

没有子 Agent 工具？ 停下并告知用户需要安装一个。切勿自行构建任务分发器。**在 Pi 上，**在询问如何构建前，先阅读此文件旁的 pi.md。 由工作者构建；由你负责协调。 阶段代码及验证工作由其工作者负责：创建阶段分支、构建、验证、发起 PR 并处理评审修改。你负责集成分支、评审、合并、报告和演示。向工作者说明计划文件路径、其负责的阶段、本技能对范围、验证、PR、修改和已锁定决策的规定，以及常见错误。每轮评审都通过给同一位工作者发消息（例如 SendMessage）来传达，因为它已经掌握差异内容。每份包含问题的评审报告都要转达；没有问题的轮次无需发送消息。评审者提交报告后通知你已空闲，也无需回复。单人模式下，你就是工作者。

phase N
  worker W ── spawned once: builds, verifies, opens PR
     │  round 1  reviewer R1 (new) ──report──▶ you ──relay──▶ W fixes, commits
     │  round 2  reviewer R2 (new) ──report──▶ you ──relay──▶ W fixes, commits
     │  round 3  reviewer R3 (new) ──report──▶ you ──relay──▶ W fixes, commits
     ▼
  merge ── W retired; phase N+1 gets a new worker

发起 PR 前先在本地验证。 运行代码库的检查，并证明该阶段实现了承诺的功能。证明应采用计划中的 Verify 行；如果没有，则使用一个在没有本阶段代码时会失败的测试，或对本地测试装置或开发服务器进行运行验证。“能编译”不算证明。

• 使用可随时弃用的环境。如果验证需要已部署的主机、共享数据库或管理员登录，请停止并询问，同时说明这些操作会造成什么影响。切勿打开凭据文件来使其能够运行。
• 对于标记为 deferred 的 Verify 行（旧计划中写作 **Demo:**），运行检查，并说明证明将推迟到演示时进行，然后继续。不要自行编造验证方式。
• 如果某一步需要用户自己的设备或个人账户，且无法使用临时账户，则运行其余步骤，将该步骤推迟到演示时进行，无需询问，并在阶段报告中注明。

留意耗时较长的验证。 构建后以及每次修复提交后，都要运行快速检查。慢速检查（E2E、Playwright、会启动服务或休眠的集成测试）在 PR 前运行一次；合并前仅当修复涉及其覆盖范围时才再次运行。评审者不要运行慢速检查。

PR 必须发起到集成分支，而不是 main。 标题格式为 Phase <n>: <imperative title>。正文应包含 ## Summary，说明用户能获得什么，列出与改动规模相称的要点，并注明计划文件路径。不要包含测试计划、清单或共同作者署名。如果没有 gh 或 GitHub 远程仓库，则在分支推送后停止并说明情况；不要伪造评审流程。

每轮评审都要使用新的子代理， 绝不重复使用，也绝不让编写者担任评审者，因为最难发现的正是自己想当然的部分。如果已安装代码库的评审技能，则使用 review-code，目标为 pr <number>，且不要加 --sub：子代理本身就是全新的上下文，再嵌套一个没有意义。否则，让子代理评审差异中的正确性、安全性、资源和性能缺陷，并评估严重程度、可能性及是否值得修复。要求使用普通文字；输出格式规范会导致任务在评审开始前就失败。等待时使用运行时提供的等待机制，绝不轮询。原样转达报告。

同一个 PR 要进行两到三轮评审， 每轮都要等上一轮的修复提交合入后再开始。无论第 1 轮是否干净，第 2 轮都必须进行，因为新的评审者能发现第一位评审者遗漏的问题。只有第 2 轮产生了修复时，才进行第 3 轮。最多三轮：如果第 3 轮后仍有值得修复的 High 或 Critical 问题，则停止合并，因为该阶段过于庞大，无法收敛。向用户报告问题和你的处理建议，并征求意见。否则，完成修复、重新验证、合并，并在阶段报告中注明最后这些修复未经评审即已合并。

只修复值得修复的问题。 所有值得修复的问题都必须修复。若某问题需要判断，且改动较小并属于本阶段范围，则予以修复；否则记录在计划中。不要处理细枝末节。一个问题可能指出多处缺陷；修复说明应逐一列出，修复必须涵盖全部缺陷。将各项修复分别提交，确保下一轮能看到。用一行说明跳过了哪些问题；悄无声息地遗漏问题，会让人以为这些问题从未存在。 **只有同时满足以下四项才合并：**最后一次修复提交后，快速检查通过；最后一次影响慢速检查的修复后，慢速检查通过；已运行所需轮次；没有待修复的问题，且 CI 为绿色。用一次阻塞调用等待 CI，不要循环轮询。如果 PR 落后于集成分支，先将集成分支合并进来并重新验证。使用合并提交，绝不压缩提交；各阶段的历史记录就是审计记录。GitHub 报告 PR 已合并后，删除阶段分支，并切回最新的集成分支。

每个阶段用一个代码块报告，然后开始下一阶段，无需询问，除非用户要求暂停。包括 PR 链接、已完成的任务、已修复和跳过的问题，以及运行过的内容。

**如果证明某个已锁定的决策有误，就停止构建。**指出该决策、代码显示的情况，以及它会使哪些后续阶段失效。由用户修改计划；绝不要悄悄绕开用户的选择重新规划。

**在最后严格按照计划运行一次演示。**所有阶段合并后，运行 ## Demo 并报告所见内容。none 表示跳过演示，直接创建最终 PR。如果你无法亲自运行，就把步骤交给用户并等待。绝不要编造演示，也不要每个阶段都安排一次演示。将所有延期、仅限用户执行的 Verify 步骤都加入交接内容。如果计划中没有 ## Demo（旧版计划），就询问并将答案记录到计划中，然后运行演示。若演示有问题，应通过负责该演示的阶段修复，并遵循相同的分支、审查和合并流程。

从集成分支向 main 创建最终 PR，内容包括功能摘要、各阶段的 PR、演示及其结果、仍未运行且延期的 Verify 步骤、用户可运行的命令，以及计划中的任何合并后步骤。如果 main 有更新，就将其合并进来并重新运行检查。然后停止；由用户合并该 PR。

需要留意的常见错误

• **用 ; 串联合并和删除分支。**合并卡住时，删除命令仍会运行，导致 PR 被关闭。
• **运行测试或 git fetch 时未设置 timeout。**命令卡住会一直阻塞调用，直到工具放弃。
• **在工作树中使用 cd /abs/worktree && 或 git -C。**隔离防护会拒绝这些命令；应从工作树根目录运行普通命令。
• **转述被截断的审查内容。**如果报告在某个问题中途结束，请向审查者索取剩余内容。