Codex App Worktree 實作篇：從 Local environments 到第一個任務

上一篇我把 Worktree 講成 AI Agent 的隔離跑道。

這一篇就不再繞圈。

我們直接做。

目標很明確：把一個 Git repo 整理到 Codex App 可以穩定使用 Worktree，讓 Agent 進入新工作區後知道規則、能跑起專案、能執行常用檢查，最後把乾淨 diff 交回來。

本文依據 2026-06-12 查閱的 OpenAI 官方文件整理。Codex App 的 UI 可能調整，所以我會用「你應該找的設定區域」來描述，而不是把每個按鈕位置寫死。

你要先準備什麼

開始前先確認幾件事。

第一，這個專案要是 Git repository。OpenAI 的 Worktrees 文件也明確說明，Worktree 需要 Git repo 才能使用。

第二，你要知道這個 repo 的基本檢查命令。不要讓 Agent 從零猜。至少準備這三類：

第三，確認哪些東西不能自動做。像正式資料庫 migration、批量刪檔、寫入正式資料、啟動會搶 port 的服務，都不適合直接放進 Worktree setup script。

這不是保守，是工程師的基本求生欲。

Step 1：先把 AGENTS.md 寫成 Agent 的 repo 說明書

Codex 可以很聰明，但 repo 規則不要每次靠 prompt 重新講。

OpenAI 的 Best practices 文件建議把 repo layout、測試指令、工程慣例和完成標準放進 AGENTS.md。我會把它當成「Agent 進 repo 前先讀的開發守則」。

一份可以起步的 AGENTS.md 長這樣：

# AGENTS.md

## Project Map

- `src/`: application code
- `tests/`: automated tests
- `docs/`: project documentation

## Safety Rules

- Preserve user changes.
- Do not run recursive or batch deletion.
- Keep Traditional Chinese content UTF-8 clean.

## Required Checks

- `npm.cmd run validate`
- `npm.cmd run build`

## Done When

- The requested files are changed.
- Relevant checks pass.
- The final response lists what changed and what could not be verified.

這份文件不用一開始就完美。先寫出專案地圖、安全規則、驗證命令，Agent 的穩定度就會差很多。

如果是 .NET API repo，我會把檢查命令改成：

## Required Checks

- `dotnet restore`
- `dotnet build`
- `dotnet test`

如果是 Vue / Vite repo，我會寫成：

## Required Checks

- `npm.cmd install`
- `npm.cmd run build`
- `npm.cmd test`

重點不是命令長什麼樣，而是讓 Agent 有一個 repo-local 的標準答案。

Step 2：設定 Local environments，讓新 Worktree 自動開機

Worktree 會建立在不同目錄。這代表它很乾淨，也代表它可能什麼都沒有。

OpenAI 的 Local environments 文件說明，Codex App 可以在 settings pane 設定 setup scripts。當 Codex 建立新的 worktree thread 時，setup script 會自動執行，用來安裝依賴或跑初始 build。

這一層不是孤立存在的。它和 AGENTS.md、Worktree、review 形成一個小型操作系統：

我會照這個順序設定：

1. 打開 Codex App。
2. 進入 Settings。
3. 找到 Local environments。
4. 選擇你的 project 或 repo。
5. 新增 setup script。
6. 依照平台需要設定 Windows、macOS 或 Linux 專用 script。

Windows + Node / Vue 專案可以先用這種最小版：

npm.cmd install
npm.cmd run build

.NET API 專案可以先用：

dotnet restore
dotnet build

這個 Blog repo 則可以用比較貼近實際的驗證入口：

npm.cmd install
npm.cmd run validate

setup script 的原則是：只做「讓工作區可以開始工作」的事。

不要把資料庫破壞性操作、正式服務部署、批量清理檔案放進去。Worktree 是隔離程式碼工作區，不是防爆箱。

Step 3：設定 Actions，把常用驗證變成按鈕

Setup script 是新 worktree 啟動時自動跑。

Actions 是你在 Codex App 裡手動觸發的常用命令。

OpenAI 文件說明，actions 會出現在 Codex App 的 top bar，並在 integrated terminal 裡執行。我的建議是先做三種 action：

這個 Blog repo 可以設定：

npm.cmd run validate

C# API repo 可以設定：

dotnet test

前端 repo 如果要啟動 dev server，可以設定一個明確 port：

npm.cmd run dev -- --host 127.0.0.1 --port 5174

為什麼要明確 port？因為多個 Worktree 同時跑前端時，很容易都搶同一個預設 port。這種小事不先處理，後面 debug 會很吵。

Step 4：建立第一個 Worktree thread

環境設定好之後，就可以開第一個 Worktree thread。

流程大致是：

1. 在 Codex App 建立新 thread。
2. 在 composer 下方選 Worktree。
3. 選擇要套用的 local environment。
4. 選擇起始 branch，例如 main、dev 或你目前的 feature branch。
5. 輸入任務 prompt。
6. 送出後，Codex 會建立 Git worktree 並開始工作。

OpenAI 的 Worktrees 文件說明，Codex 預設會基於你選的 branch 建立 worktree，而且可以在完成後選擇留在 worktree 工作，或 handoff 回 Local。

我會把第一個任務寫得很小，像這樣：

請在 Worktree 中檢查這個 repo 的文章驗證流程。

請先閱讀 AGENTS.md、package.json、scripts/local-dev.cjs。
請不要修改檔案，只回報：
1. 這個 repo 的主要驗證命令是什麼
2. 發布文章前應該跑哪些檢查
3. 目前 Worktree setup 是否還缺什麼

第一次不要急著叫它大改架構。先確認 Agent 看得懂 repo，才讓它動刀。

