Community程式設計與開發github.com

證據審查

對任何內容——無差異的整個專案、路徑、未提交的變更、分支或 GitHub PR / GitLab MR——進行深度、基於證據的程式碼審查。重現問題而非猜測,像嚴格的維護者一樣判斷層級選擇與重用,並編寫包含 ID、嚴重性、狀態與驗證的結構化報告。

證據審查 是什麼?

此技能模擬一位資深工程師在為最終交付負責時所進行的程式碼審查。它超越單純的差異比對,完整閱讀範圍內的程式碼,執行工具,並以可丟棄的腳本重現可疑發現。審查遵循兩個標準:一是「專案審計」,要求詳盡閱讀、建置與測試、清晰定義嚴重性等級與狀態,並誠實記錄「狀態良好」的部分;二是「嚴格維護者」,檢查變更是否屬於正確的抽象層、指出重複造輪子的地方、追蹤共享狀態的所有讀寫者,並在依賴發生前釐清合約。報告以證據深度而非篇幅取勝,每個發現都附有 ID、嚴重性(從嚴重到低)、驗證狀態(是否透過執行程式碼重現),以及定位資訊。此技能支援多種模式:無參數時的專案模式(完整審查整個儲存庫或指定路徑並輸出報告檔案)、差異模式(針對已暫存/未暫存的變更或分支,結果直接顯示在聊天中)、PR/MR 模式(使用獨立工作目錄安全地提取並審查合併請求),以及更新模式(基於新提交重新驗證現有報告)。它會根據檔案數量(約 40 個檔案或 8000 行程式碼)自動進行規模化處理,透過劃分類別並使用子代理或多次迭代來管理大型審查範圍。

相容平台✓Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/avi-dev-user/evidence-review/tree/HEAD

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

在你喜歡的 AI 中提問

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

說明文件

證據審查 是做什麼的?

你正在進行一位資深工程師在為最終交付負責時所做的審查:他們會完整閱讀範圍內的程式碼、執行工具、重現他們懷疑的部分,並誠實說明他們無法檢查的部分。兩個標準界定了門檻:

  • 專案審計。 完整閱讀範圍內的程式碼,執行建置與測試,每個嚴重的發現都以可丟棄的腳本重現,使用清晰的嚴重性等級,狀態會隨著修復而演進,並包含一個誠實的「狀態良好」部分。
  • 嚴格維護者。 首先詢問這個變更是否屬於這個層級,並透過檔案與行號指出現有的輔助函數或擴展點,在聲明某項操作安全之前,先追蹤共享狀態的每個讀取者,區分阻塞性與非阻塞性問題,並在依賴發生前鎖定合約。

深度來自證據,而非篇幅。一份簡短但每個發現都真實的報告,勝過一份為了看起來詳盡而填充內容的長報告。

1. 解析範圍

給定的引數:"$ARGUMENTS"(空引號表示無引數)。如果這看起來仍然是文字上的佔位符,表示你的代理沒有替換引數:請從使用者的請求中獲取它們。

引數範圍模式輸出
無整個儲存庫,工作目錄的當前狀態專案報告檔案
路徑該完整路徑,加上其定義中所呼叫的一層深度的內容專案報告檔案
diff已暫存 + 未暫存的變更:git diff HEAD變更在聊天中
branch [基線]git diff <基線>...HEAD(三個點:從合併基礎點開始)變更在聊天中
`pr <編號網址>`PR/MR 的頭部相對於其目標分支變更
--update <檔案>重新驗證現有報告;僅限於專案模式,可搭配或不搭配路徑更新編輯該檔案
  • branch 模式的基線分支: git symbolic-ref --short refs/remotes/origin/HEAD;如果失敗,則嘗試 main,再失敗則嘗試 master;如果兩者都不存在,則視為待解決問題(參見第 2 節)。
  • 專案模式中的骯髒工作目錄: 審查工作目錄的當前狀態,並記錄 HEAD <SHA> + 未提交的變更 作為修訂版。已修改的檔案使用 path:line,不使用固定連結。
  • 無引數且工作目錄骯髒: 此為待解決問題(專案模式還是差異模式?)。
  • 單一儲存庫: 對於路徑,執行擁有該路徑的套件的命令(最近的 package.json / pyproject.toml / go.mod / Cargo.toml / *.csproj),並從儲存庫根目錄向下讀取到該套件的規則檔案。

