#cursor#worktree#parallel-agent#apply#git

Cursor 內建 Worktree 進階應用

7 min read

06-cursor-cli-with-worktree 講的是手動 worktree + CLI 並行；這篇談 Cursor 自動建立的 worktree（並行 Agent / Apply）的進階用法：怎麼排多任務、Apply 時選 merge 還是覆蓋、衝突怎麼收尾、以及用 git worktree list 做日常管理。入門概念留給官方文件，這裡直接上實戰。

進階情境一：多任務並行、分開驗收再 Apply

同一顆需求可以拆成多個「子任務」，各開一個 Agent 在獨立 worktree 跑，最後只 Apply 你要的那幾個，不必一次全收。

範例：你想同時進行「重構 utils」「補單元測試」「產 API 文件」：

  • 開三個並行 Agent（或分三次開，每次選 worktree 執行），各自給不同 prompt
  • 跑完後你會有三個結果：可能「重構」很滿意、「測試」要微調、「文件」直接丟掉
  • 只對「重構」那張卡片按 Apply，其他不 Apply，等於只把重構合進主分支，主目錄不會被另外兩個任務改到

進階點：不必一次 commit 所有改動，可以「挑任務 Apply、挑卡片 Apply」，主分支只收你驗收過的。

進階情境二：Apply 時選 Merge 還是 Full Overwrite？

Apply 時 Cursor 會盡量乾淨合併；若同一個 Best-of-N 或多次 Apply 造成衝突，會問你：

選項 什麼時候用
Merge（衝突解決 UI） 想保留主分支部分內容、只納入 worktree 裡部分改動；或多個 worktree 的改動要「挑段落合併」時
Full Overwrite 確定要以 worktree 的檔案內容為準、主分支該檔整份替換；或衝突太多、你打算以「這張卡片」為唯一真相時

實務建議：單一任務、單一 Agent、改的檔案少 → 多半直接 merge 就過。同一份需求跑過多個模型（Best-of-N）、你要從 A 卡 Apply 一部分、再從 B 卡 Apply 另一部分 → 容易衝突，此時要麼只選一張卡 Apply，要麼用 merge 逐檔手動解，不要混用多張 Full Overwrite 同一批檔案，會互相蓋掉。

進階情境三：主目錄有未提交變更時的行為

建立 worktree 時，Cursor 會把主目錄已追蹤的變更與新檔帶進 worktree（Git 忽略的不會帶）。所以：

  • 先在主目錄改一點、不 commit，再開 worktree Agent → Agent 會在你「當前狀態」的基礎上改，Apply 回去時要處理的是「你的未提交變更 + Agent 的變更」的合併
  • 若想讓並行任務完全從乾淨的 main 出發，建議先 git stash 或 commit 再開 worktree，避免「半成品 + Agent 改動」混在一起，Apply 時衝突變多

進階用法反過來用：刻意在主目錄留一點 WIP，開 worktree 做實驗性改動，Apply 時用 merge 把實驗裡滿意的部分合進來，不滿意的留在 worktree 不 Apply。

進階情境四：用 git worktree list 做檢查與清理

Cursor 建的 worktree 會出現在 git worktree list 裡，路徑通常在 .cursor/worktrees/<repo>/<id>：

git worktree list

可以養成習慣：

  • Apply 完、確認主分支沒問題後，Cursor 會自動管理數量；若你發現列表裡 worktree 很多、磁碟吃緊，可查官方設定（如 cursor.worktreeMaxCount、清理間隔），或關掉不用的 Cursor 專案視窗，讓舊 worktree 被清掉
  • 除錯時：看列表就知道目前有幾個「沙盒」在、對應哪個 branch，避免搞混哪個是主目錄、哪個是 Agent 的

不建議手動 git worktree remove Cursor 建的路徑，除非你確定該 Agent 已不用，否則可能和 Cursor 內部狀態不一致。

進階情境五：並行 Agent 改到同一批檔時怎麼收尾

若你同時開兩個 Agent，一個改 src/auth/、一個改 src/api/，通常不會衝突，各自 Apply 即可（先 Apply A 再 Apply B，或反過來，merge 多半能自動解）。

若兩個 Agent 都動到同一檔案（例如都改 package.json 或同一個 config.ts）：

  • 先 Apply 第一個 → 主目錄已有變更
  • 再 Apply 第二個 → 會進入合併流程，可能出現衝突
  • 此時用 Cursor 的衝突解決 UI 手動選「要留主分支的哪一段、要留 worktree 的哪一段」，或若第二個 worktree 的版本你要整份採用，再選 Full Overwrite

策略：規劃並行任務時，盡量讓每個 Agent 動的檔案集合不重疊，例如一個負責前端目錄、一個負責後端目錄，Apply 時就很少需要手動解衝突。

小結

  • 多任務並行：拆成多個 worktree 子任務，驗收後只對滿意的卡片 Apply，主分支只收你要的
  • Apply 選擇：要保留主分支部分內容用 Merge；要整檔以 worktree 為準用 Full Overwrite；多張卡改同一批檔時避免重複 Full Overwrite
  • 主目錄狀態：未提交變更會帶進 worktree；要乾淨基準就先 stash/commit；也可刻意留 WIP 做「實驗 worktree + 選擇性 merge」
  • 管理：用 git worktree list 檢查與配合 Cursor 清理策略；並行任務盡量讓改動的檔案不重疊，減少衝突

下一篇：09-worktree-advanced — Best-of-N 多模型比較、worktrees.json 設定與清理。