使用 AI Agent 開發最迷人的地方，是你可以把一個問題丟出去，幾分鐘後就看到它真的改了檔案、跑了測試、整理了 diff。

但這也是最危險的地方。

如果所有任務都直接寫在同一個本機 checkout 裡，前台正在修的 bug、背景正在跑的重構、昨天還沒收尾的實驗分支，很快就會混在一起。人類工程師會開始問：「這段是我改的，還是 Agent 改的？」而這通常就是版本控制宇宙開始冒煙的前一刻。

所以我現在會把 Codex App 的環境設定分成三層來看：

  • AGENTS.md：告訴 Agent 這個 repo 怎麼工作。
  • Local environments：告訴 Codex App 新工作區要怎麼安裝、建置、測試。
  • Worktree：讓每一個任務有自己的隔離跑道。

這篇先不把 Codex App 寫成按鈕導覽手冊，而是把重點放在 Worktree。因為真正改變 AI Agent 開發體驗的，不是多一個 UI 選項，而是你終於可以放心讓 Agent 在旁邊工作，又不把自己的工作區弄成一鍋粥。

本文依據 2026-06-12 查閱的 OpenAI 官方文件整理。Codex App 的 UI 仍可能調整，所以我會把會變動的按鈕細節寫得保守一點，把不太會變的工程概念講清楚。

先講結論：Worktree 是 AI Agent 的隔離跑道

Worktree 可以先用一句話理解：

Worktree 是同一個 Git repository 的另一個 checkout。它有自己的檔案目錄，但共用同一份 Git 歷史與 metadata。

這件事很重要。

它不是你手動複製一份專案資料夾，也不是把整個 repo clone 第二次。Git worktree 的價值在於：同一個 repository 可以同時展開多個工作區，每個工作區可以檢查不同分支、保留不同檔案狀態、跑不同任務。

在 Codex App 裡，OpenAI 官方文件把模式分成 Local、Worktree、Cloud。其中 Local 是直接在你目前的專案目錄工作；Worktree 則會建立 Git worktree，讓改動先留在另一個 checkout 裡。官方的 Worktrees 文件 也明確說明，Worktree 是為了讓 Codex 在同一個專案中平行處理獨立任務，彼此不要互相干擾。

換成日常開發語言就是：

Local 是你的主工作桌。Worktree 是旁邊那張乾淨的實驗桌。

你可以叫 Agent 去實驗桌上拆東西、改東西、跑測試。它成功了，你再把結果帶回來；它失敗了，你不會發現自己的主工作桌也被拆到剩螺絲。

環境設定不是主角，但它決定 Worktree 能不能變成流程

談 Worktree，很容易直接跳到「怎麼設定」。但在那之前，我更想先把順序講清楚：

Worktree 先解決任務邊界；環境設定再讓這個邊界可以重複使用。

如果沒有 Worktree，Agent 會直接在你的主要 checkout 裡工作。它也許能完成任務，但所有變更都會和你手邊的開發狀態混在一起。

如果有 Worktree，但沒有整理好 Local environments，Agent 會進到乾淨工作區，卻可能缺 dependency、缺 build output、缺環境啟動步驟。它不是做不到，而是會花更多時間猜。

所以 Codex App 的環境設定，應該被看成 Worktree 的配套，而不是取代 Worktree 的主角。AGENTS.md 負責規則，Local environments 負責啟動流程，Worktree 負責隔離任務。

這三者合在一起，才會變成一個可重複的 AI Agent 開發流程。

操作細節我會放到下一篇，這一篇先把「為什麼這件事值得做」講完。

Worktree 能做什麼：它把 Agent 任務變成可審查的分流

Worktree 對 AI Agent 開發的價值，不只是「避免改到本機檔案」。那只是最表層的好處。

真正的價值是任務分流。

1. 讓背景任務不要污染前景工作

你正在 Local 修一個緊急 bug，同時想讓 Codex 幫你補測試、整理文件、分析重構方向。這些任務如果都寫在同一個 checkout，diff 會混在一起。

