平行開發實戰：3 個 Claude Code Agent、3 個 Worktree、1 個 Termdock

成果：3 個功能，40 分鐘完成

先看最終結果。三個 Next.js 電商功能，平行開發，乾淨合併，所有測試通過：

實際牆鐘時間：40 分鐘。同樣的工作量用序列開發大約要 2 小時。省下來的時間來自三個 agent 同時運作，各自在獨立的 worktree 中執行，透過 Termdock 的三欄面板一次監控。

這篇文章完整走過這個 session 的每一步：每個終端打什麼指令、每個 agent 收到什麼 prompt、怎麼合併結果。如果你需要 git worktree 和多 agent 隔離的原理說明，請參考 Git Worktree 多 Agent 設定指南。這裡只講實作。

環境準備

開始之前需要四樣東西：

• Git 2.20+：worktree 功能從這個版本開始穩定
• Claude Code：需要 --worktree（-w）flag，v2.1.50 起可用
• Termdock：用來做多面板終端配置
• 乾淨的 main branch：沒有未 commit 的變更，沒有殘留的 worktree

確認環境：

git --version        # 建議 git version 2.44+
claude --version     # v2.1.50 或更新
git worktree list    # 應該只有你的主要 working tree
git status           # clean working tree

情境：電商衝刺開發

你要為一個 Next.js 電商應用開發三個功能：

1. 商品搜尋：搜尋欄位搭配分類篩選、價格區間，對商品資料庫做全文搜尋
2. 購物車：加入和移除商品、用 localStorage 跨 session 保存購物車狀態、顯示總金額
3. 訂單確認信：結帳後用 Resend 發送含訂單明細的確認信

這三個功能適合平行開發，因為它們各自在不同的程式碼區域。商品搜尋在 app/search/ 和 lib/search/。購物車在 app/cart/ 和 lib/cart/。信件在 lib/email/ 和 app/api/orders/。重疊極少：它們共用 types/product.ts 的 Product type 和幾個工具函式。

第一步：先定義共享型別

啟動 agent 之前，把共享的 interface commit 到 main。這是減少合併衝突最有效的方法。

# 建立三個功能都需要的共享 Product type
cat > types/product.ts << 'EOF'
export interface Product {
  id: string;
  name: string;
  description: string;
  price: number;
  category: string;
  imageUrl: string;
  inStock: boolean;
}

export interface CartItem {
  product: Product;
  quantity: number;
}

export interface Order {
  id: string;
  items: CartItem[];
  total: number;
  customerEmail: string;
  createdAt: Date;
}
EOF

git add types/product.ts
git commit -m "add shared types for product, cart, and order"

每個 agent 從同一個基準分支出去，拿到同樣的型別定義。

第二步：在 Termdock 建立三欄配置

開啟 Termdock。建立三個垂直面板的配置。每個面板跑一個 Claude Code agent，各自在自己的 worktree 中。

三個 agent 最好用的配置是三等分直欄。某個 agent 需要更多注意力的時候（它問了問題，或是完成了需要審查），拖拉面板邊框就能放大。Termdock 的拖拉調整即時生效。

也可以用兩上一下的配置，看你螢幕的長寬比。重點是三個 agent 都要同時看得到。如果需要切分頁才能看到某個 agent，你會漏掉它的問題，它就空等。

第三步：在 3 個 Worktree 中啟動 3 個 Agent

在 Termdock 的每個面板中，用 --worktree flag 啟動 Claude Code session：

面板 1，商品搜尋 Agent：

claude -w feature/product-search

session 啟動後，給它任務：

在 app/search/page.tsx 建立商品搜尋頁面。需求：
- 全文搜尋輸入欄，對商品名稱和描述搜尋
- 分類篩選下拉選單（用既有種子資料的分類）
- 價格區間篩選，有最低和最高輸入
- 搜尋結果以 ProductCard 元件的格線顯示
- 在 lib/search/index.ts 建立 server-side 的 searchProducts 函式
- 使用 types/product.ts 的 Product type
- 處理 loading 狀態和空結果狀態

面板 2，購物車 Agent：

claude -w feature/cart

在 app/cart/page.tsx 建立購物車。需求：
- 在 lib/cart/context.tsx 建立 CartProvider context，包覆整個 app
- 為商品卡片做加入購物車按鈕元件
- 購物車頁面顯示所有品項，可調整數量和移除
- 用 localStorage 保存購物車，頁面載入時還原
- 在導航列顯示購物車總額和品項數
- 使用 types/product.ts 的 CartItem type
- 處理邊界情況：商品缺貨、數量超過庫存

