用 Codex 標出需要人工追查的變更

一份修改同時包含產品程式、測試與重構時，審查者需要確認需求是否完成，也要檢查既有行為、資料契約與模組邊界是否受到影響。

Codex 可以先閱讀差異與專案規則，標出需要人工追查的位置，減少審查者在大量正常變更中尋找風險的時間。

這項協助需要明確範圍與判斷標準。/review 產生的是審查發現（Review Finding），每一項都要回到實際程式、測試與需求核對。

開發者負責決定哪些意見需要修正、哪些屬於設計討論，以及哪些是缺少上下文造成的誤判。

/review 會讀取指定範圍的差異

Codex 的 /review 可以審查相對於基準分支的變更、目前尚未提交的變更，或指定提交。

未提交範圍可能同時包含已暫存、未暫存與未追蹤檔案，因此啟動前要先執行 git status --short，確認畫面中的檔案都屬於這次任務。

今天我們使用「Review uncommitted changes」審查工作目錄。若開發者還有另一項尚未完成的修改，該差異也會進入審查上下文，使審查發現混合兩個目的。

開始前先建立獨立分支或工作樹，並留下清楚的 Git Checkpoint。

/review 會啟動專用審查者，讀取選定差異（Diff）並回報有優先順序、可採取行動的發現，不會在審查過程直接修改工作目錄。命令只會在開啟的專案位於 Git 儲存庫時出現。

審查前先交代變更意圖與不可破壞行為

單看差異可以知道哪些行被改動，卻不一定看得出改動原因。審查提示詞（Prompt）要補上需求、預期資料流、公開契約與驗證結果，讓 Codex 判斷一項差異是否偏離任務。這些資訊可以來自 issue、任務摘要與 AGENTS.md。

本次變更意圖包含兩部分。第一部分是讓缺少 labels 的 issue 視為未分類，四種標籤統計保持零值，該 issue 仍留在排名結果中。第二部分只整理 buildIssueReport() 的內部結構，將 result 改名為 labelStats，並抽取私有的 countTrackedLabels()。

不可破壞行為也要寫清楚。大小寫、前後空白與重複標籤規則保持原狀。文字與 JSON 輸出契約不變。排名規則、錯誤處理、公開函式簽章及套件設定都不變。

審查者若沒有這些限制，就可能提出一般的風格建議，破壞了團隊標準。

審查條件應對應專案的風險

架構邊界檢查這次修改是否仍由正規化層處理外部資料，報表層只負責組合統計與排名。若 countTrackedLabels() 被公開匯出，或呼叫端開始各自處理缺值，責任就可能分散到錯誤位置。

測試缺口要核對需求中的每個結果。只確認不再拋出 TypeError，仍缺少四種統計與排名保留的斷言。

錯誤處理則要檢查修正有沒有吞掉其他異常，例如把任何非陣列資料都默默轉成空集合，使格式錯誤失去可見度。

安全風險與資料相容性也要檢查。這項任務沒有網路、憑證或權限修改時，審查者可以明確回報未發現直接安全邊界變更，同時確認沒有新增敏感資料輸出、任意檔案存取或未驗證輸入路徑。

資料相容性則聚焦 labels 缺省、空陣列及既有正常資料是否得到相同結果。

最後核對 AGENTS.md。修改是否只落在允許區域、測試命令是否完整執行、禁止檔案是否保持不變，以及差異是否混入套件、部署設定或祕密檔案。專案規則提供的是這個儲存庫的具體判斷基準。

審查包含實作與測試的 Diff

今天繼續使用前幾篇留下的工作目錄。差異應包含 test/issue-report.test.ts 中缺少 labels 的業務案例、正規化缺值的實作，以及 buildIssueReport() 的改名與抽取方法。

啟動審查前，先確認檔案清單與驗證紀錄。

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

git diff 預設不顯示未追蹤檔案內容，因此仍要對照 git status --short。

若測試檔尚未被 Git 追蹤，應先直接閱讀內容，或依團隊流程暫存後再審查。這一步只整理審查範圍，不建立提交，也不推送遠端。

在 Codex CLI、IDE 或 Desktop 的輸入區輸入：

/review

接著選擇審查未提交變更。若介面提供自訂審查指示，貼上以下內容；也可以在啟動審查前後，以同一段文字指定標準：

