Community程式設計與開發github.com

驗證層

在提交前證明 AI 代理的變更確實有效,並建立檢查機制讓後續驗證更便宜。會實際啟動應用程式執行變更,挑選最適合的測試類型(端到端、屬性、差異測試),僅執行 diff 觸發的可靠性檢查,在三輪修復失敗後移交給人類,為每個提交蓋上驗證方式的戳記,並將每次遺漏轉化為規則。同時也會在儲存庫中建立驗證層本身——包含 `verify` 技能、功能映射表、diff 觸發的可靠性檢查清單、REVIEW.md、提交門檻——並防止變更修改自己的裁判。

驗證層 是什麼?

這個驗證層技能為 AI 代理(如 Claude Code)提供了一個嚴謹的框架,用於證明任何程式碼變更在提交前確實有效,並隨著時間推移讓驗證過程更加可靠與便宜。其核心理念是將人類的職責從逐行審查 diff 轉變為定義「完成」的標準與審視證據,而代理的任務則是誠實地產生該等證據。該技能支援多種平台,包括網頁應用、後端 CLI、桌面程式(透過 Computer Use)及行動模擬器;測試策略則涵蓋端到端測試、屬性測試(使用 fast-check、Hypothesis 或 proptest)及差異測試,並根據變更性質選擇。驗證過程遵循嚴格的規則:**三輪修復後移交人類**,**變更永遠不能修改自己的裁判**(測試、lint 規則、檢查清單等),**僅執行 diff 觸發的檢查清單項目**,並**為每個提交蓋上誠實的驗證戳記**(即使只是 `none`)。若缺陷通過測試或審查,該技能會引導系統性地將該次遺漏轉化為規則,包含找出模式、嘗試反駁、確認可捕捉性,並獲得人類批准後才加入。文件中也提供了無驗證層與有驗證層操作的具體對比範例,展示如何避免「單元測試全過但應用程式在真實資料上崩潰」的情況。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kleenpulse/verification-layer/tree/main

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

在你喜歡的 AI 中提問

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

說明文件

驗證層:完成代表有證據

您在提交之前證明某項變更確實有效,並建立檢查機制讓下一次證明更便宜。人類的職責從逐行閱讀 diff 轉變為定義「完成」的標準及審視證據。您的任務是誠實地產生那些證據。

其原則來自 How the Claude Code team thinks about verification(Addy Osmani,2026 年 11 月)。references/templates.md 中的檔案格式是此技能自有的;該文章描述了實務做法,但沒有展示任何格式。

使用時機

  • 您完成了一項變更,正準備說「完成」或進行提交
  • 使用者問「這能用嗎?」、「請證明」或「請驗證這個」
  • 儲存庫沒有可重複的方式來啟動並冒煙測試該應用程式
  • 使用者想知道某個功能、重寫或遷移該寫哪些測試
  • 某次審查或測試套件遺漏了一個已影響使用者的錯誤,使用者希望下次能抓到它
  • 某個測試不穩定,有人想重試或跳過它
  • 使用者希望同時運行多個代理,但無法閱讀每個 diff

請勿用於: 逐行審查他人的 diff(那是審查,不是驗證)、僅一行文件的註解變更(無法執行任何內容)、或為了提高覆蓋率數字而增加測試。

核心原則

當證據說變更已完成時,它才算完成;而且變更永遠不得編輯自己的裁判。 「測試通過」是薄弱的證據,尤其是當同一個變更也寫了這些測試時。強有力的證據是實際運行的應用程式確實做了使用者要求的事,並且是由變更無法觸及的項目來檢查。

規則

  1. 執行變更。 啟動真正的應用程式並實際操作被變更的行為。這比單元測試更重要。一個全部通過的單元測試套件,但應用程式卻無法啟動,就是驗證失敗。
  2. 三輪,然後交給人類。 執行檢查、修復失敗、再次執行。如果三輪後仍有檢查失敗,停止並將證據移交給人類。不要開始第四輪。
  3. 絕不為了通過而削弱裁判。 在同一個要被裁判的變更中,不得編輯、跳過或刪除測試、lint 規則、檢查清單項目或 REVIEW.md 規則。如果裁判有誤,請說明原因,並在一個使用者批准的獨立提交中修改它。
  4. 從基底分支讀取裁判。 審查規則、檢查清單和閘道設定應來自預設分支,絕非來自正在測試的分支。
  5. 證據屬於一個提交。 對舊提交的驗證無法說明新提交的任何狀況。在進行任何新的編輯後,必須重新驗證或報告證據已過時。
  6. 先執行便宜的檢查,並且在本地執行。 測試、建置和 lint 應在 PR 開啟前完成,而不是佔用審查者的時間。
  7. 僅執行 diff 觸發的檢查清單項目。 通常會匹配 3 到 10 個項目。每次都執行全部項目會讓大家學會忽略清單。
  8. 為每個提交蓋上驗證方式的戳記,包括 none。 誠實的 none 之後可以被搜尋到。遺失的戳記則無法。
  9. 不穩定的測試就是一個錯誤。 不要跳過它、添加 sleep、或重試直到變綠。找到根本原因。如果找不到,刪除該測試並記錄原因。
  10. 要求人工介入的檢查必須說明原因。 「需要審查」不是理由。「變更了 session 檔案格式;舊的轉錄可能無法載入」才是。
  11. 每個遺漏都變成規則,而規則需要被修剪。 一個溜過去的錯誤代表驗證層有漏洞。用一個檢查來堵住它,並移除那些不再有存在價值的檢查。

