# Verification Discipline

> 驗證哲學——怎麼證明一件事真的對,而不是「看起來對」。用於任何需要驗收正確性的工作:期望值必須來自獨立來源、不信自報結果、對帳要精確(冷/暖成本分列)、估值不進門檻只收實測、工程障礙不得偽裝成驗證結論、「沒被用到的檢查」移除前先定性、分層回歸的時機、用「該有而沒有」的視角掃缺,以及逐項比對兩份產物時的錨點對齊/多維度/內容層等值/差異判讀原則。

- Skill: `poloplay0114/verification-discipline-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add poloplay0114/verification-discipline-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/poloplay0114/verification-discipline-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: poloplay0114 (https://skillmd.com/u/poloplay0114)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/poloplay0114/verification-discipline-2

---


# 驗證紀律(Verification Discipline)

## 什麼時候用

任何時候你要說「這個對了 / 通過了 / 沒問題」。驗證的敵人不是「明顯的錯」,是**看起來對的錯**——
自己驗自己、只驗做過的沒驗漏掉的、單一維度過了就宣稱全對。這技能講怎麼讓「對」是**證明出來的**,
不是**宣稱出來的**。

---

## 通用法則

### 法則 1:期望值必來自獨立來源(絕不用被驗者自己算的值)

驗證 = 拿產物的輸出跟**一個獨立的正確答案**比。那個答案**不能是被驗的東西自己產生的**——
否則就是「自己跟自己比」,永遠相等,證明了個寂寞(套套邏輯)。
- 正確答案的來源:權威發布的範例、人手算、另一個獨立實作、產物注入前就存在的原始基準。
- ✗ 用引擎算一次當「標準答案」,再用同一引擎算一次去對 → 假交叉。
- 若「正確答案」也要靠不可信的第二方,要求**兩方真獨立**(不同來源、沒互相抄)。

### 法則 2:不信自報的「我驗過了」

「我確認過沒問題」不是證據,**輸出才是證據**。宣稱通過前,實際跑驗證命令、貼出關鍵結果。
- 代理/工具說「real=0 / 全綠」→ 不照單全收,看它憑什麼這樣說(是真比對出來的,還是它自己講的)。
- 尤其是「一個環節自己給自己打分」的設計 → 預設不信,要有外部客觀關卡兜底。

### 法則 2.5:驗證對象=系統出口,不是中間物;報「系統對」不報「碼對」

「對」只有一種合法定義:**真入口進 → 系統完整跑 → 拿到使用者真正到手的那份出口物 → 對獨立基準零缺陷**。
- **pytest 綠 / 單元測綠 / 內部模組綠 / 中間檔(canonical/暫存)綠 = 手段,不構成任何「對」的宣稱。**
  它們證的是「碼的某層沒壞」,不是「系統跑出來的東西對」。
- **不准用「直接呼函式產出」代替真入口路徑**——函式產的 ≠ 系統產的;中間物對 ≠ 出口物對
  (出口常經下游步驟再變形,如反推的 delivered 檔由 來源保留步驟 重寫→可能與 canonical 不同)。
- **回報用語(硬規)**:「N 測綠」永遠不寫在結論位;結論位只准寫**「系統出口:X 份對 / Y 份不對」**。
  測試綠只能放「手段/佐證」位。把「碼綠」講成「系統對」= 假宣稱。
- 對應姊妹技能 **ui-station-delivery**:一個站是否「能用」看真使用者從入口走到終點,不是清單打勾;
  此處把同一原則推到「正確性」面——系統出口的正確性才算數。

### 法則 3:對帳要精確,數字對得上

驗收後做**對帳**:預期幾項、實得幾項、差在哪。
- 「基準 N + 新增 M = N+M」——加得起來才算數;對不上代表有東西沒被驗到或被吞掉。
- **★一次性成本與穩態成本分列,不得互相掩蓋**:含「首次建置/種快取」的流程,效能數字要**冷(含一次性
  成本)/ 暖(穩態)分開報、分開立基準**。拿暖批數字當唯一基準=把冷路徑的真實成本藏掉(換期/來源更新
  時冷路徑會真實發生);拿冷批總數嚇人=誤判穩態。兩條各自有各自的斷言。
- 「零差異」的「零」要能說清楚:是**每一格都比過都相等**,還是「沒看到紅字」?後者可能是根本沒比。
- **★基準一律報雙數字,別單報一數**:測試套件的「通過數」和「收集數(含跳過)」是**兩個不同指標**——
  單報一個數,下次拿另一個指標對帳就會出現假矛盾(如 collect 1391 減 passed 1382 = 9,看似漏 9 條、
  其實是拿 collect 減 passed)。定式:**永遠報「passed X + skipped Y(collect X+Y)」**,對帳時
  passed 對 passed、collect 對 collect,同指標相比才閉合。刪沒刪測試看 `git diff` 的 `-def test_`,
  別靠數字差反推。
- **★任何落進報告/任務描述/交接的套件數字,必標「哪個 commit 的定態」**:數字沒綁定 commit =
  漂移源。**重構/修正「進行中」的中途快照數字(還有紅、新測還沒全落、斷言改到一半)絕不落文件**——
  落了就會被下次對帳當基準,製造假矛盾(如「1416→1406,-10」實為記錄漂移:那 1406 是 E 重構中途
  某測試模組 還紅、7 條新測還沒全加時的快照,非 commit 定態;定態是 +7→1423/0-fail)。定式:
  寫數字就寫「<commit> 定態:passed X + skipped Y(collect X+Y)/fail Z」,中途數字要嘛不寫、
  要嘛明標「(重構中途快照,非定態)」。

### 法則 4:分層驗證,各層各司其職,不重複驗同一件事

驗證分層,一個保證只住一層:
- **快篩層**(秒級,每次改動):健康檢查 + 少數關鍵基準值抽查。
- **針對性層**(改什麼驗什麼):依相依追蹤,只驗被這次改動影響到的部分。
- **全量層**(慢、全面,只在合併/大關口跑,可排離峰):全部重驗。
日常改動走針對性層,**全量只在關口跑一次**——但關口一定要跑,別因為慢就跳過。
（此處講「每層各驗什麼正確性職責」;為什麼分層能省時間、成本怎麼算,見姊妹技能 **engineering-economy**
的「測試分層經濟學」。兩者是同一件事的正確性面與成本面,合起來讀才完整。)

### 法則 5:「該有而沒有」視角——掃缺,不只驗已做的

大多數驗證只檢查「做了的對不對」,漏掉「**該做而沒做的**」。主動問:
- 哪些情況**應該**被覆蓋卻沒有測試?哪些欄位/維度**應該**存在卻是空的?
- 哪些「應該自動處理」的東西其實漏接了?
把「什麼都沒發生」也當成一種要驗的結果——沉默不等於正確,可能是根本沒跑到。

### 法則 6:失敗模式永遠偏安全側

驗證判不準時,往「安全」倒,不往「方便」倒:
- 拿不準 → **當成沒過**(多查一次),不要「大概沒事」放行。
- 抽取/判斷不確定 → **交還給人**,不要自己猜一個填進去。
- 原則:多問一次人(煩但安全)恆優於自動做錯(省事但危險)。

### 法則 7:估值不進門檻,只收實測

門檻/驗收的判定**只認量出來的數**。估算可以報(幫助規劃),但必須明標「估、非實測」,且**不得**寫進
結論位、不得拿來宣稱門檻已達。「估 4.6 分鐘(達標)」不是達標——量出來 4.6 分鐘才是。估值一旦混進
門檻,下游所有以它為基礎的決策都建在沙上。

### 法則 8:工程障礙不得偽裝成驗證結論

驗證跑不完(OOM、環境掛、依賴壞)時,結論是「**門檻維持未過 + 一個待修工項**」——不是「被擋住所以
先算過」、也不是「轉成待裁」。障礙是工作,不是驗收結果;把「我遇到問題」講成「問題擋住了驗證所以
免驗」,是門檻在無聲鬆動的起點。修掉障礙、量出實數,門檻才動。

### 法則 9:「沒被用到的驗證」移除前,先定性「對的空」還是「漏的空」

發現某層檢查對某類產物空轉(檢查跑了但沒任何規則吃到它)時,別急著當「純浪費」移除。先定性:
- **對的空(by-design)**:該類產物有**更強的替代 oracle** 覆蓋同一風險(如逐位元一致性取代逐項啟發式)
  → 空是對的,移除是真省;但要能**指名那個替代 oracle 是誰、覆蓋到哪**。
- **漏的空(coverage hole)**:那層檢查空,是因為**當初根本沒為這類產物寫規則** → 「沒被用到」不是
  「不需要」,是本來就漏驗;此時移除=把洞一起封版。
- **判準**:該產物**會不會在那個維度變化**?會變而無人驗=漏;不變或有更強 oracle=對的空。
定性清楚之前,「純浪費」三個字不成立。

---

## 逐項比對兩份產物的原則(值對 ≠ 全對)

當「驗證」= 拿產出跟黃金基準逐格/逐項比對時,以下原則防「假綠」:

### 比對 1:錨點對齊,不靠絕對位置

用**穩定的複合鍵**對齊兩份(如「分頁名 + 欄標題 + 列鍵」),**不要用絕對行號/序號**——
上面插一列、順序換一下,絕對位置就全錯位,比出一堆假差異或假相等。同名要靠複合鍵區分,別只認名字。

### 比對 2:多維度,別讓單維度給你假綠

「值一樣」不代表「對」。一個格子有多個維度都要對:
- **值**對(算出來的數字) **≠** **公式/來源**對(是硬寫死的死值,還是活公式?) **≠** **格式**對
  (數字格式、樣式、邊框)。
- 只比值 → 可能公式被壓平成死值、格式跑掉,值卻剛好一樣 → 假綠。要比就多維度一起比。

### 比對 3:公式要保住「活性」,別讀成死值再比

比對含公式的產物時,別把公式**求值後**當內容比——那會把「活公式」和「同值的死值」看成相等,
放過「公式被壓平」這種真退化。要保留並比對公式本身(來源表達式),不是只比它這次算出的數。

### 比對 4:差異分流判讀——「零差異」的零怎麼判出來

比出差異時,分三類判讀,別一律當錯或一律放過:
- **真錯**:產物邏輯錯 → 修產物。
- **假影**:比對器自己的問題(對齊錯、維度沒覆蓋全、把可接受的格式差當差異)→ 修比對器。
- **可接受**:已知且無害的差異(如某來源本身的瑕疵照實反映)→ 標記接受,不是無聲忽略。
**先把比對器修到「完整可信」,再信它報的零**——不完整的比對器報「零差異」是假綜合,比不比一樣。

### 比對 5:等值只認「內容層」,巧合窗口的綠是假綠

- **等值門開在內容層**:兩份產物「相等」的判定,比的是**內容單位逐位元**(壓縮包=逐 part;文件=逐節點),
  不是整檔外殼。**容器級差異**(打包時間戳、壓縮參數)不是等值失敗——那是「可重現性」議題,另立另修
  (固定時間戳=可重現建置,加分項),別讓它污染等值判定,也別拿「外殼一致」冒充內容等值。
- **通過的原因必須是「內容相等」,不能是巧合**:曾有等值測試靠「兩次產出恰好落在同一個 2 秒時間戳
  bucket」而綠——換一天跑就紅。任何比對若存在「不相等也可能過」的巧合窗口,先把產出**確定性化**
  (固定一切非內容輸入),再比對;測試要附「巧合不可能」的論證,不然那個綠不算數。

---

## 本專案案發現場(佐證,非通用必需)

- **期望值獨立(法則 1)**:某財務報表自動化專案鐵則「積木算範例輸入 vs 範例**公布**答案 real=0,期望值來自
  真實來源、非 AI 生、非積木自算」;求值器「絕不用引擎跟引擎自己算的比」,真獨立第二方=注入前的
  Excel 原始快取(Excel 算的,非本引擎)。
- **不信自報(法則 2)**:三道客觀防線不靠「管理者看碼」(讀不懂=形式),靠 authority real=0 客觀鐵證;
  上網查證的 expected 必來自網頁 worked example,非重算。
- **對帳精確(法則 3)**:每批合併報「baseline 1341 + 31 新測 = 1372」;「逐格 0 差異」的零是拿成品
  逐格比對出來的,不是「沒看到紅」。
- **★對帳基準要當場重量,別憑上批記錄(元教訓)**:曾以文件記的舊 baseline 數對帳,結果差 2——不是
  混入異物,是**記錄漂移**(舊數比真值低 2)。教訓:**開批對帳前當場重新量基準**(如 `pytest
  --collect-only` 數當前測試數),別信「上次記的是多少」;記錄會 stale,現量才準。
- **分層回歸(法則 4)**:三層回歸(smoke/針對性/全配方大體檢),全套件只在合併關口/大體檢跑一次。
- **該有而沒有(法則 5)**:某定期大體檢專掃「全配方該有卻缺的零件」;曾掃出某工具函式漏登記——
  只提報不硬補,人確認。
- **比對器先修完整再信它(比對 4)**:曾因比對器不完整(只比有無、漏 font_color/欄錨點)→ 假綜合;
  教訓=先把比對器補到真完整(border 比樣式字串、加顏色、複合鍵欄錨點)再一次修完再信零。
- **公式保活性(比對 3)**:整批功能化時堅持公式不 data_only 壓平,反推檔逐格對成品才算,防「值對但
  公式退化成死值」。
- **估值被擋在門檻外(法則 7)**:一輪效能改造中,實作者交「暖批 ~4.6 分鐘(估)」欲收線;把關者擋:
  估的不進門檻,修完阻礙、真批量重測出實數才判。實作者同輪誠實標「是估、非實測,不當實績交」——正確姿態。
- **「唯一真阻」被歸位(法則 8)**:大檔記憶體尖峰把批量實測 OOM 殺掉兩次,回報一度寫成「唯一真阻=
  記憶體尖峰(擋住實測與基準寫入)」——被把關者攔:障礙是待修工項,門檻維持紅;治本(串流+磁碟點查)
  後同一頁零 OOM 跑完,實數才落。
- **empty 檢查定性(法則 9)**:某類逐位元照搬型產出的啟發式資料檢查層全空,一度被定性「純浪費、移除」;
  追問後定性為「對的空」——該類有更強 oracle(逐 part 位元一致 vs 基準)覆蓋同一風險,且指得出名;
  但同時挖出真正的洞(來源期別無人驗),兩件事分開處置,沒有一起被「浪費」二字帶走。
- **2 秒 bucket 假綠(比對 5)**:全檔雜湊等值測試曾靠「兩次寫出恰落同一時間戳 bucket」而綠;真批量
  重測時全檔雜湊不合、逐 part 比對卻證明 25 個 part 全部逐位元一致——差異純為打包時間戳。處置:
  等值門正名為 part 級(當場已達),另以固定時間戳做可重現建置(加分),實作者主動揭露假綠成因。