# Zc Branch Finish And Cleanup

> 分支收尾与清理

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

---


# 分支收尾与清理

## 概述

任务“做完”不等于 branch 可以安全结束。只有当变更已经验证、去向已确定、残留工作区已清理，branch / worktree 才算真正收尾。

这个技能只处理收尾判定与清理：

- 这个 branch 现在应该 merge、开 PR、继续保留，还是直接丢弃
- 关联 worktree 是否还需要保留
- 失败实验、半成品和临时分支如何安全退出

它不替代实现、审查或发布流程；它只负责把这些流程的结果变成一个干净、可追踪、可回滚的结束状态。

## 何时使用

在以下时点进入本技能：

- 一个功能或修复已经完成实现，准备结束开发分支
- 一个 worktree 中的实验已经得出结论，需要保留或放弃
- 多 agent 并行执行结束，准备 fan-in 之后清理各自分支
- PR 已合并、被拒绝，或决定不继续推进，需要处置残留 branch / worktree

## 收尾决策树

```
任务结果明确了吗？ ─── 否 ──→ 不收尾，先补齐验证或结论
    │
   是
    ▼
变更应该进入主线吗？ ─── 否 ──→ 丢弃或归档实验分支
    │
   是
    ▼
当前团队通过 PR 合入吗？ ─── 是 ──→ 推送 + 开/更新 PR + 等待合入
    │
   否
    ▼
直接 merge 到目标分支 → 验证目标分支状态 → 删除已完成分支
```

关键点：

- 先判定“是否保留”，再判定“如何合入”
- 未经验证的 branch 不能因为“差不多完成了”就进入收尾
- 未合入主线的实验分支，只有明确保留价值时才继续存在

## 收尾前门禁

收尾前必须确认：

- 任务范围已经冻结，没有继续顺手改的内容
- 当前 branch 的测试、lint、构建或本任务要求的验证已完成
- 审查结论已明确：可合入、待修复或放弃
- branch 的目标去向已明确：merge、PR、保留、归档或删除
- 没有未解释的脏文件、临时脚本或生成物

如果上述任一项不明确，就不要进入 cleanup 动作。

## 四种结束状态

### 1. 合入主线

适用于：功能完成、验证通过、审查通过，且应该进入目标分支。

动作：

1. 确认 branch 相对目标分支的差异是预期范围
2. 使用团队约定的方式 merge 或 rebase 后合入
3. 在目标分支重新运行必要验证
4. 删除已完成 branch
5. 若 branch 绑定 worktree，清理对应 worktree

### 2. 提交 PR 等待合入

适用于：变更已准备好，但团队要求经由 PR 流程进入主线。

动作：

1. 推送 branch 并创建或更新 PR
2. 在 PR 描述中写明范围、验证证据和风险点
3. branch 保持最小存活时间，只为等待审查和合入而存在
4. PR 合并后删除 branch，并清理关联 worktree

### 3. 暂时保留

适用于：实验有价值，但当前不合入；或后续还会基于该分支继续工作。

动作：

1. 记录为什么保留、保留多久、谁负责
2. 标明当前状态是 `paused`、`blocked` 或 `needs-follow-up`
3. 清理无关临时文件，避免下次恢复时状态不明
4. 定期复核，过期未恢复的分支要么合入，要么删除

保留不是默认值。没有明确后续计划的 branch，不应长期悬挂。

### 4. 丢弃或清理失败实验

适用于：方案被否定、实现失败、或成本明显高于价值。

动作：

1. 先保留需要沉淀的结论、数据或复盘记录
2. 确认 branch 上没有还要转移的变更
3. 删除分支或直接移除 worktree
4. 清除临时文件、缓存和不再需要的脚本

不要把“也许以后有用”的实验分支长期留着替代文档。

## Worktree 收尾协议

如果 branch 通过 worktree 运行，收尾时把 branch 和 worktree 视为一个整体：

- branch 已合入或放弃后，worktree 也应同步清理
- 仅当该 worktree 仍承担后续明确任务时才保留
- 清理前先确认没有未提交变更或未转移的调试资料
- 移除 worktree 后，确保主仓库或其他工作区不再引用该路径

worktree 是隔离手段，不是长期存档机制。

## 多分支 / 多 Agent 场景

并行执行结束后，不要只做“合并成功”检查，还要逐个确认各分支的收尾状态：

- 哪些分支已经合入，可以删除
- 哪些分支因失败或冲突需要重做，应清理现场后重新开始
- 哪些分支暂时保留，原因和负责人是什么
- 哪些 worktree 已经没有活跃任务，应立即移除

如果一个并行批次完成后还残留大量无主分支，说明收尾协议没有真正执行。

使用 `zc team` 时，先运行 dry-run：

```bash
zc team shutdown <team-name> --plan
```

它只读取 fan-in 状态，不关闭 tmux、不删除 worktree。重点看每个 worker worktree：

- `clean`：没有未提交变更，可以继续判断是否合入或删除
- `dirty`：仍有未提交变更，必须先转移、提交或明确丢弃
- `ahead`：分支领先目标引用，需要判断是否合入或开 PR
- `merged`：已合入的分支可以进入删除流程
- `unknown`：状态无法判断，必须人工检查后再清理

只有每个 worktree 的去向明确后，才运行不带 `--plan` 的 `zc team shutdown <team-name>`。

## 最小收尾清单

- [ ] branch 的最终去向已明确
- [ ] 必要验证已完成，证据可追溯
- [ ] 需要保留的信息已转移到 PR、任务系统或文档
- [ ] `zc team shutdown <team-name> --plan` 没有暴露未解释的 `dirty` / `unknown`
- [ ] 不再需要的 branch 已删除
- [ ] 不再需要的 worktree 已移除
- [ ] 没有遗留未解释的脏文件或临时产物

## 与其他技能的衔接

- **git-workflow-and-versioning** — 定义提交、分支和 worktree 的日常纪律；本技能负责这些对象的结束状态
- **parallel-agent-dispatch** — 并行批次 fan-in 后，逐个分支进入收尾判定
- **team-orchestration** — 团队停机前，先明确每个 worker 的 branch / worktree 去向
- **verification-before-completion** — 收尾前的验证证据必须真实存在，不能凭感觉删除或合入分支

## Red Flags

- 任务未验证完成就急着删分支
- PR 已合并但 branch / worktree 长期残留
- 失败实验既不记录结论，也不清理现场
- 用“先留着吧”替代明确的保留期限和责任人
- 多 agent fan-in 后只关心代码合并，不处理分支残留