視覺完成是「畫面看起來對」、功能完成是「使用者意圖真的被滿足」。 兩者在簡單情境下重合、在邊界情境下分裂。視覺完成出現得早（手動 happy path 一試就過）、功能完成需要刻意對照「使用者意圖完整集合」才看得出來。

寫程式時把「畫面對了」當成完工訊號 = 把驗收標準降到視覺層、漏掉「功能在邊界情境下是否還對」這層。

為什麼視覺驗收會早於功能驗收成立

驗收訊號的成本梯度

成本低的訊號出現早 → 容易誤判完工。

視覺驗收的盲區

視覺驗收只看「螢幕上呈現的」、不看「應該呈現但沒呈現的」。後者沒有視覺訊號 — 不會閃紅、不會報錯、只是「該有的東西沒出現」。

這個盲區包括：

• Filter 把該顯示的藏掉了（見 #55 Filter 與 Source 的層錯位）
• Pagination 漏抓了某幾頁
• Sort 漏了某類元素
• Async race condition 把舊資料留在畫面

共通點：錯誤的形式是「不該不在的不在」、不是「畫面壞了」。

多面向：四類「畫面對但功能漏」

面向 1：Filter / Sort / Count 跟 source 不同層

見 #55。視覺層 filter 套在分批 source 上、稀疏 case 顯露語意縫。

面向 2：Async race / 競態

1input.addEventListener('input', async () => {
2  const r = await search(input.value);
3  render(r);  // 慢的 query 後到、畫面是舊 query 的結果
4});

畫面有結果、看起來對、但對應的不是當前 query。

面向 3：Empty state / loading state 不分

1<div class="results">
2  {{ if results }}{{ for r }}{{ render r }}{{ end }}{{ end }}
3</div>

「還在 loading」跟「真的沒結果」共用同一個畫面 — 都是空。視覺對、功能上「使用者不知道狀態」。

面向 4：Form submit 後狀態回饋失真

1button.onclick = () => { saveData(); button.textContent = "Saved"; };

按了顯示 saved、但 saveData 是 async 還沒完成 / 失敗 — 畫面對、實際資料沒進 DB。

四個面向共用結構：動作有視覺回饋、但回饋的「時機」或「對象」跟「實際語意」對不上。

「畫面對」屬於哪個 checkpoint

驗收要分散在四個時點（寫之前 / 開發中 / ship 前 / ship 後）— 詳見 #68 驗收的時間軸：四個 checkpoint。

「畫面對」是 開發中 的視覺驗收訊號 — 用來判斷「邏輯有跑、UI 沒崩」。它不能取代：

• 寫之前的「意圖完整集列舉」
• Ship 前的「邊界 / 規模 case」
• Ship 後的「真實使用者紀錄」

把「畫面對」當完工 = 把開發中的中介訊號當終點訊號 = 跳過後三個 checkpoint。

跟 #42「2 次門檻」的關係

#42 2 次門檻 講「第 1 次成功是低資訊量訊號、第 2 次（同方向 / 同類）才是真訊號」。

「畫面對」就是 #42 在「驗收訊號」面向的應用：「畫面對了一次」是低資訊量訊號、跟「程式跑通一次」「測試過一次」是同類。它告訴你「至少不是完全壞的」、不告訴你「對了」。

把低資訊量訊號當完工 = 跨情境就是「同方向加碼到第 3 次」 — 都是「太早信任早期成功」的同個錯誤。

識別「視覺完成但功能未完成」的訊號

訊號 1：驗收靠「再點一下試試」

如果發現 bug 的方式是「我再操作一次就看出來了」 — 表示 happy path 過了、邊界 case 沒過。看到這個訊號要主動列邊界 case。

訊號 2：使用者描述的 bug 含「有時候」「偶爾」「我以為」

「有時候 load more 沒動」「我以為都篩過了」 — 這類語言反映的是「畫面跟意圖之間有縫、使用者用視覺驗收結果跟意圖對不上」。

訊號 3：實作時下意識覺得「先這樣、晚點補」

1// TODO: 處理 cache 跟 fresh 的合併
2const data = cached || fresh;

