Git Worktree Design — 智慧拆分平行開發

分析使用者需求，判斷是否適合以 git worktree 拆分成多個 feature branch 平行開發，提供建議方案並執行。

流程

1. 分析當前狀態

執行以下指令了解 repo 狀態：

# 確認當前分支
git branch --show-current

# 列出既有 worktree
git worktree list

# 取得 remote 資訊
git remote -v

# 確認工作目錄狀態
git status --short

若有未提交的變更，提醒使用者先處理（commit 或 stash）再繼續。

2. 全局設計（拆分方案 + Feature Spec）

在建立任何 worktree 之前，先從全局視角完成所有 feature 的設計。這一步同時產出 拆分方案 和每個 feature 的 Spec 草案，讓使用者一次 review 整體規劃。

#### 2a. 需求拆分

根據使用者需求，分析並拆分成多個獨立的 feature branch。

拆分原則：

#### 2b. 設計各 Feature Spec

針對每個拆分出來的 feature，根據使用者的原始需求和專案現況，自動推導出完整的 Spec 內容（不是丟空白範本）。

每份 Spec 應包含：

重點：在全局設計階段就考慮跨分支相依，例如 feature A 產出的共用元件是否影響 feature B，合併順序是否有先後。

#### 2c. 呈現完整方案給使用者

以表格 + 各 feature spec 摘要的形式向使用者呈現完整方案：

📋 Worktree 拆分方案（共 N 個分支）

| # | 分支名稱 | Worktree 目錄 | 負責功能 |
|---|----------|---------------|----------|
| 1 | feature/hero-redesign | ../project-hero | Hero 區塊重新設計 |
| 2 | feature/pricing-page | ../project-pricing | 定價頁面 |
| 3 | feature/testimonials | ../project-testimonials | 用戶見證區塊 |

---

📝 Feature Spec 摘要：

### 1. feature/hero-redesign
- 目標：重新設計 Hero 區塊，加入動態背景與 CTA
- 驗收：首屏載入 < 2s，CTA 按鈕可點擊跳轉
- 相依：無，可獨立開發

### 2. feature/pricing-page
- 目標：新增月/年切換的定價頁面
- 驗收：切換月/年時價格正確更新，手機版排版正常
- 相依：無，可獨立開發

### 3. feature/testimonials
- 目標：新增用戶見證輪播區塊
- 驗收：輪播自動播放，手動切換無 bug
- 相依：無，可獨立開發

---

建議合併順序：1 → 2 → 3（無強制相依，可任意順序）

確認執行？(Y/n)

使用 notify_user 工具向使用者展示完整方案（拆分 + Spec 摘要）並等待確認。

3. 建立 Worktree

使用者確認後，依序執行：

# 建立各 worktree（新分支）
git worktree add -b <branch_name> <worktree_path>

#### Worktree 目錄命名規則

• 目錄放在當前 repo 的同層級（../）
• 格式：../<project-name>-<feature-short-name>
• 取 repo 目錄名作為 <project-name> 前綴，避免與其他專案混淆

4. 安裝依賴

偵測專案使用的套件管理器並安裝依賴：

# 偵測 lock file 判斷套件管理器
# pnpm-lock.yaml → pnpm install
# yarn.lock → yarn install
# package-lock.json → npm install
# bun.lockb → bun install

對每個 worktree 執行：

cd <worktree_path> && <package_manager> install

注意：每個 worktree 有獨立的工作目錄，node_modules 不會共享，必須各自安裝。

5. 寫入 Feature Spec 檔案

將步驟 2 設計好的 Spec 內容，使用 write_to_file 工具寫入到每個 worktree 的根目錄 <worktree_path>/git-worktree-spec.md。

#### Spec 檔案格式

# Feature Spec: <功能名稱>

> 此文件由 Git Worktree Design Skill 自動產生，供 AI Agent 作為開發指引。

## 分支資訊

| 項目 | 值 |
|------|-----|
| 分支名稱 | `feature/<name>` |
| 基於分支 | `<base_branch>` |
| Worktree 路徑 | `<absolute_path>` |
| 建立時間 | `<timestamp>` |

## 目標

（從步驟 2 的設計內容填入）

## 實作範圍

- [ ] 具體任務 1
- [ ] 具體任務 2
- [ ] 具體任務 3

## 驗收標準

- 條件 A 成立時，應有行為 X
- 條件 B 成立時，應有行為 Y

## 技術約束

- 不得引入新的 npm 依賴（視情況填寫）
- 需相容既有的設計系統 / API 介面
## 跨分支備註

與其他 worktree 分支的相依關係、合併順序建議等。

6. 確認結果

所有 worktree 建立完成後，執行：

git worktree list

以表格形式展示結果：

✅ Worktree 建立完成！

| Worktree 目錄 | 分支 | 狀態 | Spec |
|---------------|------|------|------|
| /path/to/project-hero | feature/hero-redesign | ✅ 就緒 | ✅ 已寫入 |
| /path/to/project-pricing | feature/pricing-page | ✅ 就緒 | ✅ 已寫入 |
| /path/to/project-testimonials | feature/testimonials | ✅ 就緒 | ✅ 已寫入 |

💡 提示：
- 切換工作目錄到對應 worktree 即可開始開發
- 所有 worktree 共享同一個 .git，commit 歷史互通

邊界情況處理

• 分支已存在：偵測到分支已存在時，改用不帶 -b 的指令（git worktree add <path> <existing-branch>），並提示使用者確認
• 目錄已存在：提示衝突並建議替代目錄名
• 有未提交變更：提醒先 commit 或 stash
• 遠端分支同步：建議先 git fetch 取得最新遠端狀態
• Worktree 清理：提醒使用者開發完成後用 git worktree remove 和 git branch -d 清理

常用維護指令

# 列出所有 worktree
git worktree list

# 移除 worktree（保留分支）
git worktree remove <path>

# 強制移除（有未提交變更時）
git worktree remove --force <path>

# 清理失效的 worktree 參照
git worktree prune

# 刪除分支（合併後）
git branch -d <branch_name>