該寫哪種測試

情境測試類型它證明什麼
使用者面向的流程(如果您只寫一個測試,就寫這個)端到端一個真實的使用者路徑從頭到尾都能運作。失敗時會顯示步驟、追蹤軌跡和螢幕截圖,而不只是「超時」。
解析器、編碼器、金錢、狀態機、任何有邊界案例的程式碼屬性(fast-check、Hypothesis、proptest)一個陳述句對數千個您沒想到的生成輸入都成立。
對已有功能的改寫、遷移或最佳化差異新舊實作對相同的輸入產生相同的輸出。

值得檢查的屬性:

屬性陳述句
往返編碼後再解碼,得到原始的內容
不變性某件事永遠成立(餘額永不為負)
冪等性執行兩次等於執行一次
等價性快速版本與一個緩慢但顯而易見是正確的版本匹配

對於差異測試:使用隨機或抽樣的真實輸入、標準化無關緊要的差異(空白、鍵值順序、時間戳記),並保留一份您已批准的差異清單。

緩慢的套件會被較少執行,因此覆蓋率會下降。保持每次編輯的迴圈快速,並將較重的測試移到提交之前。

必須保留的事項(不可觸碰)

  • 現有的測試、lint 規則、檢查清單項目、REVIEW.md 和閘道設定:絕對不能在它們所裁判的提交中變更。
  • 指令輸出、結束代碼、失敗步驟名稱和計數:必須按實際列印的內容報告。
  • 戳記:必須報告您真正執行了什麼。永遠不要為您沒有執行的執行寫 e2e。
  • 螢幕截圖和追蹤軌跡:必須按原樣附加或連結,而不是憑記憶描述。

方法

A. 驗證一項變更(每次)

  1. 說明「完成」的定義。 從使用者角度寫一兩句話:他們做什麼、他們看到什麼。如果儲存庫有功能映射表,找到該項目並使用其預期結果作為評分標準。如果您無法陳述「完成」,請在驗證前先詢問。

  2. 執行便宜的檢查。 建置、lint、型別檢查、快速測試。修復失敗。這是第一輪。

  3. 執行變更。 如果儲存庫有 verify 技能(請在您修改的程式碼附近的 .claude/skills/ 中尋找),請使用它。如果沒有,請自行啟動應用程式:

    • 網頁:透過瀏覽器驅動(Chrome 擴充功能、DevTools MCP、Playwright)。
    • 行動裝置:透過行動 MCP 使用模擬器。
    • 桌面:透過 Computer Use。
    • 後端或 CLI:在本機執行服務或指令並呼叫它。

    實際操作被變更的路徑,以及一個不應被變更的相鄰路徑。捕捉螢幕截圖、追蹤軌跡或輸出。

  4. 執行被觸發的檢查清單項目。 從基底分支讀取可靠性檢查清單。對每個項目,測試其觸發條件是否與您的 diff 匹配。對每個匹配的項目執行檢查並記錄結果。在您的報告中列出匹配項目的名稱。

  5. 添加缺少的測試。 使用上面的表格。確認新測試在沒有您的變更時會失敗,而加上變更後會通過。

  6. 計算輪次。 每個「執行檢查、修復、再次執行」是一個輪次。如果三輪後仍有檢查失敗,請停止。報告失敗內容、您每輪嘗試了什麼,以及您對原因的最佳猜測。

  7. 蓋上戳記並報告。 將戳記添加到提交訊息中(格式在 references/templates.md 中)。在您的報告中提供:「完成」的定義、您執行了什麼、證據、匹配的檢查清單項目,以及任何未驗證的項目及其原因。

B. 建立驗證層(每個儲存庫一次,然後調校)

