用 Git Worktree 跑多 Agent 開發 — 完整設定指南

核心問題：AI Agent 會搶你的工作目錄

你讓 Claude Code 重構認證模組。做到一半，你想讓第二個 agent 同時處理 API 層。你開了另一個終端，在同一個 repo 裡啟動新的 Claude Code session，幾分鐘內兩個 agent 就開始編輯重疊的檔案、互相覆蓋修改，產出一份兩邊都編譯不過的程式碼。

這是單一目錄開發的根本限制。Git 預設每個 repository 只追蹤一個 working tree。每個 staged change、每個已修改檔案、每個未 commit 的編輯，都被所有讀取該目錄的 process 共享。兩個 AI agent 同時寫入同一個目錄，跟兩個開發者在同一台機器上、不用版本控制地同時編輯同一份檔案沒有兩樣，只不過 agent 寫得更快，所以衝突也來得更快。

Git worktree 徹底消除這個問題。

Git Worktree 是什麼、為什麼存在

Git worktree 能建立額外的工作目錄，並連結到同一個 repository。每個 worktree 有自己 checkout 的 branch、自己的 staged changes、自己的工作檔案，但它們共享同一份 .git 歷史紀錄、同一組 remote、同一組 ref。

# 你的主 repo 在 ~/project
# 為 feature branch 建立一個 worktree
git worktree add ../project-feature-auth feature/auth

# 現在你有兩個目錄：
# ~/project              → main branch
# ~/project-feature-auth → feature/auth branch

關鍵概念：worktree 不是 clone。git clone 會複製整個 repository，建立獨立的 .git 目錄和完整歷史。Worktree 則共用原始的 .git 目錄。這代表：

• 磁碟用量極小。 Worktree 只存工作檔案，不複製整個 git object database。2 GB 的 repo，clone 用 2 GB，worktree 只用 checkout 出來的檔案大小。
• Branch 自動同步。 在任一 worktree 做的 commit，其他所有 worktree 立刻可見。在一邊 push，在另一邊 pull，底層是同一個 repo。
• 不需要設定 remote。 Worktree 繼承父 repository 的 origin remote、驗證方式和 hooks。不用額外設定。

限制：每個 worktree 必須在不同的 branch 上。你不能在兩個 worktree 同時 checkout 同一個 branch。這對多 agent 開發來說反而是優點，它強制每個 agent 用自己的 branch，正是你需要的。

為什麼 Git Worktree 完美適合 AI Agent

AI 寫程式 agent 有三個特性讓 worktree 成為理想的隔離機制：

Agent 改檔案很兇。 一個 Claude Code prompt 可能動到你專案中的 15 個檔案。兩個 agent 共用一個目錄，必然會編輯同一個檔案，而且兩個 agent 都不知道對方做了什麼修改。Worktree 保證檔案系統層級的隔離，agent A 根本看不到 agent B 的變更。

Agent 比人類快。 人類開發者切換任務的速度慢到兩個人在同一台機器上很少撞車。AI agent 在幾秒內就能寫入、讀取、編譯、迭代。碰撞窗口以秒計算，不是以小時。Worktree 完全關閉這個窗口。

Agent 從平行化中獲益比人類大。 人類一次只能專注一件事。三個 agent 平行處理三個不同的功能，就是實打實的 3 倍產出，每個 agent 都拿到你的完整 codebase context，全速運作。瓶頸從 agent 速度轉移到你監控和合併的能力。

Claude Code 的內建 Worktree 支援

Claude Code 在 2026 年 2 月加入了原生 worktree 支援，透過 --worktree（簡寫 -w）flag。這是跑平行 agent 最簡單的方式。

--worktree Flag

# 在新的 worktree 中啟動 Claude Code
claude --worktree feature-auth

# 簡寫
claude -w feature-auth

一條指令做三件事：

1. 在 .claude/worktrees/feature-auth/ 建立新的 git worktree
2. 建立並 checkout 名為 feature-auth 的新 branch
3. 在該 worktree 中啟動 Claude Code session

省略名稱的話，Claude Code 會自動產生隨機名稱：

claude --worktree
# 建立類似 .claude/worktrees/jade-fox-42/ 的東西

平行跑多個 Agent

開三個終端視窗，啟動三個 worktree：

# 終端 1
claude -w feature/auth

# 終端 2
claude -w feature/api-layer

# 終端 3
claude -w tests/integration

每個 agent 有自己的 branch、自己的目錄、自己的工作檔案。三個 agent 可以同時讀寫、編譯、跑測試，完全不知道彼此存在。每個 worktree 的額外開銷微乎其微，500 MB 的典型專案，每個 worktree 大約加 500 MB（工作檔案），git object database 繼續共用。