請依 AGENTS.md 審查目前未提交變更。變更目的如下：

1. issue 缺少 labels 時視為未分類，四種標籤統計不增加，issue 仍保留在排名結果中。
2. 將 buildIssueReport() 內的 result 改名為 labelStats，並把原有計數區塊抽成私有 countTrackedLabels()。
3. 保留大小寫、空白、去重、零值、排序、文字與 JSON 輸出行為。

請集中檢查：
- 架構與責任邊界是否被改變。
- 測試是否完整驗證需求，且沒有弱化既有斷言。
- 缺值處理是否掩蓋其他格式錯誤或改變錯誤契約。
- 是否引入安全風險、資料相容性問題或違反 AGENTS.md。

每項 finding 請提供嚴重度、檔案與行號、觸發條件、可觀察影響、判斷證據及最小修正方向。缺少證據時標為待確認。

這一輪只審查，不要修改檔案、測試、設定，也不要建立 commit。

審查發現要有可重現的失敗情境

有效的審查發現需要指出某段程式在什麼輸入或流程下造成什麼影響。

像是「這段可以寫得更乾淨」缺少行為風險，也無法判斷優先順序。若意見指出非陣列 labels 會被當成空集合，就要說明資料契約是否允許該輸入，以及哪個測試或呼叫端能重現。

檔案與行號可以協助定位，程式片段仍要和完整呼叫路徑一起閱讀。Codex 有時會看到區域差異，卻沒有注意上游已完成驗證。也可能根據名稱推測函式用途，漏掉專案特有規則。審查者應要求它補上型別、測試或呼叫端證據。

嚴重度要和實際影響相符。會造成資料錯誤、公開契約破壞、安全漏洞或主要流程失敗的項目優先處理。命名偏好、可讀性建議與沒有目前使用情境的防禦性處理，需要較低優先級或獨立討論。

將審查意見分成三種處理結果

開發者收到審查發現後，可以分成「必修」、「可討論」與「誤判」。

必修項目已有足夠證據顯示需求、契約、安全或既有行為受損，應先建立重現方式，再做範圍清楚的修正。修正後重新執行相關測試與 /review。

可討論項目常涉及責任位置、命名、抽象層次或尚未發生的邊界輸入。這類意見可以記錄替代方案、影響與決定理由，再由熟悉模組的人判斷是否納入。若決定延後，應留下後續條件，避免同一建議每次審查都重新出現。

誤判需要保存駁回證據。例如審查發現認為缺少 labels 會改變排名，既有業務測試已證明 issue 仍保留且順序符合規則，就可以引用測試與程式路徑說明。單純寫「不同意」無法幫助下一位審查者理解判斷依據。

可以用以下紀錄整理結果：

修正審查發現要建立新的驗證循環

接受一項審查發現後，不要直接要求 Codex「全部修好」。先挑選單一項目，固定重現案例與不可修改範圍，再讓它提出最小修正。這樣能避免審查意見把原本小型差異擴張成另一輪重構。

修正完成後，先執行針對該審查發現的測試，再跑原有相關測試與 AGENTS.md 指定的完整檢查。

接著重新檢視差異，確認修正沒有帶入額外行為。必要時再次使用 /review，並告知前一項審查發現、採用的修正與驗證結果。

Codex 回報「沒有發現問題」時，仍要保留人工審查。這個結果代表選定範圍與現有上下文中沒有被標出的高可信度問題，無法涵蓋未提供的業務知識、執行環境差異與測試未定義的情境。

最後合併判斷由人完成

完成審查後，開發者要回到需求、完整差異、測試輸出與審查發現分類。確認必修項目已處理，可討論項目有決定與理由，誤判有核對證據，未執行的驗證也已清楚標示。這些材料才構成可追溯的審查紀錄。

/review 適合先找出可疑區域，也能提醒測試缺口、錯誤處理與規則違反。

它沒有掌握的歷史背景、產品承諾與事故經驗，仍需要開發者及熟悉系統的人補上。測試綠燈與零 findings 都是判斷材料的一部分。

本篇任務完成時，應留下選定的審查範圍、自訂條件、Codex findings、三類處理結果、修正後驗證與人工結論。合併、建立提交或推送遠端仍依團隊流程另外執行，不由這次 /review 自動決定。

參考資料：

• Codex 程式碼審查