finishing-a-development-branch Agent Skill 实战教程:安装配置与 9 个核心用法
finishing-a-development-branch Agent Skill 实战教程:安装配置与 9 个核心用法
代码写完、测试全绿,接下来合回主干还是发 PR?obra/superpowers 仓库(GitHub 29.7 万 star,MIT 协议)把这件收尾小事写成了一门手艺:finishing-a-development-branch 技能会在实现完成时先验测试、再探测环境,然后原样弹出一个三选项菜单等你拍板——整合的决定权永远在人类手里。这篇教程覆盖安装挂载、六步收尾流程、三态环境判定、三个执行选项、工作区清理与实测记录,末尾是官方文档里白纸黑字的十条「自我合理化」对照表。
相关背景可参考 AI 编程总纲,工具档案见 Superpowers 产品页。同仓库的 brainstorming、diagnosing-superpowers 两篇实战已在站内上线,可搭配阅读。
这套技能解决什么问题
编码代理干完活之后最常见的两种翻车:一种是自作主张把分支合了、甚至删了,你的半成品连商量都没得商量;另一种是问一句「接下来怎么办」,然后陷入漫长的来回确认。SKILL.md 给出的解法是一个固定次序:Verify tests → Detect environment → Present options → Execute choice → Clean up。测试不绿不谈整合,菜单只弹一次、逐字按原文弹,你选完它执行,执行完清理自己开的工作区。
技能开始工作前还有一条明确的自我声明,要求代理先播报:
“I'm using the finishing-a-development-branch skill to complete this work.”
这句写在 SKILL.md 的 Overview 里,用途是让你在会话里能一眼确认技能确实触发了——如果代理干完活一声不吭直接开始合并,那就是没走这套流程。

六步收尾流程全貌:从验测试到清理工作区,依据官方 SKILL.md 绘制
安装与挂载
Superpowers 是一整套技能库,finishing-a-development-branch 是其中之一,安装整库即可(技能由代理按场景自动触发,不需要单独装)。官方 README 列出了 Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Hermes Agent 等十余种宿主的安装方式,各宿主要分别安装。Claude Code 走官方插件市场一行命令:
/plugin install superpowers@claude-plugins-official
OpenCode 用户在会话里直接说一句即可:
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
Hermes Agent 的装法是 hermes plugins install obra/superpowers --enable,装完重启会话生效。README 同时提醒了一个已知局限:Hermes 没有 post-compaction 钩子,超长会话压缩过首轮对话后会丢掉引导指令——技能不触发了就开个新会话。装好后不需要任何配置文件,技能全靠触发条件自动生效。
用法一:验测试,绿了才谈整合
收尾第一步永远是跑全量测试套件(npm test / cargo test / pytest / go test ./...,按项目实际栈选)。测试挂了就报告失败并停下,SKILL.md 给了固定的报告格式:
Tests failing (<N> failures). Must fix before completing:
[Show failures]
这个顺序没法绕:菜单只在绿灯之后出现。官方文档里专门列了一条对应的「合理化借口」——“Tests passed earlier this session”(这个会话早些时候测试是过的)——反驳原文是:A green run only proves the tree it ran on,绿色的测试结果只证明跑它的那棵树,不证明你即将整合的这棵。
用法二:探测环境,两条命令定分岔
第二步用一组命令捕获三个环境变量,后续弹哪种菜单、怎么清理,全由这三个值决定:
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)
注意中间那两行注释是 SKILL.md 原文:第五步会先切到主仓库根目录,等清理时再取路径就取错了,所以三个值必须现在就存好。

