並行開發 - Parallel Worktree Development 實戰範例

「下週三要上 5 個獨立功能,週一才開工。」這是 sprint 結尾最常見的噩夢。傳統做法是工程師開 5 個 branch、輪流切、開發完一個 merge、開發下一個——序列化保證你來不及。

本範例示範如何用 Superpowers 的 Using Git Worktrees + Subagent-Driven Development + Dispatching Parallel Agents 三個 skills 的組合,把「5 個獨立功能」壓縮成「5 個並行的 worktree + 5 個 subagent」,從週一早上到週二下午就全部提交完。

專案概述

情境:Next.js 14 電商前端,週三 deploy 前 PM 派 5 個任務:

1. F1:/products/[id] 頁加入麵包屑導航
2. F2:/cart 加入「移除商品」確認 modal
3. F3:/checkout 把地址輸入改為 Google Places Autocomplete
4. F4:/orders 加入 CSV 匯出 button
5. F5:全局加上 <SEO> 元件補 Open Graph tags

目標:

• 全部 5 個任務於週二下午 5pm 前完成 + reviewed + merged
• 無 merge conflict
• CI 全綠

技術棧:Next.js 14 (App Router) + TypeScript + Tailwind + Vitest

核心挑戰:5 個任務「號稱獨立」其實有共享風險——

• F1、F3 都動 app/(shop)/layout.tsx
• F4、F5 都需要新 npm dep(papaparse、next-seo)
• 全部都需要 VE component,但 VE 元件不應跨 worktree 重複修改

完整開發流程

第 1 步:Brainstorming — 任務依賴性盤點

觸發:

使用 brainstorming skill 評估這 5 個任務能否並行,以及最佳並行策略

AI 回應摘要:

## 依賴性矩陣分析

| 任務 | 動的檔案 | 依賴 |
|------|---------|------|
| F1 麵包屑 | product page, breadcrumb.tsx (新) | 無 |
| F2 移除 modal | cart page, confirm-modal.tsx (新) | 無 |
| F3 G. Places | checkout page, address-input.tsx (新) | 無 |
| F4 CSV 匯出 | orders page, export-button.tsx (新), + papaparse | 與 F5 共用 npm install lock |
| F5 SEO | root layout, + next-seo | 與 F4 共用 npm install lock |

## 結論
- ✅ 5 個任務業務邏輯獨立
- ⚠️ F1 與 F3 都會改 layout.tsx,需最後合併協調
- ⚠️ F4 與 F5 共享 package.json,需要合併時解決 conflict

## 策略
- 全部 5 個並行,worktree 隔離
- 合併時依 F1→F3、F4→F5 順序解 conflict(而不是隨機順序)
- 共用 component 放到 shared/ 而非各自 worktree

第 2 步:Writing Plans — 5 個 worktree 的批次計畫

觸發:

使用 writing-plans skill 把並行計畫轉成可執行的 worktree + subagent 任務

計畫:

階段 1(15 min):建立 5 個 worktree
- [ ] git worktree add ../shop-f1-breadcrumb -b feat/breadcrumb
- [ ] git worktree add ../shop-f2-cart-modal -b feat/cart-remove-modal
- [ ] git worktree add ../shop-f3-places   -b feat/places-autocomplete
- [ ] git worktree add ../shop-f4-csv      -b feat/csv-export
- [ ] git worktree add ../shop-f5-seo      -b feat/global-seo
- [ ] 每個 worktree 跑 pnpm install

階段 2(2-4 hr):dispatch 5 個 subagent 並行開發
- [ ] 每個 worktree 對應一個 subagent
- [ ] subagent 內含完整 context (任務描述 + 該 worktree 路徑)
- [ ] subagent 完成後 commit 在自己分支
- [ ] 不直接 push

階段 3(30 min):收集成果 + 解 conflict
- [ ] 切回主倉庫,按依賴順序 cherry-pick
- [ ] F1 → F3(layout 解 conflict)
- [ ] F4 → F5(package.json 解 conflict)
- [ ] F2 (獨立,隨意順序)

階段 4(1 hr):全量 review + merge
- [ ] 統一 PR(superpowers 偏好 atomic PR,但時程壓力下可一個 PR 含 5 commit + 各自 commit message 詳述)
- [ ] code-reviewer subagent 並行審 5 個 commit
- [ ] 每 commit 個別 revert-friendly

驗收標準:
- [ ] 5 個功能全上 staging
- [ ] CI 全綠(包含 lint、tsc、vitest)
- [ ] 5 個任務各自的 unit test 覆蓋
- [ ] 無功能面 regression