「晚點補」的部分通常就是視覺看不見的功能缺口。如果視覺驗收會過、TODO 會被忘記到 production。

訊號 4：測試只有 happy path 截圖

PR / commit 附的截圖只有「最常見的 case」 — 沒有「沒結果」「載入中」「失敗」「資料規模特別大 / 特別小」的截圖 → 驗收層級停在視覺。

設計取捨：怎麼把驗收從視覺升到功能

四種做法、不同情境合理。

A：寫之前列「使用者意圖的完整 case 集合」、實作後逐一對照

• 機制：開工前列 happy path / 邊界 case / 失敗 case 三類、實作完逐一檢查
• 選 A 的理由：把驗收標準從「能用」升到「對齊意圖」
• 代價：需要主動想 case、寫之前花時間

B：靠自動化測試（unit / e2e）覆蓋邊界

• 機制：每個 case 寫一個測試、CI 跑
• 跟 A 的取捨：B 持續性更好、但成本高、且測試是寫的人決定的、漏想 case 一樣會漏
• B 才合理的情境：大專案、團隊協作、回歸風險高

C：靠使用者回報

• 機制：先 ship、使用者反映再修
• 跟 A 的取捨：C 工程量最低、但 trust 損失高、bug 進 production 才被發現
• C 才合理的情境：原型期、使用者願意幫忙找 bug、易回滾

D：只做視覺驗收（反模式）

• 為什麼是反模式：把驗收標準降到視覺層、漏掉「功能跟意圖之間的縫」這層 — 而那層的失敗最常見也最貴
• 看起來吸引人的原因：成本最低、happy path 過了就 OK、不需要列邊界 case
• 實際發生的代價：silent 缺口累積、系統性使用者不信任、ship 後發現修起來比早期貴 N 倍（見 #68 瀑布原則）

判讀徵兆

核心原則：視覺驗收是必要、不是充分。功能驗收要對照「使用者意圖完整集合」、不只是「畫面對」。視覺對 + 意圖縫 = 比畫面壞更危險、因為它不會觸發任何訊號。

延伸到測試驗收：「測試 PASS」也是視覺訊號的同類 — 沒看過該測試 RED 過、不知道它有沒有 catch 能力。詳見 #69 Test-First：先看到 RED 才相信 GREEN。

驗收不是單一動作、是分散在四個時點的累積判斷。

每個 checkpoint 抓的失敗類型不同、跳過任一個 = 那類失敗會在更晚的 checkpoint 出現（或不出現、變成 silent bug）。

為什麼分散驗收、而不是集中

集中驗收的問題

「寫完一次驗收完整」這個想法看似省事、實際撞兩個牆：

1. 失敗類型不在同一時點：開發中發現的是邏輯 bug、ship 前發現的是整合 bug、ship 後發現的是 silent 缺口 — 用同一種驗收方法不能 catch 全部
2. 成本指數爆炸：到 ship 前才發現「需求理解錯」要重做整個 feature；到 ship 後才發現邏輯 bug 要熱修。早期 checkpoint 修一個 case 用 5 分鐘、ship 後修同個 case 用 5 小時

分散驗收 = 在每個 checkpoint catch 「該時點獨有的失敗類型」、累積成完整覆蓋。

早期 checkpoint 的槓桿

「寫之前」的成本最低（列清單 5 分鐘）但能 catch 最貴的失敗類型（需求理解錯 = 整個 feature 重做）。ROI 最高。

「Ship 後」的成本最高（使用者反映、需要熱修）但只能 catch 最罕見的失敗類型。ROI 最低。

實務上常常 collapse 成「寫的時候 + ship 後出問題才修」、跳過寫之前 / ship 前。這是把 ROI 倒過來。

四個 Checkpoint 各自驗收什麼

Checkpoint 1：寫之前

動作：列「使用者意圖完整集合」 — happy path、邊界 case、失敗 case、規模 case 各列幾條。

能 catch：