變更模式仍會審查周圍的程式碼。 審查的單位是變更的區塊 加上 它們所在的完整函式、每個變更符號的呼叫者、變更所觸及狀態的每個讀取者與寫入者、涵蓋這些變更的測試,以及描述它們的文件。孤立地閱讀差異,正是昂貴錯誤獲得批准的方式。

取得 PR 或 MR

永遠不要 checkout 到使用者的工作目錄之上。始終在一個暫存位置使用獨立的工作目錄:

  • GitHub:git fetch origin pull/<編號>/head:pr-<編號>;GitLab:git fetch origin merge-requests/<編號>/head:mr-<編號>。然後執行 git worktree add <暫存目錄>/pr-<編號> pr-<編號>。
  • 元資料:gh pr view <編號> --json title,body,comments,reviews,baseRefName,headRefName 或 glab mr view <編號> --comments。如果兩者 CLI 均不可用或未登入,則僅審查差異,並在報告標頭說明未讀取討論歷史。
  • 為了執行基線以進行比較(第 4 節),在合併基礎點處新增第二個工作目錄。永遠不要在頭部工作目錄之間來回切換。
  • 結束時移除這些工作目錄(git worktree remove)。

2. 背景與一輪提問

收集以下資訊,並保留在報告標頭中:

  • 修訂版本(完整 SHA)、分支、遠端 URL。如果沒有遠端,則跳過此處其餘部分,並使用 path:line。否則先執行 git fetch --quiet,然後執行 git branch -r --contains <sha>;如果 fetch 失敗,則將該 SHA 視為未推送。連結僅在 SHA 已推送且主機為 GitHub 或 GitLab 時才固定到該 SHA(將 SSH 遠端轉換為 https):
    • GitHub https://github.com/<組織>/<儲存庫>/blob/<sha>/<路徑>#L<a>-L<b>
    • GitLab https://<主機>/<群組>/<儲存庫>/-/blob/<sha>/<路徑>#L<a>-<b>
    • 其他情況:path:line。
  • 專案規則:CLAUDE.md、AGENTS.md、CONTRIBUTING.md、lint/型態設定檔、PR 範本,以及上層目錄中的規則檔案。首先根據專案自身的規則判斷發現,其次才考慮一般品味。
  • 系統的目的:README、文件、部署清單、CI 設定、進入點。
  • 對於 PR:其描述、連結的議題、現有的審查評論及其解決方式,以及目標分支。閱讀先前輪次的審查,以免重提已解決的觀點,並檢查所請求的變更是否確實執行。
  • 意圖。 用一句話說明該程式碼或變更正在解決什麼問題。如果你無法做到,這是一個待解決問題,因為答案可能會改變它的實作方式。

報告語言,以優先順序取勝:使用者的明確請求;專案的規則檔案;上層目錄中的規則;目標受眾(上游開源 PR 使用英文);專案現有文件的語言。如果都不適用,則為待解決問題。

待解決問題。 收集來自第 1 節和第 2 節的每個待解決問題(範圍、基線分支、受眾、請求者希望涵蓋的關注點、語言、意圖),並一起、在一則訊息中提問。不要問任何你可以自己找到答案的問題。如果沒有人可以回答(非互動式執行,或用戶表示不要詢問),請使用這些預設值,並在報告標頭的「假設」下方逐項列出:無引數時為專案模式;受眾為維護者;語言為英文;無指定的關注點;意圖為 PR 描述或 README 中所述。

請求者命名的關注點,無論其嚴重性為何,都會在報告頂部擁有自己的章節。

3. 預算與分類

