前幾天已經讓 Codex 實作功能、修正問題、補測試與重構程式。

Codex 可以很快修改很多檔案，因此更需要用 Git 清楚記錄每一步。速度越快，如果所有改變都混在一起，Review 和回復的成本也會越高。

今天不增加功能，而是整理一套之後都會使用的 Git 工作節奏，並替明天的搜尋與篩選功能準備乾淨 branch。

一次 commit 只做一件事

「一件事」不是指只能修改一個檔案。

新增任務功能可能同時需要修改元件、樣式與測試，這些檔案共同完成同一個可驗證目的，放在一個 commit 很合理。

真正應該避免的是把不同目的混在一起，例如：

• 新增搜尋功能
• 重構 localStorage
• 更新所有套件
• 重新格式化整個專案

如果這四件事出現在同一個 commit，Reviewer 很難判斷每項修改的理由；其中一項有問題時，也很難只回復那一部分。

為什麼不要讓整段對話變成一個 commit？

和 Codex 的一段對話可能包含：

實作功能
-> 發現測試不足
-> 補測試
-> 順手重構
-> 更新文件

對話是一段協作過程，不代表它自然就是一個 Git 單位。

Commit 應該按照可獨立理解與驗證的目的切分，而不是按照「這些修改剛好發生在同一次聊天」切分。

回頭看目前的 commit 訊息

這個系列已經建立過幾個 commit，例如：

• initial commit
• add AGENTS.md
• add issue creation
• fix bug
• reconstruct

從歷史可以大致知道開發順序，但因為這只是一個示範專案，其實我取的 fix bug 和 reconstruct 沒有說明修了哪個問題、重構了哪一部分。

更具體的寫法可以是：

fix: persist issues across reloads
refactor: separate issue persistence logic

好的 commit message 要說什麼？

Commit message 應該讓人只看一行，就知道這次變更的主要目的。

可以使用：

類型: 完成的事情

常見類型例如：

• feat：新增使用者功能
• fix：修正錯誤行為
• test：只新增或改善測試
• refactor：不改變外部行為的結構調整
• docs：只修改文件
• chore：工具或維護工作

類型不是最重要的部分，真正重要的是描述要具體。fix: fix bug 即使格式正確，仍然沒有提供足夠資訊。

開始任務前先檢查 working tree

每次交給 Codex 新任務以前，先確認：

• 目前在哪一個 branch
• working tree 是否有未提交修改
• 最新 commit 是不是預期狀態
• 是否已經同步到正確的基準版本

如果工作區原本就有修改，不代表不能繼續，但一定要先知道它們屬於誰、是否會和新任務重疊。

否則 Codex 完成後看到的 diff，會混合原有變更和 AI 新增內容。

一個任務使用一個 branch

明天要讓 Codex 根據 Issue 實作搜尋與狀態篩選，所以今天可以先建立專用 branch，例如：

git switch -c feature/search-and-filter

Branch 名稱不是固定規則，只要團隊能從名稱理解目的即可。

建立後再確認一次狀態，確保：

• 已經位於新 branch
• 起點是預期的最新版本
• working tree 乾淨

這樣明天所有修改都會集中在這個功能 branch，不會直接混入原本的穩定版本。

讓 Codex 先建議，不要直接提交

如果完成一個任務後，不確定 diff 應該是一個 commit 還是多個，可以先請 Codex 分析：

請檢查目前 Git 狀態與未提交 diff，建議合理的 commit 切分方式。

要求：
- 每個 commit 只包含一個可以獨立說明的目的
- 功能實作與保護該功能的測試應放在一起
- 無關重構、文件或套件變更應分開
- 每個建議列出應包含的檔案與原因
- 為每個 commit 建議一個具體 message
- 如果所有修改本來就屬於同一件事，直接建議只建立一個 commit

這次只分析，不要修改檔案、不要執行 git add 或 git commit，也不要改寫既有歷史。

這個 Prompt 沒有強迫 Codex 一定要拆成很多 commits。過度切分也會造成問題，例如把功能程式和必要測試拆開後，中間的 commit 可能無法通過驗證。
目前沒有任何還沒有 commit 的內容所以這邊就不示範了。

提交前的固定流程

之後每個任務都會遵循：

確認 branch 與 working tree
-> 完成單一範圍的修改
-> 執行測試、lint 與 build
-> Review 完整 diff
-> 確認沒有無關檔案
-> 建立 commit
-> 再次確認 Git 狀態

Commit 是驗證完成後的結果，不應該只因為 Codex 回報「已完成」就直接建立。

哪些檔案不應該被提交？

Review 變更檔案時，要特別注意：

• 套件安裝產物
• 建置輸出
• 測試暫存與 coverage 報告
• 編輯器或作業系統產生的檔案
• .env 或包含密碼、Token 的設定
• 和目前任務無關的格式化修改

是否提交某類產物仍要依專案規則判斷，但敏感資訊不應因為 Codex 建立了檔案，就自動進入 Git 歷史。

今日小結

今天沒有硬拆已經完成的 commit，也沒有改寫過去的 Git 歷史，而是建立一套之後能重複使用的節奏：一個任務、一個 branch，一個 commit 只處理一個可理解且可驗證的目的。