• 需求理解跟使用者意圖不同
• 邊界 case 從一開始就忘了想
• 規模 case 沒考慮（10 筆 vs 10 萬筆行為不同）
• 隱含假設沒攤開（「應該都會有 title」「永遠不會空」）

範例：寫 filter 之前列：「title 含 X、content 含 X、兩者都含、都不含、source 全空、source 全是、稀疏 case、密集 case」 — 8 個 case 寫之前看見、實作時主動處理。

Checkpoint 2：開發中

動作：寫一塊測一塊 — 單元跑通、視覺看一眼、邊改邊試。

能 catch：

• 邏輯錯誤（branch 寫錯、迴圈邊界錯）
• 視覺錯誤（layout 跑掉、樣式套錯）
• API 用錯（呼叫順序錯、參數錯）

不能 catch：

• 跨多個 case 的整合錯
• 規模相依失敗
• 競態 / async race
• 跨環境差異

Checkpoint 3：Ship 前

動作：E2E 跑邊界 / 規模 / 失敗 case。

能 catch：

• 跨 case 整合錯（filter 切換 + load more 互動）
• 規模相依（500 筆時 jank）
• 競態（快速切換 query 時）
• 真實環境 case（slow network、large data）

不能 catch：

• 罕見組合（特定 user pattern）
• 真實使用者意外行為
• 長尾邊界（千分之一機率的狀態）

這個 checkpoint 最常被跳過 — 因為設計 E2E case 成本高、要刻意製造規模 / 失敗 / 競態場景。但跳過 = ship 後才發現。

Checkpoint 4：Ship 後

動作：log monitor、error tracking、使用者行為紀錄。

能 catch：

• silent 缺口（沒人 report、log 看出來）
• 罕見組合
• 真實使用者意外行為
• 跨時間退化（穩定 vs 漸變）

特性：成本最高、反應最慢、只能 catch 前三個 checkpoint 都漏的失敗。價值在於「保底」、不是主力驗收。

為什麼 Ship 前 checkpoint 最常被跳過

四個 checkpoint 中、Ship 前是被跳過機率最高的一個。原因是結構性的、不是隨機的：

寫之前跟 Ship 後都是「被外部 / 別人推著」、有現成觸發；開發中是反射動作、不需要刻意。只有 Ship 前需要寫的人主動停下、設計 E2E case、執行 case — 沒有現成觸發、沒有便利路徑。

這正是 #67 寫作便利度跟意圖對齊反相關 在驗收動作上的應用：跟「便利路徑」對齊的 checkpoint 會被做、要「主動設計」的 checkpoint 會被跳。

修這個結構性偏差的方法：

• 把 Ship 前 case 設計列進開工前的「使用者意圖完整集合」（推到 Checkpoint 1、有便利路徑）
• 用 layout test / E2E test 把 case 固化（#15）— 寫一次、之後 CI 自動跑、不需要主動觸發
• 公司 / 團隊建立「Ship 前 checkpoint review」會議 — 把它變成外部驅動

為什麼 Checkpoint 1（寫之前）也常被跳過 — 同個結構性偏差

Checkpoint 1 跟 Ship 前 checkpoint 共享同一個結構性問題：沒有便利路徑、需要刻意停下來。

真實案例（這個 blog 的 search filter bug 修復）：

修 #55 層錯位 bug 時、跳過了 Checkpoint 1。直接從 bug 描述進策略選擇 + 實作。Phase 1-4 都做完、跑了 Playwright tests 過 4/4 — 看起來完工。

事後 retrospective Checkpoint 1（user 提醒「需求確認是該 skill 最重要功能之一」）才發現遺漏：

修完 bug + ship test = 表面完成。但 Checkpoint 1 本來該 catch 的 3 個 case 都漏到後期 retrospective 才被發現。Test 過 ≠ 對齊使用者完整意圖。

修這個結構性偏差的方法（同 Ship 前）：

• 把「列使用者意圖完整集」做成 checklist 模板、寫之前 5 分鐘填、外化成觸發
• 用 #21 visible 三問 強迫自己列出「使用者會看到的維度」
• 修 bug 不止修 bug、也檢視該 feature 的所有相關意圖維度

