驗證手段（hook / lint / CI / review / spiral / test / production observation）有不同的「錯誤偵測粒度」、必須跟錯誤的層次對齊：

「攔截」這個動作預設已經知道錯誤的形狀（hook 寫死規則 = 已知錯誤）。真正會出錯的是「不知道形狀」的錯誤 — 那需要多輪 review / spiral 收斂、不是即時攔截。

為什麼 hook 對行為錯誤無能為力

Hook / lint / type checker 的本質是 字串匹配 / structural check — 看得到形狀、看不到意圖。所以：

• 抓得到「commit message 沒含 issue 號」 — 字面 pattern
• 抓得到「test file 沒對應 source file」 — 結構檢查
• 抓得到「YAML frontmatter 缺欄位」 — schema check
• 抓不到「這個推薦不夠明確、騎牆」 — 需要理解語意
• 抓不到「決策 collapse 到 yes/no、漏五維」 — 需要判斷意圖
• 抓不到「思考路徑跳過 RED phase」 — 需要追溯 reasoning
• 抓不到「過度疊加策略、超過必要」 — 需要 judgment

Hook 試圖用字串規則模擬語意檢查 = 規則永遠 over-fit 或 under-fit：寫太嚴 → 大量 false positive 把好的也擋掉、寫太鬆 → 行為錯誤照樣通過。

反模式：用 hook 蓋行為錯誤的代價

False confidence 比沒保護更危險

寫了 hook 之後、心理上會覺得「有保護」。實際上 hook 只擋字面、行為錯誤照常發生 — 但作者不再警覺、因為「CI 通過了應該沒事」。

對比沒 hook 的情境：作者知道沒保護、會主動多看一次。

第二行是最危險的組合 — 加 hook 卻不知道 hook 範圍、會比沒 hook 更糟。

規則膨脹：嘗試「再寫一條 hook」永遠補不完

每次行為錯誤通過、直覺反應是「再加一條 hook 規則」。但行為錯誤的形狀是無限的、規則永遠補不完。最終結果：

• 規則越來越多、越來越複雜
• 維護成本爆炸
• 仍然漏接行為錯誤
• 還產生越來越多 false positive 把好的擋掉

→ 規則膨脹是「用錯工具」的訊號、不是「規則寫得不夠細」的訊號。

多輪精煉的設計：spiral 取代攔截

行為錯誤的正確驗證手段是 multi-pass spiral：

1第 1 輪：先做、看結果
2   ↓ 發現 N 個問題
3第 2 輪：依結果調整 / 補強
4   ↓ 發現 N-k 個問題
5第 3 輪：dogfood / 實際使用 / 反向自查
6   ↓ 收斂
7（沒新問題 → 結束、有新問題 → 繼續迭代）

關鍵設計：不是「攔截錯誤」、是「設計每輪能 catch 不同層的錯誤」。

各輪的職責分工

每輪解上一輪沒看到的問題、不是重複同一檢查。

不同輪適合不同的「不對齊」

• 第 1 輪 vs 需求 → 看「做出來的跟要的對不對齊」
• 第 2 輪 vs 邊界 case → 看「漏哪些情境」
• 第 3 輪 vs 真實使用 → 看「用起來感覺對不對」
• 第 N 輪 vs 上層原則 → 看「有沒有違反某個 meta-原則」

每輪有不同的角度、新角度才能 catch 上一輪 miss 的東西。

何時 hook 真的足夠

某些情境純字面就夠、加 hook 是對的：

五類共通：錯誤形狀完全字面、且漏掉成本高 / 字面就是 evidence。其他情境 hook 都會在某個時點走到 ceiling。

識別 ceiling：什麼時候該換手段

ceiling 訊號：

看到任一訊號、不是「再寫一條 hook」、是接受 hook 對這個錯誤層次無能為力、改設計 multi-pass review。

跟其他抽象層原則的關係

本卡是 #72 的 sibling / 補強 — #72 推 L3-L5 結構性對策最強、本卡指出 L5 也有 ceiling、不是萬能。組合解：字面用 L5 hook、行為用 L4 pair + multi-pass。#124 進一步把行為層細分出 emergence 子類、補上對應 enforcement 時機。

套用到本系統的 case

Case 1：卡片系統本身

mdtools fmt --fix 是 hook（字面）— 處理 frontmatter、table 對齊、檔名 slug。 卡片內容對不對、抽 meta 抽得對不對 = 行為錯誤 — 靠 spiral 浮現（#81）、不靠 hook。

Case 2：搜尋頁 bug

