Git 分支管理
每個變更都應該有自己的分支。這包括一行修正和沒有對應 issue 的變更。請不要在基礎分支上進行提交。
1. 找出基礎分支
使用第一個能提供答案的來源：
- 專案說明文件。 閱讀
CLAUDE.md、CONTRIBUTING.md和.github/文件。如果它們指定了基礎或整合分支，請使用它。 - 遠端預設分支。
git symbolic-ref --short refs/remotes/origin/HEAD # 會印出 origin/<名稱> gh repo view --json defaultBranchRef -q .defaultBranchRef.name - 歧義情況。 如果遠端也有
develop或development分支，且沒有任何文件說明哪個是基礎分支，請詢問使用者。不要自行猜測。
當整合分支（例如 develop）是基礎分支時，針對已發行版本的熱修復應從預設分支開始。僅在使用者明確表示該工作是熱修復時才使用此規則。
2. 檢查當前位置
git status --porcelain
git rev-parse --abbrev-ref HEAD
- 如果工作目錄中有不是你做的變更，請停止。詢問使用者該如何處理它們。
- 如果你已經在處理同一工作的分支上，請留在該分支。
- 如果你在基礎分支上且有尚未提交的編輯，請移動它們：使用
git switch -c <名稱>可以將它們保留在工作目錄中。
3. 從遠端 tip 開始建立分支
git fetch origin --prune
git switch -c <名稱> origin/<基礎分支>
git log -1 --oneline
從 origin/<基礎分支> 開始可以確保過時的本地基礎分支不會造成問題。不要在基礎分支上執行 git pull 來「跟上進度」。這是不必要的。
4. 命名分支
如果專案有命名慣例，請使用它。如果沒有，請使用 <類型>/<參考>-<簡介> 格式：
| 部分 | 值 |
|---|---|
類型 | feat, fix, docs, chore, refactor, test, release, hotfix |
參考 | Issue 編號 (42)、Pipeline 票證 (ticket-007)，或留空 |
簡介 | 二到五個小寫單字，以連字號連接 |
範例：fix/42-null-session-crash、feat/ticket-007-search-filters、docs/readme-install-steps。
5. 工作期間
- 以小型、各自獨立的步驟進行提交。主題行使用祈使句，不超過 72 個字元。在內文說明原因。
- 不要在提交訊息中加入
Co-Authored-By: Claude標記。這是 gener8v 的規則。 - 在第一次推送之前，你可以對
origin/<基礎分支>進行 rebase。分支推送之後，請改用合併基礎分支到目前分支的方式。對已推送的分支進行 rebase 會改寫歷史，而engineering:git-safety會檢查這個動作。 - 使用能在第一次失敗時停止的鏈式命令來推送：
set -o pipefail git fetch origin && <測試命令> 2>&1 | tail -n 40 && git push -u origin HEADset -o pipefail，| tail會隱藏它前面命令的結束代碼。絕對不要在沒有set -o pipefail的情況下，將 git 命令或測試命令透過tail管道傳遞。
並行工作
對於兩個或更多同時編輯程式碼的 agent，在啟動任何 agent 之前，請先閱讀 resources/parallel-work.md。簡而言之：從基礎分支建立一個批次分支，每個 agent 從該批次分支建立一個工作目錄和一個分支，並且不能有兩個 agent 同時編輯相同的檔案。
完成條件
- 你已位於一個名稱明確的分支上，且該分支從目前的
origin/<基礎分支>開始。 git status顯示沒有屬於其他人的變更。
相關技能
engineering:github-pr-merge：在工作完成時開啟 PR。engineering:git-safety：強制推送、刪除分支等命令的核准規則。engineering:github-issue-workflow：issue 或 pipeline 票證的完整生命週期。它會先呼叫此技能。