Worktree 清理

退出 worktree session 時，Claude Code 根據狀態自動處理：

• 沒有任何變更： Worktree 和 branch 自動移除。零手動清理。
• 有變更或 commit： Claude Code 詢問你要保留還是移除。保留的話，目錄和 branch 都留著方便之後繼續。移除的話，刪除 worktree 目錄和 branch，拋棄所有未 commit 的變更和本地 commit。

也可以隨時手動清理：

# 列出所有 worktree
git worktree list

# 移除特定 worktree
git worktree remove .claude/worktrees/feature-auth

# 清理過期的 worktree 引用
git worktree prune

子 Agent 的 Worktree 隔離

Claude Code 的子 agent 系統也支援 worktree 隔離。當子 agent 需要做可能與主 agent 衝突的變更時，可以設定它使用自己的 worktree：

# 在自訂 agent 定義中 (.claude/agents/refactor-agent.md)
---
isolation: worktree
---

設定 isolation: worktree 後，子 agent 自動拿到自己的 worktree。子 agent 完成任務且沒有變更時，worktree 靜默清理。有變更時，留在子 agent 的 branch 上供你審查和合併。

實戰步驟：Auth、API、Tests 三個 Agent 平行作業

完整的操作流程。你要開發新的使用者管理功能，需要修改認證模組、API 層和整合測試。不逐一處理，而是三個 Claude Code agent 平行作業，各自在自己的 worktree 中運作。

第一步：確認起始狀態

# 確認 main branch 乾淨
git status
# On branch main
# nothing to commit, working tree clean

# 確認沒有既存 worktree
git worktree list
# /Users/you/project  abc1234 [main]

第二步：建立 Worktree 並啟動 Agent

開三個終端視窗或面板，在每個裡面：

# 終端 1 — Auth agent
claude -w feature/user-auth
# Prompt："實作基於 JWT 的使用者認證，包含 refresh token rotation。
# 加上 login、logout、token refresh endpoint。使用 prisma/schema.prisma
# 中既有的 User model。"

# 終端 2 — API agent
claude -w feature/user-api
# Prompt："為使用者 profile 管理建立 CRUD API endpoint：
# GET /api/users/:id、PATCH /api/users/:id、DELETE /api/users/:id。
# 用 zod 做輸入驗證。遵循 app/api/ 中既有的 route 模式。"

# 終端 3 — Test agent
claude -w feature/user-tests
# Prompt："為使用者管理功能寫整合測試。涵蓋認證流程
#（login、logout、token refresh）、profile CRUD 操作、
# 以及錯誤情境（無效 token、缺少欄位、未授權存取）。
# 使用 tests/setup.ts 中既有的測試設定。"

三個 agent 現在各自獨立運作。Auth agent 建立 middleware 和 token 邏輯。API agent 建造 route handler。Test agent 根據既有 codebase 模式撰寫測試案例。

第三步：監控進度

三個 agent 同時跑的時候，事情開始變有趣，你需要同時盯三個。每個終端顯示各自 agent 的進度、檔案修改、以及 agent 提出的任何問題。

三個平行終端正是專業終端配置發揮價值的場景。你需要三個 agent 同時可見，而且能對需要注意的那個終端自由調整大小。Termdock 可以自由拖拉調整終端面板，三個 agent 並排、或兩上一下，隨著你的注意力在 agent 之間切換即時重新排列。

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

三個 agent 都完成後，檢查各自做了什麼：

# 檢查 auth agent 的變更
cd .claude/worktrees/feature/user-auth
git log --oneline main..HEAD
git diff main --stat

# 檢查 API agent
cd .claude/worktrees/feature/user-api
git log --oneline main..HEAD
git diff main --stat

# 檢查 test agent
cd .claude/worktrees/feature/user-tests
git log --oneline main..HEAD
git diff main --stat

第五步：合併成果

合併順序很重要。從其他 branch 依賴的變更開始：

# 回到 main
cd ~/project

# 先合併 auth（API 和 tests 依賴 auth 的型別）
git merge feature/user-auth

# 再合併 API
git merge feature/user-api

# 最後合併 tests（tests 引用 auth 和 API 的程式碼）
git merge feature/user-tests

如果三個 agent 在真正各自獨立的區域工作，合併會順利完成。當他們碰到相同的檔案（共享型別或設定檔很可能如此）你會得到標準的 git merge conflict，幾分鐘內就能解決。

衝突解決策略

三個平行 agent 有時會產生衝突的變更。這是預期中的。解決策略取決於衝突類型。

類型一：Import 和依賴衝突

最常見的衝突。Agent A 加了 import { AuthToken } from '@/types'，agent B 在同一行加了 import { UserProfile } from '@/types'。