放到 Worktree 後，每個任務都有自己的檔案狀態。你可以讓 Agent 在背景跑，等它完成後再開 diff 審查。

2. 讓多個 Agent 任務平行前進

AI Agent 的速度快，但人類 review 的注意力有限。Worktree 的好處是你可以讓任務先分開產出：

任務適合放哪裡原因
正在手動修的 bugLocal你需要前台掌控
補測試Worktree改動範圍清楚，容易審查
文件同步Worktree可獨立驗證，不需要卡住主線
大型重構探索Worktree可能失敗，應該先隔離
定期檢查或 automationWorktree適合背景執行

這就像把開發流程從「所有人擠在同一張桌子」改成「每個任務有自己的工作台」。

3. 讓失敗變便宜

AI Agent 最適合做探索型任務，但探索一定會有失敗品。

如果 Agent 在 Local 直接做大型重構，你 review 的壓力會很大，因為它可能跟你原本的未提交改動混在一起。Worktree 讓你可以更輕鬆地說：

這個方向不值得合併，先丟掉。

失敗變便宜，探索才會變多。探索變多，才更有機會找到真的有價值的解法。

4. 讓 Handoff 有明確邊界

Codex App 支援把 thread 在 Local 和 Worktree 之間 handoff。官方文件提醒，Git 同一個 branch 不能同時 checkout 在兩個地方，因此 handoff 背後會處理必要的 Git 操作。

我的使用習慣是：

  • 還在探索：留在 Worktree。
  • 要用熟悉的 IDE 深看：handoff 回 Local。
  • 要直接整理成 PR：在 Worktree 建 branch、commit、push。
  • 只是想保留一個長期環境：建立 permanent worktree。

這樣做的重點不是追求流程漂亮，而是每一步都有可回頭的邊界。

為什麼現在特別推薦 AI Agent 搭配 Worktree

以前人類自己開發時，一次通常只專心處理一條主線。即使偶爾開兩個分支，也還是人類自己知道腦中上下文。

AI Agent 改變了這件事。

你現在可能同時叫 Agent 做三件事：

  • 修登入錯誤。
  • 補 API 測試。
  • 掃一輪權限邏輯。

這三件事如果共享同一個工作區，問題不是 Agent 夠不夠聰明，而是工作區本身沒有隔離。沒有隔離，就很難判斷哪個 diff 屬於哪個任務；沒有邊界，就很難做 code review；沒有乾淨的任務狀態，就很難放心讓 Agent 自動化。

所以 Worktree 其實是在幫 AI Agent 補一個工程上的護欄。

它讓你把 Agent 從「直接進我的桌面幫我改檔案」升級成：

你先去自己的工作區完成任務，跑完檢查，再拿 diff 回來給我看。

這個差異非常大。

AI Agent 開發最需要的不是盲目信任，而是可審查、可還原、可平行化。Worktree 剛好把這三件事接起來。

Codex App 裡的三層責任分工

我會把一個適合 AI Agent 的 Codex App 專案拆成三層。

第一層：AGENTS.md 是工作規範

AGENTS.md 解決的是「Agent 進來後要遵守什麼」。

它應該寫清楚 repo map、安全規則、建置測試指令、語言風格、完成標準。OpenAI 的 Best practices 文件 也把 AGENTS.md 定位成給 agent 自動載入的 repo 說明書。

沒有這層，Agent 每次都要靠 prompt 臨時補規則。你會覺得自己在管理一個很聰明、但每天失憶的同事。

第二層：Local environments 是開機流程

Local environments 解決的是「新 worktree 起來後要怎麼進入可工作狀態」。

OpenAI 的 Local environments 文件 說明，它可以設定 worktree 的 setup scripts，也可以定義常用 actions。這代表你不需要每次都提醒 Agent 先 install、restore、build、test。

這層的核心不是自動化炫技，而是降低猜測。Agent 一進工作區就知道怎麼把專案準備好，也知道常用驗證入口在哪裡。