第 3 步:Executing Plans — 建立 worktree 群

依 Using Git Worktrees skill,把 5 個任務分散到 5 個實體 worktree(不是 branch),讓 subagent 各自隔離工作:

# 主倉庫在 ~/repo/shop-frontend
cd ~/repo/shop-frontend

# 建立平行 worktrees
git worktree add ../shop-f1-breadcrumb -b feat/breadcrumb main
git worktree add ../shop-f2-cart-modal -b feat/cart-remove-modal main
git worktree add ../shop-f3-places    -b feat/places-autocomplete main
git worktree add ../shop-f4-csv       -b feat/csv-export main
git worktree add ../shop-f5-seo       -b feat/global-seo main

# 各自 install(可並行)
for dir in ../shop-f1-breadcrumb ../shop-f2-cart-modal ../shop-f3-places ../shop-f4-csv ../shop-f5-seo; do
  (cd $dir && pnpm install) &
done
wait

為什麼是 worktree 而非 branch:worktree 是實體隔離的工作目錄,subagent 可以同時在 5 個目錄寫碼,互不影響、各自有 install 的 node_modules、各自有 build cache。branch 切換會清掉這些,subagent 之間會踩對方。

第 4 步:Dispatching Parallel Agents — 並行觸發 5 個 subagent

觸發(主控對話):

使用 dispatching-parallel-agents skill 開發這 5 個獨立功能,每個 subagent 對應一個 worktree

主控 Agent 同時派 5 個 subagent,每個都完全自足(不需要回頭問問題):

F1 subagent prompt(範例):

你是 F1 subagent,工作目錄 ~/repo/shop-f1-breadcrumb
任務:為 /products/[id]/page.tsx 加入麵包屑導航

具體:
1. 新增 src/components/breadcrumb.tsx
2. 在 /products/[id]/page.tsx 頂部加入 <Breadcrumb />
3. 從 product data 抽出 category 路徑
4. 寫 vitest 覆蓋 breadcrumb 元件
5. commit message 用 "feat: 加入產品頁麵包屑" (不含感謝詞)

驗收:
- pnpm test 綠
- pnpm build 綠
- 完成後不要 push,留在你自己的分支

注意:不要動 layout.tsx(那是主控會處理)

(其他 4 個 subagent 同樣格式,各自 worktree)

dispatching 的關鍵:

• 完全自足:subagent 不該問主控問題,任何「不清楚」就要在 prompt 中先定義
• 結果唯一性:subagent 結束只回「done: 5/5 tasks in worktree X」訊息
• 不要共用檔案:每個 subagent 動的檔案不重疊(已在 brainstorm 階段確認)

第 5 步:Subagent-Driven Development — 監督 5 個 subagent

依 Subagent-Driven Development skill,主控不要寫碼,只做:

1. 派發:5 個 subagent 同時起來
2. 監督:看每個 subagent 的 commit 進度,但不介入
3. 收尾:5 個全完成後,主控做合併與協調

主控的 review checklist(每個 subagent 完成後):

- [ ] 該 worktree 的 commit 在自己的 branch 上
- [ ] pnpm test 該 worktree 內綠
- [ ] pnpm build 該 worktree 內綠
- [ ] 修改的檔案都在當初 scope 內(不越界)
- [ ] commit message 繁中且語義清楚

第 6 步:合併 — 解衝突的順序是關鍵

5 個 subagent 完成,回到主倉庫按依賴順序 cherry-pick:

cd ~/repo/shop-frontend
git checkout -b feat/batch-wednesday-release main

# F2(獨立, 先合)
git cherry-pick feat/cart-remove-modal

# F1 → F3(layout.tsx 可能 conflict)
git cherry-pick feat/breadcrumb
git cherry-pick feat/places-autocomplete
# ↑ 若 layout.tsx 衝突,F3 那邊解 - 保留 F1 的 Breadcrumb,加入 F3 的 AddressInput

# F4 → F5(package.json 可能 conflict)
git cherry-pick feat/csv-export
git cherry-pick feat/global-seo
# ↑ 解 package.json conflict - 兩個 dep 都保留

pnpm install  # 因為 package.json 可能變了
pnpm test
pnpm build

為什麼順序重要:隨機順序合會踩出莫名其妙 conflict。依賴性矩陣告訴你哪些任務會共編輯同一檔,腦中有這個圖就能避開亂世。

第 7 步:批次 review 與部署

雖然傳統建議一個 PR 對應一個原子任務,但時程壓力下,批次 PR 也是合法選項(只要 commit 細粒度可 revert):

git push -u origin feat/batch-wednesday-release
gh pr create --title "[批次] 週三 5 功能並行釋出" \
             --body "$(cat <<EOF
