Community程式設計與開發github.com

程式碼審查

在任務、功能或分支完成且合併前使用;審查 PR、差異、進行中的工作或其他代理或模型編寫的程式碼;當被問到「這會破壞什麼」或「合併是否安全」時;以及在收到審查意見後、實際執行前使用。

程式碼審查 是什麼?

此技能定義了一個結構化、高品質的程式碼審查流程,適用於任何 AI 輔助開發環境。它將審查分為兩個主要軸線:**規格**(是否構建了正確的東西)和**品質**(構建得是否良好),並要求以客觀證據和對使用者實際影響的嚴重程度分級來支持審查結果。技能支持對 PR、分支、提交範圍甚至未提交的變更進行審查,並能自動解析範圍。它鼓勵使用子代理(subagent)以全新的上下文進行平行審查,並提供了詳細的審查者提示模板。審查過程包括釐清範圍、收集意圖,並在「規格」軸(檢查缺失、多餘、誤解的功能)和「品質」軸(檢查測試、正確性、可讀性、設計、安全性、效能)上進行平行審查。對於高風險變更,還可選擇性地進行「爆炸半徑」審查,以找出 grep 無法發現的潛在破壞。最終的審查報告會根據對使用者的實際影響對問題進行分級(嚴重、重要、次要、小細節、僅供參考),並明確定義了阻斷合併的標準:只有經由可執行的測試或逐步追蹤驗證過的關鍵或重要問題才能阻斷合併。此技能也包含了當作者收到審查意見時應如何行動的指引,強調以技術事實回應,而非表面同意。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hesedcasa/frankenskills/tree/main/skills/review

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

審查 (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 步:處理發現(當你是作者時)

審查意見是你要評估的輸入,而不是要執行的命令。

  1. 在反應之前先全部閱讀。如果任何項目不清楚,在實作任何東西之前先詢問清楚:項目之間通常相關聯。
  2. 將每個項目重述為一個技術要求,並根據程式碼進行驗證。對於這個程式碼庫來說是正確的嗎?它會破壞什麼東西嗎?當前程式碼是否有原因?審查者是否擁有完整的上下文?
  3. 在錯誤時用證據反駁:一個測試、一個 file:line、一個度量。如果一個建議添加了一個未使用的「合適」功能,請檢查使用情況;YAGNI 也適用於審查者。將任何與使用者先前決定衝突的事項升級給使用者。
  4. 按順序修復:關鍵/阻斷 → 簡單 → 複雜。每個修復首先需要一個失敗的測試來重現發現(通過 test),然後是修復,然後是整個套件變綠。進行一次專注的修復傳遞,而不是無盡的循環。
  5. 你未修復的次要問題將在你最終的訊息中放入「已延遲」清單。你決定不修復的發現是一個帶有原因的記錄決定。
  6. 不要做表面上的同意。 不說「你說得完全正確!」、「抓得好!」,或感謝。說明你更改了什麼(「已修復:空行現在會發出僅包含標題的 CSV;測試 exports header for empty view」)或為什麼程式碼保持不變。如果你反駁錯了,用一句話說明並修正。

在 GitHub 上,在行內評論執行緒中回复,而不是作為頂層評論。

合併前(完成定義)

  • 每個規格成功標準都已滿足並在運行系統中驗證
  • 新行為有測試,在沒有變更時會失敗;完整套件變綠,輸出乾淨
  • 沒有未解決的關鍵或重要發現;延遲事項已記錄原因
  • 沒有死程式碼、除錯輸出或註解掉的區塊;變更範圍限定在任務內
  • Lint、型別檢查、構建通過
  • 遷移、配置和標誌已考慮;有風險的變更改存在回滾路徑
  • 公共介面和使用者可見行為已記錄;難以逆轉的決策有 ADR
  • 提交訊息和 PR 描述以獨立的方式說明更改了什麼以及為什麼更改
  • 在專案要求的關鍵點,已獲得人工批准

常見的合理化藉口

想法現實
「測試通過了,所以沒問題」測試無法捕捉錯誤的設計、安全漏洞或誤讀的規格。
「我寫的,我知道是對的」相同的作者,相同的盲點。需要新鮮的眼光。
「AI 生成的程式碼大概沒問題」它出錯時既自信又看似合理。需要更多而不是更少的審查。
「重構後更乾淨了」如果讀者掌握的概念數量相同,那只是移動了。
「我們以後再清理」「以後」很少會來。現在就修復,或者明確地歸檔。
「規格沒有提到那個輸入」沉默並非允許。根據使用者得到的結果來分級。
「審查者說是次要問題,所以就是次要問題」根據影響重新分級。
「修正很明顯,不需要測試」失敗的測試是證明發現是真實的並且現在已消失的唯一證據。
「審查者大概是對的」先根據程式碼進行驗證。

紅旗

  • 「LGTM」沒有閱讀證據
  • 沒有 file:line 的發現,或未檢查呼叫者和警衛就聲稱的發現
  • 規格和品質發現合併成一個排序列表
  • 小細節埋沒在正確性錯誤之上
  • 審查者被授予了作者的會話歷史
  • 在沒有先進行失敗測試的情況下修復審查發現
  • 實施某些回饋項目而忽略其他項目
  • ...(原文截斷處)

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能