
Superpowers 实战用 finishing-a-development-branch 技能规范开发分支的合并、PR 与工作区清理【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers本篇技术文章以 Superpowers 框架中的finishing-a-development-branch技能文档为主体完整讲解它在实现完成、测试通过这一节点上的标准收尾流程先验证测试、再检测 git 环境、然后向人类伙伴呈现集成选项、执行选择最后按来源归属原则清理 worktree。读完后你将掌握一套可在任意 Agent 协作开发场景中复用的分支收尾方法论包括环境检测命令、合并/PR/保留/丢弃四种路径的具体命令序列以及防止误清理工作区的回归测试验证方式。技能定位开发流程的最后一环在 Superpowers 的技能体系中finishing-a-development-branch专门处理实现已完成、所有测试通过、需要决定如何集成这些工作的场景见 SKILL.md 的 frontmatter 描述。它的核心原则被概括为一句话Verify tests → Detect environment → Present options → Execute choice → Clean up.验证测试 → 检测环境 → 呈现选项 → 执行选择 → 清理并且要求在启动时明确宣告Im using the finishing-a-development-branch skill to complete this work.我正在使用 finishing-a-development-branch 技能完成这项工作。从源码结构看它是整个开发流程图的终点节点executing-plans 的 Step 3Complete Development规定所有任务完成并验证后必须宣告并使用superpowers:finishing-a-development-branch按其流程验证测试、呈现选项、执行选择subagent-driven-development 的 Finish 阶段在最终整分支评审Final Review通过后先删除该计划的工作区目录rm -rf workspacegit 历史此时已是唯一记录随后同样进入Use superpowers:finishing-a-development-branchREADME.md 也将它列为标准流程之一Activates when tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.也就是说本技能既是计划执行和子代理驱动开发两条路径的公共收尾出口也是集成决策权从 Agent 交还给人类伙伴的正式节点。Step 1: Verify Tests验证测试第一步是运行项目的完整测试套件npm test/cargo test/pytest/go test ./...且规则是刚性的测试失败则报告失败项并停止——选项菜单menu只出现在绿色套件之后。文档中给出的报告格式为Tests failing (N failures). Must fix before completing: [Show failures]测试通过才继续进入 Step 2。这一条对应技能末尾Common Rationalizations表中最重要的反驳之一Tests passed earlier this session本会话早些时候测试是过的——现实是必须在你即将集成的这棵树上运行套件。一次绿色运行只能证明它当时运行的那棵树不能证明合并后的结果。Step 2: Detect Environment检测环境进入收尾阶段后先用三条只读 git 命令确定自己处于什么工作区形态GIT_DIR$(cd $(git rev-parse --git-dir) 2/dev/null pwd -P) GIT_COMMON$(cd $(git rev-parse --git-common-dir) 2/dev/null pwd -P) # Capture now, while still inside the workspace — Step 5 changes directory # before cleanup (Step 6) needs this value WORKTREE_PATH$(git rev-parse --show-toplevel)注意注释中的关键细节WORKTREE_PATH必须在进入工作区时立刻捕获因为 Step 5执行选择会先改变目录而 Step 6清理要用这个值——不能事后重查。三个值的组合决定了菜单形态和清理方式状态菜单清理方式GIT_DIR GIT_COMMON普通仓库标准 3 选项没有 worktree 需要清理GIT_DIR ! GIT_COMMON命名分支标准 3 选项按来源归属处理见 Step 6GIT_DIR ! GIT_COMMONdetached HEAD精简 2 选项无 merge外部托管——原地保留这套用 git 原语检测状态、而不是嗅探平台环境变量的设计来自 Superpowers 的 worktree 重构rototill设计文档 2026-04-06-worktree-rototill-design.md。该文档明确了设计原则Detect state, not platform用GIT_DIR ! GIT_COMMON判断我是否已在 worktree 中而非检测环境变量识别是哪个 harness——这是 git 2.52015 年起就稳定的原语跨平台通用且新 harness 出现时无需维护。设计文档同时解释了为什么 detached HEAD 状态必须去掉 merge 选项无法从 detached HEAD 发起合并。using-git-worktrees 的 Step 0 还补充了一个收尾场景同样值得注意的防护——submodule guardGIT_DIR ! GIT_COMMON在 git 子模块内部也为真所以判断是否 worktree前应先执行git rev-parse --show-superproject-working-tree有返回路径说明你在子模块而非 worktree应当作普通仓库处理。codex-tools.md 的平台参考也复用同一组检测命令并说明 Codex App 沙箱detached HEAD、外部托管 worktree下 Agent 应改为提交全部工作后引导用户走 App 的原生Create branch/Hand off to local控件。Step 3: Determine Base Branch确定基础分支基础分支就是本次工作所分叉的那个分支——通常已在计划文档、对话上下文或分支的 upstream 中被指明。如果尚不清楚就问This branch split from — is that correct?这个分支是从 你的最佳猜测 分出来的——对吗文档强调合并前必须确认合错基础分支的代价是昂贵到难以撤销merging into the wrong base is expensive to undo。这一条同样出现在 Rationalizations 表里专门反驳 The base branch is obviously main基础分支显然是 main这种偷懒推断。Step 4: Present Options呈现选项菜单必须逐字照写Present the menu exactly as written每个选项都来自文档给出的固定列表Agent 不得自行增删——尤其是不得主动提供丢弃选项见下节专项说明。普通仓库与命名分支 worktree —— 恰好呈现这 3 个选项Implementation complete. What would you like to do? 1. Merge back to base-branch locally 2. Push and create a Pull Request 3. Keep the branch as-is (Ill handle it later) Which option?Detached HEAD —— 恰好呈现这 2 个选项Implementation complete. Youre on a detached HEAD (externally managed workspace). 1. Push as new branch and create a Pull Request 2. Keep as-is (Ill handle it later) Which option?呈现后等待人类回答——集成决策权属于人类伙伴。文档的原文表述是Discarding the work happens only in response to your human partner explicitly asking for it.丢弃工作只会发生在人类伙伴明确提出要求时。Step 5: Execute Choice执行选择Option 1: Merge Locally本地合并# Get main repo root for CWD safety MAIN_ROOT$(git -C $(git rev-parse --git-common-dir)/.. rev-parse --show-toplevel) cd $MAIN_ROOT # Merge first — verify success before removing anything git checkout base-branch git pull git merge feature-branch # Verify tests on merged result test command两个要点值得注意CWD 安全先通过git-common-dir反推出主仓库根目录再cd因为合并操作必须发生在主仓库而非 worktree 内顺序保证先合并、验证成功之后才允许删除任何东西Merge first — verify success before removing anything。合并结果测试失败时停止保留 worktree 和分支原样展开调查——此时还没有任何 push合并是纯本地的、可恢复的。合并结果变绿后先执行 Step 6 清理 worktree再删除分支git branch -d feature-branchOption 2: Push and Create PR推送并创建 PRgit push -u origin feature-branch # From a detached HEAD, name the new branch on the remote: # git push origin HEAD:refs/heads/new-branch随后用托管平台forge的工具对base-branch创建 PR/MR——有 CLI 用 CLI没有就用多数 forge 在 push 时打印的创建 URL——若仓库存在 PR 模板与约定则遵循并把 URL 报告给人类伙伴。保留 worktree——人类伙伴会在该 worktree 里迭代处理 PR 评审反馈。Rationalizations 表专门反驳了 The PR is up, so the worktree is clutter nowPR 已经开了worktree 现在是杂物这种直觉PR feedback gets fixed in that worktree. It stays until the work lands.PR 反馈就在那个 worktree 里修。它留到工作落地为止。Option 3: Keep As-Is保持原样报告一句即可Keeping branch . Worktree preserved at.If your human partner asks to discard the work仅当人类明确要求丢弃丢弃路径只作为对明确丢弃请求的响应而存在且必须先确认——把将永久删除的内容逐项列出This will permanently delete: - Branch name - All commits: commit-list - Worktree at path Type discard to confirm.等待精确的确认词。文档规定只有输入的单词discard才授权删除——Yeah, get rid of it 这类口语化同意不算数。确认到达后MAIN_ROOT$(git -C $(git rev-parse --git-common-dir)/.. rev-parse --show-toplevel) cd $MAIN_ROOT然后执行 Step 6 清理 worktree并强制删除分支git branch -D feature-branch注意这里用git branch -D强删区别于 Option 1 中合并完成后的安全删除git branch -d。Step 6: Cleanup Workspace清理工作区本步只在 Option 1 和已确认的丢弃时运行Option 2 和 Option 3 永远保留 worktree。两个调用方此时都已cd到主仓库根——worktree 移除必须从 worktree 外部执行——并且使用的是 Step 2 中捕获的GIT_DIR/GIT_COMMON/WORKTREE_PATH值在目录改变之前捕获的。分三种情况情况一GIT_DIR GIT_COMMON。普通仓库没有 worktree 需要清理结束。情况二WORKTREE_PATH位于.worktrees/或worktrees/之下。Superpowers 自己创建了该 worktree因此拥有清理权git worktree remove $WORKTREE_PATH git worktree prune # Self-healing: clean up any stale registrations情况三其他位置。宿主环境拥有该工作区——原地保留。若平台提供退出工作区的工具则使用它。这里的判定标准就是 rototill 设计文档中的Provenance-based ownership来源归属所有权原则Whoever creates the worktree owns its cleanup.谁创建 worktree谁负责清理。Superpowers 创建的落在.worktrees/或worktrees/下由 Superpowers 清理harness 创建的如.claude/worktrees/、~/.codex/worktrees/、.gemini/worktrees/或旧的用户全局路径则一律不碰。这条所有权边界还有一条可执行的回归测试保障tests/claude-code/test-worktree-path-policy.sh 会断言finishing-a-development-branch技能文件1不再提及旧的全局路径~/.config/superpowers/worktrees2仍然保留 .worktrees/orworktrees/ 的项目本地清理所有权表述确保重构演进中不会把别人的工作区误删。Quick Reference速查表选项合并推送保留 Worktree清理分支1. 本地合并yes--yes2. 创建 PR-yesyes-3. 保持原样--yes-丢弃仅限明确要求---yes强删Common Rationalizations九种典型越界冲动与纠正技能文档最有方法论价值的部分是它预先列举了 Agent 在收尾阶段的九种合理化借口并逐条给出事实性纠正。完整继承如下借口现实Tests passed earlier this session本会话早些时候测试通过过在你即将集成的树上运行套件。绿色运行只证明它当时运行过的那棵树。They obviously want it merged他们显然想合并集成是人类伙伴的决定。呈现菜单并等待。They seem done with this feature — Ill offer to discard it他们好像用完这个功能了——我主动提议丢弃吧菜单按原文就是完整的。丢弃只发生在人类伙伴原话提出时。Yeah, get rid of it counts as confirmation是啊扔了吧也算确认只有输入的单词discard授权删除。The PR is up, so the worktree is clutter nowPR 开了worktree 就是杂物了PR 反馈就在那个工作区里修。它留到工作落地。This other worktree looks stale — Ill clean it too另一个 worktree 看起来过期了——顺手清掉只清理.worktrees/或worktrees/下的 worktree。其余的属于宿主。The merged-result failure is probably flaky合并结果失败大概是偶发抖动合并结果失败就停止一切。分支和 worktree 保持原样直到调查清楚。The base branch is obviously main基础分支显然是 main确认分叉点或开口问。合错基础分支难以撤销。The push was rejected — force-push will fix itpush 被拒——force-push 能修好push 被拒意味着远端移动了。先调查force-push 只在人类伙伴明确要求时进行。这张表本质上是把权限边界写成了可检查的行为规则测试门禁、决策权归属、确认词字面匹配、清理所有权范围——每一条都可以被测试或评审直接核验。适用前提与延伸阅读需要说明的前提本文所述流程绑定 Superpowers 的技能文档Markdown 指令文件它约束的是运行在 Claude Code、Codex、Gemini CLI 等 harness 中的 Agent而非直接运行给人类的脚本base-branch、feature-branch、test command等占位符需在具体项目中替换。工作区创建侧的完整规则同意询问、原生工具优先、git check-ignore安全检查等见 skills/using-git-worktrees/SKILL.md环境检测与 Codex App 沙箱收尾见 skills/using-superpowers/references/codex-tools.md设计动机与决策记录见 docs/superpowers/specs/2026-04-06-worktree-rototill-design.md 与 docs/superpowers/plans/2026-04-06-worktree-rototill.md行为回归测试见 tests/claude-code/test-worktree-path-policy.sh。【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考