codex的工作樹何時使用, 如何使用?

Codex 的「工作樹（worktree）」是建立一份與目前專案隔離的 Git 工作副本，讓 Codex 修改程式碼時，不會直接碰到你正在使用的目錄與分支。

什麼時候適合使用工作樹？

最常見的是以下情況：

1. 你還在原本專案中工作，但想讓 Codex 同時修改

例如你目前在：

sha3-project/
└── main branch

你正在手動分析 RTL，同時想讓 Codex：

• 修正 testbench
• 嘗試另一種 Keccak RTL 寫法
• 改 Yosys synthesis script
• 執行 EQY equivalence debugging

這時可以讓 Codex 使用工作樹。Codex 會在另一份隔離的目錄中修改，不會弄亂你目前尚未 commit 的內容。

2. 同時讓多個 Codex 任務處理同一個 repository

例如：

• 任務 A：修正 Verilator warnings
• 任務 B：分析 EQY equivalence failure
• 任務 C：重寫 synthesis script

每個任務使用自己的工作樹：

repo-main/            # 你目前使用的版本
codex-task-a/         # Verilator 修正
codex-task-b/         # EQY 分析
codex-task-c/         # synthesis script

因此三個 Codex agent 可以同時修改同一個 repository，而不會彼此覆蓋。這也是 Codex App 內建工作樹的主要目的。

3. 想讓 Codex嘗試高風險或實驗性的修改

例如：

• 大幅重構 RTL
• 更改 module interface
• 將 positional port connection 改成 named connection
• 嘗試不同 synthesis frontend
• 自動修改很多檔案
• 升級 dependency

如果結果不好，可以直接丟棄整個工作樹，你原本的專案不受影響。

什麼時候不一定需要工作樹？

以下情況直接在目前工作目錄執行通常比較方便：

• 只請 Codex 解釋程式碼
• 只修改一兩行，而且你希望立刻在目前目錄看到結果
• repository 沒有其他未完成修改
• 你只執行一個 Codex 任務
• 你希望 Codex直接接續你目前尚未 commit 的修改

特別要注意：新的 Git worktree 通常基於某個已存在的 commit 或 branch。

因此你目前目錄裡「尚未 commit」的修改，不一定會自動出現在新工作樹中。假如 Codex 必須看到這些修改，可以先 commit、建立 temporary branch，或者直接讓 Codex 在目前工作目錄處理。

在 Codex App 中如何使用

一般流程如下：

1. 在 Codex App 中開啟一個 Git repository。
2. 建立新的 Codex thread／task。
3. 選擇使用隔離的 worktree，而不是直接使用目前 checkout 的工作目錄。
4. 告訴 Codex要完成的任務，例如：

Analyze the EQY equivalence failures between
keccak_f1600.sv and keccak_f1600.v.

Make changes only in this worktree.
Run the available tests and summarize every RTL modification.

1. Codex會在隔離副本中讀取、修改及測試程式碼。
2. 完成後，在 Codex App 裡檢查 diff。
3. 接著可以選擇：
4. 保留並繼續修改
5. 在 editor 中開啟
6. 將修改帶回本機分支
7. 建立 commit 或 pull request
8. 丟棄工作樹

Codex App 可讓你直接查看 agent 產生的 diff、留下修改意見，或在編輯器中手動調整；工作期間也不需要改變你原本 repository 的 Git 狀態。

工作樹與 Git branch 的關係

工作樹和 branch 不完全相同：

• Branch：Git 裡的一條版本歷史線。
• Worktree：實際存在於磁碟上的另一份工作目錄。

一個 worktree 通常會 checkout 一個獨立 branch：

main working directory
└── branch: main

Codex worktree
└── branch: codex/fix-keccak-equivalence

兩個目錄共用同一份 Git object database，所以不像完整 git clone 那麼浪費空間，但各自有：

• checkout 的檔案
• branch
• staging area
• 未提交修改

不透過 Codex，手動使用 Git worktree

假設你目前在：

cd ~/project/sha3

建立新的 branch 與工作樹：

git worktree add -b codex/fix-eqy ../sha3-fix-eqy main

意思是：

git worktree add

新增工作樹。

-b codex/fix-eqy

建立名為 codex/fix-eqy 的 branch。

../sha3-fix-eqy

新工作目錄的位置。

main

以 main branch 為起點。

建立後：

cd ../sha3-fix-eqy

就會進入獨立工作樹。

查看目前所有工作樹：

git worktree list

可能顯示：

/home/edmund/sha3          a1b2c3d [main]
/home/edmund/sha3-fix-eqy  d4e5f6g [codex/fix-eqy]

完成並合併：

cd ~/project/sha3
git merge codex/fix-eqy

移除工作樹：

git worktree remove ../sha3-fix-eqy

刪除已不需要的 branch：

git branch -d codex/fix-eqy

針對你的 RTL／Yosys 工作流程，我的建議

你可以把工作樹用在「讓 Codex實際修改與測試」，而不是單純問問題。

例如主目錄保留目前可運作版本：

sha3/

另外建立：

sha3-eqy-debug/
sha3-verilator-fix/
sha3-slang-compatible/

分別讓 Codex：

EQY debug:
Compare the SystemVerilog and generated Verilog implementations.
Do not change module interfaces.
Run EQY after each meaningful change.

Verilator cleanup:
Resolve actionable Verilator warnings without changing cycle-level behavior.
Separate testbench warnings from synthesizable RTL warnings.

Slang compatibility:
Make the RTL compatible with read_slang and Yosys while preserving behavior.
Run lint and synthesis checks.

這樣即使其中一個 Codex 任務進行了錯誤的大規模修改，你的主要工作目錄仍然安全。OpenAI 官方也將工作樹定位為多個 agent 平行處理同一 repository、探索不同修改方向而不互相衝突的方式。