修改速度加快後，審查範圍也要跟著收斂

Codex 可以在一次任務中修改程式、測試與文件。當所有變更同時出現在差異（Diff）裡，開發者需要一次確認需求理解、資料結構、命令列行為、測試案例與說明文件。只要其中一處出現疑問，就要回頭追查其他檔案是否受到影響。

將修改的範圍縮小，把中型任務拆成幾個可驗證的目標。每一批只修改完成該目標所需的檔案，執行對應檢查，接著交給開發者審查。

前一批通過後，再進入下一批。萬一 Codex 走偏，也能在變更範圍擴大前被發現。

我們繼續延續 codex-hands-on 的命令列工具，加入 --format json 輸出。原有文字輸出需要保持不變，JavaScript 物件表示法（JavaScript Object Notation, JSON）內容則要包含排序後的議題與四種標籤統計。

這項工作會拆成三個小批次進行，先建立 JSON 格式化函式與單元測試，接上命令列參數與整合測試，最後更新 README 使用範例。

每一批次完成後，Codex 都要提供修改摘要、檔案範圍、差異與測試結果。審查者一次只需要確認一層責任，包括資料格式、命令列整合或文件契約。

這種節奏也能讓後續回饋直接指向該批次的程式原始碼。

先把中型需求切成三個可驗證目標

拆分任務時，要先找出功能的責任邊界。--format json 涉及三件事，資料如何組成 JSON、命令列如何接收參數，以及使用者如何知道這項功能。這三件事有先後依賴，也各自有清楚的完成條件，因此適合依序處理。

第一批次只建立格式化函式。輸入為既有排名與標籤統計結果，輸出為可序列化的資料結構或 JSON 字串。這一批不修改命令列入口。單元測試要固定欄位名稱、零值與排序，先讓資料契約穩定下來。

第二批次才處理 --format json 參數。命令列在指定格式時呼叫第一批次建立的函式，未提供參數時則沿用現有文字輸出。整合測試要從命令列入口執行，確認標準輸出可被 JSON.parse 解析，也要檢查既有文字模式沒有改變。

第三批次只更新 README.md，加入參數說明、執行命令與輸出範例。這一批次以文件和實際程式的一致性作為驗收條件。若範例欄位與測試不一致，應回頭確認前兩批次的結果，不能只修改文件來掩蓋差異。

修改前先確認基準與專案規則

開始前要先確認目前分支、未提交變更與 AGENTS.md。審查窗格顯示的是 Git 儲存庫目前的變更，其中也可能包含開發者先前留下的內容。

若工作目錄已有其他修改，Codex 的產出就容易和既有差異混在一起。

git status --short
git branch --show-current
git diff --stat

若 git status --short 有輸出，先辨識檔案來源。屬於其他工作的修改應保留，並在提示中明確列為不可變更範圍。無法安全區分時，先暫停這次操作，處理工作目錄狀態後再開始。

接著請 Codex 讀取 AGENTS.md、package.json、命令列入口、既有格式化程式與相關測試，提出三個批次的計畫。

這一輪只做探索，不建立檔案。計畫中的檔名與測試命令要能在儲存庫找到，禁止修改區域也要列入每一批次限制。

我要在 codex-hands-on 加入 --format json 輸出。

請先讀取目前生效的 AGENTS.md、package.json、命令列入口、輸出格式化程式與相關測試，將工作規劃成以下三批次：

第 1 批次：JSON 格式化函式與單元測試。
第 2 批次：命令列參數整合與命令列整合測試。
第 3 批次：README 參數說明與使用範例。

原有文字輸出必須保持不變，不新增套件，不修改部署設定。
請為每批列出目標、預計修改檔案、驗收條件與測試命令。
這一輪只提出計畫，不要修改檔案或執行測試。

第一批次先固定 JSON 資料契約

第一批次要處理 JSON 的欄位與資料形狀。假設輸出包含 issues 與 labelStats，就要確認議題排序沿用既有結果，四種標籤都會出現，沒有資料時保留 0。

函式應接收已處理的資料，避免在格式化階段重新排名或計數。

現在只執行第 1 批次：建立 JSON 格式化函式與單元測試。

先確認專案現有模組格式與測試命名，再使用一致的寫法。
格式化函式接收既有的排序結果與四種標籤統計，不要重新計算資料。
輸出包含 issues 與 labelStats，且 bug、feature、documentation、security 四個欄位都要存在，缺少的數量為 0。

只修改格式化模組及其直接單元測試。不要修改命令列入口、README、package.json、鎖定檔或其他檔案，也不要新增套件。

完成後執行這一批的指定單元測試，輸出修改摘要、檔案清單、git diff --stat、完整測試命令與結果，然後停止，等待我審查。

審查時先看檔案清單，確認沒有命令列與文件變更。接著檢查函式輸入是否沿用既有資料、欄位名稱是否清楚，測試是否涵蓋四種標籤、零值與議題順序。

若序列化結果依賴物件順序，也要確認測試驗證的是資料契約，不能只比對碰巧成立的輸出字串。

可以使用 git diff --check 找出空白與衝突標記問題，再用專案實際提供的測試命令驗證。若測試失敗，要求 Codex 說明原因與準備修改的位置。

