finishing-a-development-branch

finishing-a-development-branch 快速入门

让 AI 在你”准备合分支”时,自动跑一遍标准化收尾流程——测试、清理、PR 描述、merge,一步不漏。

这是什么?解决什么问题?

finishing-a-development-branch 是 Obra 公司在 obra/superpowers 仓库下提供的一个 Skill,和 using-git-worktrees 是配对关系——using-git-worktrees 负责”开发前的隔离”,finishing-a-development-branch 负责”开发后的收尾”。
它解决的问题,是开发分支即将合并时最容易跳过的几个”清理动作”:

• 没跑完整测试:开发期间只跑过单测,忘了跑 lint / type check / 集成测试,合并后主干挂了。
  
• 调试代码没删:console.log("TODO") 这种调试残留合并进了主干。
  
• commit 信息不规范:40 个 commit 里 30 个是”fix typo”,合并不了 / squash 后丢失信息。
  
• PR 描述缺失:只有一行”fix bug”,reviewer 不知道改了什么、为什么改、影响面。
  
• worktree 忘清理:worktree 留在那里,后续 dev 环境乱了。
  
• release note / changelog 缺失:用户不知道新版本加了什么。
  Skill 沉淀的”分支收尾”标准化流程:
  

1. 跑完整质量门禁:lint、type check、unit test、integration test、覆盖率。
   
2. 清理临时代码:debug 日志、TODO 注释、注释掉的代码块。
   
3. 整理 commit 历史:交互式 rebase 把杂乱的 commit 合并 / 重写。
   
4. 生成 PR 描述:改了什么、为什么改、影响面、测试方式、风险。
   
5. merge / squash / rebase 选择:根据团队规范选合适策略。
   
6. 清理 worktree:合并后删除开发用的 worktree。
   
7. 更新 CHANGELOG / release note。
   它适合的场景:每个 feature 分支开发完成、版本发布前的最后准备、Code Review 前的自查清单。
   

准备工作

1. 一个支持 Skill 加载的 AI 编程助手(Claude Code 体验最佳)。
   
2. 项目在 Git 仓库里,且开发用的是 using-git-worktrees 隔离环境。
   
3. 项目里有 lint / type check / test 脚本定义。
   
4. Clone 仓库:
   

git clone https://github.com/obra/superpowers.git<br>
```<br>
5. 软链 Skill:<br>
```bash<br>
ln -s superpowers/skills/finishing-a-development-branch ~/.claude/skills/finishing-a-development-branch<br>
```<br>
## 3 步快速上手<br>
### 第 1 步:安装 Skill<br>
重启 AI 助手,Skill 生效。<br>
### 第 2 步:验证安装<br>
向 AI 发送请求:
> "我用 obra 的 finishing-a-development-branch 流程,准备把 feature/user-profile 分支合到 main。请列出收尾 checklist。"

如果 AI 输出的是分阶段的 checklist(测试 / 清理 / 整理 commit / 生成 PR / merge),说明 Skill 加载成功。

### 第 3 步:用 finishing-a-development-branch 跑第一个任务

让 AI 按 Skill 流程帮你收尾一个 feature 分支:

**Step 1:跑质量门禁**

```bash

git checkout feature/user-profile

git rebase main

npm run lint

npm run typecheck

npm test

Skill 会让 AI 主动检查所有这些是否通过,不通过就停下来让你修。

Step 2:清理临时代码

# 找所有 console.log / debugger / TODO

rg "console\.(log|debug)" src/

rg "debugger;" src/

rg "TODO|FIXME|XXX" src/

Skill 会让 AI 列出所有发现,让你逐个 review 是删是留。

Step 3:整理 commit 历史

# 交互式 rebase,合并 "fix typo" 类 commit

git rebase -i HEAD~10

Skill 会建议把无意义的 commit squash,有意义的拆开重写 message。

Step 4:生成 PR 描述