按順序執行這些步驟。每個步驟本身都很有用,所以可以在使用者想要的任何地方停止。

  1. 一個 verify 技能。 將其放在 .claude/skills/verify/ 中,盡可能靠近它所覆蓋的程式碼(monorepo 可以每個應用程式有一個)。它記錄如何啟動應用程式並進行冒煙測試。在信任它之前,連續執行數次:它必須快速且每次都給出相同的結果。

  2. 一個功能映射表。 從使用者的角度列出功能。對於每個功能:路徑、鍵盤快捷鍵、選擇器和預期結果。代理將其作為指南和評分標準。

  3. 為最重要的流程寫一個端到端測試。 然後在表格指出適用的地方加入屬性測試和差異測試。

  4. 一個可靠性檢查清單。 每個項目包含三個部分:一個可以從 diff 讀取的觸發條件、一個檢查,以及導致該項目的安全事故或 PR。沒有事故,就沒有項目。範例:觸發條件「session 儲存或訊息類型變更」,檢查「新欄位是否能從沒有該欄位的舊轉錄中安全載入?」。

  5. 一個 REVIEW.md。 它告訴審查者在此程式碼庫中應注意什麼。在幾輪審查中調校這個單一審查者,每一輪都基於上一輪的發現。不要在頂部堆疊更多審查者。程式碼擁有者不斷改進它,直到它能標記出他們會標記的內容。

  6. 本地強制執行。 一個在代理完成時執行測試的鉤子,或一個要求測試套件通過的目標。

  7. 一個提交閘道。 當 session 沒有執行任何審查或驗證步驟時,它會阻止提交。以三種模式推出:

    模式行為
    off無作用
    observe記錄它會阻止的內容。先執行此模式以找出誤報。
    enforce阻止提交。提交可以附帶一個跳過的書面理由。在同一個 session 中被阻止兩次後,下一個提交會通過,以免代理卡住。

在添加鉤子、閘道或 CI 變更之前先詢問使用者。它們會改變每個人提交的方式。

C. 將遺漏轉化為規則

當一個錯誤通過了測試或審查時使用此方法。

  1. 找出模式,而非錯誤。 查看人類的審查意見和還原提交。一個候選規則必須至少在兩個 PR 中出現,並且只需從 diff 就能看出。
  2. 嘗試反駁它。 執行三次獨立的嘗試來證明該規則是錯誤的、太寬泛或已被涵蓋。如果有子代理可用,請使用三個。只有當規則通過考驗時才保留它。
  3. 檢查它是否是可捕捉的。 透過三個獨立的錯誤查找器重新播放導致事故的 PR。如果有兩個或更多找到了該錯誤,則它是可檢測的,並且在小 diff 上的遺漏應該變成 REVIEW.md 規則或檢查清單項目。
  4. 讓人類批准它。 程式碼擁有者決定規則是否放入。您提議;他們批准。
  5. 為審查者評分。 保留一組小型的案例集,每個案例都有一個一句話的答案關鍵,以及大小相似、已合併的乾淨變更作為對照組,以防止過度標記。保留一個調校集和一個獨立的測試集。將發現標記為 重要、吹毛求疵 或 預先存在。當更多召回率只能 fitting 評估集時,停止調校。
  6. 修剪。 測試套件、檢查清單和 .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)

單元測試通過了,但應用程式在每個現有使用者的資料上崩潰。執行變更並使用舊檔案才是找到問題的方法,而檢查清單項目則是告訴您應該嘗試這樣做。

交付前的自我檢查

  1. 您的報告中有一行從使用者角度撰寫的「完成的定義」。
  2. 應用程式已啟動並實際操作了被變更的路徑,或者報告中說明了「未執行」及其原因。
  3. git diff <base> 顯示未編輯現有的測試、lint 設定、檢查清單、REVIEW.md 或閘道設定。如果有編輯,則該編輯已被特別說明,並位於其自己的提交中。
  4. 未添加 .skip、.only、xit、sleep、retry 或提高的超時時間來使測試通過(請搜尋 diff 中的每個項目)。
  5. 您匹配的檢查清單項目已按名稱列出,並附有每個項目的結果。
  6. 每個新測試都已確認在沒有變更的情況下會失敗。
  7. 輪次計數為三或更少。如果第三輪仍然失敗,報告會移交給人類,且您並未提交。
  8. 提交訊息中有一個 Verified-By: 戳記,且其中的每個單詞都與您實際執行的內容匹配。
  9. 證據是在當前的 HEAD 上收集的,而不是在較早的提交上。
  10. 每個新的檢查清單項目或規則都帶有導致其產生的安全事故或 PR 名稱。

相關技能