運作證明 是做什麼的?
此技能擁有一項決定權:工作是否可以稱為「完成」。這是一個嚴格的關卡,而非建議。
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. 執行流程
按順序執行。不要跳過或重新排序。
- 在儲存庫中建立
.proof/<task-name>/(使用簡短的 kebab-case 名稱)。一個成品在成為此處的檔案之前,不算是證明。 - 在收集證據之前,先在
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-JUDGMENTid 列在depends on中。
- 使用此機器上實際可用的命令來驅動真實表面(例如,用
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;用你實際執行的確切命令替換它。 - 先執行反面案例。將「一個被改變的行為」定義為 diff 中每個新增或修改的分支(if/else、守衛檢查、驗證或新的路由);在報告中列出每一個,並在斷言表中為其提供一行。邊界情況是可判定的:相同的輸入在變更前的實作中被接受(或表現不同),而在變更後被拒絕(或正確表現)。透過重建原始狀態來捕獲變更前的基線——
git stash、變更前提交的工作樹/檢出,或原始檔案的副本——在報告中說明是哪一種,對其執行完全相同的命令,並將結果儲存為00-pre-change.log(第 11 節)。這個「顯示它在變更前會失敗」的階段是反面案例的基線,永遠不是一個終端 FAIL 斷言行(第 9 節)。然後,對於每個被改變的行為,執行一個反面案例(錯誤輸入、缺少權限、邊界值、移除的前置條件),並記錄它以預期的方式失敗。一個在變更前也失敗的壞案例不計算在內。如果該案例在變更後被接受,則測試不在真實路徑上;修正並重新收集。 - 資料流:在收集之前,在
report.md中寫下一行預期的轉換(輸入形狀 -> 輸出形狀),並在每個跳轉處引用它。然後在每個跳轉處(輸入 -> 中間 -> 持久化 -> 輸出)捕獲一個真實樣本,並帶有相同的關聯 id。對於持久化,貼上真實的讀取查詢及其原始回傳值;重新列印你寫入的值不是快照。同時依照第 4 步 (00-pre-change.log) 捕獲反面案例的變更前基線:它必須顯示在變更前被拒絕的值到達了輸出。 - DESIGN 觀察到的值必須來自機械化捕獲的來源(計算後的樣式 JSON、
getBoundingClientRect、DOMtextContent、CDP 輸出)並儲存為檔案;不要用肉眼從螢幕截圖上讀取數字。基線必須給出數值公差(每邊 <=2px,每個通道 <=8);超過則為 FAIL。螢幕截圖僅供人眼審查,永遠不是數值來源。 - 根據 references/report-template.md 撰寫報告;複製它,不要發明一種格式。只保留與所選設定檔相關的部分,並完整刪除不適用的部分——刪除它們並不違反「複製它,不要發明一種格式」。
- 關卡判斷(第 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. 正直規則
expected在收集任何證據之前註冊。如果observed符合pass criterion但偏離了expected:修正實作以符合expected,或將斷言標記為 FAIL。永遠不要將expected改寫為觀察到的值——這會破壞正直性,並且會使返回監督的審查者感到困惑。- 卡片的唯一兩條
expected生命線是:(a) 在收集之前修改它以反映需求變更,以及 (b) 由使用者以書面方式要求。系統發起的變更(「看起來expected是小了,我們調整一下」)是被禁止的。 - 再一次:如果你的實作有偏差,不要將
expected設定為觀察到的值。修正實作或標記 FAIL。
9. 偏差與修復
reduce不是pass:將一個 FAIL 行標記為USER-JUDGMENT + 推理,或將其降低到更低的證據等級,不是合法的 PASS 路徑。如果一個行無法達到其要求的等級,它就是 FAIL。- 無信號:不完整的證據集對評估者來說看起來就像一個遺漏的證據集。不要假設隱含的基線;檔案必須存在。
- 路徑失效:在變更提交處捕獲的證據在後續提交中失效。如果你提交了技能詮釋介入,然後移除了它,那麼詮釋介入捕獲的證據不再有效。重新執行。
- 無序依賴:違反拓撲順序產生暫時通過的結果,而在生產中失敗。
depends on是強制性的。 - 重新排序的位置:收集證據後插入斷言行(除了在寫作時未預見到的資料流轉換行,這些必須在報告中得到標記和解釋)會破壞「預先註冊」的保證——這樣做會使包含那行的整個報告失效;重新收集。
- 預測後遺失:如果你在收集之前寫下了
expected,但在報告中遺失了所有參考,那麼你不知道你預測了什麼。Expected registered (UTC)標頭是你唯一能夠證明預先註冊的防衛。當你複製模板時,直接將其包含在內。 - 絕對路徑作為證據:證據檔案必須相對於
.proof/是相對路徑。它們是你的工作空間的一部分。將絕對路徑嵌入到.proof/中會使其在不同環境中不可重現。
10. 複查 / 歷史
所有 .proof/ 項目必須被提交。當一個 .proof/ 目錄中存在多個項目時,這意味著該任務被證明多次,可能是在解決個別的資訊請求。始終參考最新的項目。項目 不得 被刪除,除非它們是為了解決特定請求而建立的,然後在任務完成後被刪除。每個 .proof/ 項目都對應於一個已解決的請求或一個最終的作業。
11. 證據索引
證據檔案(相對於 .proof/) | 來源命令 | 擷取時間 (UTC) | 內容類型 | sha256 |
|---|