让 AI 根据 commit 历史 + diff 生成 PR 模板:

## 改动概述

- 新增用户个人资料页

- 支持头像上传、昵称修改、个性签名

## 改动原因

- 完成 PRD-2026-001 的需求

- 用户反馈: 个人中心功能缺失

## 改动详情

- 新增 `pages/profile/` 目录

- 接入头像上传 OSS SDK

- 新增 `api/user.ts` 三个方法

## 影响面

- 前端: profile 路由 + 个人中心入口

- 后端: user API 扩展 3 个字段

## 测试方式

1. 登录后点击头像 → 进入个人资料

2. 上传图片 < 2MB, 应展示新头像

3. 修改昵称,刷新后保持

## 风险

- 上传接口未做 CDN 缓存,首屏略慢

- 头像存储未做去重,同一用户可能上传多张

Step 5:合并

# 推送到远端,创建 PR

git push origin feature/user-profile

gh pr create --title "feat: 用户个人资料页" --body "$(cat pr-description.md)"

# PR 评审通过后合并

gh pr merge --squash

Step 6:清理 worktree

git worktree remove ../user-profile-worktree

git branch -d feature/user-profile

常见踩坑

1. 跳质量门禁。“本地跑过测试了”不等于”所有测试都过”,Skill 强调要跑 lint / type / 单测 / 集成 / 覆盖率,全过才合并。

2. debugger / console.log 残留。开发期间随手加的日志忘了删,合并后用户看到 console 里一片红。

3. commit 不规范。“fix""update""改” 这种 commit 信息合并后 3 个月回看,根本不知道改了什么。Skill 强调 Conventional Commits。

4. PR 描述不写”为什么”。reviewer 看到 diff 第一反应是”为什么这么改”,而不是”改了什么”。Skill 强调 PR 描述必须包含”原因”。

5. worktree 不清理。多个 worktree 留着会污染工作目录,Skill 建议合并后立刻清理。

6. CHANGELOG 不更新。用户/客服不知道新版本有什么变化,Skill 强调 release note 必更新。

初级用法

用法 1:每次合并前自查。让 AI 按 Skill 帮你跑一遍收尾 checklist,避免漏。

用法 2:统一 PR 模板。让 AI 帮你生成团队标准的 PR 描述模板,所有 PR 都用同一格式。

用法 3:CHANGELOG 自动生成。让 AI 解析 Conventional Commits,自动生成 CHANGELOG.md,版本发布时一目了然。

高级玩法

玩法 1:Release 自动化。让 AI 帮你配”打 tag → 自动生成 release note → 发版到 GitHub Releases”的流水线,SemVer 版本号自动 bump。

玩法 2:Pre-commit Hook。把 Skill 的”质量门禁”写成 pre-commit hook,本地 commit 时自动跑,根本进不了仓库。

玩法 3:Post-merge 自动化。merge 后自动触发 CI 跑全套测试 + 自动部署 staging,Skill 强调”主分支永远可部署”。

小技巧

1. commit 粒度要”原子”。一个 commit 只做一件事,出问题时能精准 revert。

2. PR 控制在 400 行以内。太大 reviewer 没耐心看,Skill 建议”小而美”的 PR。

3. Screenshots / 录屏必带。UI 改动必须有截图,reviewer 一眼能看出效果。

4. 风险声明要诚实。“已知问题”列出来,不要等 reviewer 帮你发现,Skill 强调”主动暴露风险”。

5. merge —squash 适合 feature 分支,merge —no-ff 适合 hotfix,根据场景选。

常见问题 FAQ

Q1: 这个 Skill 跟 finishing-a-development-branch 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: finishing-a-development-branch 来自 Obra,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了?

A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 finishing-a-development-branch 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

参考链接

• finishing-a-development-branch 仓库

• Skill 路径

• Conventional Commits

• Semantic Versioning

• Git Worktree 文档

• GitHub PR 模板