#69 Test-First 是 Checkpoint 2/3 的具體協議；本卡是 Checkpoint 1 + 為什麼前後兩個 checkpoint 都被結構性跳過的解釋。

更上位的「為什麼跳過」解釋見 #72 高 ROI 無外部觸發的工作會被結構性跳過 — 本卡的 Checkpoint 1 + Ship 前是 #72 在「驗收動作」面向的展現、修法（外化觸發到 PR template / CI / pair）對應 #72 的 L3-L5 對策。

瀑布原則：漏一層代價指數放大

漏掉一個 checkpoint 不是線性影響、是指數放大：

「Ship 後修 bug 多」不是「ship 後驗收做得好」、是「上游 checkpoint 沒做好把 bug 全推下來」 — 看起來在做事、實際在付出指數成本。

為什麼指數放大

每個 checkpoint 漏掉的失敗、進入下一個 checkpoint 時：

1. Context 已經消失：下一個 checkpoint 才發現時、寫的人可能已經在做其他事、要重建上下文
2. 依賴已經建立：別的代碼已經依賴這個有 bug 的 feature、改一處要連帶改五處
3. 使用者已經受影響：ship 後修還要處理使用者信任 / 資料一致性 / 通知

每多漏一層、上述三個因素都疊加、成本翻 N 倍而不是 +N。

防線概念：每個 checkpoint 是獨立防線

把驗收看成 defense in depth — 每個 checkpoint 是一道防線、漏掉一道下一道接住。但每道防線的修復成本不同、越上游越便宜。

跟 a11y 三道防線（#37 動態 focus / #38 aria-live / #39 native HTML）共骨：分散獨立防線比集中單一防線更穩、因為單點失效不會打穿全系統。

Checkpoint 之間的累積關係

每個 checkpoint 都該補前面的洞 — 不是等量分配、是優先填上游：

1[寫之前 ROI: 高]   抓需求 / 邊界 / 規模意圖
2       ↓ 漏掉的進入下一層
3[開發中 ROI: 中]   抓邏輯 / 視覺 / 單元
4       ↓ 漏掉的進入下一層
5[Ship 前 ROI: 中-低] 抓整合 / 規模 / 競態
6       ↓ 漏掉的進入下一層
7[Ship 後 ROI: 低]   抓罕見 / silent / 長尾

「Ship 後修 bug 多」= 上游 checkpoint 沒做好、不是「ship 後驗收做得好」。

跟其他原則的關係

跟 #42 2 次門檻

「畫面對一次」「測試過一次」「使用者沒反映一次」都是低資訊量訊號 — 對應「開發中 checkpoint 過了一次」。第 2 次（跨多個 case / 規模 / 時間）才是真訊號 — 對應「ship 前 checkpoint 也過了」。

#56 視覺完成 ≠ 功能完成 是這個關係在「視覺驗收」面向的應用。

跟 #67 寫作便利度跟意圖對齊反相關

寫之前 checkpoint 列「意圖完整集」 = 跟便利度脫鉤、強制看見意圖。跳過 = 接受被便利驅動。

跟 #56 視覺完成 ≠ 功能完成

「畫面對」是開發中 checkpoint 的訊號、不是終點訊號。把它當完工 = 跳過 ship 前 / ship 後 checkpoint。

不該套用本原則的情境

「驗收分散在四個時點」這條原則在 ship 給其他人的開發情境成立、但有合理例外：

四類共同特徵：「ship 後的失敗成本」≈ 0 — 因為沒有真實使用者、沒有信任損失、沒有累積技術債。本原則的瀑布原則建立在「漏一層代價指數放大」上、ship 後成本為 0 時自然不放大。

判讀：寫之前自問「失敗會不會影響別人」 — 否 → 本原則可放寬；是 → 本原則嚴格適用。

判讀徵兆

核心原則：驗收的價值在「分散在多個時點」、每個 checkpoint catch 不同類型的失敗。把驗收 collapse 成單一時點 = 接受該時點之外的失敗都 silent 通過。早期 checkpoint ROI 最高、跳過代價最大。

