finishing-a-development-branch

概觀

這個技能能做什麼

finishing-a-development-branch 技能會在你完成開發、且測試套件通過之後，協助你安全地收尾 Git 開發分支。它會帶你走過一個清楚且可重複的流程，讓你可以選擇要在本機合併、推送並建立 Pull Request、保留分支之後再處理，或是直接丟棄整個分支。

這個技能的核心原則很簡單：

Verify tests → Determine base branch → Present options → Execute choice → Clean up

與其臨時輸入一堆 Git 指令、或是漏掉重要檢查，finishing-a-development-branch 會在功能或修正分支的最後階段，替你的 agent 準備一份一致的檢查清單。

誰適合使用 finishing-a-development-branch？

• 使用 Git 分支開發、想要有一套結構化「分支收尾流程」的開發者
• 需要在合併或開 PR 前，強制確認測試通過的團隊
• 使用 obra/superpowers 技能組，希望讓 agent 更安全地管理 Git 流程的使用者
• 經常會問「這個分支可以合併了嗎？要怎麼整合進去？」的任何人

它特別適合已經有自動化測試，以及標準基準分支（例如 main 或 master）的版本庫。

這個技能解決的問題

• 在合併或建立 Pull Request 前忘記執行測試
• 不確定某個功能分支當初是從哪個分支切出來的
• 對要在本機直接合併、開 PR、還是放棄這次工作，缺乏一致的決策流程
• 因為收尾不明確，導致一堆殘留分支讓版本庫變得雜亂

透過強制先做測試檢查，再給出一小組明確選項，finishing-a-development-branch 能減少失誤，讓你的 Git 工作流程更可預期。

什麼時候適合用這個技能

在以下情況使用 finishing-a-development-branch：

• 某個功能或修正已完整實作
• 預期所有測試都會通過，或你希望測試失敗時能阻擋整合
• 你已經準備好要決定這個分支要如何整合，或是否應該被丟棄

在以下情況 不 適合使用：

• 你還在這個分支上積極開發或做實驗
• 版本庫沒有可用的測試、或你無法執行有意義的測試套件
• 你需要複雜的多分支發佈管理，而非單純「功能分支 → 基準分支」的流程

如果你主要需要的是寫程式或審查變更的協助，可以搭配專注在實作或程式碼審查的其他技能一起使用；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

這會讓你的 agent 環境能使用這個技能，將引導式 Git 流程套用到你目前的版本庫。

2. 確認版本庫前置條件

為了讓這個技能如預期運作，你的專案應該：

• 是一個 Git repository，且有明確的基準分支（通常是 main 或 master）。
• 有可執行的測試套件，通常透過像是：
  • npm test
  • cargo test
  • pytest
  • go test ./...

實際指令會依你的技術棧而定；這個技能只假設在整合前，必須存在某個可執行的測試指令。

3. 宣告要使用這個技能

當你準備開始收尾流程時，這個技能預期你（或你的 agent）會明確宣告：

"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?"

確認正確的基準分支非常重要，因為這決定了你的工作會合併到哪裡，或是 PR 應該指向哪一個分支。

第 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 等 Git hosting 平台啟動程式碼審查、CI 或核准流程。
• 選項 3 – 你還不想立刻決定，但希望確認測試已通過、且目前分支狀態清楚。
• 選項 4 – 這只是實驗性分支，或做法已過時，希望把這個分支乾淨地移除。

第 4 步：執行選定選項

根據你的選擇，技能會執行相對應的 Git 操作與相關清理。雖然底層 SKILL.md 對部分細節指令有截斷，但意圖大致如下：

• 對 本機合併：切換到基準分支，將開發分支合併進來，並在適當時機選擇是否刪除已完成的分支。
• 對 push + PR：把分支推送到遠端，並引導你建立指向已判定基準分支的 Pull Request。
• 對 保留分支：不改動目前分支，且明確標示由你稍後再處理整合。
• 對 丟棄分支：在再次確認後，安全地捨棄或刪除該分支。

在這整個步驟中，技能都以可預期性與安全性為優先：避免在測試失敗時合併、避免合併到錯誤基準分支，也避免意外遺失工作成果。

實務使用小訣竅

納入你的個人工作流程

• 每當你覺得某個功能已經「完成」時，就執行 finishing-a-development-branch。
• 把測試關卡當作在「合併 vs 開 PR」前的最後品質檢查。
• 在團隊環境中，預設使用選項 2，以確保會啟動審查與 CI pipeline。

搭配團隊慣例使用

如果你的團隊有特定分支與審查規範（例如一定要先 PR 到 develop，或永遠不自動刪分支），就把選項的使用方式跟這些規則對齊。這個技能的結構能讓這些團隊政策更容易被穩定執行。

搭配其他 superpowers 技能

在 obra/superpowers 套件中，finishing-a-development-branch 是用來補足實作、重構或測試類技能的。你可以先用那些技能推進分支內容，等到真的準備好整合時再呼叫這個技能收尾。

常見問題

我應該在什麼時候執行 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」。具體操作方式會依你的 agent 環境與 Git hosting 平台的整合方式而定。至少，它會幫你將分支推送上去，並引導你建立一個指向已偵測到的基準分支的 PR。

它會自動刪除我的分支嗎？

SKILL 描述著重在提供選項與執行你選擇的流程（包含清理）。實際的刪除行為則可能會依你的環境如何詮釋「清理步驟」而不同。請將選項 4（discard this work）視為具破壞性的操作，只在你真的確定不再需要這個分支時才選擇它。

finishing-a-development-branch 適合複雜的版本發佈流程嗎？

這個技能主要是針對單純的功能或修正分支，合併回單一基準分支的情境。如果你管理多個長期維護的 release 分支、hotfix 流程或複雜的部署 pipeline，你仍然可以在每個分支上使用 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

安裝完成後，依照技能流程操作：先跑測試、確認基準分支、選擇一個選項，然後讓這個技能處理整合與清理步驟。