Branch Worktree Guardian

Branch Worktree Guardian

Git 分支和 Worktree 管理工具，用於預防在錯誤分支上開發的問題。

問題背景

在多 AI Agent 同時開發或複雜的分支管理場景中，容易發生以下問題：

1. 分支混淆：在錯誤的分支上進行開發
2. 覆蓋風險：不同開發者的變更互相覆蓋
3. 合併混亂：分支狀態不清導致合併困難

核心原則

1. 新開發需求 = 新分支 + 新 Worktree

# 標準流程
1. 確認 main 分支為最新
2. 創建 feature 分支
3. 創建 worktree 到獨立目錄
4. 切換到 worktree 目錄開發

2. 保護分支禁止直接編輯

保護分支列表：

• main
• master
• develop
• release/*

在這些分支上嘗試編輯時，Hook 會詢問是否繼續或建立新分支。

3. Worktree 命名規範

格式：{project-name}-{branch-short-name}

範例：

• book_overview_app-5w1h-skill
• book_overview_app-branch-worktree
• book_overview_app-ui-unification

快速參考

建立新開發環境（完整流程）

# 1. 確保 main 是最新的
git checkout main
git pull origin main

# 2. 創建 feature 分支
git checkout -b feat/your-feature-name

# 3. 創建 worktree（在專案同級目錄）
git worktree add ../project-name-feature-name feat/your-feature-name

# 4. 切換到 worktree 目錄
cd ../project-name-feature-name

# 5. 確認分支正確
git branch --show-current

查看現有 Worktree

git worktree list

清理已合併的 Worktree

# 移除 worktree（保留分支）
git worktree remove /path/to/worktree

# 移除 worktree 並刪除分支（謹慎使用）
git worktree remove /path/to/worktree
git branch -d branch-name

驗證當前分支

# 使用 SKILL 腳本
python .claude/skills/branch-worktree-guardian/scripts/verify_branch.py

# 手動檢查
git branch --show-current
git worktree list | grep $(pwd)

使用腳本

create_feature_worktree.py

創建新的 feature 分支和對應的 worktree。

# 基本用法
python .claude/skills/branch-worktree-guardian/scripts/create_feature_worktree.py \
    --branch feat/new-feature \
    --worktree ../project-new-feature

# 從特定基礎分支創建
python .claude/skills/branch-worktree-guardian/scripts/create_feature_worktree.py \
    --branch feat/new-feature \
    --worktree ../project-new-feature \
    --base develop

verify_branch.py

驗證當前分支是否適合編輯。

# 檢查當前目錄
python .claude/skills/branch-worktree-guardian/scripts/verify_branch.py

# 檢查指定目錄
python .claude/skills/branch-worktree-guardian/scripts/verify_branch.py --path /path/to/project

Hook 整合

PreToolUse Hook (branch-verify-hook.py)

在 Edit 或 Write 工具執行前自動檢查：

• 是否在保護分支上
• 如果是，詢問用戶是否繼續

SessionStart Hook (branch-status-reminder.py)

Session 啟動時提醒：

• 當前所在分支
• 現有 worktree 列表
• 如果在保護分支，建議建立 feature 分支

常見情境處理

情境 1：發現在錯誤分支上

# 1. 暫存當前變更
git stash

# 2. 創建正確的分支和 worktree
git checkout main
git checkout -b feat/correct-branch
git worktree add ../project-correct-branch feat/correct-branch

# 3. 切換到新 worktree
cd ../project-correct-branch

# 4. 恢復變更
git stash pop

情境 2：多個 AI 同時開發

每個 AI 應該：

1. 使用獨立的 worktree 目錄
2. 使用不同的分支名稱
3. 在 Session 開始時確認分支

情境 3：緊急修復需要在 main 上操作

Hook 會詢問是否繼續。選擇「繼續」時：

1. 明確知道風險
2. 完成後立即 commit
3. 考慮是否需要 cherry-pick 到其他分支

配置說明

settings.json 配置

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {"type": "command", "command": ".claude/hooks/branch-verify-hook.py"}
        ]
      },
      {
        "matcher": "Write",
        "hooks": [
          {"type": "command", "command": ".claude/hooks/branch-verify-hook.py"}
        ]
      }
    ]
  }
}

保護分支自訂

修改 branch-verify-hook.py 中的 PROTECTED_BRANCHES 列表：

PROTECTED_BRANCHES = [
    "main",
    "master",
    "develop",
    "release/*",
    # 添加更多保護分支...
]

相關文件

• Git Worktree 官方文件
• 專案 Hook 系統方法論
• 敏捷重構方法論