在逐行閱讀任何內容之前,決定「範圍內」的含義。

  • 從逐行閱讀中排除: 鎖定檔案、vendor/、node_modules/、dist//build/、生成的程式碼、最小化檔案、二進位檔案、快照、大型測試資料、API 集合。透過 grep 或略讀來找出重要的內容(釘選的漏洞版本、機密、端點列表)。
  • 計算剩餘內容, 僅計算非測試來源檔案。大約超過 40 個檔案或 8000 行,將程式碼劃分為不同類別,並派發唯讀的子代理,每個類別一個,以收集候選發現,並附上檔案:行號與推理。在此規模下這是必需的,而非可選項目:一個上下文無法讀取所有內容,而靜默的略讀比誠實的拆分更糟糕。每個候選項都在主執行緒中進行驗證(第 7 節)。如果你的代理沒有子代理,則每次處理一個類別,在多次處理之間保留書面的候選清單,並在範圍中說明工作是如何劃分的。
  • 測試: 完整閱讀涵蓋風險最高路徑的測試,以及每個發現所依賴的 mock 所在的測試;略讀其餘測試以了解設定和覆蓋率,並在範圍中說明。
  • 依風險排序: 首先處理進入點和認證,然後是任何寫入資料儲存的內容,接著是向外部的呼叫,最後是其餘部分。
  • 誠實記錄覆蓋率。 報告的範圍部分說明哪些內容被完整閱讀、哪些被略讀、哪些被跳過。永遠不要聲稱完成了你沒有完成的完整閱讀。

4. 基線健康狀態

執行任何操作前的安全性

  • 你未編寫的程式碼(來自 fork 或未知貢獻者的 PR,你剛收到的儲存庫):安裝、建置和測試會執行它,包括安裝鉤子和測試設定。列出你打算執行的命令及其會執行的內容,並先詢問。如果沒有人可以回答,請不要執行:僅進行靜態審查,並在報告標頭中說明。
  • 檢查測試的指向。 閱讀測試設定和環境檔案。如果測試套件會觸及 localhost 之外的任何內容(共享資料庫、測試 API、真實佇列),請不要執行它;記錄原因。
  • 保持 checkout 乾淨。 使用尊重鎖定檔案的命令進行安裝(npm ci、pip install -r 並盡可能使用雜湊,uv sync --frozen)。將建置和覆蓋率輸出傳送到 checkout 目錄之外,或確認它已被 gitignore 忽略(測試執行器通常預設將覆蓋率寫入儲存庫:傳遞輸出目錄,例如 jest --coverageDirectory <暫存目錄>)。結束時,git status 必須顯示你沒有做出任何變更。
  • 永遠不要針對生產或共享環境執行任何操作。生產檢查應變成帶有確切要執行命令的建議(例如在生產資料庫上執行查詢計畫)。

要執行什麼

在 package.json scripts / pyproject.toml / Makefile / CI 設定中找到真實的命令,然後執行並記錄每項及其確切結果:型態檢查、lint、建置、測試(附上每個檔案的覆蓋率),以及該生態系的依賴審計(npm audit、pip-audit、cargo audit、govulncheck、bundle audit、dotnet list package --vulnerable;osv-scanner 作為備用)。審計需要網路和鎖定檔案;如果缺少其中任一,請記錄。大多數審計工具在發現安全公告時會以非零狀態碼退出:這是一個結果,而不是失敗的命令。

  • 一個沒有測試、建置或 linter 的專案:記錄「未設定任何項目」一次。這算是一個發現,而不是每個檔案都算一個。
  • 僅在依賴項存在已知漏洞、已超過生命週期結束日期,或阻礙必要升級時,才報告過時的依賴項。
  • 一個你無法安裝的私有依賴項:記錄它,針對可用的程式碼(已安裝的副本、已供應的副本)進行審查,並說明哪些函式庫行為未經驗證。

在變更模式中,在頭部執行測試套件,如果某項測試失敗,也要在基線(在其自己的工作目錄中)執行,以便每個失敗標記為新增或已存在。

5. 映射系統

在逐行閱讀之前,為自己記錄以下內容:

  • 進入點:HTTP 路由、協定處理器(WebSocket、gRPC、電話服務等)、CLI 命令、佇列消費者、定時任務、遷移、啟動程序。
  • 信任邊界:誰可以到達每個進入點,呼叫者如何被認證,以及租戶/用戶身份從何而來。
  • 資料儲存,它們的索引,以及哪些路徑讀取和寫入每個集合或資料表。
  • 對外部的呼叫:超時、TLS、重試、不明確的失敗意味著什麼。
  • 中間步驟可能失敗的多步驟操作。
  • 資料的真實形狀。 從 README、API 文件、測試資料、種子資料和 API 集合中收集範例值:路徑格式、日期格式、ID 格式、大小寫。每個解析器和路徑輔助函數之後都會針對所有這些進行檢查。

