Community程式設計與開發github.com

運作證明

在聲稱完成之前,證明變更確實有效。驅動真實表面,捕獲可重現的證據,並在缺少證明時關閉失敗。

運作證明 是什麼?

此技能是一個嚴格的守門員,用於判斷工作是否可以被視為「完成」。它強制要求:任何聲稱「完成」、「已修復」或「已上線」的變更,都必須附有可重現的證據,而這份證據必須來自於實際運行的系統(例如 API 回應、UI 螢幕截圖或日誌),而非僅是程式碼審查或理論推斷。它支援多種平台(如 Claude Code、Cursor、Codex),並提供明確的證據層級(「主張」低於「成品」低於「成品 + 反面案例」)。其核心機制是透過「報告模板」定義預期的接受標準,然後執行真實的驅動命令來收集原始輸出(如 `curl`、`npm run dev`、瀏覽器 DevTools),並特別要求先執行反面案例(證明變更前會失敗)作為基線。如果任何必需的關卡項目缺失,或證據並非來自實際的變更 diff,就會直接判定為「FAIL」而不通過。此技能特別適用於功能驗證、UI 佈局確認、資料流追蹤或合約實作,但不適用於純文件、純配置或理論性的概念驗證。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/fan56/skills/tree/main/public/proof-it-works

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

在你喜歡的 AI 中提問

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

說明文件

運作證明 是做什麼的?

此技能擁有一項決定權:工作是否可以稱為「完成」。這是一個嚴格的關卡,而非建議。

1. 核心法則:完成 = 已證明

  • 聲稱不是證據。只有第二個代理人可以檢查的可重現成品才算數。
  • 當第 6 節中任何必需的關卡項目缺失時,你不能說「完成」、「已修復」、「通過」或「已上線」。
  • 「應該可以運作」、「看起來正確」、「理論上沒問題」和「編譯通過」都不算是完成狀態。
  • 如果證明是不可能的,則聲明為 UNAVAILABLE/BLOCKED(第 7 節)——永遠不要宣告 PASS。書面的使用者豁免可以將 FAIL 關閉為 FAIL-WAIVED(第 7 節)。一個機器無法測試的維度可以保持為 PENDING USER 並在使用者批准後以 PASS-BY-USER 關閉(第 7 節)。這三種——FAIL-WAIVED、PENDING USER、PASS-BY-USER——是唯一非機器證據的退出方式;它們都不是 PASS。
  • 證據必須來自報告(第 3 節,Change ref)中指定的工作樹和變更提交;過時的成品無效。
  • 此技能僅對具有執行時期表面或設計交付成果的工作進行關卡檢查。對於該工作,其最低證據集(一個正面 + 一個反面)會取代(而非疊加)任何較輕的檢查。沒有執行時期表面的工作則不在範圍內,此技能會完全讓步。它不會覆蓋使用者已核准為最低限度的交付。

2. 證據等級

三個等級,嚴格排序:Claim(口頭或推理,零證據)< Artifact(來自此任務表面的真實原始成品檔案)< Artifact + reverse case。關卡只接受後兩種;某個項目需要哪一種等級,由所選設定檔的關卡項目決定,而非由全域規則決定。Claim 永遠無法支援 PASS,且沒有任何項目可以被標記為高於其實際等級。

3. 綁定 / 任務綁定

  • 在 report.md 頂部,逐字引用使用者請求中定義驗收目標的句子——諸如「將 X 改為 Y 並證明它」之類的指令也算;它不需要說明工作已完成。將其標記為 Acceptance target (user verbatim)。只有在請求完全沒有定義驗收目標(它從未說明「完成」應該是什麼樣子)時,才用一行文字說明,要求使用者陳述一個目標,然後停止——因為沒有什麼可以關卡檢查。第 2 節中的證據等級 Claim 是一個獨立的概念,並保留其名稱。
  • Change ref(報告標頭)= 包含待測試變更的提交——不是添加此報告的提交,也不一定是 HEAD。如果沒有 git,請使用 sha256 of changed files + file list 來取代雜湊值。提交報告後,HEAD 會向前移動;這是正常的,驗證者會根據 Change ref 而不是 HEAD 來判斷。
  • Working tree(報告標頭)是自由文字,不是一個雙值列舉,例如 tracked clean; .proof/ untracked。
  • 宣告此變更觸及的檔案/函式/路由/元件,取自目前的 diff。
  • 每個選定的設定檔必須至少有一個證據項目落在這個 diff 上(執行或檢查一個被觸及的路徑)。接觸不到 diff 中任何內容的證據 = FAIL,即使所有成品都存在。
  • DESIGN 基線必須有一個外部來源(第 6 節,proof-profiles.md);無法追溯的基線是 Claim,並使其關卡項目失敗。