面板 3，訂單確認信 Agent：

claude -w feature/order-email

建立訂單確認信流程。需求：
- 在 app/api/orders/route.ts 建立 POST /api/orders endpoint
- 接受購物車品項和顧客 email，建立 Order 紀錄
- 用 Resend（已在 package.json 中）寄送確認信
- 在 lib/email/templates/order-confirmation.tsx 用 React Email 做信件模板
- 使用 types/product.ts 的 Order type
- 信件內容包含訂單摘要、品項清單和總金額
- 寄信失敗時加上錯誤處理

三個 agent 現在各自獨立運作。每個有自己的 branch、自己在 .claude/worktrees/ 下的工作目錄、自己的程式碼副本。它們看不到彼此的變更，也無法互相干擾。

第四步：從 Termdock 監控

這是 Termdock 在工作流中發揮價值的環節。三個 agent 跑起來之後，你的工作從寫程式轉變為監控進度和回答問題。

三個面板要注意什麼：

Agent 的問題。 Claude Code 有時會問確認：「搜尋結果要用 server component 還是 client component？」快速回答，不要讓 agent 卡住。三個面板同時可見，你能馬上發現問題。

錯誤修復。 如果某個 agent 撞到編譯錯誤開始鬼打牆，介入。直接輸入修正：「停。Resend 的 import 是 import { Resend } from 'resend'，不是 from '@resend/node'。」

完成狀態。 Agent 完成的時間不同。訂單確認信 agent 通常最先完成（UI 工作較少）。看到它 commit 並回報完成時，可以先開始審查它的產出，其他兩個繼續跑。

Termdock 的 workspace 層級 git 同步在這裡很實用。你可以一眼看出哪個 worktree 有新的 commit、哪個有未 commit 的變更、哪個還在被寫入。不需要在每個面板手動跑 git status。

第五步：審查每個 Agent 的產出

三個 agent 都完成後，合併之前先審查。在每個面板（或該 worktree 對應的 Termdock 面板）中：

# 商品搜尋 worktree
cd .claude/worktrees/feature/product-search
git log --oneline main..HEAD
# a1b2c3d add search page with filters
# d4e5f6g add searchProducts function
# h7i8j9k add ProductCard component

git diff main --stat
# app/search/page.tsx         | 87 +++
# components/ProductCard.tsx  | 42 +++
# lib/search/index.ts         | 56 +++
# ... 12 files changed

# 購物車 worktree
cd .claude/worktrees/feature/cart
git log --oneline main..HEAD
git diff main --stat
# app/cart/page.tsx            | 95 +++
# lib/cart/context.tsx         | 68 +++
# components/AddToCartButton.tsx | 34 +++
# ... 9 files changed

# 訂單確認信 worktree
cd .claude/worktrees/feature/order-email
git log --oneline main..HEAD
git diff main --stat
# app/api/orders/route.ts     | 45 +++
# lib/email/templates/order-confirmation.tsx | 72 +++
# ... 7 files changed

檢查明顯問題：每個 agent 的程式碼能編譯嗎？有正確使用共享型別嗎？有沒有兩個 agent 同時修改的檔案？

第六步：按依賴順序合併

合併順序很重要。被其他功能依賴的先合併。

這個情境中，三個功能大致獨立，但有自然的順序：搜尋和購物車是獨立的，訂單確認信會引用購物車品項。先合併搜尋和購物車，再合併訂單確認信。

# 回到主要 working tree
cd ~/project

# 合併商品搜尋（獨立功能）
git merge feature/product-search
# Auto-merging...
# Merge made by the 'ort' strategy.

# 合併購物車（獨立功能）
git merge feature/cart
# Auto-merging...
# Merge made by the 'ort' strategy.

# 合併訂單確認信（引用 CartItem type，已在 main 上）
git merge feature/order-email
# Auto-merging...
# Merge made by the 'ort' strategy.

如果有衝突，幾乎一定在共用檔案，例如 app/layout.tsx（多個 agent 加 import 或 provider）或 package.json（不同 agent 加不同依賴）。這些是機械性衝突，幾秒鐘就能解決。

第七步：驗證與清理

在 main 上跑完整測試套件，確認一切正常運作：

npm run build        # 驗證編譯
npm run test         # 跑所有測試
npm run lint         # 檢查 lint 錯誤

