入门 约 20 分钟 2026-10-11 02:26:00 · 28 阅读

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 里,用途是让你在会话里能一眼确认技能确实触发了——如果代理干完活一声不吭直接开始合并,那就是没走这套流程。

finishing-a-development-branch 六步收尾流程图

六步收尾流程全貌:从验测试到清理工作区,依据官方 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 原文:第五步会先切到主仓库根目录,等清理时再取路径就取错了,所以三个值必须现在就存好。

三态环境判定表:普通仓库、命名分支 worktree、detached HEAD 分别对应的菜单与清理策略

三态环境判定:探测结果决定菜单形态与清理策略的对照表

三种状态的判定逻辑: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,而是问自己那份没提交的东西还要不要。

实测终端输出:普通仓库收尾流程与 worktree 清理被拒报错

本机实测记录:两个场景的真实终端输出,命令序列逐字引自 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 快照),实测部分为本机临时仓库记录,版权归原作者所有。

评论 (0)