解法： 兩個 import 都留。這些是加法性的變更，語義上不衝突，git 只是無法自動合併它們，因為碰到同一行。

類型二：共享設定檔衝突

多個 agent 修改同一份設定檔，package.json、prisma/schema.prisma、或共用的 constants 檔。

解法： 仔細合併。package.json 就合併兩邊加的依賴。Prisma schema 確認不同 agent 的 model 定義沒有衝突。用 git mergetool 或手動解決，這些衝突是機械性的，不是邏輯性的。

類型三：架構性衝突

Agent A 和 agent B 對同一個系統邊界做了不同的架構決策。Agent A 預期透過 middleware 做認證，agent B 在每個 route handler 中實作 inline auth 檢查。

解法： 選一種方式，然後請一個 agent 統一。這時候用合併後的狀態開一個新的 Claude Code session：

claude "Auth agent 用了 middleware-based 認證，但 API agent 加了 inline
auth 檢查。統一到 middleware-based auth。移除 inline 檢查，確保每個
route 都使用 auth middleware。"

預防：在衝突發生前減少它們

最好的衝突解決就是衝突預防。啟動平行 agent 之前：

1. 先定義 interface。 在 branching 之前，在 main 上建立共享的 type 和 interface。所有 agent 都從同一份 types 檔 import 的話，實作更可能相容。
2. 分配不重疊的目錄。 Auth agent 在 lib/auth/ 和 app/api/auth/ 工作。API agent 在 app/api/users/ 工作。Test agent 在 tests/ 工作。最小重疊等於最小衝突。
3. 用明確的 prompt。 告訴每個 agent 其他 agent 在做什麼：「auth agent 正在 lib/auth/middleware.ts 實作 JWT middleware。建造你的 API routes 時，假設該 middleware 存在且 export 一個 requireAuth 函式。」

什麼時候合併：判斷框架

不是每個 worktree 都需要立刻合併。判斷框架如下。

重點： 完成的、獨立的工作立刻合併。未完成的工作保持 worktree 開著。永遠先合併被依賴者，再合併依賴者。

通則：短命的 worktree。Worktree 偏離 main 越久，合併越痛苦。目標是在幾小時內合併，不是幾天。

手動 Worktree 設定（不用 Claude Code 的 --worktree）

Claude Code 的 --worktree flag 最快，但任何 AI CLI 工具都能搭配手動 worktree。Gemini CLI、Codex CLI、aider，任何在本機目錄運作的 agent 都能跑在 worktree 裡。

手動建立 Worktree

# 從你的主 repo 目錄
git worktree add ./worktrees/feature-auth -b feature/auth
git worktree add ./worktrees/feature-api -b feature/api
git worktree add ./worktrees/feature-tests -b feature/tests

在每個 Worktree 中啟動 Agent

# 終端 1 — Claude Code 在 auth worktree
cd ./worktrees/feature-auth && claude

# 終端 2 — Gemini CLI 在 API worktree
cd ./worktrees/feature-api && gemini

# 終端 3 — 任何 agent 在 test worktree
cd ./worktrees/feature-tests && aider

混合 agent 的設定很強大。你可以在複雜的 auth 工作上跑 Claude Code，在直接的 API routes 上跑 Gemini CLI（省 Claude Code 額度），在測試生成上跑 aider。每個 agent 在自己的目錄，在自己的 branch 上。雙工具策略在這裡自然適用，根據任務複雜度分配 agent 到 worktree，不要因為工具偏好而綁死。

清理手動建立的 Worktree

# 列出所有 worktree
git worktree list

# 移除 worktree（保留 branch）
git worktree remove ./worktrees/feature-auth

# 移除 worktree 並刪除 branch
git worktree remove ./worktrees/feature-auth
git branch -d feature/auth

# 手動刪除目錄後清理過期引用
git worktree prune

監控多個 Agent：真正的瓶頸

Worktree 和 agent 的技術設定很直接。真正的瓶頸是注意力管理。三個 agent 平行跑代表三個輸出串流、三組檔案變更、三個 agent 可能問你問題然後等你回答。

有效的監控需要三件事：

可見性。 所有 agent 終端必須同時可見。分頁式終端毫無用處，如果你看不到 agent B 的問題因為在專注 agent A，agent B 就空轉。三個 agent 全部同時可見的平鋪式配置是最低要求。

快速切換。 Agent C 完成了需要你審查時，你要能放大那個面板但不失去對 agent A 和 B 的視野。固定大小的面板行不通，因為注意力需求持續在變。

Git 狀態感知。 每個 worktree 有自己的 branch、staged changes 和 commit 歷史。手動追蹤三個目錄的三個 branch 很容易出錯。整合式的狀態顯示，看到哪個 worktree 領先 main、哪個有未 commit 的變更、哪個有 merge conflict，省的是真實的時間。

