把一次修改分成五個階段

任務背景不足時，Codex 只能自行推測預期行為、影響範圍與完成條件。開啟 Codex 後直接輸入「幫我修好」，它仍會嘗試尋找問題並修改程式，最後程式可能通過編譯，實際行為卻偏離需求，開發者也很難判斷代理人在哪一步誤解了問題。

一次容易掌握的工作，可以分成五個階段。先說明任務，再確認 Codex 提出的計畫，接著允許它修改程式、執行驗證，最後由開發者審查完整差異。

每個階段都有可以檢查的輸出。需求有誤時，停在任務說明；影響範圍不合理時，停在計畫確認；測試失敗時，則不接受變更。

今天我們會使用 Codex 命令列介面（Command-Line Interface, CLI）操作 codex-hands-on 專案，修正一個標籤統計錯誤。

同一筆議題（issue）的標籤陣列若重複出現 bug，目前會被計算兩次。預期結果是每筆 issue 對同一種標籤最多只貢獻一次。

這項修改範圍集中，也有明確的輸入與預期輸出，適合練習完整循環。提示內容應交代目標、背景、限制與完成條件，並透過測試與差異檢查確認成果。

這五個階段可以套用在 CLI、IDE、Desktop 與 Cloud。各入口的操作按鈕不同，判斷順序維持一致。

準備乾淨的任務起點

先在終端機進入 codex-hands-on 專案目錄，確認目前分支與工作目錄狀態。本文沿用已完成標籤統計功能的分支，開始前不應留下其他尚未提交的修改。乾淨起點可以讓後續差異只呈現這次錯誤修正，也能在方向錯誤時回到清楚的基準。

cd codex-hands-on
git branch --show-current
git status --short

git status --short 沒有輸出時，代表工作目錄乾淨。若看到已修改或未追蹤的檔案，先確認內容屬於哪一項工作，再選擇提交、暫存或移到另一個工作目錄。

不要讓 Codex 在來源不明的修改上繼續工作，否則審查時很難分辨每一行由誰產生，也很難確認它服務哪個需求。

接著執行現有測試，保存修改前的基準結果。若測試在任務開始前已經失敗，先記錄失敗項目，並判斷它是否與標籤統計有關。

準備完成後，在專案根目錄執行 codex 開啟對話。

說明可重現的錯誤與完成條件

第一輪先把錯誤描述清楚，不授權修改。任務內容要說明觀察到的結果、預期結果、相關功能，以及這一輪允許的動作。

標籤統計的重現資料可以使用一筆含有 ['bug', 'bug', 'security'] 的 issue。目前輸出為 bug: 2，預期輸出為 bug: 1 與 security: 1。

在 Codex CLI 輸入：

請先分析 codex-hands-on 的標籤統計錯誤，這一輪不要修改檔案。

重現情境：單一 issue 的 labels 為 ['bug', 'bug', 'security'] 時，目前 bug 數量會增加 2，security 增加 1。

預期行為：每一筆 issue 對同一種標籤最多計數一次，所以這筆資料應讓 bug 增加 1、security 增加 1。不同 issue 擁有 bug 標籤時仍要分別計數。

請找出相關實作與測試，說明錯誤原因，列出檔案路徑與對應程式位置。
無法從程式確認的資訊請明確標示。

收到分析後，要核對 Codex 找到的函式是否真的負責標籤統計，也要查看現有測試是否包含重複標籤。

原因說明需要連到具體程式，例如迴圈逐一累加標籤，卻沒有在單筆 issue 的範圍內排除重複值。

若 Codex 追到命令列格式化層或排名函式，應請它補充資料流。確認責任位置後，再進入下一步。

先確認計畫再允許修改

錯誤位置確認後，要求 Codex 提出修正計畫。計畫需要說明預計修改的檔案、處理方法、測試案例與驗證命令，暫時不產生程式變更。

這一步可以提早發現範圍偏移，例如 Codex 想改變輸入格式、重寫整個統計模組，或加入新的相依套件。

請根據剛才確認的原因提出修正計畫，先不要修改檔案。

計畫需列出：
1. 預計修改的檔案與函式。
2. 如何在單一 issue 範圍內排除重複標籤。
3. 要新增或調整的測試情境。
4. 完成後要執行的測試命令。

請維持現有輸入格式、四種標籤名稱、排名功能與命令列輸出格式，不要新增套件，也不要整理無關程式。

合理的計畫只會動到標籤統計實作與對應測試。排除重複值的範圍要落在每一筆 issue 內，不能把整批資料的同名標籤合併，否則兩筆帶有 bug 的 issue 只會得到一次計數。

計畫也需要保留 bug 與 security 各自累加的能力，並加入重複標籤、不同 issue 同標籤，以及既有案例的驗證。

若計畫與這些規則一致，就回覆允許執行。若內容有誤，可以指出具體段落，例如要求它將去重範圍改為單筆 issue，重新列出計畫。

確認計畫代表同意目前的修改方向，後續仍要依實際差異與測試結果決定是否保留。

依確認過的計畫修改程式

計畫通過後，在同一段對話要求 Codex 執行。這次指示要重申範圍與停止條件，避免代理人在修改期間遇到其他問題後自行擴大工作。

