Worktrees

Worktrees（git worktree，把同一儲存庫 checkout 到多個獨立目錄的原生 git 能力）讓 Agent 在隔離的 Git checkout 裡工作。官方文件說明：每個任務都有自己的 files、dependencies 和 changes，你的 main checkout 不會被碰到。

閱讀目標：讀完本章，你應該能判斷什麼時候必須用 worktree，並能配置 .cursor/worktrees.json、清理策略和 Editor Window 中的 /worktree / /best-of-n。

1. 先看入口邊界

官方頁面先給了一個關鍵邊界：

位置	怎麼用 worktree
Agents Window	UI-native worktrees，只在 Agents Window 可用
Editor Window	使用 Worktree Skills commands，例如 `/worktree`、`/best-of-n`
Cursor CLI	可以讀取 `.cursor/worktrees.json` 的 setup 配置

所以不要只問“Cursor 有沒有 worktree”。要先看你處在哪個介面。

2. Worktree 解決什麼

flowchart TD
  Main["Main checkout"] --> TaskA["Agent task A"]
  Main --> TaskB["Agent task B"]
  TaskA --> WTA["Worktree A"]
  TaskB --> WTB["Worktree B"]
  WTA --> ReviewA["Review / commit / PR A"]
  WTB --> ReviewB["Review / commit / PR B"]
  ReviewA --> MainDecision["Apply or merge intentionally"]
  ReviewB --> MainDecision

適合使用：

同一個 repo 上啟動多個 agents。
風險重構，不想汙染當前 checkout。
需要獨立安裝依賴、構建和測試。
想比較多個實現候選。
需要一個簡單 cleanup path。

不適合省掉 review。Worktree 只是隔離，不是質量保證。最後仍然要看 diff、跑測試、決定 commit、PR 或 apply。

3. Agents Window 流程

官方說明：當你在 Agents Window 中把 agent 啟動或移動到 worktree，Cursor 會為這個 agent 建立一個 separate checkout。任務在 worktree 裡繼續執行，變更不會進入 main checkout。

Agent 完成後，你可以：

在 Agents Window 中 review 結果。
繼續在 worktree 裡工作。
從這個 checkout 建立 commit 或 PR。
把結果帶回 main workspace。

4. `.cursor/worktrees.json`

Cursor 會用 .cursor/worktrees.json 自定義 worktree setup。官方說明它會在這些地方建立 worktree 時檢查該檔案：Agents Window、Editor Window、Cursor CLI。

查詢順序：

worktree path。
project root path。

配置支援三個 setup key：

Key	用途
`setup-worktree-unix`	macOS / Linux 命令或指令碼路徑，優先於 generic fallback
`setup-worktree-windows`	Windows 命令或指令碼路徑，優先於 generic fallback
`setup-worktree`	所有系統的通用 fallback

每個 key 可以是 command array，也可以是相對 .cursor/worktrees.json 的 script filepath。

{
  "setup-worktree-unix": [
    "pnpm install",
    "cp $ROOT_WORKTREE_PATH/.env.local .env.local",
    "pnpm run build"
  ],
  "setup-worktree-windows": [
    "pnpm install",
    "copy %ROOT_WORKTREE_PATH%\\.env.local .env.local"
  ]
}

官方提醒：不建議把 dependencies symlink 到 worktree。這樣可能影響 main worktree。更好的做法是用 fast package manager，例如 bun、pnpm 或 uv。

深讀：為什麼 setup 裡複製 env 要謹慎

官方示例會複製 .env 或 .env.local，因為很多專案離開環境變數無法啟動。但真實團隊不能盲目把金鑰複製到每個 worktree。

建議把可複製的本地開發 env 和生產金鑰分開；worktree setup 只複製開發必需、可回收、低風險的配置。涉及客戶資料、生產 token、付款後臺 key 的檔案不要自動擴散。

5. 除錯和清理

如果 worktree setup 失敗，官方建議開啟 editor 的 Output panel，選擇 Worktrees Setup。

Cursor 也可以自動清理舊 worktrees，減少磁碟佔用。

{
  "cursor.worktreeCleanupIntervalHours": 6,
  "cursor.worktreeMaxCount": 20
}

設定	含義
`cursor.worktreeCleanupIntervalHours`	多久檢查一次舊 worktrees
`cursor.worktreeMaxCount`	超過多少個 worktrees 後清理舊項

6. Editor Window 命令

Editor Window 中，用 Worktree Skills commands。

命令	作用
`/worktree`	在獨立 checkout 中完成當前 chat 後續任務
`/apply-worktree`	把 worktree 裡的結果帶回 main checkout 測試
`/delete-worktree`	完成後刪除隔離 checkout
`/best-of-n`	讓多個模型用同一 prompt 並行產出候選

示例：

/worktree fix the failing auth tests and update the login copy

/best-of-n 會讓每個候選 run 拿到自己的 worktree。它只負責比較 runs，不會自動 merge 回 main checkout。選出結果後，你可以在 worktree 中 commit/push，或用 /apply-worktree 帶回 main。

7. 驗收清單

Worktree 任務完成後檢查：

git worktree list 能看清當前 worktrees。
每個任務有獨立目標和驗收方式。
setup 過程沒有複製不該擴散的金鑰。
依賴安裝、build、test 都在 worktree 內完成。
diff 只包含該任務需要的檔案。
選中候選後才 apply、commit、push 或 open PR。
舊 worktree 有清理策略。

本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

Agents Window 和 Editor Window 使用 worktrees 的入口有什麼區別？
.cursor/worktrees.json 的三個 setup key 分別解決什麼問題？
/best-of-n 為什麼不能代替人工 review 和 merge？

透過標準：你能為一個多 Agent 並行任務設計 worktree 隔離、setup、驗證和清理策略。

官方來源

Cursor Worktrees —— 官方說明 Agents Window worktrees、setup 配置、cleanup、Editor Window commands 和 /best-of-n。
Cursor CLI Worktrees —— 官方說明 CLI worktree 入口。