SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场finishing-a-development-branch

finishing-a-development-branch

编程与开发

查看项目

更新于 10-16 08:54

技能介绍

用途

该技能用于开发收尾阶段：当代码实现完成、所有测试通过，并且需要决定如何集成这项工作（合并、发起 PR 或清理）时使用。它把收尾过程规范化为结构化步骤，减少随意提问和误操作。

主要能力

  • 在提供集成选项前，先运行项目测试套件验证测试结果。
  • 检测当前 Git 环境：普通 repo、具名分支 worktree，或 detached HEAD，并据此决定显示的菜单与清理方式。
  • 确定基础分支（通过 git merge-base 尝试 main/master，或向用户确认）。
  • 提供结构化选项并执行对应 Git 工作流。
  • 针对特定选项执行 workspace 清理，并运行 git worktree prune 自愈。

使用方式

开始时声明："I'm using the finishing-a-development-branch skill to complete this work."

流程按以下步骤进行：

Step 1：验证测试

提供选项前先验证测试通过，运行项目的测试套件，如：

# 运行项目的测试套件
npm test / cargo test / pytest / go test ./...

如果测试失败，必须显示失败信息并要求先修复，停止流程，不进入 Step 2。测试通过后继续。

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)

据此决定菜单与清理方式：

  • GIT_DIR == GIT_COMMON（普通 repo）：标准 4 个选项，没有要清理的 worktree。
  • GIT_DIR != GIT_COMMON，具名分支：标准 4 个选项，清理基于来源（见 Step 6）。
  • GIT_DIR != GIT_COMMON，detached HEAD：精简 3 个选项（无 merge），不清理（外部管理）。

Step 3：确定基础分支

# 尝试常见基础分支
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

或者询问："This branch split from main - is that correct?"

Step 4：提供选项

普通 repo 和具名分支 worktree 提供以下 4 个选项：

实现完成。你想怎么处理？

1. 在本地 merge 回 <base-branch>
2. Push 并创建 Pull Request
3. 保持分支原样（我稍后处理）
4. 丢弃这项工作

选择哪一项？

Detached HEAD 提供以下 3 个选项：

实现完成。你位于 detached HEAD（外部管理的 workspace）。

1. 作为新分支 push 并创建 Pull Request
2. 保持原样（我稍后处理）
3. 丢弃这项工作

选择哪一项？

选项保持简洁，不添加解释。

Step 5：执行选择

Option 1：本地 Merge

# 获取 main repo root，保证 CWD 安全
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

# 先 merge——删除任何东西前验证成功
git checkout <base-branch>
git pull
git merge <feature-branch>

# 验证 merge 后结果上的测试
<test command>

# 仅在 merge 成功后：清理 worktree（Step 6），然后删除分支

然后清理 worktree（Step 6），再删除分支：

git branch -d <feature-branch>

Option 2：Push 并创建 PR

# Push 分支
git push -u origin <feature-branch>

# 创建 PR
gh pr create --title "<title>" --body "$(cat <<'EOF'
## 总结
<2-3 条更改内容>

## 测试计划
- [ ] <验证步骤>
EOF
)"

不要清理 worktree，用户需要它保留，以便根据 PR 反馈迭代。

Option 3：保持原样

报告："Keeping branch . Worktree preserved at ."

不要清理 worktree。

Option 4：丢弃

先确认：

这将永久删除：
- Branch <name>
- 所有 commits：<commit-list>
- 位于 <path> 的 worktree

输入 'discard' 确认。

等待完全一致的确认。确认后：

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

然后清理 worktree（Step 6），再强制删除分支：

git branch -D <feature-branch>

Step 6：清理 Workspace

仅针对 Options 1 和 4 运行。Options 2 和 3 始终保留 worktree。

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)
WORKTREE_PATH=$(git rev-parse --show-toplevel)
  • 如果 GIT_DIR == GIT_COMMON：普通 repo，没有要清理的 worktree，完成。
  • 如果 worktree 路径位于 .worktrees/、worktrees/ 或 ~/.config/superpowers/worktrees/ 下：该 worktree 由 Superpowers 创建，由我们负责清理。
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"
git worktree remove "$WORKTREE_PATH"
git worktree prune  # 自愈：清理任何陈旧注册
  • 否则：宿主环境（harness）拥有这个 workspace，不要移除它。如果平台提供 workspace-exit 工具，就使用它；否则将 workspace 保留在原位。

选项快速参考

  • 1 本地 merge：执行 merge，不 push，不保留 worktree，清理分支。
  • 2 创建 PR：不 merge，执行 push，保留 worktree，不清理分支。
  • 3 保持原样：不 merge、不 push、保留 worktree、不清理分支。
  • 4 丢弃：不 merge、不 push、不保留 worktree，强制清理分支。

适用场景

  • 功能开发完成、测试通过后，决定集成方式。
  • 使用 git worktree 进行并行开发时，规范化收尾与清理。
  • 需要以结构化菜单避免开放式提问的自动化/智能体工作流。

限制与注意事项

  • 测试失败时不得继续 merge 或创建 PR，必须先修复。
  • 未在合并结果上验证测试就 merge 属于危险操作。
  • 未确认不得删除工作成果；Option 4 需要输入 'discard' 完全一致确认。
  • 未经明确请求不得 force-push。
  • 仅为 Options 1 和 4 清理 worktree；不得为 Option 2 清理，否则会移除用户 PR 迭代所需的 worktree。
  • 移除 worktree 前必须先删除分支会导致失败，应先在 worktree 仍引用分支时避免删除；正确顺序为先 merge、移除 worktree、再删除分支。
  • 在 worktree 内部运行 git worktree remove 会静默失败，必须先 cd 到 main repo root。
  • 不得清理 harness 拥有的 worktree，否则会导致幽灵状态；只清理 .worktrees/、worktrees/ 或 ~/.config/superpowers/worktrees/ 下的 worktree。
  • 移除后应运行 git worktree prune。