Claude Code worktree：平行執行多個工作階段，互不衝突

Claude Code worktree 是什麼

git 支援 worktree 已經很多年了：git worktree add 會把一個分支簽出到第二個目錄，背後用的是同一份 .git 資料。Claude Code 在此基礎上更進一步：加上 --worktree（或 -w），它會替你建立 worktree、在裡面啟動工作階段、擋下會落到主要簽出目錄的修改，並在你結束時提示清理。

worktree 只隔離檔案，其他一概不管。想在一個對話裡把任務分給多個 worker，用 subagent；各種做法的比較見多個 Claude Code 代理。

• 預設位置：儲存庫根目錄下的 .claude/worktrees/<name>/。
• 預設分支名稱：worktree-<name>。不給名稱的話，Claude Code 會自動取一個，例如 bright-running-fox。
• 與簽出目錄共用的：.git 目錄（所以提交和分支在哪裡都看得到）、專案範圍的外掛，以及「不再詢問」的權限核准。
• 不共用的：所有被 gitignore 的內容，例如 .env、node_modules 和建置產出。worktree 是一份全新的簽出。

worktree 工作流程，一步一步來

1. 忽略 worktree 資料夾

   把 .claude/worktrees/ 加進 .gitignore，這樣 worktree 裡的檔案不會在主要簽出目錄中顯示為未追蹤。如果你從沒在這個儲存庫裡執行過 Claude，先執行一次 claude，接受工作區信任提示；在那之前，互動式的 --worktree 會直接結束。

2. 每個任務開一個工作階段

   每個任務在一個終端機裡執行 claude --worktree <name>。用既有的名稱再次執行，會重新開啟那個 worktree，而不是新建一個。你也可以在工作階段中途請 Claude「work in a worktree」，它會用 EnterWorktree 工具把自己移進一個 worktree。

   # 兩個互相隔離的工作階段，各開一個終端機
   claude --worktree feature-auth
   claude --worktree fix-flaky-test
   
   # 從 1234 號 pull request 建立 worktree（# 要加引號）
   claude --worktree "#1234"
   
   # 不讓 worktree 出現在 git status 裡
   echo ".claude/worktrees/" >> .gitignore

3. 把未追蹤的檔案帶過去

   在儲存庫根目錄建立 .worktreeinclude 檔案，用 .gitignore 語法列出專案需要的被忽略檔案，例如 .env 和 .env.local。Claude Code 會把符合的檔案複製到它建立的每個 worktree，包括 subagent 和桌面應用程式的 worktree。接著在 worktree 裡安裝相依套件，或在設定裡處理好：下面的例子從你目前的工作建立分支，重複使用同一份 node_modules，而且只簽出 web 套件。

   {
     "worktree": {
       "baseRef": "head",
       "symlinkDirectories": ["node_modules"],
       "sparsePaths": [".claude", "packages/web"]
     }
   }

4. 讓工作階段去做事

   工作階段處於隔離狀態時，Claude Code 會拒絕指向主要簽出目錄的檔案編輯、工作目錄在主要簽出目錄的指令，以及被導向主要簽出目錄的 git 指令（git -C、--git-dir、GIT_DIR）。它不會追蹤 cp 這類一般 shell 指令寫了什麼，所以權限和沙盒依然重要。

5. 像一般分支一樣審查和合併

   每個 worktree 都是一個一般的分支。在裡面提交、推送、開 pull request，像審查隊友的程式碼一樣審查它。所有 worktree 共用 .git，所以主要簽出目錄裡馬上就看得到這個分支。

6. 結束並清理

   結束時，Claude Code 會檢查 worktree。未命名工作階段的 worktree 如果是乾淨的，會連同分支自動刪除；已命名的工作階段則會先詢問。如果有變更、未追蹤的檔案或新提交，它會問你要保留還是刪除這個 worktree，並印出一行 claude --worktree <name> --resume 指令，方便之後回來繼續。

來源：Claude Code 文件，Run parallel sessions with worktrees

Claude Code 的 worktree 設定

以下設定都寫在設定檔（~/.claude/settings.json、.claude/settings.json 或 .claude/settings.local.json）的 worktree 底下。

Claude Code worktree、切換分支與 git worktree 比較

用 git worktree 手動操作

想用某個既有的分支，或把資料夾放在儲存庫之外，就用原生 git；worktree.baseRef 無法指定分支名稱。Claude Code 依然會和這些 worktree 共用外掛與權限核准。

1. 建立 worktree、啟動 Claude，用完刪除

   把 feature-a 換成新分支名稱；如果要簽出既有的分支，拿掉 -b 即可。

   git worktree add ../app-feature-a -b feature-a
   cd ../app-feature-a && claude
   git worktree list
   git worktree remove ../app-feature-a

在 worktree 裡執行 subagent 和背景工作階段

• 請 Claude「use worktrees for your agents」，或在 .claude/agents/ 裡自訂 subagent 的 frontmatter 中加上 isolation: worktree，每個 subagent 就會在各自的暫時 worktree 裡編輯。
• 沒有變更的 subagent worktree 會在 subagent 結束時刪除。有變更的會一直保留，直到 cleanupPeriodDays 之後，定期清理能在不遺失工作的前提下把它刪掉。
• 背景工作階段（claude --bg）預設只能在 worktree 裡編輯；可以用 claude --bg --worktree 啟動，或把 worktree.bgIsolation 設為 "none"。
• 在桌面應用程式裡，開始工作階段前先打開輸入框下方的 Worktree 開關。

worktree 清理與常見問題

• claude -p --worktree 執行時沒有結束提示，所以會留下 worktree。用 git worktree remove 刪除；如果 git 顯示已鎖定，先執行 git worktree unlock。
• Can only use --worktree in a git repository：執行 git init 並做第一次提交，或為 SVN、Perforce 或 Mercurial 設定 WorktreeCreate hook。
• 如果 Git LFS 是用 --local 安裝的，LFS 檔案會顯示為指標檔：在 worktree 裡執行 git lfs pull。
• 當 .claude 或 .claude/worktrees 是符號連結時，Claude Code 不會建立 worktree。
• hook 裡的 ${CLAUDE_PROJECT_DIR} 一律指向主要簽出目錄；要取得 worktree 路徑，請讀取 hook 輸入中的 cwd 欄位。
• 基準為 "fresh" 且沒有自己的提交、或 PR 已經合併的 worktree，依名稱重新開啟時會重設到預設分支。

worktree 讓工作階段互不干擾，Crewmark 讓它們一直有事做。

worktree 解決了衝突問題，但每個工作階段仍然要等你輸入才會動。Crewmark 把 Claude Code、Codex、DeepSeek Harness 或 OpenCode 工作階段變成有職位、目標和工作時間的 AI 員工，並依心跳喚醒它，從看板上接手下一個 issue。

1. 每個 worktree 一位員工

   給每位員工各自的 worktree 和職位，例如同一個儲存庫裡的一位程式設計師和一位審查者，就像多個 Claude Code 代理裡那樣。

2. 讓心跳啟動工作

   在工作時間內，每位員工每 15、30 或 60 分鐘在同一個對話中醒來一次；參見如何讓 Claude Code 主動工作。

3. 指派 issue，審查分支

   把工作放到看板上，每位員工接手一個 issue，在自己的分支上提交，需要你拍板時傳訊息給你。閱讀什麼是 AI 員工。

Claude Code worktree 常見問題