落地前自我審查
在提交重大變更之前,執行此檢查清單。在 CI 發現問題之前先抓住它——或者更糟,在使用者發現之前。
使用時機
當以下任何一項為真時,執行此技能:
- 變更超過 100 行程式碼
- 修改超過 5 個檔案
- 觸及核心基礎設施(執行器、儲存、主要調度循環)
- 引入新的抽象或公開 API
- 對邊界情況或設計選擇不確定
快速閘門:
git diff --stat HEAD | tail -5 # 變更了多少?
git diff --name-only HEAD | wc -l # 變更了多少檔案?
略過條件
- 小型變更(≤50 行,≤3 個檔案)
- 純文檔或課程更新
- 僅測試變更(測試本身有它們自己的審查)
- 具有明顯且有限範圍的簡單一行錯誤修復
- 無邏輯變更的機械性重構
檢查清單
1. 邊界情況
- [ ] 處理了空值/空輸入?
- [ ] 測試了邊界條件(差一錯誤、空列表、零)?
- [ ] 考慮了並發訪問或競爭條件?
- [ ] 如果處理文字,考慮了 Unicode/編碼問題?
2. 錯誤路徑
- [ ] 所有異常在正確層級被捕獲(不過於廣泛)?
- [ ] 錯誤訊息具有資訊性(什麼失敗了、為什麼、該怎麼做)?
- [ ] 失敗模式優雅地失敗,而非靜默失敗?
- [ ] 沒有裸露的 `except:` 或吞沒的錯誤?
3. 測試覆蓋率
- [ ] 關鍵路徑有測試?
- [ ] 上述識別的邊界情況有測試?
- [ ] 測試實際執行且通過?
- [ ] 沒有留下 `pass` 或 `...` 的測試樁?
4. 文檔
- [ ] Docstrings/註解與當前行為匹配?
- [ ] 如果公開介面變更,README 已更新?
- [ ] 提交訊息捕捉了變更內容和原因?
- [ ] 相關的架構文檔仍然準確?
5. 程式碼品質
- [ ] 命名清晰且與周圍程式碼一致?
- [ ] 沒有明顯的程式碼壞味道(上帝函數、魔術數字、硬編碼路徑)?
- [ ] 遵循檔案/套件中的現有模式?
- [ ] 靜態分析 / 型別檢查通過?
一行煙霧測試
# 在提交之前執行(根據你的堆疊調整):
make format && make typecheck && pytest -x -q && echo "✅ 可以發布"
如果任何步驟失敗,在提交之前修復它。不要帶著紅色狀態發布。
反模式
| 反模式 | 修復方式 |
|---|---|
| "CI 會抓到它" | CI 是最後手段,而非你自身判斷的替代品。先抓住問題。 |
| "我之後再補測試" | 之後不會來。現在就寫測試,否則永久接受這個缺口。 |
| "我手動測試時它運作正常" | 手動測試不可重現。寫一個自動化測試,以便未來的工作階段也能驗證它。 |
| "錯誤訊息是一個 TODO" | TODO 錯誤訊息會以 TODO 錯誤訊息的形式發布。現在就寫真正的訊息。 |
| "我可以從程式碼看出它處理了這個情況" | 如果沒有測試,未來的重構會在不察覺的情況下破壞它。 |
為什麼這很重要
自主代理被訓練成產出足夠好的輸出以避免修正。沒有結構化的審查閘門,自主程式碼提交會繞過通常能捕捉迴歸和邊界情況的人類審查環節。這項技能扮演了那個閘門的角色——五個有針對性的透鏡依序執行,確保沒有明顯的問題遺漏。
報酬會複合累積:每一次成功抓住真實問題的審查,都是一次 CI 往返的節省、一個使用者錯誤的避免,以及一個不需要的回退 PR。