三态环境判定:探测结果决定菜单形态与清理策略的对照表
三种状态的判定逻辑:GIT_DIR == GIT_COMMON 是普通仓库,弹标准三选项,没有 worktree 要清;两者不等且当前是命名分支,说明你在 Superpowers 自己开的 worktree 里,同样弹三选项,但清理时按路径归属处理;两者不等且处于 detached HEAD,那是外部环境托管的工作区,菜单缩减为两选项(没有本地合并项),清理环节原样保留不碰。
用法三:确认基线分支
基线分支就是这个工作从哪分叉的——通常写在计划里、对话里,或者分支的上游配置里。要是都对不上,SKILL.md 要求直接问:“This branch split from <your best guess> - is that correct?”,确认之后才准合并。原文给的理由很直白:merging into the wrong base is expensive to undo,合错基线的撤销代价很高。对照表里也有一条对应借口「The base branch is obviously main」——「显然是 main」不构成确认的理由。
用法四:菜单逐字弹,整合权在你
普通仓库和命名分支 worktree 弹的是一模一样的三选项:
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 (I'll handle it later)
Which option?
detached HEAD 场景缩减为两选项:
Implementation complete. You're on a detached HEAD (externally managed workspace).
1. Push as new branch and create a Pull Request
2. Keep as-is (I'll handle it later)
Which option?
官方要求 Present the menu exactly as written——菜单逐字按原文呈现,选项一个不多一个不少,然后等你的答复。丢弃工作这条路不在菜单里,只在你明确提出要丢弃时才会走,而且要先确认。这正是技能的设计核心:整合的决定是人做的,代理只负责执行。
用法五:三个选项各自怎么执行
选项 1 本地合并的命令序列(节选):
# 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>
注意最后一步:合完要在合并结果上把测试再跑一遍。合并后测试挂了就停下,worktree 和分支都保持原样等排查——什么都没推远端,本地合并完全可恢复。全绿之后才走第六步清理,再删分支 git branch -d <feature-branch>。
选项 2 推送建 PR:先 git push -u origin <feature-branch>(detached HEAD 场景用 git push origin HEAD:refs/heads/<new-branch> 给新分支命名),然后用托管平台的工具建 PR——有 CLI 用 CLI,没有就用 push 时平台打印的创建链接,遵循仓库的 PR 模板,把 URL 报给你。这个选项下 worktree 保留不删,官方说法是 PR feedback gets fixed in that worktree,评审意见还要回到这个工作区里改。
选项 3 保持现状只做一件事,报告一句:“Keeping branch <name>. Worktree preserved at <path>.”
用法六:丢弃要走显式确认
只有你明确要求丢弃时,技能才会先展示将要永久删除的内容:
This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>
Type 'discard' to confirm.
确认词是逐字输入的 discard,SKILL.md 原文写明 Only the typed word `discard` authorizes deletion——「嗯删了吧」不算数。确认后清理 worktree,再用 git branch -D <feature-branch> 强删分支。
用法七:按出处清理工作区
第六步清理只对选项 1 和确认过的丢弃执行,选项 2、3 永远保留 worktree。判定逻辑分三档:GIT_DIR == GIT_COMMON 是普通仓库,没有 worktree 要清,直接结束;WORKTREE_PATH 在 .worktrees/ 或 worktrees/ 目录下的,是 Superpowers 自己开的,负责清理:
git worktree remove "$WORKTREE_PATH" git worktree prune # Self-healing: clean up any stale registrations
其余情况一律视为外部环境管理的目录,原样保留。要是 remove 被拒,说明 worktree 里有从未提交的文件——计划、笔记、草稿——它们只存在于那里。官方指令是绝不能自行加 --force,先用 git -C "$WORKTREE_PATH" status --porcelain -uall 列出文件给你看,再给你三个选择:提交进分支、移到主仓库根目录、或删除(不可恢复)。
实测:在真实 Git 仓库走一遍
以下输出是本机在临时 Git 仓库里按 SKILL.md 命令序列实测的结果,两个场景:普通仓库的完整收尾,以及 worktree 清理被拒的真实报错。
场景一,普通仓库的 feature/sub 分支收尾。Step 1 先跑测试:
$ python3 -m unittest discover -v test_add (test_calc.T.test_add) ... ok test_sub (test_calc.T.test_sub) ... ok ---------------------------------------------------------------------- Ran 2 tests in 0.000s OK
Step 2 探测环境,普通仓库里两个值相同:
$ 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) $ echo "$GIT_DIR / $GIT_COMMON" /tmp/tedit_fdb_repo2/.git /tmp/tedit_fdb_repo2/.git
命中普通仓库一档:标准三选项菜单。人选了选项 1 之后,合并、复测、删分支一气呵成:
$ git checkout main; git merge feature/sub Updating 317f60d..641c4f2 Fast-forward calc.py | 3 +++ test_calc.py | 5 ++++- $ python3 -m unittest discover 2>&1 | tail -1 OK $ git branch -d feature/sub Deleted branch feature/sub (was 641c4f2).
场景二,worktree 清理被拒。在 .worktrees/feature-scratch 里留了一个未提交的 notes.txt,直接 remove 会拿到 git 的原话拒绝:
$ git worktree remove .worktrees/feature-scratch fatal: '.worktrees/feature-scratch' contains modified or untracked files, use --force to delete it $ git -C .worktrees/feature-scratch status --porcelain -uall ?? notes.txt
这正是 SKILL.md 那条「removal refused」分支描述的情形——拒绝意味着有文件只存在于这个 worktree 里。按菜单选项 1 先提交进分支再清理,remove 和 prune 都无输出即成功。这个报错本身就值得记住:见到它第一反应不该是加 --force,而是问自己那份没提交的东西还要不要。

本机实测记录:两个场景的真实终端输出,命令序列逐字引自 SKILL.md
速查表与十条「自我合理化」
SKILL.md 末尾的 Quick Reference 把四个去向压缩成一张表:本地合并动 Merge 和分支清理;建 PR 动 Push 并保留 worktree;保持现状全部不动;丢弃只响应显式请求且强删分支。
更有意思的是 Common Rationalizations 一节,官方直接把代理可能找的十条借口连反驳一起列成了表:「测试早些时候过了」不对,绿色只证明跑过的那棵树;「他们显然想合」不对,整合是人的决定;「PR 都开了 worktree 就是杂物了」不对,评审意见就在那个工作区里改;「删不掉加 --force 就好了」不对,拒绝就意味着有文件只在那里存在。遇到代理行为可疑时,对着这张表查是定位问题最快的办法。
写在最后
这套技能的价值不在命令本身——git merge 谁都会敲——而在它把「谁有权决定整合」这件事写死了:代理验完测试、探完环境、弹出菜单,然后停下来。配合同仓库的 brainstorming(动手前先磨设计)和 receiving-code-review(评审反馈先核实再动手),一个特性从立意、实现到收尾的完整链路就都有章可循了。
本文步骤与配图依据 obra/superpowers 官方 SKILL.md 与 README 整理(2026-10 快照),实测部分为本机临时仓库记录,版权归原作者所有。