finishing-a-development-branch

完成开发分支

概述

提供一个结构化、安全的流程，用于完成开发分支上的工作，包括验证、选择合并策略和清理。此技能可确保分支在通过测试后才会合并，且每项破坏性操作都必须获得用户明确确认。

使用时机

• 功能分支上的所有计划工作都已完成
• 分支已准备好进行代码审查或合并
• 开发工作完成后进行清理
• 准备拉取请求，以供团队审查

阶段 1：确认所有测试均已通过

[HARD-GATE] 在验证通过前，不得进行任何合并或 PR 操作。

进行任何合并或 PR 操作之前，调用 verification-before-completion 以确认：

• 所有测试均已通过（适用时包括单元测试、集成测试和端到端测试）
• 没有 lint 错误或警告
• 构建成功
• 没有应该提交但尚未跟踪的文件

# Run the project's full verification suite
# Do NOT skip this step even if "tests were passing earlier"

如果验证失败，请停止。继续之前先修复失败项。测试未通过时，不得创建 PR 或合并分支。

停止——继续阶段 2 之前，必须通过验证。

阶段 2：确定基准分支

使用以下检测逻辑，确定要合并到哪个分支：

自动检测

# Check for common base branch names
git branch -a | grep -E 'remotes/origin/(main|master|develop)$'

# Check what branch was the fork point
git log --oneline --decorate --graph HEAD...main --first-parent 2>/dev/null
git log --oneline --decorate --graph HEAD...master --first-parent 2>/dev/null

基准分支选择决策表

条件	基准分支	置信度
存在 main	main	高
仅存在 master	master	高
存在 develop 且项目使用 GitFlow	develop	中
找到多个候选项	询问用户	必须
以上分支均不存在	询问用户	必须

确认基准分支是最新状态

git fetch origin
git log HEAD..<base-branch> --oneline

如果基准分支自功能分支创建以来已有更新，请告知用户。他们可以先将基准分支变基或合并到功能分支。

基准分支分歧决策表

分歧情况	操作
基准分支没有新提交	正常继续
基准分支有 1-5 个新提交	告知用户，建议变基
基准分支有 6 个或更多新提交	警告用户，建议先合并或变基再继续
检测到合并冲突	停止——先解决冲突

停止——继续之前，请与用户确认基准分支。

阶段 3：展示合并选项

向用户准确展示以下四个选项。不得添加或删除选项。

How would you like to finish this branch?

  A) Create PR    -- push and open a pull request for review
  B) Merge        -- merge into <base> with a merge commit
  C) Squash merge -- squash into one commit, merge into <base>
  D) Leave as-is  -- keep the branch, decide later

选项选择决策表

情况	推荐选项	原因
有代码审查流程的团队项目	A) 创建 PR	支持审查工作流
历史记录整洁的个人项目	B) 合并	保留完整的分支历史记录
有许多 WIP 提交、历史记录杂乱	C) 压缩合并	在基准分支上生成一个整洁的提交
工作未完成或情况不确定	D) 保持原样	没有风险，可稍后决定

停止——等待用户选择选项。不得默认选择某个选项。

阶段 4：执行所选选项

选项 A：创建拉取请求

# Push the branch
git push -u origin <branch-name>

# Generate PR title from branch name or recent commits
# Generate PR body from commit messages and diff summary
gh pr create --title "<title>" --body "<body>"

生成 PR 标题：

• 根据分支名称生成：feature/add-auth 转为 Add authentication
• 控制在 70 个字符以内
• 使用祈使语气

生成 PR 正文：

• 总结更改内容（做了什么以及原因）
• 列出关键修改
• 说明任何破坏性更改
• 包含测试计划

选项 B：在本地合并

# Switch to base branch
git checkout <base-branch>

# Merge feature branch
git merge <feature-branch>

# Delete the feature branch
git branch -d <feature-branch>

执行合并前必须获得确认。

选项 C：压缩合并

# Switch to base branch
git checkout <base-branch>

# Squash merge
git merge --squash <feature-branch>

# Commit with a comprehensive message
git commit -m "<squash commit message>"

# Delete the feature branch
git branch -d <feature-branch>

压缩提交消息应总结分支上的所有更改，而不仅仅是最后一次提交。

执行压缩合并前必须获得确认。

选项 D：保持分支原样

无需采取任何操作。告知用户：

Branch <branch-name> left as-is.
You can return to it later with: git checkout <branch-name>

阶段 5：清理

执行选项 A、B 或 C 后，进行清理：

移除工作树（如适用）

如果分支是在 Git 工作树中开发的：

# Navigate out of the worktree first
git worktree remove <worktree-path>
git worktree prune

清理远程跟踪分支（仅限选项 B 和 C）

如果该分支之前已推送：

# Delete remote branch after local merge
git push origin --delete <branch-name>

删除远程分支前必须获得确认。

验证最终状态

git status
git log --oneline -5

确认基准分支处于预期状态。

确认要求

[HARD-GATE] 执行以下操作前，必须获得用户的明确确认。切勿擅自执行。务必先询问。

操作	需要确认的原因
合并到基分支	会更改基分支的历史记录
压缩合并	会丢失各个提交的历史记录
删除本地分支	如果尚未推送，则无法撤销
删除远程分支	会影响其他协作者
强制移除工作树	可能会丢弃未提交的更改
变基到更新后的基分支	会重写提交历史

反模式 / 常见错误

反模式	错误原因	正确做法
未运行测试就合并	有问题的代码会进入基分支	始终先运行完整验证
跳过基分支最新状态检查	太晚才发现合并冲突	运行 git fetch 并检查分歧情况
自动选择合并策略	用户可能倾向于其他方案	务必提供全部四个选项
未经确认就删除分支	有数据丢失风险	每次删除前都要询问
CI 未通过就创建 PR	浪费审查者的时间	创建 PR 前先修复 CI
仅根据最后一次提交编写压缩提交信息	会丢失整个分支工作的背景信息	在压缩提交信息中概述所有更改
留下过时的远程分支	使代码库变得杂乱	合并后清理远程分支
创建 PR 后强制推送	会破坏审查评论	避免对 PR 分支强制推送

错误处理

错误	操作
合并冲突	报告冲突并请用户解决，切勿自动解决
推送被拒绝	获取更新并检查是否需要变基或合并
PR 创建失败	检查 gh auth status 并报告错误详情
分支已删除	跳过删除，继续进行其余清理
测试失败	立即停止，切勿合并或创建 PR
远程不存在基分支	请用户确认正确的基分支

集成点

技能	集成方式
verification-before-completion	必须在阶段 1 中、任何合并操作之前调用
using-git-worktrees	如适用，清理时包括移除工作树
git-commit-helper	压缩提交信息遵循约定式提交格式
code-review	创建 PR（选项 A）后进入代码审查工作流
planning	完成分支是计划执行的最后一步
deployment	合并到 main/release 可能会触发部署流水线

技能类型

RIGID — 必须严格遵循此流程。每个阶段都必须按顺序完成。切勿跳过验证。未经用户确认，切勿合并。切勿擅自决定合并策略。未经询问，切勿删除分支。