finishing-a-development-branch

概览

这个技能能做什么

finishing-a-development-branch 技能帮助你在开发工作已经实现完成且测试套件通过时，安全地收尾一个 Git 开发分支。它会引导你遵循一套清晰、可重复的工作流，让你可以选择在本地合并、推送并创建 Pull Request、暂时保留分支，或者直接丢弃。

这个技能的核心原则很简单：

验证测试 → 确定基准分支 → 给出选项 → 执行选择 → 清理收尾

相比随手敲 Git 命令、或遗漏关键检查，finishing-a-development-branch 为你的特性分支或 bugfix 分支提供了一份一致的收尾清单。

谁适合使用 finishing-a-development-branch？

• 使用 Git 分支开发、希望有一套结构化“分支收尾流程”的开发者
• 在合并或发起 PR 前要求测试必须通过的团队
• 使用 obra/superpowers 技能集、希望代理更安全地管理 Git 工作流的用户
• 经常会问“这个分支已经可以合并了吗？应该怎么集成？”的任何人

它尤其适合已经有自动化测试，并且有标准基准分支（例如 main 或 master）的代码仓库。

这个技能解决哪些问题

• 在合并或创建 Pull Request 前忘记跑测试
• 不确定某个特性分支是从哪个分支上创建的
• 在“本地合并、走 PR、还是丢弃工作”之间反复犹豫、决定不一致
• 因收尾流程不清晰而遗留在仓库里、造成混乱的旧分支

通过强制“先测再说”，然后给出一小组明确的选项，finishing-a-development-branch 能减少错误，让你的 Git 工作流更加可预测。

什么时候适合使用这个技能

在以下场景下使用 finishing-a-development-branch：

• 某个功能或修复已经完整实现
• 预期所有测试都应通过，或者你希望在测试失败时阻止集成
• 你已经准备好决定这个分支应该如何集成，或是否要直接丢弃

在以下情况 不适合 使用：

• 你仍在这个分支上积极写代码或做探索性尝试
• 仓库没有可用的测试，也无法运行有意义的测试套件
• 你需要复杂的多分支发布管理，而不是简单的“feature → base branch”工作流

如果你主要需要写代码或做代码评审的帮助，可以搭配其他面向实现或 code review 的技能一起使用；finishing-a-development-branch 专注于最后的集成步骤。

使用方法

安装与配置

1. 安装技能

通过 Skills CLI 从 obra/superpowers 仓库安装 finishing-a-development-branch：

npx skills add https://github.com/obra/superpowers --skill finishing-a-development-branch

安装后，该技能会在你的代理环境中可用，从而能针对当前仓库执行引导式 Git 工作流。

2. 确认仓库前置条件

为了让技能按预期工作，你的项目应当：

• 是一个 Git 仓库，并有明确的基准分支（通常为 main 或 master）。
• 拥有可运行的测试套件，通常通过如下命令之一执行：
  • npm test
  • cargo test
  • pytest
  • go test ./...

具体命令取决于你的技术栈；技能只要求在集成前存在并可以执行 某个 测试命令。

3. 明确宣布使用技能

当你开始分支收尾时，技能期望你（或你的代理）明确声明：

"I'm using the finishing-a-development-branch skill to complete this work."

这样可以让协作者清楚当前正在走结构化流程，也便于沟通和审计。

引导式工作流步骤

步骤 1：验证测试

在做任何集成决策之前，技能会运行或提示你运行项目的测试套件。常见命令包括：

npm test
# or
cargo test
# or
pytest
# or
go test ./...

• 如果测试失败：技能会报告失败用例数量、展示失败详情，并停止后续流程。它会明确说明在测试通过之前无法继续合并或创建 PR。
• 如果测试通过：工作流进入下一步。

这种严格的“先测试”闸门能有效避免将有问题的代码合并或提交到 Pull Request 中。

步骤 2：确定基准分支

接下来，finishing-a-development-branch 会尝试确定你的开发分支是从哪个基准分支上创建的，使用类似如下的 Git 命令：

git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

如果无法自动判断基准分支，技能会退回到询问澄清，例如：

"This branch split from main - is that correct?"

确认正确的基准分支很关键，因为这决定了你的工作会被合并到哪里，以及 Pull Request 应该以哪个分支为目标。

步骤 3：给出集成选项

当测试通过且基准分支已确定后，技能会给出如下四个简明选项：

Implementation complete. What would you like to do?

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work

Which option?

这些选项刻意保持短小直接，避免冗长说明，方便你快速做决定。

典型使用场景：

