Skip to content

Superpowers 系列(八):交付边界

Agent 写完代码后,真正高风险的动作才刚开始:合并、推送、创建 PR、删除 worktree、清理分支。这些动作影响的不只是当前 diff,还会影响用户仓库和协作状态。

Superpowers 通过 using-git-worktreesfinishing-a-development-branch 把交付边界控制起来:改动在哪里发生,什么时候能集成,谁决定集成,什么可以清理,什么必须停下来问用户。

工作区隔离先解决归属问题

using-git-worktrees 的核心不是“会用 git worktree”,而是先判断当前是否已经处于隔离环境,再决定是否创建新的工作区。

它的顺序很讲究:

  1. 检测当前 Git 目录和 common dir。
  2. 排除 submodule 误判。
  3. 如果运行环境已有原生 worktree 能力,优先使用原生能力。
  4. 没有原生能力时,才回退到 Git worktree。
  5. 项目内 worktree 目录必须确认被 Git 忽略。
  6. 进入实现前运行项目 setup 和基线测试。

这个机制首先解决“这些改动属于谁”的问题。没有隔离,Agent 修改、用户未提交修改、仓库原有失败会混在一起,后续回滚和收尾都会变危险。

基线测试解决因果判断问题

实现前运行基线测试,看起来只是质量动作,其实它是因果边界。

如果基线已经失败,后续失败不一定由本次改动引入。如果基线通过,后续失败才更容易归因到新改动。没有基线,review 和 verification 会被一个问题困住:我们不知道红灯从什么时候开始红。

这也解释了为什么 worktree 和测试要放在同一个 Skill 里。隔离保证空间边界,基线保证时间边界。

分支收尾不是实现者的自由动作

finishing-a-development-branch 第一件事是重新运行完整测试。测试失败时,它不会展示合并或 PR 菜单,而是停下来报告失败。这个顺序直接来自 finishing-a-development-branch/SKILL.md 的收尾流程:先确认合并结果质量,再让用户选择集成方式。它防止用户在未知质量状态下做集成决策。

测试通过后,它会检测当前是普通仓库、命名 worktree,还是 detached HEAD。不同环境展示不同菜单:

  • 普通仓库或命名 worktree:本地合并、推送并创建 PR、保持分支。
  • detached HEAD:推送为新分支并创建 PR,或保持现状。

集成选择由用户决定。Agent 不应因为“看起来完成了”就自动合并,也不应因为“PR 已经开了”就清理工作区。

删除和清理必须有所有权判断

分支收尾里最敏感的是删除。Superpowers 的规则很保守:丢弃工作只在用户明确要求时发生,并且需要确认。worktree 清理也只在能判断归属时进行,例如位于 .worktrees/worktrees/ 下的工作区。

如果 worktree 删除被拒绝,因为里面还有未提交或未跟踪文件,Agent 不能 force remove。拒绝信息意味着那些文件可能只存在于那个工作区,强删会造成不可恢复损失。

这个设计的本质是:Agent 可以执行可恢复工程动作,但不可逆动作需要用户授权。

交付边界的结论

在 Superpowers 里,开发完成不等于交付完成。代码可以已经写完,测试也可以已经通过,但合并、推送、创建 PR、删除 worktree 仍然是另一类动作。

这些动作需要独立菜单、环境判断和用户选择。收尾流程不是“最后整理一下”,而是一组高权限动作的门禁。Superpowers 稳定的地方在于,它把最后一步也设计成流程,而不是一句“我帮你处理掉”。


参考资料

系列导航