Cursor Worktree 進階：Best-of-N 與 worktrees.json

上一篇 08-worktree-intro 講了 Cursor 自動 worktree 與 Apply。這篇進階兩件事：Best-of-N（同一個 prompt 多模型一起跑、再選一個 Apply）和 worktrees.json（worktree 建立時自動裝依賴、跑遷移、複製 .env）。

Best-of-N：一次 prompt，多個模型一起跑

Best-of-N 就是：你丟同一個任務，Cursor 用多個模型同時在各自 worktree 裡做，最後你看到多張「卡片」，每張對應一個模型的改動，選一張按 Apply。

什麼時候用 Best-of-N？

一句話：多個模型同時做同一題，你當評審挑一個，特別適合難題或要品質的改動。

使用方式

在 Cursor 裡開 Agent 時，選擇「多個模型」或 Best-of-N 相關選項（依目前介面為準）。送出 prompt 後會出現多張卡片，切換卡片可比較各模型的改動，滿意的那張按 Apply 合回主分支。

若同一個 Best-of-N 裡你要 Apply 多張（例如先 Apply A 再 Apply B），Cursor 可能會問：用合併與衝突解決，還是 Full Overwrite（整檔覆蓋）。

worktrees.json：worktree 建立時自動準備環境

Cursor 建立 worktree 時，預設會把主目錄的已追蹤檔案帶過去，但不會幫你裝依賴、複製 .env、跑資料庫遷移。
透過 .cursor/worktrees.json，可以指定「每個新 worktree 建立後要執行的指令」，例如 npm ci、cp .env、npm run db:migrate。

設定檔放哪？

Cursor 會依序找：

1. 專案根目錄的 .cursor/worktrees.json
2. worktree 路徑下的設定

通常放在專案根目錄 .cursor/worktrees.json 即可。

三個設定鍵

每個鍵可以是：

• 字串：腳本檔路徑（相對於 .cursor/worktrees.json 所在目錄）
• 陣列：一連串 shell 指令，依序執行

範例：Node 專案

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

$ROOT_WORKTREE_PATH 是 Cursor 提供的環境變數，指向主工作目錄，用來複製 .env 等檔案。
Windows 下複製可能要用 copy 或 PowerShell，所以可以拆成 OS 專用：

{
  "setup-worktree-unix": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ],
  "setup-worktree-windows": [
    "npm ci",
    "copy %ROOT_WORKTREE_PATH%\\.env .env"
  ]
}

範例：需要跑資料庫遷移

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env",
    "npm run db:migrate"
  ]
}

複雜流程：用腳本檔

若指令很多或要寫邏輯，可改放腳本，在 worktrees.json 裡只寫檔名：

{
  "setup-worktree-unix": "setup-worktree-unix.sh",
  "setup-worktree-windows": "setup-worktree-windows.ps1",
  "setup-worktree": ["echo 'Using generic fallback'"]
}

腳本放在 .cursor/ 目錄下，例如 .cursor/setup-worktree-unix.sh，內容可包含 npm ci、複製 .env、chmod、遷移等。
Windows 用 .ps1，記得在腳本裡用 $env:ROOT_WORKTREE_PATH 取得主目錄路徑。

建議：不要用 symlink 把依賴連進 worktree，容易和主 worktree 打架；用 npm ci、pnpm、bun、uv 等重新安裝較穩。

Worktree 清理與數量上限

Cursor 會自動管理 worktree 數量，避免磁碟爆掉：

• 每個 workspace 有 worktree 數量上限（例如 20）
• 超過時會依 最後使用時間 刪除最舊的
• 清理是 依 workspace，不同 repo 互不影響

若想調整（依 Cursor 版本與設定是否支援），可在設定裡找例如：

• cursor.worktreeMaxCount：最多保留幾個 worktree
• cursor.worktreeCleanupIntervalHours：多久跑一次清理

實際鍵名以 Cursor 設定為準。

除錯 worktree 設定

若 worktree 建立後依賴沒裝好、遷移沒跑，可打開 Cursor 的 Output 面板，在 dropdown 選 「Worktrees Setup」，看建立時執行的指令與錯誤訊息，方便排查 worktrees.json 或腳本問題。

小結

• Best-of-N：同一 prompt 多模型並行，在各自 worktree 產出，你比較後選一張 Apply；適合 benchmark、難題、求品質
• worktrees.json：在 .cursor/worktrees.json 用 setup-worktree / setup-worktree-windows / setup-worktree-unix 指定建立後要跑的指令或腳本
• 用 $ROOT_WORKTREE_PATH（Unix）或 %ROOT_WORKTREE_PATH% / $env:ROOT_WORKTREE_PATH（Windows）複製主目錄的 .env 等
• Worktree 有數量上限與自動清理；除錯看 Output → Worktrees Setup

下一步：10-headless-scripts — 無頭模式用 --print、--force 在腳本裡真的改檔案。