第三層：Worktree 是任務隔離

Worktree 解決的是「這次任務的改動要放在哪裡」。

它讓每個任務有自己的檔案狀態，讓背景探索不污染主要 checkout，也讓 review 變得比較乾淨。Codex App 的 Features 文件 也把 Worktree 描述成用來隔離改動、支援獨立任務並行的模式。

這三層合起來，才是我會推薦的 AI Agent repo 基礎設施。

不是因為它看起來很完整，而是因為它把規則、啟動、隔離三件事拆開了。

使用 Worktree 時，這些坑要先知道

Worktree 很好，但它不是魔法。

被 .gitignore 排除的東西不會自然跟過去

官方 troubleshooting 文件提醒，Worktree 會在不同目錄建立，而且只會繼承 Git 追蹤的檔案。如果程式跑不起來，常見原因是缺 dependency、缺本機設定，或缺沒有被 commit 的檔案。

這也表示 .env、本機憑證、暫存資料通常不會自然出現在 worktree。你需要用 setup script、範例設定檔，或手動安全地補上。

多個 worktree 可能搶同一個 port

如果你同時在兩個 worktree 跑同一個 frontend dev server，它們可能都想用 localhost:5173。這不是 Codex 的問題，是本機開發環境本來就需要分 port。

我的建議是把 dev server action 寫得明確一點，必要時讓不同 worktree 使用不同 port。

不要讓 Agent 在隔離區做不可逆操作

Worktree 隔離的是檔案工作區，不是你整台機器，也不是共享資料庫。

如果某個任務會動到 DEV DB、清資料、跑 migration，還是要用更嚴格的規則處理。Worktree 可以降低程式碼混亂，但不能替你承擔資料操作風險。

Worktree 不是 review 的替代品

Worktree 讓 diff 乾淨，不代表 diff 一定正確。

真正好的流程是：

  1. Agent 在 Worktree 完成任務。
  2. Agent 跑必要檢查。
  3. 你看 diff。
  4. 必要時請 Agent /review 或重新檢查。
  5. 確認後再 commit、push、開 PR 或 handoff。

Worktree 負責隔離，工程師負責判斷。

我的推薦流程：Local 掌舵，Worktree 探路

我現在會把 Codex App 的使用方式想成一句話：

Local 掌舵，Worktree 探路。

Local 保留你正在專注處理的主線。Worktree 交給 Agent 做可隔離、可驗證、可丟棄的任務。

實務上可以這樣分：

  • 小修正、你要全程盯著：用 Local。
  • 補測試、補文件、找錯誤：用 Worktree。
  • 大型重構、方案比較：用 Worktree。
  • automation、定期檢查：用 Worktree。
  • 需要本機 IDE 深度驗證：從 Worktree handoff 回 Local。

這樣的流程會讓 AI Agent 從「幫我改 code 的工具」變成「可以分派任務的協作者」。

差別在於，協作者需要工作區。

最後整理：Worktree 讓 AI 開發變得像工程流程

Codex App 的 Worktree 不是一個炫技功能。它真正解決的是 AI Agent 開發最容易失控的地方：任務邊界。

沒有 Worktree，你很容易把所有改動都倒進同一個 checkout。短期看起來很快，長期會讓 review、測試、回復、合併都變痛苦。

有 Worktree，你可以讓 Agent 在隔離工作區裡做事。它可以失敗，可以重來，可以平行探索，也可以把乾淨 diff 帶回來讓你審。

所以我會推薦：

  • 把 AGENTS.md 當成 repo 的 Agent 使用說明書。
  • 把 Local environments 當成 Worktree 的自動開機流程。
  • 把 Worktree 當成 AI Agent 的標準工作區。

AI Agent 開發不是要把所有控制權交出去，而是把可重複的工作分派出去，並保留工程師該有的審查權。

Worktree 做的，就是把這件事變得比較像工程，而不是賭運氣。

參考資料

相關閱讀