驗證層:完成代表有證據
您在提交之前證明某項變更確實有效,並建立檢查機制讓下一次證明更便宜。人類的職責從逐行閱讀 diff 轉變為定義「完成」的標準及審視證據。您的任務是誠實地產生那些證據。
其原則來自 How the Claude Code team thinks about verification(Addy Osmani,2026 年 11 月)。references/templates.md 中的檔案格式是此技能自有的;該文章描述了實務做法,但沒有展示任何格式。
使用時機
- 您完成了一項變更,正準備說「完成」或進行提交
- 使用者問「這能用嗎?」、「請證明」或「請驗證這個」
- 儲存庫沒有可重複的方式來啟動並冒煙測試該應用程式
- 使用者想知道某個功能、重寫或遷移該寫哪些測試
- 某次審查或測試套件遺漏了一個已影響使用者的錯誤,使用者希望下次能抓到它
- 某個測試不穩定,有人想重試或跳過它
- 使用者希望同時運行多個代理,但無法閱讀每個 diff
請勿用於: 逐行審查他人的 diff(那是審查,不是驗證)、僅一行文件的註解變更(無法執行任何內容)、或為了提高覆蓋率數字而增加測試。
核心原則
當證據說變更已完成時,它才算完成;而且變更永遠不得編輯自己的裁判。 「測試通過」是薄弱的證據,尤其是當同一個變更也寫了這些測試時。強有力的證據是實際運行的應用程式確實做了使用者要求的事,並且是由變更無法觸及的項目來檢查。
規則
- 執行變更。 啟動真正的應用程式並實際操作被變更的行為。這比單元測試更重要。一個全部通過的單元測試套件,但應用程式卻無法啟動,就是驗證失敗。
- 三輪,然後交給人類。 執行檢查、修復失敗、再次執行。如果三輪後仍有檢查失敗,停止並將證據移交給人類。不要開始第四輪。
- 絕不為了通過而削弱裁判。 在同一個要被裁判的變更中,不得編輯、跳過或刪除測試、lint 規則、檢查清單項目或 REVIEW.md 規則。如果裁判有誤,請說明原因,並在一個使用者批准的獨立提交中修改它。
- 從基底分支讀取裁判。 審查規則、檢查清單和閘道設定應來自預設分支,絕非來自正在測試的分支。
- 證據屬於一個提交。 對舊提交的驗證無法說明新提交的任何狀況。在進行任何新的編輯後,必須重新驗證或報告證據已過時。
- 先執行便宜的檢查,並且在本地執行。 測試、建置和 lint 應在 PR 開啟前完成,而不是佔用審查者的時間。
- 僅執行 diff 觸發的檢查清單項目。 通常會匹配 3 到 10 個項目。每次都執行全部項目會讓大家學會忽略清單。
- 為每個提交蓋上驗證方式的戳記,包括
none。 誠實的none之後可以被搜尋到。遺失的戳記則無法。 - 不穩定的測試就是一個錯誤。 不要跳過它、添加 sleep、或重試直到變綠。找到根本原因。如果找不到,刪除該測試並記錄原因。
- 要求人工介入的檢查必須說明原因。 「需要審查」不是理由。「變更了 session 檔案格式;舊的轉錄可能無法載入」才是。
- 每個遺漏都變成規則,而規則需要被修剪。 一個溜過去的錯誤代表驗證層有漏洞。用一個檢查來堵住它,並移除那些不再有存在價值的檢查。
該寫哪種測試
| 情境 | 測試類型 | 它證明什麼 |
|---|---|---|
| 使用者面向的流程(如果您只寫一個測試,就寫這個) | 端到端 | 一個真實的使用者路徑從頭到尾都能運作。失敗時會顯示步驟、追蹤軌跡和螢幕截圖,而不只是「超時」。 |
| 解析器、編碼器、金錢、狀態機、任何有邊界案例的程式碼 | 屬性(fast-check、Hypothesis、proptest) | 一個陳述句對數千個您沒想到的生成輸入都成立。 |
| 對已有功能的改寫、遷移或最佳化 | 差異 | 新舊實作對相同的輸入產生相同的輸出。 |
值得檢查的屬性:
| 屬性 | 陳述句 |
|---|---|
| 往返 | 編碼後再解碼,得到原始的內容 |
| 不變性 | 某件事永遠成立(餘額永不為負) |
| 冪等性 | 執行兩次等於執行一次 |
| 等價性 | 快速版本與一個緩慢但顯而易見是正確的版本匹配 |
對於差異測試:使用隨機或抽樣的真實輸入、標準化無關緊要的差異(空白、鍵值順序、時間戳記),並保留一份您已批准的差異清單。
緩慢的套件會被較少執行,因此覆蓋率會下降。保持每次編輯的迴圈快速,並將較重的測試移到提交之前。
必須保留的事項(不可觸碰)
- 現有的測試、lint 規則、檢查清單項目、REVIEW.md 和閘道設定:絕對不能在它們所裁判的提交中變更。
- 指令輸出、結束代碼、失敗步驟名稱和計數:必須按實際列印的內容報告。
- 戳記:必須報告您真正執行了什麼。永遠不要為您沒有執行的執行寫
e2e。 - 螢幕截圖和追蹤軌跡:必須按原樣附加或連結,而不是憑記憶描述。
方法
A. 驗證一項變更(每次)
-
說明「完成」的定義。 從使用者角度寫一兩句話:他們做什麼、他們看到什麼。如果儲存庫有功能映射表,找到該項目並使用其預期結果作為評分標準。如果您無法陳述「完成」,請在驗證前先詢問。
-
執行便宜的檢查。 建置、lint、型別檢查、快速測試。修復失敗。這是第一輪。
-
執行變更。 如果儲存庫有
verify技能(請在您修改的程式碼附近的.claude/skills/中尋找),請使用它。如果沒有,請自行啟動應用程式:- 網頁:透過瀏覽器驅動(Chrome 擴充功能、DevTools MCP、Playwright)。
- 行動裝置:透過行動 MCP 使用模擬器。
- 桌面:透過 Computer Use。
- 後端或 CLI:在本機執行服務或指令並呼叫它。
實際操作被變更的路徑,以及一個不應被變更的相鄰路徑。捕捉螢幕截圖、追蹤軌跡或輸出。
-
執行被觸發的檢查清單項目。 從基底分支讀取可靠性檢查清單。對每個項目,測試其觸發條件是否與您的 diff 匹配。對每個匹配的項目執行檢查並記錄結果。在您的報告中列出匹配項目的名稱。
-
添加缺少的測試。 使用上面的表格。確認新測試在沒有您的變更時會失敗,而加上變更後會通過。
-
計算輪次。 每個「執行檢查、修復、再次執行」是一個輪次。如果三輪後仍有檢查失敗,請停止。報告失敗內容、您每輪嘗試了什麼,以及您對原因的最佳猜測。
-
蓋上戳記並報告。 將戳記添加到提交訊息中(格式在
references/templates.md中)。在您的報告中提供:「完成」的定義、您執行了什麼、證據、匹配的檢查清單項目,以及任何未驗證的項目及其原因。
B. 建立驗證層(每個儲存庫一次,然後調校)
按順序執行這些步驟。每個步驟本身都很有用,所以可以在使用者想要的任何地方停止。
-
一個
verify技能。 將其放在.claude/skills/verify/中,盡可能靠近它所覆蓋的程式碼(monorepo 可以每個應用程式有一個)。它記錄如何啟動應用程式並進行冒煙測試。在信任它之前,連續執行數次:它必須快速且每次都給出相同的結果。 -
一個功能映射表。 從使用者的角度列出功能。對於每個功能:路徑、鍵盤快捷鍵、選擇器和預期結果。代理將其作為指南和評分標準。
-
為最重要的流程寫一個端到端測試。 然後在表格指出適用的地方加入屬性測試和差異測試。
-
一個可靠性檢查清單。 每個項目包含三個部分:一個可以從 diff 讀取的觸發條件、一個檢查,以及導致該項目的安全事故或 PR。沒有事故,就沒有項目。範例:觸發條件「session 儲存或訊息類型變更」,檢查「新欄位是否能從沒有該欄位的舊轉錄中安全載入?」。
-
一個 REVIEW.md。 它告訴審查者在此程式碼庫中應注意什麼。在幾輪審查中調校這個單一審查者,每一輪都基於上一輪的發現。不要在頂部堆疊更多審查者。程式碼擁有者不斷改進它,直到它能標記出他們會標記的內容。
-
本地強制執行。 一個在代理完成時執行測試的鉤子,或一個要求測試套件通過的目標。
-
一個提交閘道。 當 session 沒有執行任何審查或驗證步驟時,它會阻止提交。以三種模式推出:
模式 行為 off無作用 observe記錄它會阻止的內容。先執行此模式以找出誤報。 enforce阻止提交。提交可以附帶一個跳過的書面理由。在同一個 session 中被阻止兩次後,下一個提交會通過,以免代理卡住。
在添加鉤子、閘道或 CI 變更之前先詢問使用者。它們會改變每個人提交的方式。
C. 將遺漏轉化為規則
當一個錯誤通過了測試或審查時使用此方法。
- 找出模式,而非錯誤。 查看人類的審查意見和還原提交。一個候選規則必須至少在兩個 PR 中出現,並且只需從 diff 就能看出。
- 嘗試反駁它。 執行三次獨立的嘗試來證明該規則是錯誤的、太寬泛或已被涵蓋。如果有子代理可用,請使用三個。只有當規則通過考驗時才保留它。
- 檢查它是否是可捕捉的。 透過三個獨立的錯誤查找器重新播放導致事故的 PR。如果有兩個或更多找到了該錯誤,則它是可檢測的,並且在小 diff 上的遺漏應該變成 REVIEW.md 規則或檢查清單項目。
- 讓人類批准它。 程式碼擁有者決定規則是否放入。您提議;他們批准。
- 為審查者評分。 保留一組小型的案例集,每個案例都有一個一句話的答案關鍵,以及大小相似、已合併的乾淨變更作為對照組,以防止過度標記。保留一個調校集和一個獨立的測試集。將發現標記為
重要、吹毛求疵或預先存在。當更多召回率只能 fitting 評估集時,停止調校。 - 修剪。 測試套件、檢查清單和
.md規則檔案只會增長,除非有人刪減它們。定期移除從未觸發的規則、與其他規則重複的規則,或保護已不存在的程式碼的規則。
操作範例
請求:「為聊天 sessions 添加一個 pinned 標記,以便已釘選的 session 排在前面。」
沒有使用此技能:
將
pinned添加到 session 型別並更新了排序。單元測試通過。完成。
使用此技能:
完成的定義: 使用者在側邊欄釘選一個 session,它會移到頂端;重新啟動後它仍然在頂端。
已執行: 建置、lint、148 個單元測試(第 1 輪:排序比較器失敗 2 個,已修復;第 2 輪:全部通過)。使用儲存庫的
verify技能啟動應用程式,釘選了一個 session,重新啟動,確認了順序。已附加螢幕截圖。匹配的檢查清單項目(共 31 項中的 2 項):
- Session 格式變更需能載入舊資料:開啟了在此變更前儲存的 session 檔案。它崩潰了:
pinned為undefined,比較器拋出異常。透過在載入時預設為false修復。第 3 輪:通過。- 排序變更需保持穩定順序:未釘選的 session 保持其先前的順序。通過。
已添加: 一個屬性測試,「排序兩次等於排序一次」,以及一個端到端步驟,用於釘選、重新啟動、檢查順序。兩者都在沒有修復的情況下失敗。
未驗證: 行動版佈局。此機器上無模擬器。
戳記:
Verified-By: run, e2e, property, checklist(2)
單元測試通過了,但應用程式在每個現有使用者的資料上崩潰。執行變更並使用舊檔案才是找到問題的方法,而檢查清單項目則是告訴您應該嘗試這樣做。
交付前的自我檢查
- 您的報告中有一行從使用者角度撰寫的「完成的定義」。
- 應用程式已啟動並實際操作了被變更的路徑,或者報告中說明了「未執行」及其原因。
git diff <base>顯示未編輯現有的測試、lint 設定、檢查清單、REVIEW.md 或閘道設定。如果有編輯,則該編輯已被特別說明,並位於其自己的提交中。- 未添加
.skip、.only、xit、sleep、retry或提高的超時時間來使測試通過(請搜尋 diff 中的每個項目)。 - 您匹配的檢查清單項目已按名稱列出,並附有每個項目的結果。
- 每個新測試都已確認在沒有變更的情況下會失敗。
- 輪次計數為三或更少。如果第三輪仍然失敗,報告會移交給人類,且您並未提交。
- 提交訊息中有一個
Verified-By:戳記,且其中的每個單詞都與您實際執行的內容匹配。 - 證據是在當前的
HEAD上收集的,而不是在較早的提交上。 - 每個新的檢查清單項目或規則都帶有導致其產生的安全事故或 PR 名稱。