一個 Claude Code session 修 auth bug，另一個在寫新的 API endpoint，第三個在跑測試然後修 failing cases。三件事同時進行，互不干擾。

這不是什麼未來願景，是 Claude Code 的 --worktree flag 已經能做到的事。Boris Cherny（Claude Code 的創造者）自己的工作流是同時跑 10-15 個 session，每個 session 各自推進不同任務。聽起來很瘋狂？其實設定比你想的簡單得多。

為什麼需要 Worktrees

先講問題。你在一個 repo 裡開了 Claude Code session A 修 bug，修到一半想讓另一個 session B 同時去加新功能。結果 B 改了你正在 debug 的檔案，A 的 git status 瞬間爆炸——unstaged changes、merge conflicts、整個 context 亂掉。

Git worktree 解決這個問題。一個 worktree 就是同一個 repo 的一個獨立工作目錄，有自己的 branch、自己的檔案，但共享同一份 git history 和 remote。你可以把它想成「同一個 repo 的平行宇宙」——每個宇宙裡的 Claude 各做各的，完事後 merge 回來就好。

一行指令開始

Claude Code 內建了 worktree 支援，不需要自己手動 git worktree add：

1
2
3
4
5
6
7
8
# 建立名為 feature-auth 的 worktree 並啟動 Claude
claude --worktree feature-auth

# 建立另一個 worktree 修 bug
claude --worktree bugfix-123

# 懶得取名？Claude 自動產生一個
claude --worktree

也可以用縮寫 -w：

1
claude -w feature-auth

Worktree 會建在 <repo>/.claude/worktrees/<name>/，branch 名稱是 worktree-<name>，base 分支預設是 origin/HEAD 指向的 branch。

實戰：三個 Terminal 同時跑

打開三個終端機視窗（iTerm2 的 split pane 或 tmux 都行）：

Terminal 1 — 修 bug

1
2
3
claude -w fix-auth-race-condition
# 進去之後：
# "auth.ts 的 race condition 導致偶發 401，幫我找到根因並修復，要附測試"

Terminal 2 — 新功能

1
2
3
claude -w feature-user-preferences
# 進去之後：
# "在 user service 加上 preferences CRUD，參考現有的 profile 模組風格"

Terminal 3 — 重構

1
2
3
claude -w refactor-db-queries
# 進去之後：
# "把 raw SQL queries 改成 ORM，從 user.ts 開始，每改一個檔案跑一次測試"

三個 Claude 各在各的 worktree 裡工作，不會互相踩到。

.worktreeinclude：自動複製 .env

新 worktree 是乾淨的 checkout，不會包含 .env、config/secrets.json 這些 gitignored 的檔案。第一次忘記這件事的時候你的 app 會直接 crash。

在 repo 根目錄建一個 .worktreeinclude 檔案：

1
2
3
.env
.env.local
config/secrets.json

Claude 建 worktree 時會自動把這些檔案複製過去。只有同時符合「match pattern」且「被 gitignore」的檔案才會被複製，tracked 的檔案不會重複。

Subagent 也能用 Worktrees

不只是你手動開多個 terminal。Claude 的 subagent 也支援 worktree 隔離——在 .claude/agents/ 的 agent 定義裡加一行 isolation: worktree，subagent 就會自己建 worktree 來工作：

1
2
3
4
5
6
7
8
9
10
# .claude/agents/test-runner.md
---
description: "Run tests in isolation"
isolation: worktree
tools:
  - Bash
  - Read
---
Run all tests and fix any failures. Do not modify source files 
outside the test directory.

或是在對話中直接說「use worktrees for your agents」，Claude 會自動替 subagent 分配獨立的 worktree。

Subagent 做完沒改東西？worktree 自動清掉。有改動？保留等你 review。

跟 Cursor 和 Copilot 比

Cursor 3 剛發布的 agent-first 架構也支援跑多個 agent，但它是在 IDE 內切換，不是真正的獨立工作目錄。如果兩個 Cursor agent 同時改同一個 repo 的不同檔案，還是有衝突風險。

GitHub Copilot 的多 agent 功能還在早期，主要靠 cloud-based workspace。你的 code 要傳到 GitHub 的 server 上跑。

Claude Code 的 worktree 方案是本地 + 獨立目錄，用 Git 原生機制做隔離。不依賴雲端、不需要特殊 IDE 支援、資料不離開你的機器。缺點是吃硬碟空間——每個 worktree 都是一份完整的 checkout（但共享 .git objects，所以不是完整 clone 那麼大）。

清理與管理

退出 worktree session 時，Claude 會自動處理：

  • 沒有任何修改 → worktree 和 branch 自動刪除
  • 有修改或 commit → Claude 問你要保留還是移除

如果你想手動管理：

1
2
3
4
5
6
7
8
# 列出所有 worktree
git worktree list

# 手動移除
git worktree remove .claude/worktrees/feature-auth

# 清理過期的 worktree 參照
git worktree prune

記得在 .gitignore 加上 .claude/worktrees/，不然 main repo 的 git status 會顯示一堆 untracked files。

Base Branch 不對怎麼辦

Worktree 預設從 origin/HEAD branch 出去。如果你的 origin/HEAD 指向的不是你想要的 branch（例如 clone 很久了，remote 的 default branch 已經改了），手動同步一下：

1
2
3
4
5
# 重新同步 origin/HEAD
git remote set-head origin -a

# 或者指定特定 branch
git remote set-head origin develop

如果你需要每次都從不同 branch 分支，可以設定 WorktreeCreate Hook 來自定義 worktree 建立邏輯。

給 3-5 個 Worktrees 同時跑的建議

Boris Cherny 的建議是 3-5 個 worktree 為一個 sweet spot。超過這個數量，context switching 的認知負擔（就算是看 Claude 的輸出也需要腦力）會開始抵消平行化的好處。

幾個實用建議：

任務要清晰獨立。如果兩個 worktree 的任務會改到同一組核心檔案，merge 的時候會很痛苦。開始之前先想清楚任務邊界。

用 session name 管理。每個 worktree session 取個好名字：claude -w fix-auth -n "修 auth race condition"，之後用 claude --resume "修 auth race condition" 就能快速回到上下文。

每個 worktree 跑完記得 push。因為 worktree 是本地的，如果你的硬碟出問題，沒 push 的 commit 就沒了。

定期清理。worktree 多了之後 git worktree list 看一下，完成的就 remove，不然佔硬碟空間。

平行跑 AI agent 聽起來很潮，但本質上就是多開幾個獨立工作目錄，用 Git 的原生機制做隔離。沒有什麼黑魔法，只是 Claude Code 把這個流程包裝成一個 --worktree flag 讓你一行指令搞定。試過一次就回不去了。

原文來源：Claude Code Common Workflows - Git Worktrees