Apr 3, 2026

Claude Code Worktree 隔離：安全實驗不怕搞壞

你讓 Claude Code 重構一個 500 行的檔案。它改了 200 行，跑測試失敗，又改了 100 行，又失敗。現在你的工作目錄一團亂，git diff 有 300 行改動，你不確定哪些要保留、哪些要丟掉。

Worktree 隔離就是為了避免這種情況。讓 Claude Code 在獨立的 git worktree 中工作，改壞了就整個丟掉，改好了再合併回來。

什麼是 Git Worktree

Git worktree 是 git 內建的功能，讓你在同一個 repo 中同時有多個工作目錄，每個指向不同的 branch。

# 傳統做法：一個 repo 一個工作目錄
/project          ← main branch

# worktree：同一個 repo 多個工作目錄
/project          ← main branch
/project-wt-1     ← feature-a branch
/project-wt-2     ← experiment branch

每個 worktree 是獨立的——在 worktree 裡改檔案不會影響主目錄。

Claude Code 的 Worktree 功能

Claude Code 把 git worktree 整合進工作流，提供三種使用方式：

1. CLI 啟動參數

claude --worktree

啟動時加 --worktree，Claude Code 會自動建立一個 worktree 並在裡面工作。你的主目錄完全不受影響。

2. Subagent 隔離

在 Claude Code 的 agent 定義中指定 worktree 隔離：

# .claude/agents/refactor.md
---
name: refactor-agent
isolation: worktree
---

你是一個專門做重構的 agent。
在 worktree 中大膽修改，跑完測試確認沒問題再回報。

或在程式碼中呼叫 subagent 時指定：

幫我啟動一個 worktree agent 來重構 utils.js，
不要動我目前的工作目錄

3. Session 中切換

在 session 中途進入 worktree：

/worktree enter

Claude Code 會建立一個新的 worktree 並切換過去。完成後：

/worktree exit

如果沒有改動，worktree 自動清理。如果有改動，Claude Code 會告訴你 worktree 的路徑和 branch 名稱，讓你決定要不要合併。

Worktree 的生命週期

建立 → 執行 → 判斷 → 清理或保留

1. 建立
   - 從當前 HEAD 建立新 branch
   - checkout 到獨立目錄
   - 複製 .worktreeinclude 指定的檔案

2. 執行
   - Claude Code 在 worktree 中正常工作
   - 所有讀寫都在隔離目錄中

3. 判斷
   - 有改動？→ 保留 worktree，回報 path 和 branch
   - 沒改動？→ 自動清理

4. 清理或保留
   - 清理：刪除目錄、移除 git worktree 記錄
   - 保留：你可以 review 後決定 merge 或丟棄

.worktreeinclude：帶入 gitignored 檔案

Worktree 預設只包含 git 追蹤的檔案。但有些 gitignored 的檔案是開發必需的（例如 .env、node_modules）。

在專案根目錄建立 .worktreeinclude：

# .worktreeinclude
.env
node_modules/
vendor/

列在這裡的檔案/目錄會被複製到 worktree 中，確保在 worktree 裡也能正常跑建置和測試。

注意事項

.worktreeinclude 是複製，不是 symlink。worktree 裡的 .env 是副本
node_modules 可能很大，複製會花時間。考慮是否真的需要，或在 worktree 中跑 npm install
不要把敏感憑證放在 .worktreeinclude 裡，除非 worktree 在本地安全環境

實戰場景

場景一：大型重構

在 worktree 中把 utils.js 拆成 string-utils.js、date-utils.js、
array-utils.js。確認所有 import 都更新、測試全過，再告訴我結果。

Claude Code 在 worktree 中大膽修改，你的主目錄繼續開發其他功能。改好了就 merge，改壞了就 git worktree remove。

場景二：套件升級測試

在 worktree 中把 React 從 17 升到 18。
修復所有 breaking changes，跑完測試。
列出所有需要改的地方和改動摘要。

套件升級經常牽一髮動全身。在 worktree 中試，不用擔心主分支被搞亂。

場景三：平行實驗

讓兩個 subagent 同時在各自的 worktree 中嘗試不同方案：

用兩個 worktree agent 分別嘗試：
1. 用 Redis 做 caching
2. 用 SQLite 做 caching
兩個都跑 benchmark，比較效能差異。

兩個方案平行開發，完全不互相干擾。

場景四：破壞性測試

在 worktree 中刪掉所有 deprecated 的 API，
看還有哪些地方在用。列出所有 breaking changes。

在主目錄做這件事太危險了——萬一忘記復原就慘了。在 worktree 中做，用完即棄。

場景五：探索式除錯

在 worktree 中加大量 console.log 來追蹤這個 bug。
找到根因後告訴我，不要把 debug code 帶回主分支。

不用擔心 debug 程式碼污染主分支。worktree 就是一個可拋棄的調查現場。

Worktree 與其他功能的搭配

Worktree + Scheduled Triggers

/schedule "nightly-upgrade-check" every day at 2am:
in a worktree, try upgrading all outdated packages.
Run tests. Report which upgrades are safe and which break things.

每天凌晨自動在 worktree 中測試套件升級，早上看結果。

Worktree + Auto Mode

在 worktree 中可以更大膽地使用 Auto Mode——因為最壞情況就是丟掉整個 worktree。

// .claude/agents/experiment.md
---
isolation: worktree
autoMode: auto
---

主目錄用嚴格的 default mode，worktree 中用 auto mode。安全與效率兼顧。

Worktree + Plan Mode

先用 Plan Mode 看計畫，確認方向後在 worktree 中執行：

1. /plan — 分析重構方案
2. 確認方案後 → /worktree enter
3. 在 worktree 中執行重構
4. Review 結果 → merge 或丟棄

管理 Worktree

查看現有 worktree

git worktree list

清理孤立的 worktree

Claude Code 正常結束時會自動清理。但如果異常退出，可能留下孤立的 worktree：

# 列出所有 worktree
git worktree list

# 移除特定 worktree
git worktree remove /path/to/worktree

# 清理所有無效的 worktree 記錄
git worktree prune

Hooks：自動化清理

{
  "hooks": {
    "WorktreeRemove": [
      {
        "command": "echo 'Worktree removed: $CLAUDE_WORKTREE_PATH'"
      }
    ]
  }
}

注意事項

Worktree 是全新 checkout

Worktree 是從 git 記錄中 checkout 的全新目錄。這意味著：

沒有 uncommitted changes：主目錄中未提交的修改不會出現在 worktree 中
沒有 untracked files：除非列在 .worktreeinclude 中
需要初始化：如果有 build artifacts 或 generated files，可能需要重新 build

磁碟空間

每個 worktree 是完整的工作目錄副本（但共用 .git 物件）。如果專案很大或 node_modules 很重，多個 worktree 會佔用可觀的磁碟空間。

Windows 特殊注意

在 Windows 上使用 worktree：

路徑長度限制可能是問題——worktree 路徑加上深層 node_modules 可能超過 260 字元
建議 worktree 建在磁碟根目錄附近（例如 C:\wt\）
Junction 和 symlink 在 worktree 中可能有問題

結語

Worktree 隔離的核心理念是**「失敗的成本趨近於零」**。

當你知道最壞情況只是刪掉一個目錄，你會更願意嘗試大膽的修改。讓 Claude Code 重構 500 行？沒問題，在 worktree 裡試。套件升級可能 break everything？沒關係，worktree 裡搞壞了就丟掉。

這不是懶惰，而是聰明地管理風險。把精力花在判斷「要不要 merge 這個結果」，而不是花在「小心翼翼地一行一行改」。