Claude Code 同 git 點同步：branch 命名 / commit 文 / PR description 自動跟團隊規矩

情境

你個團隊定咗條鐵律：branch 一定要 feat/JIRA-123-short-slug，commit 一定係 conventional（feat(auth): ...），PR description 一定要有 ## What / ## Why / ## Test plan 三段。

你裝咗 Claude Code，叫佢「commit 同 push」。佢出：

Update authentication module
- Modified login.ts
- Added tests

技術上 OK。但用團隊規矩去睇：全部唔合格。Branch 叫 update-auth，commit 唔係 conventional，PR description 一段過。Reviewer 打回頭：「跟返 template 啦。」

問題唔係 Claude 蠢 —— 係你冇話畀佢知團隊嘅規矩。Claude 預設用業界嗰套籠統寫法，唔知你公司用 GitFlow 定 trunk-based、唔知你 PR template 喺邊、唔知 JIRA-123 係必要 prefix。

呢篇拆做 4 步，將團隊嘅 git 規矩寫入 Claude 嘅預設行為，順手加埋 rebase / conflict 救命招。

跟住做

1. 將 git conventions 寫入 CLAUDE.md

CLAUDE.md 擺喺 repo root，每個 Claude Code session 都會自動讀。寫一段 ## Git Conventions：

## Git Conventions

### Branch naming
- Format: `<type>/<JIRA-ID>-<kebab-slug>`
- type: feat / fix / chore / refactor / docs
- 例: `feat/PAY-412-stripe-webhook-retry`
- 主線: `main`（protected, no direct push）

### Commit message (Conventional Commits)
- Format: `<type>(<scope>): <subject>`
- type: feat / fix / chore / refactor / docs / test / perf
- scope: 模組名（auth / payment / ui ...）
- subject: 廣東話或英文都得，唔好過 72 字
- Body: 解釋「點解」，唔係「做咗乜」

### PR description (必跟 template)
## What
<一句講改咗乜>

## Why
<點解要改 / 連返 JIRA-ID>

## Test plan
- [ ] 跑 `pnpm test`
- [ ] 手動測試 [關鍵 flow]

呢段一加，Claude 之後嘅 commit / PR 就會自動跟。重點：要寫例子，唔好淨係寫規則。Claude 跟例子比跟抽象規則準十倍。

2. /commit 同 /pr slash command

CLAUDE.md 係預設行為，但你想「一鍵」做晒成套 git 動作。咁就寫個 slash command。

檔案 .claude/commands/commit.md：

---
description: Stage + commit 當前改動，跟 conventional commits
---

請執行：

1. 跑 `git status` 同 `git diff` 睇清楚改咗乜
2. 推斷 type（feat / fix / chore / refactor）同 scope
3. 寫 conventional commit message，subject 唔好過 72 字
4. Body 解釋「點解改」（睇 JIRA ID from branch name）
5. `git add` 相關檔案（唔好 `-A`，避免 commit 到 `.env`）
6. `git commit` 用 heredoc 確保 formatting
7. 跑 `git status` 確認

檔案 .claude/commands/pr.md：

---
description: Push 同開 PR，跟 team template
---

請執行：

1. 確認 branch 名跟 `<type>/<JIRA>-<slug>` format
2. `git push -u origin HEAD`
3. 用 `gh pr create` 開 PR，body 跟 template：
   ## What / ## Why / ## Test plan
4. JIRA ID 從 branch 抽出，放入 Why 段做 link
5. Return PR URL

之後你打 /commit 同 /pr，Claude 就會自動跟你寫低嗰套流程。新同事入嚟第一日就有齊套規矩。

3. 用 hook 自動檢查 commit message

CLAUDE.md + slash command 係指引層。Hook 係強制層 —— Claude 想點都好，hook 過唔到就 commit 唔到。

.claude/settings.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'git commit'; then npx commitlint --from HEAD~1 || exit 2; fi"
      }
    ]
  }
}

配合 commitlint.config.js（標準 conventional 設定）。Claude 一 commit，hook 就會跑 commitlint，唔合規就打回頭、Claude 收到錯誤、自己再改個 message。你完全唔使插手。

同樣可以加：

• git secrets --scan 防止將 API key commit 出去
• pnpm typecheck 防止 commit 啲行唔到嘅 code
• Branch name regex 檢查，防止直接 commit 落 main

4. Conflict resolution playbook