• 选项 1 – 你希望快速在本地完成合并，多见于个人项目或只有你一名维护者的仓库。
• 选项 2 – 你在团队中开发，需要借助 GitHub 等托管平台进行 code review、CI 和审批。
• 选项 3 – 你暂时还不想做集成决策，但希望确认测试已经通过、分支状态清晰。
• 选项 4 – 之前只是做尝试性实验，或方案已经过时，想干净地移除这个分支。

步骤 4：执行所选操作

根据你的选择，技能会执行相应的 Git 操作和相关清理。虽然底层 SKILL.md 中对部分详细命令做了截断，但总体意图如下：

• 对于 本地合并：切换到基准分支，将开发分支合并进去，并在合适的情况下可选择删除已完成的分支。
• 对于 push + PR：将分支推送到远程，并引导你创建一个以识别出的基准分支为目标的 Pull Request。
• 对于 保持不动：不对当前分支做任何修改，并清楚标记后续由你自行安排集成。
• 对于 丢弃：在你确认真的不再需要后，安全地放弃或删除该分支。

在整个步骤中，技能都强调可预期性和安全性：避免在测试未通过时合并、避免合并到错误的基准分支、避免误删还需要的工作成果。

实战使用小贴士

融入你的个人工作流

• 每当你认为某个 feature 已经“完成”，就运行一次 finishing-a-development-branch。
• 让“测试闸门”作为你决定本地合并还是走 PR 之前的最后质量检查。
• 在团队环境中，默认优先使用选项 2，以确保触发 review 和 CI 流水线。

与团队规范配合

如果团队有特定的分支与评审策略（例如所有分支必须先 PR 到 develop，或禁止自动删除分支），可以将这些规则映射到选项使用方式上。这个技能本身的结构有利于你持续、统一地遵守团队约定。

与其他 superpowers 技能组合

在 obra/superpowers 套件中，finishing-a-development-branch 主要用来补足实现、重构、测试等技能之后的最终集成环节。先用其他技能推进分支演进，真正准备集成时再调用本技能。

常见问题（FAQ）

我应该在什么时候运行 finishing-a-development-branch？

当你的改动已经实现完成、预期测试可以通过，并准备好决定如何集成这个分支（合并、PR、保留或丢弃）时，运行 finishing-a-development-branch。它定位为分支生命周期中的最后一步，而不是日常开发时频繁使用的辅助工具。

如果测试失败会发生什么？

如果测试失败，技能会报告失败情况并停止流程。它不会继续执行合并或创建 Pull Request。你需要在该分支上修复失败的测试、重新运行测试，之后再重新调用 finishing-a-development-branch。

没有自动化测试套件也能用吗？

这个技能是围绕“先验证测试”这一原则设计的。理论上你可以在没有测试的项目上硬套这套流程，但等于绕开了它的一项核心安全机制。最佳做法是用于可以运行 npm test、cargo test、pytest 或 go test ./... 之类命令的仓库。

它是如何决定要合并到哪个分支的？

finishing-a-development-branch 会使用 Git 的 merge-base，针对 main 或 master 等常见分支名称，尝试自动识别基准分支。如果结果不明确，它会询问你来确认基准分支。这样可以确保合并和 Pull Request 都指向正确的目标分支。

它会自动创建 Pull Request 吗？

在文档描述中，当你选择选项 2 时，技能的行为是“push 并创建 Pull Request”。具体细节取决于你的代理环境与 Git 托管平台的集成方式。最低层面上，它会推送你的分支，并引导你基于检测到的基准分支打开 PR。

它会自动删除我的分支吗？

SKILL 描述的重点在于给出选项并执行相应工作流，包括清理步骤。分支删除的具体行为可能依赖于你环境中对清理动作的实现。可以将选项 4（丢弃这次工作）视为具有潜在破坏性的操作，仅在确认不再需要该分支时才选择。

finishing-a-development-branch 适合复杂发布流程吗？

这个技能主要针对简单的特性或修复分支，并将它们合并回单一基准分支。如果你维护多个长期存在的发布分支、hotfix 流程或复杂的部署管线，仍然可以在单个分支维度上使用 finishing-a-development-branch，但在整体发布策略上可能还需要额外的流程或工具配合。

怎么再次安装 finishing-a-development-branch？

使用 Skills CLI 指向 obra/superpowers 仓库即可：

npx skills add https://github.com/obra/superpowers --skill finishing-a-development-branch

安装完成后，按照技能流程操作：运行测试、确认基准分支、选择一个选项，然后交由技能处理集成和收尾清理步骤。