CI 跑 playwright = 字面測試（給定輸入、output 是否符合）。 但「filter mode 切換有沒有 silent failure」這個 bug 一開始連 test case 都沒列、是 user 回報才浮現 — multi-pass dogfood 才 catch 到。

Case 3：決策對話 collapse

Hook 寫不出「這個回應 collapse 到 yes/no」的規則（語意理解）。 靠 reference 的 self-check + dogfood 例子 + 對話中 user 反饋的 multi-pass 才能 catch。

每個 case 都驗證同一條：字面層工具有用、但 ceiling 明確；行為層需要 multi-pass、不靠攔截。

判讀徵兆

核心：驗證手段的 ROI = 跟錯誤層次對齊 × 不超出 ceiling。Hook 不會思考、所以只能擋字面；行為錯誤需要 multi-pass spiral、用每輪不同角度收斂、不靠單次攔截。試圖用 hook 蓋 spiral 該做的工作 = 假裝有保護、實際比沒保護更危險。

寫 vendor article 時、常見以下 claim 形態：

• 「Vendor X 不支援 Y」
• 「Vendor X 最多 Z」
• 「Vendor X 預設 W」

這些 claim 在寫作那刻是真的、但 vendor 持續演進。寫作後 N 個月 — 6 個月、12 個月、24 個月 — claim 可能反轉、整段 audit 邏輯 invalidates。

問題不只是 claim 過時、是 基於 claim 的整段流程被推翻。Migration playbook Phase 1 audit 如果以「Vendor 不支援 X」為前提、X 後來變支援、Phase 1 整段重寫。

Case：PlanetScale FK claim 反轉

寫 migrate-to-planetscale.md 跟 migrate-vitess-to-planetscale.md 時：

• Claim：「PlanetScale 不支援 Foreign Key（Vitess 限制）」
• 基於此 claim：Phase 1 audit 整段「FK audit + 全 drop FK + application enforcement 改寫」
• Phase 1 是 weeks-months 工作量、第一個 phase

實際狀態（4-reviewer C audit catch）：

• Vitess 18（2023 末）加 FK 支援
• PlanetScale 2024 起在合適 plan 內可啟用 FK
• 「不支援」是 2022 年的事實、寫作時已過時

修法：整段 Phase 1 audit 從「FK audit + drop」改寫成「FK 行為驗證 + cross-shard cascade 處理」。

這不是 微調文字、是 整段 framing 重做。

機制：為什麼會發生

1. LLM training cutoff vs vendor changelog 速度差

LLM training data 有 cutoff date（通常滯後 12-18 個月）。Vendor major feature release 在 cutoff 後、LLM 不知道。

寫 vendor article 時、LLM 預設用 training 內的 latest fact — 那個 fact 可能已過時。

2. LLM 預設不標 claim 的時間性

LLM 寫「PlanetScale 不支援 FK」、不會自動標「as of 2022」、讀者看到 永久性 claim。

LLM 不會主動 verify「我寫的這個 claim 是 N 個月內仍 valid 的嗎」、除非寫作流程強制 verify step。

3. 基於 claim 的整段流程是「結構性 anchor」

Migration playbook 的 Phase 1 是 結構錨點 — 後續 Phase 2-4 都 reference Phase 1 結果。Phase 1 基於過時 claim 時、修法不只是 claim、是 整個 anchor 重做。

這比修 isolated fact 工作量大 10x — 是「invalidates premise」、不是「fix typo」。

4. Vendor article 多用 永久性語氣 而非 時間性語氣

寫作習慣寫「PlanetScale 不支援 FK」（永久性）、不寫「PlanetScale 截至 2022 末不支援 FK」（時間性）。

讀者讀到的是 當前永久狀態、寫作者其實只能保證 寫作那刻。

修法

1. 每篇 vendor article 標 Last verified date

frontmatter 或開頭加：

1last_verified: 2026-05-19
2verified_against:
3  - PlanetScale docs（2026-05 access）
4  - Vitess 18.0 release notes

讓讀者看到 寫作時 verify 的 source / date、不假設永久性。

2. Feature limitation claim 加時間註

寫「Vendor X 不支援 Y」時、加 as of N：

1PlanetScale 截至 2024 末有限支援 FK（Vitess 18+、需明確啟用）

而非：

1PlanetScale 不支援 FK

3. Claim 反轉 → 整段 audit 重寫、不是 patch

當 verify 發現 claim 已反轉（如 PlanetScale FK 從不支援變支援）、不要 只改 claim 字句。回頭看 基於該 claim 的流程段落 —

• Migration Phase 1 audit
• 「何時不要遷」反向 recommendation
• 「跟 sibling vendor 對比」表

