用 Worktrees 並行開發

你是 Codex Worktree 並行開發顧問，幫我用 worktree 安全地並行推進多個任務。

【角色】
你清楚為什麼需要 worktree、Local / Worktree / Handoff 的區別、基本流程、什麼時候留在 worktree、什麼時候 handoff 回 Local。

【輸入】
- 我要並行的任務：___
- 它們會改到重疊的檔案嗎：___
- 哪些要隔離、哪些要儘快合回：___
- 我的 Git 熟練度：___

【工作流程】
1. 判斷哪些任務值得開 worktree 隔離
2. 給開 worktree 和並行推進的流程
3. 說明什麼時候留在 worktree、什麼時候 handoff
4. 給 handoff 回 Local 的安全步驟

【輸出規範】
▌一、哪些任務該用 worktree
▌二、開 worktree 與並行流程
▌三、留在 worktree vs handoff 的判斷
▌四、handoff 回 Local 的步驟

【硬約束】
- 改動重疊的任務避免同時並行，防衝突
- handoff 前確認改動已驗證
- 不可逆 Git 操作人工確認
- 工作樹邊界清晰，不互相干擾
- 不確定的機制標註需查官方文件

Worktree 讓 Codex 可以在同一個 Git repository 中為不同任務建立隔離 checkout。它適合並行任務、後臺任務和實驗性改動，核心價值是減少對目前 Local checkout 的干擾。

為什麼需要 worktree

flowchart LR
    Local["Local checkout<br/>你的目前工作"] --> Risk["直接並行修改會衝突"]
    WorktreeA["Worktree A<br/>任務 1"] --> Review["獨立審查"]
    WorktreeB["Worktree B<br/>任務 2"] --> Review
    Risk --> WorktreeA
    Risk --> WorktreeB

適合：

• 同一 repo 中並行跑多個 Codex thread。
• 讓後臺任務不影響目前 IDE 和 dev server。
• 試一個方案但不想汙染本地工作樹。
• 等 Codex 完成後再決定是否 handoff 回 Local。

不適合：

• 非 Git 專案。
• 只改一個小檔案的簡單任務。
• 你不熟悉 Git worktree 和 branch 限制。

Local、Worktree、Handoff

Local：

• 你目前日常使用的 checkout。
• 適合前臺開發、IDE、已有 dev server。

Worktree：

• 同一 repo 的另一份 checkout。
• 有自己的檔案副本。
• 與 repo 共享 Git metadata。
• 適合隔離任務。

Handoff：

• 在 Local 和 Worktree 之間移動 thread 和程式碼。
• 適合把後臺任務帶回前臺審查或繼續開發。

不要手動在多個 worktree 中同時 checkout 同一個 branch。Git 會阻止這種情況，以避免同一個 branch 被多個 working tree 同時修改。

基本流程

1. 在 App 中建立新 thread。
2. 選擇 Worktree mode。
3. 選擇起始 branch。
4. 提交任務 prompt。
5. Codex 在隔離 worktree 中工作。
6. 在 App 中審查 diff。
7. 選擇繼續在 worktree 上建立 branch，或 handoff 回 Local。

任務 prompt 仍要寫清：

• 目標。
• 檔案範圍。
• 禁止事項。
• 驗證命令。
• 是否允許新增依賴。

Worktree 只隔離檔案，不替你定義任務邊界。

官方流程裡，Worktree mode 會讓 Codex 基於你選擇的 starting branch 建立 Git worktree。預設，Codex 使用 detached HEAD，這樣可以建立多個 worktree 而不汙染本地 branches。需要長期保留時，再在 worktree 上建立 branch。

什麼時候留在 worktree

留在 worktree 適合：

• 任務可以獨立驗證。
• 依賴和環境在 worktree 中可用。
• 準備直接從 worktree 建立 branch 和 PR。
• 不需要你目前 Local 的特殊狀態。

檢查：

• 測試能否在 worktree 中執行。
• dev server 是否能獨立啟動。
• 是否有未提交依賴或環境檔案缺失。

什麼時候 handoff 回 Local

Handoff 回 Local 適合：

• 你想用常用 IDE 審查。
• 只能執行一個本地服務例項。
• 任務需要你目前 Local 的未提交上下文。
• 要繼續人工開發。

Handoff 前先確認：

• Local 工作樹是否乾淨或已儲存。
• 是否會覆蓋目前未提交改動。
• .gitignore 檔案是否需要額外處理。
• 目標 branch 是否已被其他 worktree checkout。

Handoff 會移動 thread 和程式碼。Codex 會處理必要的 Git 操作，因為 Git 不允許同一個 branch 同時 checkout 在多個 worktree 中。

如果你在 worktree 上建立了 feature/a branch，再試圖在 Local checkout 同一個 branch，Git 會報錯：

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

這種情況下，不要強行改 Git metadata。要麼把 worktree 切到別的 branch，要麼用 Handoff 把 thread 和改動帶回 Local。

Codex-managed 和 permanent worktrees

Codex-managed worktree：

• 預設由 Codex 為單個 thread 建立。
• 更輕量，適合一次性任務。
• thread handoff 回 worktree 時會回到同一個關聯 worktree。
• 會受自動清理策略影響。

Permanent worktree：

• 從 project sidebar 的 three-dot menu 建立。
• 會成為長期 project。
• 不會因為普通 thread archive 自動刪除。
• 適合長期分支、長期環境或固定實驗線。

不要把 permanent worktree 當作隨手建立的草稿目錄。它會佔用磁碟和認知負擔。

自動清理和磁碟空間

Worktree 會佔磁碟空間，尤其當專案有依賴、build cache 或大型生成物時。

建議：

• 定期清理不再需要的 Codex-managed worktrees。
• Permanent worktree 只用於長期環境。
• 不把 worktree 當備份。
• 重要改動及時建立 branch 或 PR。

自動清理前，仍要確認是否有未儲存的重要工作。

官方文件說明：Codex 預設保留最近 15 個 Codex-managed worktrees。你可以在 settings 裡調整上限或關閉自動刪除。

Codex-managed worktree 不會自動刪除的情況包括：

• conversation 被 pinned。
• thread 仍在進行。
• worktree 是 permanent worktree。

會自動刪除的情況包括：

• associated thread 被 archive。
• 需要刪除舊 worktrees 以保持數量限制。

刪除前 Codex 會儲存 snapshot。如果你重新開啟對應 conversation，可以看到恢復選項。

local environment 配合

worktree 是另一份 checkout，只包含 Git 跟蹤檔案。依賴、生成檔案、未提交設定、本地快取通常不會自動出現。

因此，worktree 任務應配合 local environment：

1. 在 .codex 中設定 setup script。
2. 建立 worktree 時自動安裝依賴或初始化。
3. 用 actions 啟動 dev server、build、test。
4. 讓 Codex 在 worktree terminal 中驗證。

如果沒有 setup script，很多“worktree 跑不起來”的問題其實不是程式碼問題，而是環境沒有初始化。

並行邊界

Worktree 適合並行，但仍要定義邊界：

安全檢查清單

使用 worktree 前確認：

• 專案是 Git repository。
• 目前 Local dirty files 已知。
• 任務範圍不會和其他 agent 衝突。
• 驗證命令能在 worktree 中執行。
• 不依賴 Local 中未提交但未帶入的檔案。
• Handoff 前已看過 diff。

Worktree 的目的不是讓並行更多，而是讓並行可控。

官方資料

• Worktrees
• Local environments
• Codex app features
• Git worktree