# Finishing A Development Branch

当实现完成、所有测试通过、需要决定如何集成这份工作时使用

- Repository: https://github.com/jnMetaCode/superpowers-zh (8437 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-26
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add jnMetaCode/superpowers-zh --skill finishing-a-development-branch -g -a claude-code -y`
Codex: `npx skills add jnMetaCode/superpowers-zh --skill finishing-a-development-branch -g -a codex -y`
Cursor: `npx skills add jnMetaCode/superpowers-zh --skill finishing-a-development-branch -g -a cursor -y`
Gemini CLI: `npx skills add jnMetaCode/superpowers-zh --skill finishing-a-development-branch -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add jnMetaCode/superpowers-zh`

## Description

当实现完成、所有测试通过、需要决定如何集成这份工作时使用

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 收尾一个开发分支

## 概述

**核心原则：** 验证测试 → 检测环境 → 展示选项 → 执行选择 → 清理。

**开始时宣告：** "我正在使用 finishing-a-development-branch 技能来收尾这份工作。"

## 步骤 1：验证测试

运行项目的完整测试套件（`npm test` / `cargo test` / `pytest` / `go test ./...`）。

**如果测试失败**，报告失败并停下, , 菜单是在测试全绿之后才出现的：

```
测试失败（<N> 个）。完成之前必须先修：

[展示失败详情]
```

**如果测试通过：** 继续步骤 2。

## 步骤 2：检测环境

```bash
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)
# 现在就捕获, , 此刻还在工作区里面。步骤 5 会切换目录，
# 而清理（步骤 6）需要这个值
WORKTREE_PATH=$(git rev-parse --show-toplevel)
```

这决定了展示哪种菜单、以及清理方式：

| 状态 | 菜单 | 清理 |
|------|------|------|
| `GIT_DIR == GIT_COMMON`（普通仓库） | 标准 3 个选项 | 无 worktree 可清理 |
| `GIT_DIR != GIT_COMMON`，命名分支 | 标准 3 个选项 | 按来源判断（见步骤 6） |
| `GIT_DIR != GIT_COMMON`，分离 HEAD | 收敛为 2 个选项（不含合并） | 由外部管理, , 原地别动 |

## 步骤 3：确定基础分支

基础分支就是这份工作从哪儿分出来的那个, , 通常在计划里、对话里，或者分支的 upstream 里已经写明了。如果还不知道，就问："这个分支是从 <你的最佳猜测> 分出来的，对吗？"**合并之前先确认：合并到错误的基础分支，代价很高。**

## 步骤 4：展示选项

**普通仓库和命名分支 worktree, , 精确展示这 3 个选项：**

```
实现已完成。你想怎么做？

1. 本地合并回 <base-branch>
2. 推送并创建 Pull Request
3. 保留分支不动（我稍后自己处理）

选哪个？
```

**分离 HEAD, , 精确展示这 2 个选项：**

```
实现已完成。你当前处于分离 HEAD（由外部管理的工作区）。

1. 作为新分支推送并创建 Pull Request
2. 保持原样（我稍后自己处理）

选哪个？
```

**照原文展示菜单**, , 简洁，每个选项都来自上面的列表。**丢弃工作只在你的人类伙伴明确提出时才发生**（见下方"如果你的人类伙伴要求丢弃这份工作"）。等他们回答；集成与否是他们的决定。

## 步骤 5：执行选择

### 选项 1：本地合并

```bash
# 切到主仓库根目录，保证 CWD 安全
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

# 先合并, , 在删除任何东西之前先验证合并成功
git checkout <base-branch>
git pull
git merge <feature-branch>

# 在合并结果上验证测试
<测试命令>
```

如果测试在**合并结果**上失败：停下，把 worktree 和分支原地留着，去排查, , 什么都还没推送，所以这次合并是本地的、可恢复的。

一旦合并结果全绿：清理 worktree（步骤 6），然后删除分支：

```bash
git branch -d <feature-branch>
```

### 选项 2：推送并创建 PR

```bash
git push -u origin <feature-branch>
# 从分离 HEAD 出发时，在远端指定新分支名：
# git push origin HEAD:refs/heads/<new-branch>
```

The rest: https://github.com/jnMetaCode/superpowers-zh/blob/HEAD/skills/finishing-a-development-branch/SKILL.md