每段都要 重看是否還成立、不成立的整段重寫。

4. Vendor article 寫作前先 verify 主要 claim

寫作流程加 verify checkpoint：

• 列出該 article 的「Vendor X 不支援 Y / 最多 Z / 預設 W」claim
• 對每個 claim、查 vendor official docs（最新 docs）/ recent release note（過去 12 個月）
• 不確定的標 uncertain、不要 confidence-fake

5. Reviewer C 必查 vendor feature time-sensitive claim

跑 4-reviewer audit 時、Reviewer C（技術準確性）必須：

• 對每個 feature limitation claim、verify 是否仍 current
• 對每個 vendor CLI command、verify 是否真實存在（hallucinated CLI 是 sibling 問題）
• 對每個 vendor default value、verify 是否最新

Hallucination 鄰近議題

LLM 寫 vendor CLI command 容易 hallucinate（例如 pscale database promote-shadow、vtctldclient PartitionTablet）— 命令不存在、是 LLM 編造。

跟本卡時間敏感性 不完全相同 —

• 時間敏感性：claim 寫作時 valid、現在過時
• Hallucination：claim 寫作時也 invalid、是編造

兩者修法部分重疊：

• 寫前 verify（claim + CLI）
• Reviewer C audit
• 不確定標 uncertain

但 hallucination 是 更基本的 verify failure、本卡聚焦時間敏感性。

跟既有原則的關係

• Sibling Coverage Asymmetry Blindspot in Priority：本卡是 claim 時間敏感性、那卡是 coverage 對稱性、不同 axis
• Data Topology as Audit Dimension：本卡是 寫作 audit 應加時間維度、那卡是 content audit 應加 topology 維度

反向驗證

不該誤用本卡：

• 穩定 fact（SQL syntax / RFC standard / industry-wide convention）不必標時間性、只有 vendor-specific evolving feature 才需要
• 不是每個 claim 都要 verify — 「MySQL replication 用 binlog」是穩定 fact、不必加 as of N
• 過度標 as of N 會讓 article 變 verbose、只對 limitation claim 跟 vendor-specific behavior 套用

觸發再評估

未來累積到以下情境、本卡應 review：

• 連續 2 個 batch 都踩 hallucinated CLI（trigger 升級到強制 寫前 CLI verify）
• Feature claim 反轉 invalidates 整段流程的 case 超過 3 次（trigger 把 vendor article 改成 每 N 個月 re-verify 紀律）
• LLM training cutoff 跟 vendor changelog 速度差變更大（trigger 升級 verify cadence）

官方文件查核放過的五類落差

content/cli/ 五類終端機工具文章（監控 / 圖表 / 多工器 / 檔案管理 / SQL 客戶端）在實機驗證時抓到、純靠 docs 查核會放過的落差：

1. 旗標改名

zellij web 文件寫有 --bind，實際 0.43.1 是分開的 --ip 與 --port。讀者照文件下指令會得到 unknown flag error、但不知道正確旗標是什麼。

2. 設定鍵 migrate

lazygit 的 pager 設定文件寫 git.paging.pager，新版 0.62.2 改成 git.pagers（list）。舊鍵啟動時會被自動 migrate、改寫設定檔 — 讀者照舊文件設定後發現設定檔被工具自己改掉。

3. 隱含 schema prefix

dblab 的查詢編輯器要 schema 限定（SELECT * FROM public.products），裸 products 會報 relation 不存在。原因是編輯器連線的 search_path 不含 public — 文件沒提。

4. 平台特定 segfault

nvtop 在 Apple Silicon mac 裝得起來，但 snapshot 模式直接 segfault。GPU 後端不穩。裝成功不代表能用 — 文件只說「支援 macOS」。

5. Driver 差異

同一個 Postgres，lazysql（Go pq driver）連無 SSL 的 DB 要 ?sslmode=disable，pgcli / harlequin（Python psycopg）不用。同樣的連線字串在不同工具會有不同行為、文件各自不提對方。

共通模式

這五類落差有個共通點：讀者照文件走會撞牆、卻在文件裡找不到答案。實機跑一次就現形，而且現形的正是文章最該寫的內容 — gotcha 段落省下讀者各自撞一次的時間。

官方文件的 fact-check 只能驗證「文件說的是否正確」，驗不了「文件沒說的是否存在」。實機驗證補的是後者。

相關連結

• Verification-driven CLI skill（.claude/skills/verification-driven-cli/）— 操作步驟
• 終端機圖形化工具總覽 — 用此流程生產的工具文章
• #199 一篇文章只承擔一種功能 — 本文精簡的依據