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

成果：3 個功能，40 分鐘

想像一座工廠。三條產線並排運轉，各自組裝不同的產品。沒有任何一條在等另外兩條。沒有工人跑錯車道。時間到了，三件成品同時下線。

這就是實際發生的事。三個 Next.js 電商功能。平行開發。乾淨合併。所有測試通過。

實際牆鐘時間：40 分鐘。同樣的工作量序列開發大約要 2 小時。省下的時間來自重疊。Agent 1 做搜尋的同時，Agent 2 做購物車，Agent 3 做信件。三條產線。一個終端視窗，三個並排面板。

這篇文章走過整個 session 的每一步。打什麼指令、注意什麼、怎麼合併。如果你需要 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

情境：電商衝刺開發

三個功能。三個不同的程式碼角落。

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

為什麼這三個能平行：它們幾乎不重疊。搜尋在 app/search/ 和 lib/search/。購物車在 app/cart/ 和 lib/cart/。信件在 lib/email/ 和 app/api/orders/。共用一個檔案 -- types/product.ts 裡的 Product type -- 加上幾個工具函式。就這樣。

重疊越少，merge conflict 越少。Conflict 越少，平行化實際省下的時間越多。

第一步：先定義共享型別

在啟動任何 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 需要更多注意力時 -- 它問了問題，或是跑完需要審查 -- 拖邊框放大。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 監控

這是平行開發從「執行 agent」轉變為「管理 agent」的時刻。你的工作不再是寫程式。你的工作是觀察、回應、介入。

注意 agent 的問題。 Claude Code 有時會問確認：「搜尋結果要用 server component 還是 client component？」快速回答。三個面板同時可見，問題一出現你馬上就看到。

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

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

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

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

三個都跑完了。合併之前先審查。

# 商品搜尋 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 錯誤

然後清理：

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 不管單獨跑還是一起跑，速度相同。省的時間純粹來自重疊。你付出 15 分鐘的合併審查成本。淨省 47 分鐘。

這隨功能數量擴展。四個平行功能省更多。兩個省較少。三個是最佳平衡點 -- 產出夠高，監控還不會手忙腳亂。

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

適合用平行 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，會有 merge conflict。預防：啟動 agent 前，把共用的設定項目先加到 main。如果還是衝突了，幾秒鐘解決。

Agent 跑到一半 context 用完。 在複雜 codebase 中，長時間執行的 agent 可能撞到 context 上限。在同一個 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。一個終端視窗。設定花兩分鐘。合併花十五分鐘。中間的一切平行執行。