每個可用狀態都需要一個清楚位置

Codex 可以在短時間內完成多輪修改。第一輪新增格式化函式，第二輪接上命令列參數，第三輪補上文件。

這些內容一旦長時間留在同一份未提交差異中，後面出現測試失敗時，開發者會很難分辨哪些修改可以保留，錯誤又是從哪一輪開始出現。

Git 檢查點（Checkpoint）是在完成一個小步驟後建立的本機提交。提交內容包含該步驟的程式變更，提交訊息說明修改目的，測試結果則記錄在任務完成紀錄中。

需要回到某個安全狀態時，開發者可以透過提交歷史定位，不需要依靠對話記憶猜測。

本文沿用 codex-hands-on 的 --format json 任務。讀者會先建立基準提交（Baseline Commit），再分別為 JSON 格式化、命令列整合與 README 建立檢查點。

最後刻意加入「未知格式自動退回文字輸出」的錯誤方向，提交後再使用 Git 回復（Rollback）演練撤銷。

整個練習只在本機分支進行，不推送遠端、不改寫共享歷史，也不接觸正式環境。

每次提交前都要先閱讀差異並執行對應測試，讓檢查點成為已確認的安全狀態，而不是單純保存 Codex 當下產出的所有內容。

建立專用分支與乾淨基準

先進入儲存庫根目錄，讀取 AGENTS.md，確認專案允許建立本機分支與提交。

接著檢查目前分支及工作目錄。git status --short 沒有輸出，代表目前沒有已追蹤或未追蹤的工作內容等待處理。

git status --short
git branch --show-current
git log -1 --oneline

若工作目錄已有修改，先確認內容歸屬。使用者自己的變更要保留，不能直接清除，也不能混進練習提交。

可以先完成原本的工作、依照團隊流程保存，或另外準備乾淨的工作目錄。來源不明時先停止，避免把其他人的成果當成 Codex 任務內容。

確認工作目錄乾淨後，建立專用分支，再用空提交標示這次任務的起點。空提交不會改動檔案，只會在歷史中留下明確位置，之後也方便比較整段任務的分支差異。

git switch -c exercise/json-output-checkpoints
git commit --allow-empty -m "chore: mark baseline before json output task"
git log -1 --oneline

把畫面顯示的短雜湊記到任務筆記，名稱可以寫成 baseline。若專案規則不接受空提交，也可以將建立分支時的 HEAD 記為基準，不需要製造檔案變更。後續所有比較都使用記錄下來的已確認的雜湊，避免用模糊的提交數量推算位置。

讓 Codex 先說明每個 Checkpoint 的條件

開始修改前，先把三個批次與提交條件交代清楚。Codex 每次只處理一批次，通過指定測試並完成差異審查後，才準備提交。

建立 commit 屬於改變 Git 歷史的動作，提示中要明確授權本機提交，並禁止推送、合併與遠端操作。

我們要在目前本機練習分支完成 --format json，並為每一批次建立 Checkpoint。

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

每次只執行單一批次。完成後先顯示 git status、git diff --stat、完整差異、實際測試命令與結果，等待我確認。取得確認後才能建立本機 commit。

只提交該批次相關檔案，不使用 "git add ."，不推送、不合併、不變更遠端，也不使用會清除其他修改或改寫歷史的命令。

請先讀取 AGENTS.md 並提出三個批次 Checkpoint 的檔案範圍、驗證條件與建議提交訊息。這一輪不要修改或提交。

計畫應列出每批次預計處理的檔案與測試。若 Codex 找到的實際路徑和預期不同，要先根據儲存庫內容校正。

提交訊息可以沿用專案現有格式，並讓一行摘要對應一項行為，例如 feat: add JSON report formatter。

開發者仍要在每批次提交前給出確認。這個檢查點能防止 Codex 把測試失敗、臨時除錯或超出範圍的修改存成安全點。

若某一批次尚有待確認風險，可以先留在工作目錄，不急著建立 Checkpoint。

第一個 Checkpoint 保存資料格式

第一批次完成 JSON 格式化函式與單元測試後，先查看工作目錄。檔案清單應只包含格式化模組與直接相關的測試。

接著檢查差異內容、空白問題及指定測試，確認四種標籤、零值與議題排序都符合需求。

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

測試通過並完成審查後，只暫存本批檔案。以下路徑只是示意，執行時要換成 Codex 已確認的實際檔名。逐一列出路徑，可以避免把工作目錄中的其他內容一起加入提交。

git add src/json-output.js test/json-output.test.js
git diff --cached --stat
git diff --cached
git commit -m "feat: add JSON report formatter"

提交完成後，執行 git status --short，確認沒有本批遺留修改，再用 git show --stat --oneline HEAD 檢查剛建立的提交內容。

任務筆記要保留提交雜湊、測試命令、通過與失敗數量，以及未執行的檢查。

Checkpoint 1：填入提交雜湊
目的：建立 JSON 報表格式與資料契約
驗證：填入實際測試命令與結果
未驗證：填入尚未執行項目，沒有則寫無

後續 Checkpoint 仍維持單一責任

