程式碼品質檢查
對最近撰寫的程式碼進行全面性的品質驗證。結合規格符合度、跨層安全性以及預先提交檢查。
步驟 1：識別變更內容
git diff --name-only HEAD
git status
步驟 2：閱讀任務文件與適用規格
按順序閱讀當前任務的文件：
prd.mddesign.md（若存在）implement.md（若存在）
python3 ./.trellis/scripts/get_context.py --mode packages
針對每個變更的套件/層，閱讀其規格索引並遵循其中的品質檢查章節：
cat .trellis/spec/<package>/<layer>/index.md
閱讀所引用的具體指引文件——索引僅是導引，並非最終目標。
步驟 3：執行專案檢查
執行專案的 lint、型別檢查與測試指令。在繼續之前修正所有失敗。
步驟 4：根據清單進行審查
程式碼品質
- Linter 通過？
- 型別檢查器通過（若適用）？
- 測試通過？
- 沒有遺留除錯用的日誌？
- 沒有被壓制的警告或型別安全繞過？
測試覆蓋率
- 新功能 → 是否已新增單元測試？
- 錯誤修正 → 是否已新增回歸測試？
- 行為變更 → 是否更新了既有測試？
規格同步
- 是否需要更新
.trellis/spec/？（新的模式、慣例、學到的教訓）
「如果我修正了一個錯誤或發現了不顯而易見的事情，我應該記錄下來，讓未來的我不會再遇到同樣的問題嗎？」→ 如果是，請更新相關的規格文件。
範圍紀律
- 是否對任務未要求的程式碼進行了整理？
- 是否針對尚未存在的案例新增了抽象、設定或擴充點？
- 是否針對不可能發生的狀態添加了推測性的備援？
- 是否修改了驗收標準中未提及的檔案？
- 是否在呼叫端添加了解決方案，而非在問題實際發生的位置進行修復？
步驟 5：跨層維度（若適用）
若您的變更僅限於單一層，請跳過此步驟。
A. 資料流（變更觸及 3 層以上）
- 讀取流程追蹤正確：儲存層 → 服務層 → API → UI
- 寫入流程追蹤正確：UI → API → 服務層 → 儲存層
- 型別/結構是否在層之間正確傳遞？
- 錯誤是否正確傳播給呼叫端？
B. 程式碼重複利用（修改常數、建立工具函式）
- 在建立新程式碼前，是否搜尋過既有相似程式碼？
grep -r "pattern" src/ - 如果相同的值重複出現，它是否代表一個穩定的概念，且所有呼叫端必須同時變更？只有在此情況下才進行提取——兩個今天恰好相同的文字字串應該保持分離。
- 在批量修改後，所有出現的位置是否都已更新？
C. 匯入/依賴（建立新檔案）
- 匯入路徑正確（相對路徑 vs 絕對路徑）？
- 沒有循環相依性？
D. 同層一致性
- 其他使用相同概念的地方是否一致？
步驟 6：報告與修復
報告您發現的每一個違規事項。然後：
- 機械性與局部問題（lint 小問題、遺漏的型別、錯誤匯入、無用分支、失敗的斷言）→ 就地修正，然後重新執行專案檢查。
- 設計或判斷問題（為共享概念命名、移動模組邊界、變更公開介面、重新分配行為的歸屬）→ 記錄證據與您的建議，然後停止。請勿無聲地重寫它。
如果某項修正會觸及當前任務範圍之外的檔案，請說明此事並停止，而不是擴大變更範圍。