Checkpoint 2「開發中」+ Checkpoint 3「Ship 前」內部的具體協議：#69 Test-First：先看到 RED 才相信 GREEN — 寫測試 + 跑兩次（RED-buggy + GREEN-fixed）才能驗證測試本身有用。跳過 RED = 接受測試可能是壞的。

測試本身需要被驗證。 一個從沒看過 RED 的測試 = 未驗證的訊號、不是「會抓回歸的測試」。

驗證一個測試真的有用、需要看到兩個訊號：

1. RED：測試在「該失敗的版本」上失敗（buggy code → 紅）
2. GREEN：測試在「該通過的版本」上通過（fixed code → 綠）

只看過 GREEN = 不知道測試有沒有 catch 能力；只看過 RED = 不知道修復有沒有真的解問題。兩個都看到 = 測試 + 修復都被驗證。

跳過 RED 把驗收標準降到「測試跑得通」、漏掉「測試自己有沒有 bug」這層。

為什麼測試需要被驗證

測試是程式 about 程式、會有 bug

測試本身是程式碼、跟其他程式碼一樣會有 bug：

這五種都會讓「跑測試一次就 GREEN」是個假訊號 — 測試 pass 不代表測試 catch 到該 catch 的東西。

RED 是測試的「使用者驗收」

對使用者代碼、我們會用「驗收訊號」（功能跑得對）證明它有用。測試也需要驗收訊號。

「測試 catch 到 bug」這個能力的驗收訊號 = 「在有 bug 的代碼上失敗」。沒看過這個訊號就相信測試 = 跳過驗收。

對應 #42 2 次門檻：一次 GREEN 是低資訊量訊號、RED → GREEN 是 2 次跑（一次 fail 一次 pass）的高資訊量訊號。

多面向：四種情境的 RED-GREEN 應用

情境 1：修 bug

11. 先寫一個 test 重現 bug 為失敗 — 例：「filter 後 0 筆但 source 還有未載入時、應該顯示 explicit empty 而非 silent」
22. 跑測試 → RED（證明測試抓到 bug、bug 真的存在）
33. 修 code
44. 跑測試 → GREEN（證明修對了 + 測試會抓回歸）

跳過第 2 步 = 不知道測試會不會抓到、不知道 bug 真的有沒有。

情境 2：加 feature

11. 寫 acceptance test 描述新 feature 該有的行為
22. 跑測試 → RED（feature 還沒實作、應該 fail；如果 GREEN 就表示 feature 已經存在或測試太寬）
33. 實作 feature
44. 跑測試 → GREEN

加 feature 時跳過 RED 風險：feature 被誤以為實作但實際是 stub、或測試根本沒驗到 feature。

情境 3：Refactor

11. 確認當前測試 GREEN（baseline）
22. Refactor（不改 behavior）
33. 跑測試 → 仍 GREEN

Refactor 不需要 RED — 因為 behavior 沒變。如果 refactor 後變 RED、表示 refactor 改到了 behavior（變成隱性 bug）、要回頭看。

情境 4：偵錯（不確定 bug 是什麼）

11. 寫一個 test 嘗試重現問題
22. 跑測試 → 看是 RED 還是 GREEN：
3   - RED → 重現成功、現在可以著手修
4   - GREEN → 沒重現到 / 測試寫錯 / bug 在別處 → 重新理解 bug
53. 修
64. 跑測試 → GREEN

「看是 RED 還是 GREEN」這個動作本身是 debug 訊號 — 比單純猜根因有用。

「只看 GREEN 不看 RED」是反模式

反模式 1：修完才補測試（Test-after）

11. 修 bug code
22. 寫測試
33. 跑測試 → GREEN
44. ship

問題：測試從沒跑過 buggy code、不知道它能不能抓到 bug。未來 regression 進來、測試可能仍然 GREEN（測試本身有 bug）。

反模式 2：「快速跑一下測試」沒看訊號

11. 寫測試
22. 跑「應該 pass 吧」、不仔細看輸出
33. 看到 PASS → 安心