第二批次接上 --format json 命令列參數，驗證 JSON 可解析，並確認原有文字輸出維持不變。

完成審查後，只加入命令列入口與整合測試，再建立 feat: expose JSON output in CLI 提交。

第三批次只更新 README.md，核對範例後建立 docs: document JSON output option 提交。

每次開始下一批次前，先執行 git status --short 與 git log -3 --oneline。乾淨工作目錄能讓新差異只包含本批修改，短提交歷史則能確認目前所在的安全點。

若狀態和任務筆記不一致，要先找出遺漏檔案或額外提交。

git status --short
git log --oneline --decorate -5

Checkpoint 的提交訊息應描述已完成的行為，避免使用 update files、fix stuff 或 Codex changes。

需要回復時，清楚的訊息能讓開發者知道該提交涵蓋資料格式、命令列整合或文件，不必先打開每份差異才能辨識。

完成三個批次後，可以用基準雜湊比較整段任務。執行 git diff BASELINE_HASH..HEAD --stat進行比對，再執行 git log BASELINE_HASH..HEAD --oneline --reverse，確認三個 Checkpoint 的順序與任務計畫一致， 其中的 BASELINE_HASH 要換成先前記錄的實際值。

刻意建立一個錯誤方向

回復演練需要一個能辨識、可撤銷的錯誤變更。接下來我們會要求 Codex 將未知的 --format 值自動退回文字輸出，例如使用者輸入 --format jsno 時，程式仍回傳成功。

這會隱藏參數拼字錯誤，也會改變既有錯誤處理契約，因此被指定為要撤銷的方向。

現在進行回復演練。請刻意加入以下錯誤行為：
未知的 --format 值自動退回文字輸出，並回傳成功狀態。

只修改命令列參數處理與直接相關測試，不調整 JSON 格式化函式或 README。
完成後顯示差異與指定測試結果，等待我確認，不要自行提交。

這是刻意設計的錯誤方向，用來練習 Git 回復，不要延伸修改其他錯誤處理。

檢查差異範圍後，把這個方向建立成獨立提交，例如 experiment: fall back to text for unknown formats。

它應位於三個有效 Checkpoint 之後。記下該提交雜湊，再確認工作目錄乾淨，避免未提交內容干擾回復結果。

git add path/to/cli-file path/to/cli-test
git diff --cached
git commit -m "experiment: fall back to text for unknown formats"
git log --oneline --decorate -5
git status --short

這個提交明確包含錯誤方向，前面的資料格式、命令列 JSON 功能與 README 仍是已接受狀態。

若錯誤修改和其他工作混在同一個 commit，先不要進行回復，應先重新整理演練內容，讓目標提交只包含預定變更。

使用 git revert 撤銷錯誤提交

git revert 會建立一個新提交，用相反差異撤銷指定 commit。原提交與撤銷紀錄都會留在歷史中，開發者可以看見錯誤方向何時加入、何時被取消，也能保留前面三個有效 Checkpoint。

先檢查準備撤銷的提交。確認雜湊、訊息與檔案都指向剛才的錯誤方向，再執行回復。下列 BAD_COMMIT_HASH 要替換為實際雜湊。

git show --stat BAD_COMMIT_HASH
git show BAD_COMMIT_HASH
git revert --no-edit BAD_COMMIT_HASH

--no-edit 會直接採用預設的 revert 訊息，其中會記錄被撤銷的提交。遇到衝突時，先停下來閱讀衝突檔案，確認目前分支是否又有其他修改。

不要讓 Codex 自動接受整份任一版本，解決後的內容仍需符合三個有效 Checkpoint 的行為。

git reset 會移動分支指標，部分用法也可能改寫尚未分享的歷史。git restore 則用於回復工作目錄或暫存區內容。

當前的目標是保留完整演練紀錄，因此固定使用 git revert。共享分支上的回復也多半採用新增撤銷提交的方式，實際操作時仍要遵守團隊規則。

回復後要重新驗證安全點

回復命令成功，只代表 Git 已套用相反差異。接著要確認未知格式重新採用預期的錯誤處理，--format json 仍能輸出有效 JSON，原有文字模式也保持正常。

先執行命令列相關測試，再依照 AGENTS.md 執行完整驗證。

git status --short
git show --stat --oneline HEAD
git diff HEAD~1..HEAD
git log --oneline --decorate -6

歷史中應依序出現基準、三個有效 Checkpoint、錯誤方向與 revert 提交。

工作目錄應保持乾淨。若回復後還有未提交變更，要先判斷來源，不能直接把回復視為完成。

Codex 的程式碼審查（Code Review）可以針對單一提交或分支差異執行。此時可要求 /review 檢查 revert 提交是否只撤銷錯誤方向，再用基準雜湊檢查整段分支差異是否仍包含三批有效成果。

審查結果要和 Git 歷史、實際差異及測試輸出一起判讀。

最後整理一份回復紀錄，寫下錯誤提交與 revert 提交的雜湊、撤銷原因、保留的 Checkpoint、測試命令與結果。

完成這次演練後，開發者能從任務基準開始，逐步保存可用狀態，並在 Codex 走偏時只取消指定方向，保留已經審查與驗證的成果。