第二個任務可以開始讓它改小東西：

請在 Worktree 中新增一篇草稿文章。

要求：
1. 使用 Hugo TOML front matter
2. 放在 content/posts/2026/06/
3. tags 最多 4 個
4. 寫完後執行 npm.cmd run validate
5. 最後回報修改檔案、驗證結果、尚未驗證的項目

好的 Worktree prompt 會把「讀什麼、改什麼、怎麼驗證、怎麼回報」說清楚。

Step 5：在 Worktree 裡檢查結果

Codex App 內建 diff pane，可以看 Agent 改了哪些檔案。Features 文件也提到，Codex App 支援 diff、stage、revert chunk、commit、push 和建立 PR。

我會照這個順序檢查：

1. 先看 diff 檔案清單。
2. 確認沒有 unrelated change。
3. 看每個檔案的內容是否符合需求。
4. 在 integrated terminal 跑驗證命令。
5. 必要時請 Agent 修正。
6. 最後才 stage、commit 或 handoff。

常用檢查可以先跑：

git status
git diff --stat

接著跑 repo 的正式驗證：

npm.cmd run validate

或是：

dotnet test

如果 diff 很大，我會要求 Agent 先整理變更摘要：

請根據目前 Worktree diff 回報：
1. 修改了哪些檔案
2. 每個檔案的修改目的
3. 有沒有不屬於本任務的變更
4. 已執行哪些驗證
5. 還有哪些風險

這一步很重要。Worktree 讓 diff 乾淨，但 review 還是工程師的工作。

Step 6：選擇收尾方式

Worktree 任務完成後，通常有三種收尾方式。

先用這張圖判斷要走哪一條路：

做法一：留在 Worktree 建 branch、commit、push

如果你已經在 Worktree 裡完成驗證，可以直接在 Worktree 建 branch，然後 commit、push、開 PR。

這適合：

• 文件調整。
• 測試補強。
• 小型 bug fix。
• 不需要本機 IDE 深度介入的任務。

做法二：Handoff 回 Local

如果你想用自己的 IDE 深看，或專案只能跑一個本機 server，就 handoff 回 Local。

這適合：

• 前端互動需要人工操作。
• 需要本機特殊工具。
• 需要接 DEV DB 或外部服務。
• 你想接手繼續改。

做法三：丟掉這個 Worktree

如果方向不對，就不要硬救。

Worktree 的好處就是讓失敗便宜。比起在 Local 裡慢慢清掉一堆實驗殘留，直接放棄一個錯誤方向更乾淨。

常見問題：Worktree 跑不起來時怎麼查

問題一：缺 dependency

症狀通常是 build 或 test 一開始就找不到套件。

先檢查 setup script 有沒有跑安裝命令，例如 npm.cmd install、dotnet restore。如果每次新 Worktree 都會遇到同樣問題，就把它寫進 Local environments。

問題二：缺 .env

.env 通常不會進 Git，所以 Worktree 不會自然拿到。

做法是準備 .env.example，讓 Agent 知道有哪些變數，但不要把秘密寫進 repo。真正的 secret 要用你自己的安全流程處理。

問題三：dev server 搶 port

多個 Worktree 同時跑前端，很容易都想使用同一個 port。

解法是把 action 寫成固定不同 port，或只在需要時啟動其中一個 dev server。

問題四：Agent 改到任務外的檔案

這通常不是 Worktree 的錯，而是 prompt 邊界不夠清楚，或 repo 規則不夠明確。

修正方式：

• 在 prompt 裡列出允許修改的檔案或資料夾。
• 在 AGENTS.md 寫明禁止 unrelated refactor。
• Review diff 時直接 revert 不相關 hunk。

問題五：Handoff 時遇到 branch 衝突

Git 不允許同一個 branch 同時 checkout 在兩個地方。OpenAI Worktrees 文件也提醒，Handoff 會處理需要的 Git 操作，因為 Local 和 Worktree 之間要安全移動 thread 與 code。

如果卡住，先確認：

git status
git branch --show-current

不要急著硬切 branch。先釐清現在這個 branch 在哪個 checkout。

我會採用的最小可行流程

如果只想先導入，不想一次做完整治理，我會用這個最小流程：

1. 在 repo 放 AGENTS.md。
2. 在 Local environments 設定最小 setup script。
3. 建立 Validate action。
4. 開一個 Worktree thread，先做讀 repo 的小任務。
5. 第二個 Worktree thread 才讓 Agent 做小型修改。
6. 每次結束都看 diff、跑 validate、再決定 commit 或 handoff。

這樣已經足夠把 AI Agent 從「直接在主工作區亂改」拉回「有隔離、有驗證、有審查」。

最後整理：操作順序不要反過來

Codex App Worktree 的操作重點不是先開很多 thread。

順序應該是：

1. 先把 repo 規則寫進 AGENTS.md。
2. 再用 Local environments 讓新 Worktree 能自動準備環境。
3. 用 actions 固定常用驗證。
4. 用 Worktree 承接每個獨立任務。
5. 用 diff、驗證、handoff、commit，把結果收回工程流程。

這樣用 Codex App，Worktree 就不只是「旁邊多一份資料夾」。

它會變成 AI Agent 開發裡最重要的分流機制。

參考資料

• OpenAI Codex App Worktrees 文件
• OpenAI Codex App Local environments 文件
• OpenAI Codex App Features 文件
• OpenAI Codex Best practices 文件

相關閱讀

• Codex App Worktree 思維：為什麼 AI Agent 開發需要隔離跑道
• AI 開發的工作拆解：Spec、MVP 與 Task
• 什麼是 AI Agent Skill