4. 選擇證明設定檔

選擇其一行測試最符合使用者驗收目標句子的設定檔;一個任務可以同時是 DESIGN 和 FEATURE,並且必須同時滿足兩者。如果沒有設定檔符合,請用一行文字說明並停止——不要將設定檔強加在沒有執行時期表面的變更上。

設定檔一行測試詳細資訊
DESIGN你產生了一個規格、佈局、互動、架構或合約,必須被證明已實作,而不只是被提出。references/proof-profiles.md
FEATURE你改變了執行時期行為,必須證明它能運作且錯誤輸入會被拒絕。references/proof-profiles.md
DATAFLOW一個值跨越了多個階段(輸入、轉換、持久化、輸出)且每個跳轉都必須被證明。references/proof-profiles.md
  • 「我的設計是否被實作了」-> DESIGN。「這個功能是否運作」-> FEATURE。「資料去了哪裡 / 是否被持久化」-> DATAFLOW。

5. 執行流程

按順序執行。不要跳過或重新排序。

  1. 在儲存庫中建立 .proof/<task-name>/(使用簡短的 kebab-case 名稱)。一個成品在成為此處的檔案之前,不算是證明。
  2. 在收集證據之前,先在 report.md 中撰寫 3-7 條驗收斷言。使用 8 個欄位:id | assertion | expected | pass criterion (checkable) | changed path (file:function/route) | level required | evidence file | depends on。禁止使用「看起來正確」、「似乎沒問題」、「如預期運作」;請使用可檢查的條件,例如「HTTP 200 且 body.field X = Y」、「rect width = 120px」、「invalid token 返回 401」。
    • expected 是在收集任何證據之前填入的預測結果(例如 401 + BAD_CREDENTIALS、rect width 240px);FEATURE/DATAFLOW 必須在每一行填入,DESIGN 可以寫 n/a。在報告標頭中記錄註冊時間為 Expected registered (UTC): <時間>——預先註冊是自行宣告的;沒有雜湊或磁碟上的儀式。
    • expected 和 pass criterion 是同一條件的兩種表達(預測 vs 可判定的檢查)。它們不得衝突;衝突的行必須在收集之前修正。狀態僅由 pass criterion 對照 observed 決定。如果 observed 符合條件但偏離了 expected,則修正實作使其符合 expected 或將斷言標記為 FAIL——永遠不要將 expected 改寫為觀察到的值(第 8 節)。
    • 用斷言所執行的檔案/函式/路由來填寫 changed path;只有不執行任何程式碼路徑的 DESIGN 行可以寫 n/a。至少一個斷言必須執行在此 diff 中被更改的程式碼路徑並指明它;一個關於未觸及路徑的斷言不具有約束力。FEATURE/DATAFLOW 必須至少有一個非 n/a 的 changed path 儲存格;DESIGN 可以使用 n/a。
    • depends on = 以逗號分隔的先決條件 id(若無則空白),按拓撲排序收集。僅當先決條件的狀態為 PASS 或 PASS-BY-USER 時,才視為已滿足;如果為其他任何狀態,則下游行為 NOT RUN(第 7 節),且任何 NOT RUN 都會導致關卡 FAIL。depends on 圖必須是無環的——存在循環即為 FAIL。USER-JUDGMENT 行是葉節點:沒有任何行可以將 USER-JUDGMENT id 列在 depends on 中。
  3. 使用此機器上實際可用的命令來驅動真實表面(例如,用 npm run dev 啟動,用 curl -i -X POST http://localhost:3000/login -d '{"user":"a","pass":"wrong"}' 測試 API,用真實瀏覽器 + DevTools 測試 UI,用 tail -f 查看日誌)。將原始 stdout/stderr/回應/螢幕截圖儲存到編號檔案中(第 11 節)。raw = 捕獲的完整輸出,未經摘要、摘錄或重新排序;脫敏是在捕獲時應用的單次轉換,因此不會破壞「原始」的定義。在儲存檔案中將令牌/密碼/金鑰替換為 ***,並在證據索引以及每個貼上的原始區塊旁邊記錄 redacted: <欄位名稱> (N 次發生) 以及檔案的 sha256,以便審查者確認沒有進行捕獲後的編輯。永遠不要對斷言所依賴的狀態碼、錯誤碼或任何值進行脫敏。報告中留下的任何 <啟動命令> / <截圖工具> 樣式的佔位符 = FAIL;用你實際執行的確切命令替換它。
  4. 先執行反面案例。將「一個被改變的行為」定義為 diff 中每個新增或修改的分支(if/else、守衛檢查、驗證或新的路由);在報告中列出每一個,並在斷言表中為其提供一行。邊界情況是可判定的:相同的輸入在變更前的實作中被接受(或表現不同),而在變更後被拒絕(或正確表現)。透過重建原始狀態來捕獲變更前的基線——git stash、變更前提交的工作樹/檢出,或原始檔案的副本——在報告中說明是哪一種,對其執行完全相同的命令,並將結果儲存為 00-pre-change.log(第 11 節)。這個「顯示它在變更前會失敗」的階段是反面案例的基線,永遠不是一個終端 FAIL 斷言行(第 9 節)。然後,對於每個被改變的行為,執行一個反面案例(錯誤輸入、缺少權限、邊界值、移除的前置條件),並記錄它以預期的方式失敗。一個在變更前也失敗的壞案例不計算在內。如果該案例在變更後被接受,則測試不在真實路徑上;修正並重新收集。
  5. 資料流:在收集之前,在 report.md 中寫下一行預期的轉換(輸入形狀 -> 輸出形狀),並在每個跳轉處引用它。然後在每個跳轉處(輸入 -> 中間 -> 持久化 -> 輸出)捕獲一個真實樣本,並帶有相同的關聯 id。對於持久化,貼上真實的讀取查詢及其原始回傳值;重新列印你寫入的值不是快照。同時依照第 4 步 (00-pre-change.log) 捕獲反面案例的變更前基線:它必須顯示在變更前被拒絕的值到達了輸出。
  6. DESIGN 觀察到的值必須來自機械化捕獲的來源(計算後的樣式 JSON、getBoundingClientRect、DOM textContent、CDP 輸出)並儲存為檔案;不要用肉眼從螢幕截圖上讀取數字。基線必須給出數值公差(每邊 <=2px,每個通道 <=8);超過則為 FAIL。螢幕截圖僅供人眼審查,永遠不是數值來源。
  7. 根據 references/report-template.md 撰寫報告;複製它,不要發明一種格式。只保留與所選設定檔相關的部分,並完整刪除不適用的部分——刪除它們並不違反「複製它,不要發明一種格式」。
  8. 關卡判斷(第 6 節):僅當每個必需的項目都存在於所需的等級,每個非 USER-JUDGMENT 的斷言都是 PASS/PASS-BY-USER,至少一個斷言帶有機器判決,並且沒有 depends on 循環時,才為 PASS;否則為 FAIL、UNAVAILABLE/BLOCKED 或 PENDING USER(第 7 節)。Gate 和 Result 使用相同的列舉,並且必須相同。

6. 嚴格關卡(缺少任一項 = FAIL)

「完成」需要每個項目都被勾選。缺少檔案、缺少反面案例、真實路徑上的 Mock、或偏離 diff 的證據,無論敘述為何,都是 FAIL。

  • 完整性(沒有未知項目):報告說明了斷言總數 N,並為 N 個斷言中的每一個列出一個狀態。唯一合法的狀態是 PASS | FAIL | NOT RUN | UNAVAILABLE | BLOCKED | USER-JUDGMENT | PASS-BY-USER。空白狀態、此集合之外的狀態、或列出的計數與 N 不同,均為 FAIL。PASS 要求每個非 USER-JUDGMENT 的行都是 PASS/PASS-BY-USER,並且沒有 FAIL/NOT RUN/UNAVAILABLE/BLOCKED。
  • USER-JUDGMENT 僅對沒有可判定機器標準的維度合法。如果機器可以判斷該行,或者已經判斷過且條件不成立,則其狀態為該機器判決(PASS/FAIL)——永遠不是 USER-JUDGMENT。綁定到這個 diff 的斷言(第 3 節)永遠不能是 USER-JUDGMENT。報告中每個斷言都是 USER-JUDGMENT 會導致 PASS 條件空洞地成立,這種情況是 FAIL:至少有一個行必須帶有機器判決。經過機器測試但不符合標準 = FAIL,而不是 USER-JUDGMENT。
  • depends on 是一個 DAG:存在循環即為 FAIL。僅當先決條件為 PASS 或 PASS-BY-USER 時才被滿足;沒有行可以依賴於 USER-JUDGMENT 行,因此這種行是葉節點。
  • 全局:綁定成立(第 3 節),至少一個斷言綁定到 diff(第 5 節第 2 步);USER-JUDGMENT 行永遠不算 PASS,也永遠不會阻止另一個項目的 PASS。
設定檔最低證據集——全部必需
DESIGN(a) 附有外部來源的基線成品:預先存在的設計檔案 + 建立提交,或使用者的逐字訊息(包含/批准了它),或在任何實作檔案存在之前作為基線檔案落地的規格表,並附有固定的 meta 區塊(source_type、source_quote_or_path、captured_at_utc、sha256、baseline_method)並在落地時填寫完成;禁止從實作中逆向工程數值到基線中;(b) 在變更提交處的真實渲染螢幕截圖;(c) 對於每個範圍內的元素(範圍 = 設計交付物中指名的每個元素;列出排除的元素及其原因),比較大小、顏色、間距、文字、狀態,每個行引用基線值和機械化來源的觀察值,並在基線中說明數值公差(每邊 <=2px,每個通道 <=8);(d) 一個在公差邊界上的值(例如,對於 +/-2 的 240px 規格,使用 243px)的反面項目,並透過原始輸出顯示其不存在/不匹配;(e) 明確宣告規格差距:Interpretation(基線讀數在實作之前撰寫,僅添加定位/映射,從不與使用者值衝突)、Excluded(不存在基線值,逐字撰寫)、UNAVAILABLE(值存在但此處無法測量)——Excluded 和 UNAVAILABLE 放在單獨的報告章節中,不得遺漏;(f) >=1 個在 diff 上的證據項目。
FEATURE(a) 一個在變更提交處執行了變更程式碼路徑的真實驅動 I/O 記錄;(b) 每個變更行為一個反面案例,其無效輸入位於可判定邊界上(在變更前被接受/表現不同,在變更後被拒絕/正確),並由變更前基線 00-pre-change.log 和顯示正確拒絕的原始輸出支持——在變更前也失敗的案例不計算在內;(c) 記錄了確切的命令/動作和變更引用;(d) 每個斷言都對應到一個帶有已填寫 changed path 的檔案,且 >=1 個斷言執行了變更的路徑並指名了已變更的檔案/函式/路由;(e) 沒有替代該鏈的 mock/stub;(f) >=1 個在 diff 上的證據項目。
DATAFLOW(0) 在收集之前撰寫預期的轉換行(輸入形狀 -> 輸出形狀)並在每個跳轉處引用;(a) 每個跳轉處(輸入、中間、持久化、輸出)一個快照,帶有相同的關聯 id;(b) 持久化快照貼上從儲存庫讀取的實際讀取查詢 + 原始回傳值,而不是重新列印寫入的值;(c) >=1 個在 diff 上的證據項目。

7. 結果狀態

狀態規則
PASS所有關卡項目都存在於要求的等級,所有非 USER-JUDGMENT 的斷言都是 PASS/PASS-BY-USER,至少一個機器判決,無 depends on 循環,綁定成立。
FAIL任何一個關卡項目缺失、更低等級、一個斷言為 FAIL/NOT RUN/UNAVAILABLE/BLOCKED、依賴循環、或缺少機器判決。
UNAVAILABLE從這個任務表面無法機械化地產生證據——外部依賴項未使用、硬體測試平台無法存取、測試環境對超出當前機器範圍的變更來說是唯讀的。提供外部可行的替代方案(日誌提取、CDP 協定)。
BLOCKED證據原則上可機械化產生,但當前的變更前驅動命令執行失敗、環境狀態損毀、或者證明必須的某個工具缺失;修復環境後重試。
PENDING USER一個維度沒有機器可判定的測試(例如佈局中的校準僅基於主觀美學)。寫下你的推理以及你認為它符合規格的原因,然後請使用者以書面方式批准;使用者拒絕 = FAIL。
PASS-BY-USER使用者以書面方式批准了 PENDING USER 斷言。狀態列必須包含「PASS-BY-USER(使用者批准於 <UTC 時間戳記>)」。
FAIL-WAIVED使用者以書面方式豁免了一個 FAIL 斷言。狀態列必須包含「FAIL-WAIVED(使用者豁免於 <UTC 時間戳記>)」。除非使用者明確書面豁免,否則 FAIL 不是 PASS。
USER-JUDGMENT保留給一個評估行;其餘規則見第 6 節。
NOT RUN取決於一個先決斷言,而該斷言不是 PASS 或 PASS-BY-USER;此狀態在其他地方永遠不被允許。
  • 只有 PASS、FAIL-WAIVED(在使用者書面豁免之後)、PASS-BY-USER(在使用者書面批准之後)會導致關卡通行。使用者批准永不撤銷一個機器 FAIL;FAIL 需要使用者豁免才能提升為 FAIL-WAIVED。PASS 永遠不需要使用者輸入。
  • 當使用 PENDING USER 時,任務持有者被要求提供一份關於相關維度的書面批准或拒絕。在獲得使用者回覆之前,狀態保持為 PENDING USER。使用者將永遠是最終的審查者和決策者。

8. 正直規則

  1. expected 在收集任何證據之前註冊。如果 observed 符合 pass criterion 但偏離了 expected:修正實作以符合 expected,或將斷言標記為 FAIL。永遠不要將 expected 改寫為觀察到的值——這會破壞正直性,並且會使返回監督的審查者感到困惑。
  2. 卡片的唯一兩條 expected 生命線是:(a) 在收集之前修改它以反映需求變更,以及 (b) 由使用者以書面方式要求。系統發起的變更(「看起來 expected 是小了,我們調整一下」)是被禁止的。
  3. 再一次:如果你的實作有偏差,不要將 expected 設定為觀察到的值。修正實作或標記 FAIL。

9. 偏差與修復

  1. reduce 不是 pass:將一個 FAIL 行標記為 USER-JUDGMENT + 推理,或將其降低到更低的證據等級,不是合法的 PASS 路徑。如果一個行無法達到其要求的等級,它就是 FAIL。
  2. 無信號:不完整的證據集對評估者來說看起來就像一個遺漏的證據集。不要假設隱含的基線;檔案必須存在。
  3. 路徑失效:在變更提交處捕獲的證據在後續提交中失效。如果你提交了技能詮釋介入,然後移除了它,那麼詮釋介入捕獲的證據不再有效。重新執行。
  4. 無序依賴:違反拓撲順序產生暫時通過的結果,而在生產中失敗。depends on 是強制性的。
  5. 重新排序的位置:收集證據後插入斷言行(除了在寫作時未預見到的資料流轉換行,這些必須在報告中得到標記和解釋)會破壞「預先註冊」的保證——這樣做會使包含那行的整個報告失效;重新收集。
  6. 預測後遺失:如果你在收集之前寫下了 expected,但在報告中遺失了所有參考,那麼你不知道你預測了什麼。Expected registered (UTC) 標頭是你唯一能夠證明預先註冊的防衛。當你複製模板時,直接將其包含在內。
  7. 絕對路徑作為證據:證據檔案必須相對於 .proof/ 是相對路徑。它們是你的工作空間的一部分。將絕對路徑嵌入到 .proof/ 中會使其在不同環境中不可重現。

10. 複查 / 歷史

所有 .proof/ 項目必須被提交。當一個 .proof/ 目錄中存在多個項目時,這意味著該任務被證明多次,可能是在解決個別的資訊請求。始終參考最新的項目。項目 不得 被刪除,除非它們是為了解決特定請求而建立的,然後在任務完成後被刪除。每個 .proof/ 項目都對應於一個已解決的請求或一個最終的作業。

11. 證據索引

證據檔案(相對於 .proof/)來源命令擷取時間 (UTC)內容類型sha256

相關技能