這三 agent 監控模式正是 Termdock 解決的核心設計問題。拖拉任何終端邊框即時調整大小。跨所有 worktree 看 workspace 層級的 Git 狀態。把檔案直接拖進需要的那個 agent 終端。完整的終端配置和 AI CLI 工具組合方式，在 2026 AI CLI 工具完全指南中有完整說明。

進階：大型 Repo 的 Worktree 設定

超過 5 GB 的 repository 或有大量 node_modules 的 monorepo，worktree 建立可能會慢，因為 git 會複製整個 working tree。兩個優化方式可以幫上忙。

Worktree 中的 Sparse Checkout

如果每個 agent 只需要 repo 的一部分：

# 建立有 sparse checkout 的 worktree
git worktree add --sparse ./worktrees/feature-auth -b feature/auth

# 設定要包含的目錄
cd ./worktrees/feature-auth
git sparse-checkout set src/auth src/types tests/auth package.json tsconfig.json

Auth agent 現在只看到它需要的檔案。Worktree 建立更快、磁碟用量更低，agent 處理的無關 context 也更少。

用 Symlink 共享依賴

Node.js 專案中，每個 worktree 都有 node_modules 浪費磁碟空間和安裝時間：

# 在主 repo 安裝一次依賴
cd ~/project && npm install

# 把 node_modules symlink 到每個 worktree
ln -s ~/project/node_modules ./worktrees/feature-auth/node_modules
ln -s ~/project/node_modules ./worktrees/feature-api/node_modules

前提是 agent 沒有在用不同的依賴修改 package.json。如果有，每個 worktree 需要自己的 npm install。

常見錯誤

在兩個 worktree checkout 同一個 branch。 Git 會阻止這個行為，但開發者有時會試著繞過。不要這樣做。每個 worktree 有自己的 branch，這就是隔離的重點。

忘記清理過期的 worktree。 如果你用 rm -rf 而不是 git worktree remove 手動刪除 worktree 目錄，git 會保留過期的引用。定期跑 git worktree prune，或使用 Claude Code 內建的自動清理機制。

讓 worktree 分歧太久。 一週沒合併的 worktree 會有痛苦的 merge conflict。早合併、常合併。如果需要讓 worktree 開著好幾天，每天在 main 上 rebase：

cd ./worktrees/feature-auth
git rebase main

沒有告訴 agent 彼此的存在。 如果 agent A 建了一個新型別是 agent B 需要的，而你沒在 agent B 的 prompt 中提到，agent B 要不發明一個不相容的型別，要不編譯失敗。在 prompt 中加入跨 agent 的 context，「auth agent 在 src/types/auth.ts 建立了 JWTPayload type，在你的 API handler 中使用那個 type。」

同時跑太多 agent。 三個平行 agent 是甜蜜點。五個以上很難有效監控，合併複雜度以平方級成長。從兩個開始，熟練後到三個，很少需要超過四個。

快速參考

重點： claude -w 是一條指令的捷徑。git worktree add/remove/list/prune 給你完整的手動控制。

清單：你的第一次多 Agent Worktree Session

1. 確認前置條件。 Git 2.20+（worktree 功能穩定版本）、Claude Code 已安裝、main branch 乾淨。

2. 選一個有 2-3 個平行子任務的工作。 理想：一個包含 auth、API、測試元件的功能。不理想：單檔案 bug 修復（直接用一個 agent 就好）。

3. 先定義共享 interface。 在 branching 之前在 main 上建立共享的 type。這能大幅減少 merge conflict。

4. 啟動 worktree。 在不同終端分別跑 claude -w subtask-a、claude -w subtask-b、claude -w subtask-c。

5. 寫包含跨 agent context 的明確 prompt。 告訴每個 agent 其他 agent 在做什麼。提到共享的 type、預期的函式簽名、目錄邊界。

6. 視覺化監控所有 agent。 平鋪你的終端讓所有 agent 同時可見。需要更多注意力時即時調整大小。

7. 按依賴順序合併。 基礎模組先、依賴模組後、測試最後。衝突立即解決。

8. 清理。 確認已合併的 branch 被移除。跑 git worktree prune 清理過期引用。合併完畢後在 main 上跑完整測試套件。

這個工作流可以從獨立開發者跑 2-3 個 agent 擴展到團隊中每個成員跑自己的一組平行 agent。Git worktree 的基本操作在任何規模都一樣，變的只有合併協調。AI CLI 工具如何融入平行開發工作流的完整圖景，在 2026 AI CLI 工具完全指南中有詳盡說明。