問題：可能測試 skip 了、可能測試 zero assertions、可能環境錯了。需要看「具體 catch 到什麼」、不只是「是否 PASS」。

反模式 3：測試 PASS 但 coverage 是 0

11. 寫測試 file
22. CI 跑、看到「all green」
33. 沒看 coverage report

問題：測試文件存在但實際沒 import / 沒執行、CI 報告 GREEN 是因為「沒 fail」不是「有 catch」。

不該套用本原則的情境

「先看 RED 再看 GREEN」原則在大多數情境成立、但有合理例外：

四類共同特徵：沒有「行為差異」可被測試 catch — 本原則建立在「測試該 catch 的事」上、沒事可 catch 時自然不適用。

跟其他抽象層原則的關係

本卡是把「測試這個動作本身」放進驗收體系：寫測試是動作、跑測試的訊號才是驗收。動作完成 ≠ 驗收完成。

對應的實作篇

把測試固化的實作 case 都該套用本卡：

• #11 playwright-early-in-loop — 第 2 次推理失敗切 playwright；切過去後寫的 evaluate query 跑 RED-GREEN 才驗證
• #15 layout-tests-with-playwright — 版型 debug 兩次以上寫測試固化；測試該先在「未修版型」跑 RED 才相信
• #23 verification-method-timing — 驗證方法選對之後、實際驗證需要 RED-GREEN

Retrospective 補驗證的協議

如果已經修完才寫測試（test-after）、可以 retrospectively 補 RED-GREEN 驗證：

 1# 1. Stash 現有變動 / 切到修前 commit
 2git stash
 3git checkout <pre-fix-commit>
 4
 5# 2. Cherry-pick 測試 commit（或手動複製 test files）
 6git cherry-pick <test-commit>
 7# 或：cp ../tests/foo.spec.ts tests/  # 複製測試檔過來
 8
 9# 3. Build + 跑測試
10make site && npm test
11# 預期：RED（測試抓到 bug）
12
13# 4. 切回 main / 修後版本
14git checkout main
15git stash pop
16
17# 5. 跑測試
18npm test
19# 預期：GREEN

兩次跑 + 兩個訊號（RED + GREEN）都對、測試才被驗證。Retrospective 補驗證 ≠ 不能補 — 比完全跳過 RED 好、比 test-first 弱。

協議已 codify 為 make verify-red-green PRE_FIX=<commit-sha>（見 Makefile）— 五步驟自動化、不需要每次手動 stash / checkout / build / restore。

Self-case：本卡誕生過程的 dogfooding 失敗

本卡是從一次真實的 dogfooding 失敗抽出來的。修 #55 Filter × Source 層錯位 bug 時、流程是：

1. 修 code（multi-index 策略）
2. 寫 4 個 Playwright tests
3. 跑測試 → 4/4 GREEN
4. 看起來完工

User 問「修改之前有先寫測試確保符合預測狀態嗎」— 才意識到沒走 RED。Retrospective 補驗證後發現：4 個測試只有 1 個真的 catch 到 bug、其他 3 個對 buggy code 也 PASS（placebo 測試）。

強化後（用 network-level + structural assertion 替換弱 invariant）：buggy code 上 1/4 PASS、3/4 FAIL。Fixed code 上 4/4 PASS。RED-GREEN 兩個訊號都看到、測試才真的驗證。

如果不做 retrospective、會帶著 3/4 placebo 測試 ship — 表面 4/4 GREEN、實際只有 1 個真的防回歸。「跑得通」≠「會 catch」這個區別、只有走過 RED 才知道。

跳過 RED 是 #72 高 ROI 無外部觸發的工作 在測試協議的展現 — 修法不是「下次記得」（L1 紀律會失敗）、是 make verify-red-green PRE_FIX=<sha>（L3 工具觸發）+ pre-commit hook 提醒（L3 結構觸發）。

判讀徵兆

核心原則：測試不是「跑得通就有用」、是「跑出該有的訊號才有用」。RED 是測試的驗收訊號、跳過 = 接受測試本身可能是壞的。RED → GREEN 兩次跑、才證明「測試真的會 catch + 修復真的解掉 bug」。