Rebase 衝突係寫 code 最痛苦嘅一環。Claude 喺呢度係救命草，但你要畀佢正確嘅 prompt。

撞到 conflict 嗰陣：

git rebase main
# CONFLICT (content): Merge conflict in src/auth/login.ts

唔好淨係叫「resolve conflict」（太含糊）。要咁叫：

我 rebase main，src/auth/login.ts 有 conflict。
讀 conflict markers，理解兩邊意圖（main 同 my branch），
保留兩邊嘅 logic 而唔係揀一邊，
跑 `pnpm test` 確認，
然後 `git add` + `git rebase --continue`。

Cherry-pick 救 commit：

從 branch feat/old-experiment cherry-pick `abc123` 個 commit 入 current branch。
如果有 conflict，跟上面 playbook。

Interactive rebase squash：

最近 5 個 commit 全部係「WIP」「fix typo」。
幫我 squash 成 1 個 conventional commit，
message 由 diff 推斷意圖。

Claude 處理 git 底層嘢比你手動快 5 倍，因為佢唔會驚 --force-with-lease。

變化

變化 1：GitFlow vs trunk-based

GitFlow 團隊：CLAUDE.md 加 develop / release/* / hotfix/* 嘅 branch policy。Claude 預設由 develop 開 feature branch，hotfix 由 main 開。Slash command /release 處理成套 release branch 流程。

Trunk-based 團隊：CLAUDE.md 寫明「short-lived branch 唔超過 2 日、merge 入 main、用 feature flag 控制 rollout」。Claude 預設 push 細 PR，唔會自己揼 5 個 feature 落同一條 branch。

兩種 workflow 嘅差異全部寫入 CLAUDE.md，Claude 就會跟你團隊嘅選擇。

變化 2：Monorepo 多 changelog

Monorepo（pnpm workspaces / Turborepo）：每個 package 有自己嘅 changelog。Conventional commit scope 變成 package 名（feat(api): ... / feat(web): ...）。

CLAUDE.md 加：「Commit scope 必須係 package 名之一：api / web / shared / docs。一個 commit 只改一個 package（除非係跨 package 嘅 refactor，scope 就用 repo）。」

配合 Changesets：/commit slash command 加多一步「跑 pnpm changeset 生成 changelog entry」。Claude 自動補 changelog，之後嘅 release 自動化就跟住順。

變化 3：Open source maintainer 收 outside PR

你係 OSS maintainer，收到陌生人交嚟嘅 PR。用 Claude 並行檢視：

Agent({ prompt: "Review PR #234 diff for code quality + 跟唔跟 CONTRIBUTING.md" })
Agent({ prompt: "Check PR #234 有冇 security risk (injection / secret leak)" })
Agent({ prompt: "Draft maintainer reply: 讚好嘅地方 + 列具體要改嘅 point" })

3 個 subagent 並行，整合返一份檢視報告。你最後加返人味，approve 定 request changes。OSS maintainer 由「30 分鐘睇一個 PR」變「5 分鐘睇一個」，啲 PR 唔再積壓三個月。

拆解：點解 work，同邊度會仆街

跟到上面就已經用得。下面呢段係畀**想由「demo 一次跟到 template」做到「全團隊用足一年都唔出事」**嘅人——初學者可以跳過，唔影響你跟住做。

git 自動化最危險嘅地方係：Claude 唔 commit 嘅嘢，你睇唔到。一個 commit 靚仔，唔代表佢冇靜靜雞做咗你唔想佢做嘅嘢。呢套流程，實際會喺呢幾個位爆，你要預咗：

1. hook 設死咗，全團隊一齊 commit 唔到 文中都提咗：個 regex 或者 commitlint config 設錯，exit 2 會擋住所有 commit。問題係呢個 config 你 commit 咗入 repo，一 pull 落嚟全團隊中招。

• 會出事：唔止你一個，pull 咗份 config 嘅人全部 commit 唔到，但佢哋唔知點解，以為自己壞咗。
• 點救：hook 加返「逃生門」——例如認 --no-verify 或者一個環境變數 bypass；config 改動單獨開 PR、寫清楚 reviewer 要本機試 commit 一次先 merge。寧願鬆少少，唔好成隊塞住。

2. git add 揀錯檔，secret 跟住 commit 出去 slash command 寫咗「唔好 -A」，但 Claude 推斷「相關檔案」嗰陣，會唔會手快加埋 .env.local、*.pem、debug 時 dump 出嚟嘅 log，冇人擔保。

• 會出事：API key / token 入咗 git history，就算之後刪返，history 仲喺度，等於洩咗，要 rotate key。
• 點救：唔好淨靠 prompt 自律——加 .gitignore 兜底，再加 git secrets --scan 或者 gitleaks 落 hook 做真正嘅閘。Claude 自律係第一層，工具掃描係最後一層。

3. Claude 自動 rebase / force push，撞甩同事啱啱 push 嘅 commit 文中話 Claude 唔驚 --force-with-lease，呢個係優點都係陷阱。喺共用 branch 上 force push，分分鐘蓋走人哋未 pull 嘅嘢。

• 會出事：同事尋日 push 嘅 commit 喺 remote 消失，佢下次 pull 先發現，排查半日。
• 點救：CLAUDE.md 寫明「protected / 共用 branch 永遠唔准 force push，只可以喺自己 feature branch 用」；--force-with-lease 一定優先過 --force，最少佢會喺 remote 有新嘢嗰陣 fail，唔會盲蓋。

4. commit message 啱 format，但「點解」嗰段係作出嚟 hook 只驗 conventional 嘅格式（type / scope / subject），驗唔到 body 講嘅「點解改」係咪真。Claude 由 diff 反推意圖，推錯咗你又冇睇，就成為一條誤導後人嘅 commit。

• 會出事：半年後有人 git blame 撞到呢條 commit，照住個錯 reason 去理解，跟住改錯嘢。
• 點救：「點解」呢段你一定要過目，尤其係 fix 類 commit——bug 嘅真正成因 Claude 估唔到，要你補。squash 多條 WIP 嗰陣更加要睇，因為佢要由一堆零碎 diff 砌返個故事。

5. JIRA ID 抽錯或者抽漏，PR 連唔返單 slash command 靠由 branch name 抽 JIRA ID。branch 名唔跟 format（例如你開漏咗、或者用咗 temp-fix），Claude 就抽唔到，PR 個 Why 段就會吉，或者填個錯 ID。

• 會出事：PR merge 咗但 JIRA 單冇 link，release note / audit trail 斷咗一截，compliance 追唔返。
• 點救：branch name regex 落 hook 做硬閘（文中第 3 步已提，記得真係加埋 JIRA prefix 嗰條）；抽唔到 ID 嗰陣 Claude 應該停低問你，唔好靜雞雞填個空白或者亂估。

呢幾個位，就係「demo 一次 commit 靚仔」同「成隊人用足一年都信得過」之間嘅距離。最緊要記住：Claude 跑 git 快過你五倍，但快嘅嘢出事都快五倍——閘要你用工具落，唔好淨靠 prompt 自律。

一個心態

Solo dev：CLAUDE.md 寫得鬆啲都得，反正你自己一個。重點係寫低你自己嘅慣性（你已經慣咗用 conventional commit，咁就寫低，Claude 跟你而唔係跟業界平均）。

2-3 人團隊：CLAUDE.md commit 入 repo，全團隊共用。新同事第一日用 Claude Code 就自動跟規矩，唔使寫 100 頁 onboarding 文檔。

大公司 enterprise：JIRA / GitHub Enterprise / 強制 PR template 嘅環境，CLAUDE.md + hook 嘅組合 = Claude 無得違規。從 audit / compliance 角度睇，AI 寫嘅 commit 同人寫嘅一樣有得追蹤。

Git 嘅規矩唔係限制，係團隊溝通嘅共通協議。Claude 跟唔到，唔係 Claude 嘅錯，係你冇將呢套協議寫低。

最後提醒：

• ✅ 先喺 CLAUDE.md 寫一段 git conventions。15 分鐘嘅工夫，之後每個 commit 慳返 2 分鐘。
• ⚠️ Hook 要先試行一次。個 regex 設錯，全團隊都 commit 唔到，你會收到 8 個 ping。
• 🎯 Rebase / cherry-pick / conflict 全部交畀 Claude。你個腦留返嚟諗架構，唔係用嚟背 git reflog 嘅語法。

下個 sprint 試吓將你團隊嘅 git 規矩寫入 CLAUDE.md。一個禮拜後 reviewer 唔再打回頭叫你跟 template —— 因為 Claude 已經自動跟咗。