Claude Code 中的 Git worktree：平行工作階段

Ailoot 的實用操作資訊請參閱文件。

Claude Code 中的 Git worktree 是什麼#

在同一個資料夾中平行啟動多個代理程式，就是在 2026 年的速度下進行 vibe-coding 時，最基本的痛點。AI 代理程式寫程式碼的速度，比人追蹤誰正在改什麼還快。沒有檔案隔離時，在同一個目錄中平行啟動兩個 Claude Code 工作階段，最後就會有一個工作階段覆寫另一個的成果。

Git worktree 在檔案系統層級解決了這個問題。你有一個主要目錄可供工作。命令 claude --worktree feature-auth 會在另一個分支上建立 .claude/worktrees/feature-auth/ 資料夾，並在其中啟動 Claude Code。檔案彼此隔離。在你明確合併之前，一個工作階段的變更不會出現在另一個工作階段中。

Anthropic 官方文件如此說明：

自我檢查的小提示：如果你曾經收到一個 commit，裡面有一半檔案是別人的成果，那你就需要 worktree。

Git worktree 和一般分支有什麼不同#

標準的 Git 流程是：你在 main 分支上執行 git checkout feature-x，Git 就會覆寫工作副本中的檔案。因為 package.json 在執行中被改動，正在執行的 npm run dev 會出問題。你把未提交的變更 stash 起來，等待 IDE 重新建立索引。切回去時，所有內容又被覆寫，因此你又得 stash 再 pop 一次。

Git worktree 提供另一種選擇：你不必在分支之間切換同一個資料夾，而是為另一個分支建立第二個資料夾。命令 git worktree add ../project-feature-x feature-x 會建立 ../project-feature-x/ 目錄，裡面有 feature-x 分支的檔案。main 仍留在原本的資料夾中，開發伺服器也會繼續執行。

過去，在 Claude Code 中使用 worktree 模式必須手動設定：先執行 git worktree add，再執行 cd，然後啟動 claude，而且每個終端機都要重複一次。--worktree 旗標（也可寫成 -w）用一個命令就能完成這三個步驟。

啟動第一個平行工作階段：--worktree 旗標#

最精簡的範例。在專案根目錄開啟第一個終端機：

claude --worktree feature-auth

Claude Code 會做三件事：

1. 使用 origin/HEAD（通常是你的預設分支）的快照建立 .claude/worktrees/feature-auth/。
2. 建立新的 worktree-feature-auth 分支。
3. 在這個資料夾中啟動工作階段。

在同一個儲存庫的根目錄開啟第二個終端機：

claude --worktree bugfix-123

完成。兩個 Claude Code 工作階段、磁碟上的檔案各自分開、Git 分支也不同。如果你在第一個工作階段撰寫驗證功能，在第二個工作階段修正失敗的測試，它們在實際檔案上就不可能互相干擾。

如果你不想輸入名稱，Claude 會替你取一個：

claude --worktree
# → 建立類似 .claude/worktrees/bright-running-fox/ 的目錄

給 Git 初學者的小提示：把 .claude/worktrees/ 加到 .gitignore。否則，在主要資料夾執行 git status 時，所有 worktree 的內容都會顯示為未追蹤檔案：

# .gitignore
.claude/worktrees/

要避免的陷阱：在新目錄中第一次啟動 --worktree 之前，先用一般的 claude（不加旗標）進入該目錄，並接受工作區信任對話框。如果沒有接受，旗標就會因為「尚未接受信任」錯誤而失敗；即使搭配無人值守模式的 -p 也一樣。

worktree 的位置與尋找方式#

預設位置固定為儲存庫根目錄下的 .claude/worktrees/<value>/。如果你的專案位於 ~/dev/my-app/，feature-auth worktree 就會位於 ~/dev/my-app/.claude/worktrees/feature-auth/。

對於非標準的配置（例如想把 worktree 放在儲存庫外），可以使用 WorktreeCreate hook；下方介紹 SVN 與 Mercurial 的章節會進一步說明。

在同一個 Claude 工作階段中，你可以切換到另一個現有 worktree。只要在聊天中說：「切換到 .claude/worktrees/bugfix-123」，Claude 就會呼叫 EnterWorktree 工具。目前的資料夾會保持原樣；你也可以用相同方式切回來。

標準 Git 命令會列出所有 worktree，包括主要 worktree 和手動建立的 worktree：

git worktree list

輸出會像這樣：

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

複製 .env 和機密資料：.worktreeinclude 檔案#

使用 --worktree 建立新資料夾時，裡面只有已提交到 Git 的內容。含有 API 金鑰的 .env 和含有本機設定的 .env.local 都在 .gitignore 中，所以不會出現在 worktree 裡。於是第一次執行 npm run dev 就會因為「MISSING DATABASE_URL」而失敗。

