# Finishing A Development Branch

> 在实现完成、所有测试通过且需要决定如何集成工作时使用 - 通过提供 merge、PR 或清理的结构化选项来指导开发工作的完成

- Skill: `vinvcn/finishing-a-development-branch` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vinvcn/finishing-a-development-branch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vinvcn/finishing-a-development-branch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vinvcn (https://skillmd.com/u/vinvcn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vinvcn/finishing-a-development-branch

---


# 完成开发分支

## 概览

通过提供清晰选项并处理所选工作流来指导开发工作的完成。

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

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

## 流程

### Step 1: 验证测试

**提供选项前，验证测试通过：**

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

**如果测试失败：**
```
测试失败（<N> 个失败）。完成前必须修复：

[显示失败]

测试通过前，不能继续 merge/PR。
```

停止。不要继续 Step 2。

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

### Step 2: 检测环境

**提供选项前，确定 workspace 状态：**

```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)
```

这会决定显示哪个菜单，以及清理如何工作：

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

### Step 3: 确定基础分支

```bash
# 尝试常见基础分支
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

```bash
# 获取 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），再删除分支：

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

#### Option 2: Push 并创建 PR

```bash
# 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 <name>. Worktree preserved at <path>."

**不要清理 worktree。**

#### Option 4: 丢弃

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

输入 'discard' 确认。
```

等待完全一致的确认。

如果已确认：
```bash
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"
```

然后：清理 worktree（Step 6），再强制删除分支：
```bash
git branch -D <feature-branch>
```

### Step 6: 清理 Workspace

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

```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)
WORKTREE_PATH=$(git rev-parse --show-toplevel)
```

**如果 `GIT_DIR == GIT_COMMON`：** 普通 repo，没有要清理的 worktree。完成。

**如果 worktree 路径位于 `.worktrees/`、`worktrees/` 或 `~/.config/superpowers/worktrees/` 下：** Superpowers 创建了这个 worktree——我们负责清理。

```bash
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 保留在原位。

## 快速参考

| 选项 | Merge | Push | 保留 Worktree | 清理分支 |
|--------|-------|------|---------------|----------------|
| 1. 本地 merge | yes | - | - | yes |
| 2. 创建 PR | - | yes | yes | - |
| 3. 保持原样 | - | - | yes | - |
| 4. 丢弃 | - | - | - | yes（force） |

## 常见错误

**跳过测试验证**
- **问题：** Merge 损坏的代码，创建失败的 PR
- **修复：** 提供选项前始终验证测试

**开放式问题**
- **问题：** "What should I do next?" 含糊不清
- **修复：** 准确提供 4 个结构化选项（detached HEAD 则为 3 个）

**为 Option 2 清理 worktree**
- **问题：** 移除了用户进行 PR 迭代所需的 worktree
- **修复：** 仅为 Options 1 和 4 清理

**移除 worktree 前删除分支**
- **问题：** `git branch -d` 失败，因为 worktree 仍引用该分支
- **修复：** 先 merge，移除 worktree，再删除分支

**在 worktree 内部运行 git worktree remove**
- **问题：** 当 CWD 位于要移除的 worktree 内时，命令会静默失败
- **修复：** 在 `git worktree remove` 前始终 `cd` 到 main repo root

**清理 harness 拥有的 worktree**
- **问题：** 移除 harness 创建的 worktree 会导致幽灵状态
- **修复：** 只清理 `.worktrees/`、`worktrees/` 或 `~/.config/superpowers/worktrees/` 下的 worktree

**丢弃时没有确认**
- **问题：** 意外删除工作
- **修复：** 要求输入 "discard" 确认

## 危险信号

**绝不要：**
- 在测试失败时继续
- 未在结果上验证测试就 merge
- 未确认就删除工作
- 未明确请求就 force-push
- 确认 merge 成功前移除 worktree
- 清理不是你创建的 worktree（来源检查）
- 从 worktree 内部运行 `git worktree remove`

**始终：**
- 提供选项前验证测试
- 展示菜单前检测环境
- 准确提供 4 个选项（detached HEAD 则为 3 个）
- 为 Option 4 获取输入确认
- 仅为 Options 1 和 4 清理 worktree
- 移除 worktree 前 `cd` 到 main repo root
- 移除后运行 `git worktree prune`