這一批次尚未被接受前，不要讓它接上命令列參數。

第二批次再接上命令列入口

第一批次通過後，第二批次只負責解析 --format json，並呼叫已完成的格式化函式。

參數未提供時，現有文字輸出必須完全沿用原流程。輸入檔錯誤、未知格式與結束狀態，則依照專案既有命令列慣例處理，不建立另一套錯誤規則。

第 1 批次已完成審查。現在只執行第 2 批次：
將 --format json 接到命令列入口，並補上命令列整合測試。

指定 json 時，使用第 1 批次的格式化函式輸出可由 JSON.parse 解析的內容。
未提供 --format 時，保留目前的文字輸出與結束狀態。
未知格式請沿用專案既有的參數錯誤處理方式。若沒有既有規則，先回報待確認。

只修改命令列參數或入口檔，以及直接相關的整合測試。
不要修改第 1 批次已通過的資料契約、README、package.json 或鎖定檔。

完成後執行指定整合測試與既有文字輸出測試，輸出修改摘要、檔案清單、git diff --stat、完整命令與結果，然後停止等待審查。

這次審查要確認參數解析只影響輸出分支，JSON 模式沒有混入提示文字或除錯訊息，文字模式的測試仍然通過。

若 Codex 為了加入一個參數而改寫整個命令列入口，差異已超出這一批次責任，可以要求它縮回局部修改。

Codex 的程式碼審查（Code Review）可以指定未提交變更、提交或基準分支，也能限制檔案與審查條件。

這一批次可以使用 /review 檢查目前差異，並要求它聚焦參數相容性、輸出純度與既有文字行為。審查只能回報問題，不應順帶修改檔案。

第三批次用實際輸出更新文件

前兩批次的程式與測試通過後，第三批才更新 README.md。

文件應寫出 --format json 的完整命令、輸入檔位置與代表性輸出。範例要從已完成的程式行為取得，欄位名稱、數值型別與巢狀結構都要和測試一致。

第 2 批次已完成審查。現在只執行第 3 批次：更新 README.md。

加入 --format json 的參數用途、完整執行命令與一份精簡輸出範例。
範例必須符合前兩批次已通過的 JSON 契約，並保留原有文字輸出說明。

只修改 README.md，不調整程式、測試、套件設定或鎖定檔。
完成後核對範例可被 JSON.parse 解析，輸出修改摘要、檔案清單、
git diff --stat、核對方式與結果，然後停止等待審查。

審查文件時，可以複製範例內容進行 JSON 解析，並與整合測試的實際輸出對照。

README 若省略部分議題資料，要清楚標示為縮短範例，保留的欄位仍需符合真實結構。命令中的路徑、引號與參數順序也要能直接使用。

第三批次只處理文件。若核對時發現程式契約有問題，先記錄問題，再回到對應批次處理。把程式修正混進文件差異，會讓審查者同時面對兩種責任，也會破壞原先的批次邊界。

每一批次都要留下可核對的完成紀錄

「完成」需要有變更範圍與驗證證據。Codex 每一批次都應回報做了什麼、修改哪些檔案、執行哪些命令、結果是否通過，以及有哪些檢查尚未執行。

只寫「測試通過」不足以確認它跑的是指定測試、完整測試，還是其他命令。

請整理本批次完成紀錄，內容包含：

本批目標與實際完成內容。
修改檔案及每個檔案的責任。
git diff --stat 與差異是否超出本批範圍。
執行過的完整測試或檢查命令、通過數量與失敗數量。
未執行的檢查、原因與仍需人工確認的風險。

只整理目前結果，不要修改檔案或開始下一批。

接著由開發者閱讀該批次的差異。第一批次確認資料契約與單元測試，第二批次確認命令列相容性與整合測試，第三批次確認文件與行為一致。

發現問題時，要把回饋指向具體檔案、程式行與驗收條件，Codex 才能在原批次內收斂修改。

每一批的檔案數量沒有固定標準。判斷方式可以看審查者能否用一句話描述該批目的，以及是否有對應的驗證方法。

若摘要同時出現資料重構、參數功能、文件改寫與套件升級，就表示範圍還能繼續拆分縮小。

最後查看完整 Diff 是否仍維持三個責任

當三個批次都完成後，再檢查整體分支差異。完整 Diff 應能沿著資料格式、命令列整合與文件說明閱讀，且沒有混入重新命名、無關排版、套件更新或部署設定。每一個檔案都要能對應到其中一批次的目標。

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

最後執行 AGENTS.md 指定的完整驗證命令，並比較各批次測試與全域測試結果。

指定測試通過只能證明局部行為，全域檢查可以找出整合後的影響。未能執行的命令要保留名稱、原因與需要補做的環境條件。

也可以用 /review 對整體未提交變更做一次審查，要求檢查需求完整性、既有文字輸出相容性、JSON 契約、測試缺口與 README 一致性。

收到結果後，仍要回到實際差異與測試輸出確認。審查回覆屬於檢查材料，需要由開發者判斷是否採納。

完成這次練習後，成果會是一個由三個批次變更組成的 --format json 功能。每一批次都有單一目標、限定檔案、獨立驗證與審查停點。

Codex 的修改速度仍然保留，開發者也能在範圍清楚時理解、接受或要求修正每一段差異。