土法解決方式是每次執行 --worktree 後都手動複製 .env。第一次有效，之後就會忘記。Anthropic 的解決方式是在專案根目錄建立 .worktreeinclude 檔案，列出 Git 忽略的檔案，讓它們自動複製到每個新 worktree。

在儲存庫根目錄建立 .worktreeinclude 檔案：

.env
.env.local
config/secrets.json

語法和 .gitignore 相同。你可以使用 glob 模式：

.env*
*.local
config/*.json
.vscode/settings.json

Anthropic 提供了一條明確規則來避免意外：

換句話說，你不會透過 .worktreeinclude 不小心複製 package.json，因為它不在 .gitignore 中。放入任何模式都很安全。

同一個 .worktreeinclude 適用於三種模式：手動使用 --worktree、子代理的自動 worktree（見下文），以及 Claude 桌面應用程式的工作階段。

從 pull request 建立 worktree 以進行程式碼審查#

常見的程式碼審查情境是：同事送來一個 PR，你需要檢查程式碼、執行測試並留下留言。使用一般的 git checkout pull/1234/head，你又得切換工作副本，並中斷目前的工作階段。

使用 --worktree 旗標，只需一個命令：

claude --worktree "#1234"

接下來會發生這些事：Claude Code 執行 git fetch origin pull/1234/head，在 .claude/worktrees/pr-1234/ 建立 worktree，並切換到 PR 分支。工作階段隨即啟動。你可以立刻要求它「閱讀差異、執行測試，並找出邏輯錯誤」；Claude 工作時，你在 main 上的主要工作階段會繼續執行。

另一種寫法是傳入完整的 pull request 網址：

claude --worktree https://github.com/OWNER/REPO/pull/1234

在實際專案中，把 claude --worktree "#N" 和你自己的程式碼審查子代理搭配使用，就能在一兩分鐘內自動完成審查。在背景啟動它，繼續在主要視窗工作，再透過 claude agents 查看結果。

基底分支：worktree.baseRef 的 fresh 或 head#

預設設定是：每個新 worktree 都從 origin/HEAD 開始。好處是起點乾淨，且一定會符合 CI 將看到的狀態。缺點是，如果你目前的分支有未提交的變更，或有幾個比遠端更新的本機 commit，它們都不會包含在新 worktree 中。

若要從目前本機 HEAD 提交開始，請在 .claude/settings.json（或全域設定）加入：

{
  "worktree": {
    "baseRef": "head"
  }
}

現在 claude --worktree experimental-feature 從目前本機 HEAD 開始，適合功能已有本機未推送提交的情況，不含仍未提交追蹤編輯。子代理若需要它們，應保存並明確轉移必要修改，再查看目的地 diff；不要與處理忽略檔的 .worktreeinclude 混淆。

此設定恰好接受兩個值："fresh"（即 origin/HEAD）和 "head"（即本機 HEAD）。不接受 "feature-branch" 或 commit hash 等任意 refs；這項限制是刻意設計的，目的是避免選項組合爆炸。

自動隔離子代理：isolation: worktree#

當你告訴 Claude：「啟動三個子代理：第一個讀取資料庫，第二個查看 API，第三個檢查測試」，預設情況下，三個子代理都會在你的工作副本中工作。即使只有兩個代理同時寫入同一個檔案，也會發生衝突。解決方式是自動為每個代理分配自己的 worktree。

方法 1：直接以文字要求。在對話中告訴 Claude：

讓你的代理使用 worktree。

Claude 會在這個工作階段中，對之後啟動的所有子代理套用隔離設定。

方法 2：直接在子代理本身明確設定。在子代理檔案中（例如 .claude/agents/code-reviewer.md），於 frontmatter 加入欄位：

---
name: code-reviewer
description: Reads the diff and writes code review comments
isolation: worktree
---

You're a meticulous reviewer. Read the diff and look for logic errors...

現在每次啟動這個子代理時，都會在 .claude/worktrees/ 中取得一個暫時的 worktree。如果子代理沒有寫入任何內容，結束時該資料夾會自動刪除。如果有未提交的變更，Claude 會詢問你要保留還是移除。

子代理 worktree 的基底分支與 --worktree 相同：預設是 origin/HEAD；若設定 worktree.baseRef: head，則使用本機 HEAD。

決策矩陣：worktree、/bg、subagent 或 Agent View#

常見組合：

• 「手動平行開發兩個功能」 — 開啟兩個終端機，各自執行 claude --worktree。這是最簡單的情境。
• 「啟動整晚的重構，然後關閉應用程式」 — 使用 /bg + /goal 並設定完成條件。工作階段會獨立於你的視窗執行。
• 「一個提示詞、三項平行調查」 — 啟動三個設定 isolation: worktree 的子代理。每個代理都在自己的沙箱中工作。
• 「現在有哪些工作正在執行？」 — 使用 claude agents。儀表板會顯示所有工作階段，並提供「執行中」、「受阻」和「已完成」篩選器。

使用 worktree 時的 5 個陷阱#

1. 啟動 worktree 後發現 .env 不見了，什麼都不能執行。 這是最常見的問題。worktree 是全新的檢出，裡面沒有 Git 忽略的檔案。解決方式是在設定 worktree 模式時，立刻新增 .worktreeinclude 檔案，加入 .env* 和必要的本機設定。確認檔案位於儲存庫根目錄，而不是 .claude/ 裡。

2. 你想切回 main 分支，在根目錄執行 cd，結果以為 worktree 裡未提交的變更不見了。 根目錄資料夾和 worktree 是兩份不同的工作副本。執行 cd 回去時，worktree 中的變更仍留在原處，沒有消失。但如果你搞混位置，以為自己在 worktree 中，卻在主要資料夾執行 git stash，stash 就會建立在 main 分支，而不是你原本預期的分支。

3. 平行啟動 5 個工作階段後，想不起來每個工作階段在做什麼。 Anthropic 的文件明確提醒，大多數開發者在認知上無法同時處理超過 2–3 個工作階段。負荷過大的徵兆是：開啟 Agent View 後，無法立刻說出每個代理正在做什麼。請將同時執行的工作階段限制在兩個。如果任務需要更多代理，就應透過 /goal + 子代理進行協調，而不是手動管理。

4. 透過 -p（無人值守模式）啟動的 worktree 不會自動清理。 命令 claude --worktree feature-x -p "do thing" 不會顯示互動式離開提示，因此 Claude 不會詢問「要移除 worktree 嗎？」這些 worktree 會不斷累積。請手動清理：git worktree remove .claude/worktrees/feature-x。也可以使用 cron 指令碼移除任何超過 7 天的項目。

5. 新資料夾中的信任對話框。 如果你第一次開啟儲存庫就立刻執行 claude --worktree，命令會失敗。先不帶旗標執行 claude，接受工作區信任後再離開，之後 --worktree 就能正常運作。這項設計是刻意的，目的是避免 Claude 未經使用者同意就存取他人的專案。

清理：哪些內容會自動刪除#

清理邏輯取決於你在 worktree 中做了什麼，以及如何啟動工作階段。Anthropic 的文件列出三種情況：

情況 1：你進入 worktree，什麼都沒做就離開，worktree 隨即移除。

情況 2：你做了一些工作但沒有提交，離開時 Claude 會詢問「保留或移除？」選擇「保留」會將資料夾和分支存下來供日後使用。選擇「移除」則會刪除目錄，連同未提交的變更和新 commit 一起刪除。這會造成破壞，別習慣性地按下「移除」。

情況 3：你使用 -p（無人值守模式）啟動，命令執行完畢並離開。worktree 會保留下來。請手動清理：

git worktree remove .claude/worktrees/feature-x

此外，子代理和 /bg 工作階段所建立的 worktree，如果超過 cleanupPeriodDays 天（一般預設值為 30 天），而且沒有未儲存的工作，就會由背景清理程序自動移除。--worktree 建立的 worktree 不會受到自動清理影響，必須由你自行負責。

SVN、Perforce 和 Mercurial 的替代方式：WorktreeCreate hook#

如果儲存庫使用 Subversion 或 Mercurial，--worktree 旗標就無法直接運作。Anthropic 提供兩個 hooks 作為擴充介面：WorktreeCreate（建立隔離副本）和 WorktreeRemove（移除副本）。

以下是官方文件中的 SVN hook 範例：

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

hook 從 stdin 讀取 worktree 名稱（{ "name": "feature-auth" }），在預先決定的目錄中執行 svn checkout，並將路徑輸出到 stdout。Claude Code 會將該路徑做為新工作階段的工作目錄。

重要注意事項：使用自己的 hook 時，不會使用 .worktreeinclude。如果新資料夾需要 .env 或其他被 Git 忽略的檔案，請在 hook 指令碼中複製它們。

接下來：三種相關的平行作業機制#

worktree 提供檔案隔離。/bg 提供脈絡隔離。子代理提供任務隔離。每種機制單獨使用都能解決一項問題。搭配使用，就能在不造成認知崩潰的情況下，同時處理三到五項平行任務。這是在 2026 年進階 vibe-coding 所需的一套技能。

這個主題自然延伸到三個相關主題：如何使用 /goal 和 Agent View 設定自主代理、如何為自己的任務建立子代理，以及如何透過 Dynamic Workflows 啟動數百個代理。

前往 Ailoot。