## 含 5 個獨立任務
- F1: 麵包屑 (@feat/breadcrumb)
- F2: 購物車移除 modal (@feat/cart-remove-modal)
- F3: Google Places Autocomplete (@feat/places-autocomplete)
- F4: CSV 匯出 (@feat/csv-export)
- F5: 全域 SEO (@feat/global-seo)

## 並行策略
- 5 個 git worktree 隔離
- 5 個 subagent 並行開發(2-4 小時)
- 依賴衝突按 F1→F3、F4→F5 順序解決

每個 commit 都可獨立 revert。
EOF
)"

觸發 code-reviewer subagent 並行審 5 個 commit:

使用 dispatching-parallel-agents skill 派 5 個 reviewer subagent,
每個審一個 commit 的 diff

5 個 reviewer 並行給意見,主控整合 → 修正 → merge。

第 8 步:Verification Before Completion

觸發:

使用 verification-before-completion skill 驗證 5 功能批次釋出

驗收清單:

✅ 功能完整性
- F1 麵包屑:正確顯示 category 路徑、可點擊導航 ✓
- F2 移除 modal:點擊移除跳出確認、取消不動作 ✓
- F3 Places:輸入地址自動完成、選取後填入表單 ✓
- F4 CSV:點擊下載 .csv、欄位正確 ✓
- F5 SEO:View Source 看到 og:title、og:image ✓

✅ 工程品質
- pnpm test 287 個測試全綠(新增 18 個)✓
- pnpm build 無警告 ✓
- pnpm lint 無警告 ✓
- TypeScript 嚴格模式編譯通過 ✓

✅ 並行效率
- 序列估算:5 任務 × 1 工程師 = 5 天
- 並行實測:1.5 天(0.25 天 setup + 0.5 天並行 + 0.25 天整合 + 0.5 天 review)
- 加速比:3.3x

✅ 無衝突殘留
- F1/F3(layout.tsx 手動 merge 後 ve 元件正常)✓
- F4/F5(package.json conflict 解後 pnpm install 正常)✓
- 5 個 worktree 都已清理(rm -rf 並 git worktree remove)✓

✅ 可回滾
- 每个 commit 都獨立、可 revert
- 出問題時可 git revert <commit-hash> 而不影響其他 ✓

關鍵學習點

1. Worktree > Branch (給 subagent 的場景)

subagent 寫碼需要實體目錄(node_modules、build cache、TypeScript cache)。branch 切換會清掉這些,subagent 之間互相破壞。worktree 是為了 subagent 而生。

2. 依賴矩陣是並行的前提

「5 個任務看起來獨立」≠「5 個任務實際獨立」。動到同一檔案的任務要合併時協調,但開發期還是能並行——只要在 brainstorm 階段先標好依賴。沒先做矩陣分析就並行,等於自找 conflict 地獄。

3. Subagent prompt 要完全自足

「不確定就問」是單 agent 場景的好習慣,但 給 subagent 的 prompt 必須把不確定性先消滅。任何「等等問主控」都會破壞並行。這也是 brainstorming + writing-plans 先行做的價值——把模糊都解析掉再 dispatch。

4. 批次 PR 在時程壓力下合法

原子 PR 是理想,但「5 天工作 1.5 天做完」這種現實壓力下,批次 PR + 細粒度 commit 是合理折衷。重點是每個 commit 獨立可 revert,而不是 commit log 一團亂。

5. 合併順序是顯式決策

依賴矩陣不僅告訴你「會衝突」,還告訴你「該用什麼順序合」。F1 先合,F3 看見 F1 已落地、自然知道要保留 F1 的 Breadcrumb ——心智負擔降到最低。

工具使用摘要

總結

並行開發的核心反模式是 「我們人多,把任務分成 5 份各自做就好」——沒有 worktree、沒有 subagent、沒有依賴矩陣,結果就是 5 個人互相 block、5 個 branch 互相 conflict、merge 完破壞彼此功能。

Superpowers 的 skills 提供的是結構化並行:

• Brainstorming 先把「真的能並行嗎?」問清楚
• Worktree 提供實體隔離,subagent 不互相破壞
• Dispatching Parallel Agents 把模糊任務轉成自足 prompt
• Subagent-Driven Development 把主控從「碼農」解放成「指揮官」

最終 5 天 → 1.5 天的加速,不是因為「我們更努力」,而是因為 skills 把並行的複雜度變成了可工程的流程。下次遇到「N 個獨立任務、deadline 緊迫」,先別加班、先別悲觀,先打開 worktree,先派 subagent。