在變更模式中,改為映射爆炸半徑:對變更所觸及的每個呼叫者和每個讀取者進行 grep,並附上檔案:行號。

6. 深度閱讀

現在閱讀 reviewer-lens.md。它是一個問題清單,而非配額:大多數章節對大多數檔案沒有什麼可說的,沒有內容的章節就保持空白。僅報告具有具體觸發場景的候選項。

完整閱讀範圍內的每個檔案,而非摘錄。包括程式碼所依賴的函式庫中介面行為重要的部分(客戶端函式庫在對等端斷開後的行為,框架在回應發送後處理錯誤的方式)。許多真正的錯誤存在於此。

不要豁免良好的程式碼。 看起來設計良好的部分會接受與其他部分相同的機械式檢查:對其熱門查詢進行查詢計畫檢查、對其解析器進行真實資料形狀檢查、對其共享狀態進行讀取者檢查。看起來謹慎的程式碼隱藏著沒有人尋找的錯誤。

維護一個持續更新的候選清單,每個候選項包含:位置、哪裡出錯、具體場景(觸發它的輸入和狀態),以及你將如何證明它。

同時維護一個做得好的事物清單,並附上證據。「確認正常」的主張需要與發現相同的嚴謹性:你檢查了讀取者、運行了測試、閱讀了函式庫程式碼。

7. 驗證

對於每個可能是高或嚴重的候選項,以及任何成本較低的中等嚴重性候選項:

  • 使用一個在暫存目錄中的可丟棄腳本重現它,絕不要在儲存庫中進行。偏好使用小規模的真實依賴(記憶體資料庫或容器化資料庫,在 HTTP 邊界處模擬上游)勝過 mock 被審查的程式碼。
  • 對於效能主張,進行測量:查詢計畫(explain()、EXPLAIN ANALYZE)、之前和之後的時間,資料大小需能顯示問題。
  • 對於關於共享狀態的「這是安全的」主張,列出每個讀取者和寫入者。
  • 限制投入: 每個候選項約 15 分鐘或 5 次嘗試。超過後,標記它並繼續前進,附上原因。一旦每個嚴重/高嚴重性候選項都有一個標籤,就停止重現。

標記每個發現的證據:

  • yes:已透過執行程式碼重現。
  • partly:主張的一部分已重現;該部分說明了是哪一部分。
  • artifact:由檔案、清單、映像層或提交證明,在此處無法執行(遺漏的部署變數、歷史中的機密)。
  • no:嘗試過但無法重現;說明為什麼仍然報告它,或者將其放棄。
  • not tried:僅基於推理。

然後誠實:

  • 一個在此部署中沒有合理觸發條件的候選項應被放棄,而非歸類為低。
  • 推理保持標記為推理(「可能」、「我無法從此處檢查」)。
  • 一個僅因為 mock 傳回真實程式碼永遠不會傳回的內容而通過的測試,是關於測試本身的發現,而非關於程式碼的證據。

8. 分類

嚴重性,根據在此部署中的影響和可達到性判斷。當可達到性取決於你無法檢查的內容(網路 ACL、誰可以到達某個埠)時,按照它是可達到的來記錄嚴重性,並在其旁邊說明哪些因素會降低它。

  • 嚴重:立即可以被利用,具有嚴重影響。
  • 高:資料遺失、跨租戶或跨用戶存取,或核心功能失效。
  • 中:一個需要特定條件的真實錯誤或風險。
  • 低:程式碼衛生、可維護性、文件、依賴項偏移。

對於函式庫,根據對典型消費者的影響進行判斷。對於單用戶工具,資料遺失仍然是高嚴重性,安全發現需要一個現實的攻擊者。

在變更模式中,同時標記每個發現:

…

[已截斷以進行翻譯]

相關技能