Codex 可以更新統計函式及直接相關測試。若需要變更公共介面、資料格式或其他模組，應先停下來說明原因。

請依照剛才確認的計畫執行修改。

只修改標籤統計實作與直接相關測試。每筆 issue 對同一種標籤最多計數一次，不同 issue 仍要各自計數，一筆 issue 中的不同目標標籤也要分別計數。

保留現有輸入、輸出、排名與 priorityScore 行為，不要新增套件或建立提交。

若完成修正需要超出已確認的檔案與函式，請先停止並說明原因。
修改後先提供變更摘要，暫時不要把任務標示為完成。

Codex 修改時，可以從工作紀錄查看它讀取及變更的檔案。

若出現其他看起來無關的調整，可以先詢問這些變更與錯誤修正的關係。沒有直接關係的內容應撤回。修改摘要也要和檔案狀態互相核對，不能只依照對話中的文字判定範圍。

此階段完成的成果仍是候選修改。即使實作看起來合理，重複標籤、不同 issue 及不同標籤能否正確計數，都需要下一階段的測試輸出支持。

Codex 若表示已完成，可以提醒它先執行約定的驗證，再整理結果。

用自動化檢查驗證修正

驗證階段先執行直接相關的測試，快速確認錯誤案例，再執行專案既有的完整測試。

專案若有格式檢查、型別檢查或靜態分析，也應依原有開發說明執行。命令名稱要以儲存庫內的設定與文件為準，不要要求 Codex 猜測一條看起來合理的命令。

請驗證目前修改：先執行標籤統計的相關測試，再執行專案既有的完整測試。
若專案已設定格式、型別或靜態檢查，也請執行相關命令。

完成後列出每一條實際執行的命令、通過與失敗數量、略過項目，並說明下列情境由哪個測試覆蓋：
單一 issue 有重複標籤、不同 issue 有相同標籤、單一 issue 有不同目標標籤。

若任何檢查失敗，請先分析原因，不要改測試來配合錯誤實作。

測試失敗時，要先判斷原因來自實作、測試預期、環境，還是原有問題。

若 Codex 接著修改程式，驗證循環要重新開始，相關測試與完整測試都要再跑一次。測試通過只能證明已涵蓋的行為，開發者仍需確認案例是否對應需求。

最佳做法是同時檢查測試、格式、型別與最後行為，並在接受修改前閱讀差異。

驗證結果應保留原始命令與結果摘要。「測試完成」或「檢查正常」缺少可核對資訊，應要求 Codex 補上實際執行證據。

閱讀差異並進行人工審查

完成驗證後，先離開對話摘要，直接查看 Git 工作目錄。執行 git status --short 確認修改檔案，再用 git diff --stat 查看變更規模，最後閱讀完整的 git diff。

審查順序可以先看測試，理解新案例表達的規則，再看實作是否用清楚且局部的方式滿足規則。

git status --short
git diff --stat
git diff

測試中應清楚建立三個情境：單筆資料重複 bug 只計一次、兩筆資料各有 bug 要計兩次，以及同一筆資料的 bug 與 security 都能計入。

實作中的去重集合應在處理每筆 issue 時重新建立。若集合放在外層，後續 issue 的相同標籤會被忽略。若直接移除所有重複資料，也可能改變其他功能使用的原始輸入。

接著檢查修改範圍、命名與既有行為。差異應集中在統計函式和相關測試，沒有新增套件、變更輸出格式或調整 priorityScore。

也要閱讀被修改函式的上下文，確認去重處理沒有影響非目標標籤、空標籤陣列或缺少標籤的既有規則。審查畫面會反映 Git 儲存庫中的全部變更，因此乾淨起點會直接影響審查結果。

若找到問題，可以把檔案、行數與預期修正回傳給 Codex，再次經過修改、驗證與審查。

差異符合需求後，才決定保留、提交或交給其他成員審查。Codex 可以協助指出風險，接受修改與後續合併仍由開發者負責。

整理可追蹤的任務完成紀錄

審查通過後，請 Codex 整理一份「任務完成紀錄」。這份紀錄要讓沒有參與對話的人看懂問題、處理方式與驗證證據，因此內容需要對應實際差異，不能加入未執行的檢查或推測性的成果。

紀錄可以留在對話中，也可以放入提交訊息（Commit Message）或拉取請求（Pull Request, PR）說明。

請根據目前實際差異與命令輸出，整理一份任務完成紀錄。
內容包含問題與重現方式、確認過的原因、修改檔案與處理方法、新增或調整的測試、實際執行的驗證命令與結果，以及仍未驗證的風險。
請勿聲稱沒有執行過的檢查，也不要建立提交。

完成紀錄應說明重複計數發生在單筆 issue 的標籤處理，修正方式是在每筆資料的範圍內排除相同標籤。測試結果要列出實際命令與通過數量。若沒有執行某項檢查，也要如實保留。

開發者最後再將紀錄和 git diff、終端機輸出互相比對。

至此，一次 Codex 任務便有了完整軌跡：可重現的問題、確認過的計畫、受控修改、驗證證據、人工審查與完成紀錄。

這套循環能讓誤解停在較早階段，也讓每次往返都有清楚目的。任務規模變大時，可以把工作拆成數個小循環，每一輪都留下可檢查的結果。