Worktree 隔離

你將學到什麼

Git worktrees 讓平行 Claude Code sessions 在不同 checkout 與 branch 編輯，不會直接碰到彼此的檔案。Claude Code 現在透過 CLI 旗標、session 內工具與 subagent 設定原生提供這個隔離能力。

本課只使用受支援的生命週期：建立、初始化、工作、恢復、整合與清理。

Worktree 隔離了什麼

Git worktree 是另一個工作目錄，有自己的 checkout 檔案與 branch，但與主 checkout 共用 repository history 和 remotes。

repository
├── main checkout                 branch: main
└── .claude/worktrees/feature-auth
                                  branch: worktree-feature-auth

隔離邊界是檔案 checkout。它不會隔離外部服務、憑證、ports、databases、套件 caches 或所有 Git 操作；這些資源必須另外協調。

Worktrees 也不負責協調代理。委派與通訊應使用 subagents 或 Agent Teams；worktrees 的作用是避免檔案修改互相碰撞。

啟動隔離 Session

將名稱傳給 --worktree 或 -w：

claude --worktree feature-auth
# 等價寫法
claude -w feature-auth

Claude Code 預設建立 .claude/worktrees/feature-auth/，branch 名稱為 worktree-feature-auth。在另一個終端使用不同名稱，即可啟動另一個隔離 session。請將產生的目錄加入 ignore 規則：

.claude/worktrees/

你也可以在既有 session 中要求 Claude「到 worktree 工作」。Claude Code 會透過受支援的 worktree 工具進入，不需要自行仿造事件串流。

初始化新的 Checkout

Worktree 包含 tracked files，但不包含所有本機狀態。請在其中安裝 dependencies，並重建必要的本機設定。

若每個由 Claude 建立的 worktree 都需要特定 gitignored files，可在 repository root 新增 .worktreeinclude，語法與 .gitignore 相同：

.env.local
config/dev-secrets.json

只有符合規則且本來就被 Git 忽略的檔案會被複製。這只是便利功能，不是 secrets policy；應縮小敏感檔案範圍，並確認誰可以讀取 worktree。

隔離自訂 Subagent

你可以要求 Claude 為 agents 使用 worktrees，或把隔離寫進 custom subagent definition：

---
name: refactorer
description: Applies mechanical refactors across independent files
isolation: worktree
---

Apply the requested refactor, run the affected tests, and report the commit.

Claude Code 會為該 subagent 建立暫時 worktree。沒有變更時可自動移除；若仍有變更，就會保留到可以在不遺失工作的情況下清理。

清理是一個狀態決策

互動式 worktree session 結束時，Claude Code 會檢查 changed 或 untracked files，以及新 commits。

狀態	互動式行為
乾淨、未命名的 worktree	自動移除 worktree 與 branch
乾淨、已命名的 worktree	詢問是否保留
含有工作內容	詢問保留或移除
非互動 -p 執行	沒有離開提示，也不會自動清理

移除仍有工作的 worktree，會刪除其目錄、branch 與其中的工作。接受移除前，先讀清楚提示並核對目標。

非互動執行或手動管理時，使用 Git 的公開指令：

git worktree list
git worktree remove .claude/worktrees/feature-auth
git worktree prune

除非已明確決定丟棄 uncommitted 或 untracked work，否則不要加入 --force。

恢復與整合

若 worktree 目錄仍存在，恢復原本位於該 worktree 的 session 會回到同一位置。使用 --fork-session 建立分支時，新 session 從你啟動 Claude 的目錄開始，原 worktree 保持不變。

整合前：

1. 在 worktree 內執行受影響的測試；
2. 檢查 git status 與 git diff；
3. commit 範圍明確的變更；
4. 依一般 Git 流程 merge、cherry-pick 或開 PR；
5. 只有在工作已安全整合或確定丟棄後才移除 worktree。

不應假設的事

• Worktrees 是獨立 checkouts；公開契約不保證特定的檔案複製實作。
• 檔案系統乾淨，不代表外部副作用已隔離。
• 互動 sessions、subagents 與 -p 執行的自動清理規則不同。
• 未公開的目錄內部結構不是穩定 orchestration API。

官方來源

• 使用 worktrees 執行平行 sessions
• Claude Code CLI 參考

下一課

下一課將使用 Agent SDK 的公開 API 建立可程式化代理，不依賴 Claude Code 內部實作。