然後清理 worktree：

git worktree list
# /Users/you/project                                abc1234 [main]
# /Users/you/project/.claude/worktrees/feature/product-search  def5678 [feature/product-search]
# /Users/you/project/.claude/worktrees/feature/cart            ghi9012 [feature/cart]
# /Users/you/project/.claude/worktrees/feature/order-email     jkl3456 [feature/order-email]

# 移除 worktree
git worktree remove .claude/worktrees/feature/product-search
git worktree remove .claude/worktrees/feature/cart
git worktree remove .claude/worktrees/feature/order-email

# 刪除已合併的 branch
git branch -d feature/product-search feature/cart feature/order-email

# 清理過期引用
git worktree prune

時間比較

序列開發和平行開發的實際比較：

平行方式不是 3 倍快。每個 agent 不管單獨跑還是跟其他 agent 一起跑，速度是一樣的。省下來的時間來自重疊：agent 1 在做搜尋的同時，agent 2 和 3 在做購物車和信件。你要付出大約 15 分鐘的合併審查成本，但淨節省很可觀。

47% 的時間節省隨獨立功能數量而擴展。四個平行功能省更多。兩個省較少。最佳平衡點是 3 個平行 agent，在產出量和監控複雜度之間取得平衡。

適用場景（以及不適用的時候）

適合用平行 agent 的時候：

• 你有 2 到 4 個觸及不同程式碼區域的功能
• 功能之間共享型別或 interface，但不共享實作檔案
• 每個功能單一 agent 要花 20 分鐘以上（低於這個值，合併成本不划算）
• 你的終端配置能同時顯示所有 agent

適合用單一 agent 的時候：

• 任務是單檔案的 bug 修復或小型重構
• 功能之間深度糾纏（同樣的檔案、同樣的函式）
• 你還不確定要什麼，需要互動式迭代

2026 AI CLI 工具完全指南涵蓋這個平行工作流如何融入更廣泛的 AI 輔助開發模式，包括何時在不同的 agent 位置使用不同工具。

常見問題排除

Agent 問到另一個 agent 建立的檔案。 Agent 看不到其他 worktree 的檔案。明確告訴它：「CartProvider 正在另一個平行 worktree 中開發。目前先 mock 購物車 context，合併之後再整合。」

建立 worktree 失敗，顯示 "already checked out"。 每個 branch 只能在一個 worktree 中 checkout。看到這個錯誤，表示之前該 branch 的 worktree 沒有清理。跑 git worktree list 找到它，再用 git worktree remove <path> 移除。

Agent 修改了共用設定檔。 如果兩個 agent 都改了 tailwind.config.ts 或 next.config.js，會產生合併衝突。預防方式：啟動 agent 前，把共用的設定項目先加到 main。如果還是衝突了，手動解決也很簡單。

Agent 跑到一半 context 用完。 在複雜的 codebase 中，長時間執行的 agent 可能撞到 context 上限。如果 agent 失去脈絡，在同一個 worktree 中開新 session：cd .claude/worktrees/feature/cart && claude。Worktree 保留了所有進度。

大型 repo 的磁碟空間問題。 每個 worktree 複製工作檔案，但共用 git object database。1 GB 的專案，三個 worktree 大約額外用 3 GB 磁碟空間。如果空間緊張，用 sparse checkout 限制每個 worktree 只包含 agent 需要的目錄。Claude Code 的 --worktree flag 透過 worktree.sparsePaths 設定支援這個功能。

快速參考：完整指令序列

# 1. Commit 共享型別
git add types/ && git commit -m "add shared types"

# 2. 開啟 Termdock 三欄配置

# 3. 啟動 agent（每個面板一個）
claude -w feature/product-search    # 面板 1
claude -w feature/cart              # 面板 2
claude -w feature/order-email       # 面板 3

# 4. 給每個 agent 任務 prompt

# 5. 監控、回答問題、審查產出

# 6. 按順序合併
git merge feature/product-search
git merge feature/cart
git merge feature/order-email

# 7. 驗證
npm run build && npm run test

# 8. 清理
git worktree remove .claude/worktrees/feature/product-search
git worktree remove .claude/worktrees/feature/cart
git worktree remove .claude/worktrees/feature/order-email
git branch -d feature/product-search feature/cart feature/order-email
git worktree prune

三個 agent。三個 worktree。一個終端視窗。設定花兩分鐘。合併花十五分鐘。中間的一切平行執行。