審查 (Review)
以全新的視角,從兩個獨立維度評判一項變更:是否構建了正確的東西(規格)和構建得是否良好(品質)。所有發現都必須有證據支持,並根據真實使用者可能遇到的實際影響進行嚴重程度分級。然後以技術嚴謹性而非服從態度來處理發現。
核心原則: 當一項變更明確改善了程式碼庫的健康狀況並且完成了要求,即使它不是你自己會寫的方式,也應批准。絕不要批准你尚未實際閱讀和檢查的變更。
流程位置: 規格 → 規劃 → 構建 (+ 測試) → 審查 → 合併。
第 1 步:確定範圍
- 使用者指定範圍(PR、分支、提交範圍、檔案)。否則:當前分支相對於其與預設分支的合併基礎,加上未提交的變更。
- 在執行任何其他操作之前,先解析固定點並確認範圍非空:使用
git rev-parse <ref>、git log <ref>..HEAD --oneline、git diff <ref>...HEAD --stat處理已提交的工作,以及git diff --cached --stat(暫存)、git diff --stat(未暫存)和git status --short(未追蹤)處理未提交的變更。審查兩者的聯集,當未提交的變更在範圍內時,告知每位審查者(審查者提示中有一行專門說明)。無效的 ref,或範圍在兩方面都為空,則在此步驟失敗。 - 對於 PR,請閱讀其描述和連結的問題。
第 2 步:收集意圖
按順序查找:變更所實作的規格和計劃(specs/<slug>/、提交或 PR 中的連結、使用者提供的路徑)、構建記錄中的 Ruling: 行,以及它關閉的問題。用兩三句話重述意圖。如果沒有規格,請說明:規格軸線將根據 PR 描述和使用者的合理期望進行判斷。
同時查找標準:CONTRIBUTING.md、CODING_STANDARDS.md、CLAUDE.md/AGENTS.md、Lint 配置、ADR、詞彙表。
規模檢查。 約 100 行變更是理想的,約 300 行對於單一邏輯變更是可接受的,約 1000 行則太大而難以良好審查:建議拆分(按檔案組堆疊或垂直切片)作為一個發現。重構與功能工作混合是兩項變更。
第 3 步:以全新上下文進行審查
作者對自己的假設視而不見,編寫程式碼的對話會話也是如此。當子代理工具可用時,使用全新上下文派遣審查者,使用 reviewer-prompt.md:向他們提供 diff(作為檔案或精確命令)、規格/計劃路徑、標準檔案和記錄裁定。絕不要提供你的會話歷史。審查者為唯讀,且不會產生自己的審查者。
平行運行,這樣一個軸線就不能掩蓋另一個軸線:
- 規格審查者: 缺失、多餘、誤解。
- 品質審查者: 正確性、測試、設計、安全性、效能。
- (可選,針對高風險或廣泛的變更) 爆炸半徑審查者: grep 無法顯示的破壞。
使用可用的最強大模型進行整個分支的審查。如果沒有子代理工具,則將每個軸線作為單獨的傳遞自行完成,並將結果標記為自我審查:比新鮮的審查者弱,由使用者決定這是否足夠。
在內聯中審查自己剛剛完成的分支不能替代此步驟。
規格軸線
將 diff 與要求進行比較:
- 缺失: 跳過、部分完成或聲稱但未實作的需求或成功標準。引用規格行。
- 多餘: 沒有人要求的行為、推測性的選項、鉤子或抽象(範圍蔓延、YAGNI)。
- 誤解: 用錯誤的方式構建了正確的功能,或解決了錯誤的問題。
- 無法從 diff 驗證: 存在於未變更的程式碼中或跨越變更的需求。列出要檢查的內容,而不是猜測。
規格是一份願景文件,而不是詳盡的清單。 在規格未提及之處,合理使用者的期望即為要求。關於某個輸入的沉默並不表示允許它崩潰。
品質軸線
首先閱讀測試: 它們揭示了意圖和覆蓋率。
測試
- 每個新行為是否都有一個測試,如果該行為被破壞,該測試會失敗?盡可能通過實驗來回答:翻轉變更添加的條件並運行測試套件,在一個可丟棄的工作樹或副本中進行,這樣被審查的 checkout 永遠不會改變。保持綠色的突變是一個發現:命名缺失的測試。
- 行為應通過公共接縫(public seams)而非內部實作進行測試;不對模擬(mocks)進行斷言;沒有由被測試程式碼計算的期望值;模擬僅在系統邊界使用。
- 錯誤修復有回歸測試。沒有跳過或禁用的測試。測試輸出乾淨。
正確性
- 符合規格;邊緣情況(null、空、零、最大值、Unicode、並發);錯誤路徑,而不僅僅是快樂路徑;差一錯誤(off-by-one)、競態條件、可能不同步的狀態。
可讀性和簡潔性
- 名稱表明了事物的用途。控制流程直接了當。能否用更少的行數?每個抽象是否值得其代價(不要在第三次使用前就進行一般化)?
- 死程式碼、無操作的變數、
// removed註解、無人需要的相容性 shim。 - 註解解釋為什麼,而不是什麼。描述解決方法(workaround)的註解通常標誌著未修復的根本原因。
設計
- 符合現有模式;新模式需要理由。
- 重構是否減少了讀者必須掌握的概念,還是僅僅移動了它們?傾向於分支、模式或層級消失的版本。
- 功能邏輯洩漏到共享模組;現有輔助函式的幾乎重複;條件語句硬塞到不相關的流程中;對同一形狀的重複 switch(缺少模型或調度器);第二個必須與第一個保持同步的布林值(缺少狀態機)。
- 只有一個呼叫者的包裝器和傳遞層(應將其內聯)。比所需範圍更廣的可變狀態。
- 在邊界進行驗證,在內部信任。沒有用無聲的 fallback 掩蓋不明確的不變量;沒有無緣無故的
any/轉型。 - 檔案增長:將檔案推送到遠超健康大小的變更應先分解。
安全性
- 不受信任的輸入(HTTP、CLI、檔案、環境變數、LLM 輸出、第三方回應)在邊界處進行驗證。查詢參數化。輸出編碼。在需要時檢查身份驗證/授權。秘密脫離程式碼、日誌和版本控制系統。新的依賴項合理、有維護、許可證相容;審查 lockfile 的 diff。
效能
- N+1 查詢、無界迴圈或擷取、缺少分頁、阻塞的同步工作、熱路徑上的大規模分配、不必要的重新渲染。盡可能量化(「1000 行時每行約 50 毫秒」)。
程式碼味道基準線(判斷性呼叫;儲存庫的文件化標準優先):神秘命名、重複程式碼、依戀情結、資料泥團、基本型別 obsession、重複開關、散彈式修改、發散式變更、推測性一般化、訊息鏈、中間人。
爆炸半徑軸線(高風險或廣泛的變更)
列出呼叫者並非此處的工作;grep 可以在一秒內完成。此處的工作是找出 grep 無法顯示的破壞:
- 找到變更之所以安全基於的一個事實(「這個呼叫只會丟棄已死亡的條目」)。通過執行程式碼來證明:一個導入固定版本的實際函式庫並呼叫確切函式的腳本。
- 查看符號搜索停止的地方:函式庫源碼和本地補丁、執行時序(非同步順序、拆卸)、序列化格式(JSON 形狀、資料庫欄位、有線協議、讀取相同位元組的其他語言)、功能標誌、三個跳躍距離外的消費者。
- 針對每個風險:如何破壞、
file:line、可能性、成本以及最便宜的檢查。將已檢查並清除的風險分開列出。
第 4 步:驗證每個發現
聽起來正確的發現,在檢查之前並非發現。
- 根據到達該程式碼的呼叫者、警衛(guards)和測試進行檢查。如果它們排除了該發現,則將其丟棄。
- 證明重要的發現:一個失敗的測試、一個重現腳本或顯示錯誤行為的命令輸出。傾向於通過運行證明的發現,而不是似是而非的發現。
- 將預先存在的缺陷與此變更引入的回歸分開標記。
- 合併共享根本原因的發現。
- 零發現是有效結果。 不要為了看起來詳盡而發明一個。
阻斷合併的門檻
只有在有證據支持時,發現才可能被評定為關鍵或重要,從而阻斷合併:
- 一個顯示錯誤行為的運行(測試、腳本或命令),或
- 一個具體的輸入,逐步通過程式碼追蹤到錯誤的輸出,每一步都有
file:line。
你無法通過這種方式確立的似是而非的疑慮(「這可能會破壞 X」,「邊緣情況可能未處理」)將被評定為次要並標記為未驗證。它不會阻斷合併。將其列出,以便作者可以檢查。
第 5 步:分級和報告
根據發布後對使用軟體的合理人員的影響進行分級,而不是根據規格是否提到觸發條件。
| 嚴重程度 | 含義 | 所需行動 |
|---|---|---|
| 關鍵 | 安全漏洞、資料遺失、核心功能破壞 | 阻斷合併 |
| 重要 | 錯誤或脆弱行為、遺漏的需求、未測試的行為、吞沒的錯誤、有害的重複或設計 | 合併前修復 |
| 次要 | 打磨、小幅簡化、更廣泛的覆蓋 | 作者決定;如果延遲則記錄 |
| 小細節 | 風格偏好 | 可選 |
| 僅供參考 | 提供上下文,無需行動 | 無 |
以槓桿效應為先:首先是正確性和安全性,然後是結構性問題和遺漏的簡化,最後是其他。如果有一個結構性問題和十個小細節,那麼結構性問題就是審查的重點。提出解決方案,而不僅僅是問題:「用一個以 kind 為鍵的查找表替換這個 if 鏈」、「內聯這個只有一個呼叫者的包裝器」、「重用 utils/date.ts 中的 formatDate」。
保持誠實:沒有橡皮圖章式的「LGTM」,沒有將真正的錯誤軟化為「可能是次要問題」,沒有將小細節誇大成關鍵。具體指出做得好的地方。
使用 reviewer-prompt.md 中的格式:規格結論、優點、按嚴重程度分類的問題(每個問題都包含 file:line、錯誤內容、為何重要、如何修復、證據)、爆炸半徑備註、拒絕評判(考慮後擱置的行為,附帶原因),以及結論:批准、附帶修復批准或要求變更。保持規格和品質部分分開;不要跨軸重新排序。
結論規則: 僅當至少有一個關鍵或重要的發現滿足上述證據門檻時,才要求變更。一個完成了要求且僅有次要或未經證實的問題的變更,應予批准,同時列出這些問題。拒絕一個正確的變更對作者的傷害,與批准一個有問題的變更相同。
第 6 步:處理發現(當你是作者時)
審查意見是你要評估的輸入,而不是要執行的命令。
- 在反應之前先全部閱讀。如果任何項目不清楚,在實作任何東西之前先詢問清楚:項目之間通常相關聯。
- 將每個項目重述為一個技術要求,並根據程式碼進行驗證。對於這個程式碼庫來說是正確的嗎?它會破壞什麼東西嗎?當前程式碼是否有原因?審查者是否擁有完整的上下文?
- 在錯誤時用證據反駁:一個測試、一個
file:line、一個度量。如果一個建議添加了一個未使用的「合適」功能,請檢查使用情況;YAGNI 也適用於審查者。將任何與使用者先前決定衝突的事項升級給使用者。 - 按順序修復:關鍵/阻斷 → 簡單 → 複雜。每個修復首先需要一個失敗的測試來重現發現(通過
test),然後是修復,然後是整個套件變綠。進行一次專注的修復傳遞,而不是無盡的循環。 - 你未修復的次要問題將在你最終的訊息中放入「已延遲」清單。你決定不修復的發現是一個帶有原因的記錄決定。
- 不要做表面上的同意。 不說「你說得完全正確!」、「抓得好!」,或感謝。說明你更改了什麼(「已修復:空行現在會發出僅包含標題的 CSV;測試
exports header for empty view」)或為什麼程式碼保持不變。如果你反駁錯了,用一句話說明並修正。
在 GitHub 上,在行內評論執行緒中回复,而不是作為頂層評論。
合併前(完成定義)
- 每個規格成功標準都已滿足並在運行系統中驗證
- 新行為有測試,在沒有變更時會失敗;完整套件變綠,輸出乾淨
- 沒有未解決的關鍵或重要發現;延遲事項已記錄原因
- 沒有死程式碼、除錯輸出或註解掉的區塊;變更範圍限定在任務內
- Lint、型別檢查、構建通過
- 遷移、配置和標誌已考慮;有風險的變更改存在回滾路徑
- 公共介面和使用者可見行為已記錄;難以逆轉的決策有 ADR
- 提交訊息和 PR 描述以獨立的方式說明更改了什麼以及為什麼更改
- 在專案要求的關鍵點,已獲得人工批准
常見的合理化藉口
| 想法 | 現實 |
|---|---|
| 「測試通過了,所以沒問題」 | 測試無法捕捉錯誤的設計、安全漏洞或誤讀的規格。 |
| 「我寫的,我知道是對的」 | 相同的作者,相同的盲點。需要新鮮的眼光。 |
| 「AI 生成的程式碼大概沒問題」 | 它出錯時既自信又看似合理。需要更多而不是更少的審查。 |
| 「重構後更乾淨了」 | 如果讀者掌握的概念數量相同,那只是移動了。 |
| 「我們以後再清理」 | 「以後」很少會來。現在就修復,或者明確地歸檔。 |
| 「規格沒有提到那個輸入」 | 沉默並非允許。根據使用者得到的結果來分級。 |
| 「審查者說是次要問題,所以就是次要問題」 | 根據影響重新分級。 |
| 「修正很明顯,不需要測試」 | 失敗的測試是證明發現是真實的並且現在已消失的唯一證據。 |
| 「審查者大概是對的」 | 先根據程式碼進行驗證。 |
紅旗
- 「LGTM」沒有閱讀證據
- 沒有
file:line的發現,或未檢查呼叫者和警衛就聲稱的發現 - 規格和品質發現合併成一個排序列表
- 小細節埋沒在正確性錯誤之上
- 審查者被授予了作者的會話歷史
- 在沒有先進行失敗測試的情況下修復審查發現
- 實施某些回饋項目而忽略其他項目
- ...(原文截斷處)