# Finish Branch

> 当一段开发完成，要给当前分支 / worktree 收尾时使用——如"收尾、把这个分支收掉、开发完了怎么处理、合并还是留着"。通常由 execute-task 执行完后调用。先只读预检状态，再清除本次开发遗留的调试代码、跑最终测试，然后给出合并/本地保留/创建 PR/丢弃选项；提交、合并、推送、删除与移除工作树都交用户拍板。不要用于：开发还没完、建立工作区（那是 setup-worktree）。

- Skill: `rollrollroll/finish-branch` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add rollrollroll/finish-branch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rollrollroll/finish-branch/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: RollRollRoll (https://skillmd.com/u/rollrollroll)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/rollrollroll/finish-branch

---


# Finish Branch — 开发收尾 Skill

## 你的任务

一段开发**实现完成**后，给当前分支 / worktree **收尾**：先只读预检状态，再清理调试残留并跑最终测试，最后给出
"合并 / 本地保留 / 创建 PR / 丢弃"的选项，把**破坏性与对外操作交用户拍板**，最后清理。

这是 agent-toolkit 的 **composable 层**能力单元，通常由 workflow 层的 execute-task（阶段 4）执行完后调用，
也可被任何"开发完了、该怎么收口"的场景单独复用。它负责"收尾决策 + 清理"——
**建立工作区交 setup-worktree**（职责分离）。

> 一句话：代码写完、测试绿了，在这里决定这段工作的去向（合并 / 留着 / PR / 丢弃），并收拾干净。

## 调用契约

**传入**

- **最终验证命令**：项目约定的完整验收怎么跑。
- **本次开发范围**（可选）：用于判断哪些调试残留是本次引入的；不给就只清能确认的部分。
- **调用来源**：由 execute-task 调用时要一并说明——清理若产生代码改动，必须回它的阶段 3 重做整体验收。

**取回**

- 状态预检结论（分支 / worktree / 暂存与未跟踪状态、与主干的领先落后）。
- 清理了什么、最终测试结果、用户选定的收尾方式与**已执行的动作**。
- 未获授权的动作停在该动作之前并如实报告，不代替用户决定。

**本 skill 不做**

- 测试没过不收尾；不自动 commit / merge / push / 开 PR / 删分支 / 移除 worktree——每项单独取得确认。
- 不自动 stash、`git clean` 或静默丢弃来制造"干净状态"。
- 不建立工作区（那是 **setup-worktree**）、不做代码审查（那是 **review-changes**）。

## 何时用 / 何时不用

**适用**：

- 一段开发完成、测试通过，要决定分支怎么处理。
- execute-task 整体验收通过后的收尾。
- 在 worktree 里干完活，要合并回去并清理 worktree。

**不适用**：

- 开发还没完 / 测试还没过 —— 先回去做完、修绿，别提前收尾。
- 要建立隔离工作区 —— 那是 setup-worktree。

## 核心流程（状态预检 → 清理调试残留 → 最终验证 → 给选项 → 授权执行）

1. **先做只读状态预检**：
   - 确认当前分支、是否位于 worktree，以及暂存 / 未暂存 / 未跟踪状态。
   - 入场时已有任何非忽略改动 → 展示摘要并停止，让用户决定；**不得先清理、提交、stash 或丢弃**，避免把用户改动混进收尾。
2. **清理本次开发的调试残留**：
   - 检查本次 diff 中的临时日志、调试打印、断点、临时开关和只为排查问题加入的代码。
   - 只清理能确认由本次开发引入的残留；用途不明确时先问用户，不顺手改无关代码。
   - 清理必须发生在最终测试之前，避免拿"清理前的绿灯"当成最终结果。
3. **跑最终测试并确认全绿**：按项目约定执行完整验收。**不绿不收尾**——回去修，修完重新跑最终测试。
4. **复核 repo / worktree 状态**：
   - 清理产生改动 → 展示 diff，取得明确提交授权后再提交；提交后重新确认状态干净。
   - 若由 execute-task 调用且清理产生了代码改动，必须回到 execute-task 阶段 3 重新做整体验收，不能沿用清理前的 review 结论。
   - 与主干的关系（领先 / 落后多少 commit）。
5. **给出收尾选项（交用户拍板）**：
   - **合并到主干**：merge 回主分支。
   - **本地保留**：留在分支，暂不合并。
   - **创建 PR**：推送并开 PR。
   - **丢弃**：放弃这段工作（删分支 / worktree）——**不可逆**。
6. **取得对应授权后执行**：
   - `git commit`、合并、push、创建 PR、删分支都必须在执行前取得用户对具体动作的明确确认。
   - 即使代码已经合并或决定丢弃，`git worktree remove` 也要单独确认；不要把"选择合并"理解为同时授权移除工作树。
   - 本地保留只报告分支 / worktree 路径和状态，不做隐含提交或清理。

## 注意事项与危险操作 gate

- **⚠️ 状态变更必须用户明确确认，不自动做**：提交、合并、push、创建 PR、删分支、丢弃、移除 worktree——遵循当前仓库 `CLAUDE.md` / `AGENTS.md` 与平台审批策略。
- **测试没过不进收尾**：先回去修绿。
- **测试必须晚于调试清理**：任何清理或修复都会使之前的测试结果失效，必须重跑。
- **整体验收也会失效**：execute-task 整体验收后若又清理出代码改动，必须回阶段 3 重审。
- **丢弃不可逆**：删分支前**二次确认**；移除 worktree 前也要明确确认。
- **先检测再动手**：状态没看清（在错分支、漏了未提交改动）就操作，容易误伤。
- **禁止隐式兜底**：不使用自动 stash、自动提交、`git clean` 或静默丢弃来制造"干净状态"。

> 检验：将要执行的提交、合并、push、开 PR、删除或移除 worktree，是否都取得了对应动作的明确授权？缺一项就停在该项之前。

## 反例（不要这样做）

❌ 测试没过就收尾 / 合并。
❌ 先跑测试，之后才删调试打印，却不重跑测试。
❌ 入场已有脏改动仍开始清理，把用户改动混进收尾。
❌ 整体验收后又改了代码，却直接沿用旧 review 结论去合并。
❌ 发现未提交改动就自动 commit / stash，让流程继续。
❌ 自动合并 / 自动 push / 自动开 PR —— 没让用户拍板（危险操作）。
❌ 合并获批后顺手移除 worktree —— 用户只确认了合并，没有确认移除。
❌ 丢弃（删分支）不二次确认就执行。
❌ 不检测状态就操作 —— 在错的分支 / 漏掉未提交改动。
❌ 在这里建立工作区 —— 越界到 setup-worktree。

## 分层与调用方

- **composable 层**能力单元：通常由 workflow 层的 **execute-task**（阶段 4 收尾）在整体验收通过后调用，
  也可被用户直接触发。
- 建立隔离工作区见 **setup-worktree**；收尾前的整体审查见 **review-changes**。