「X、不是 Y」這個句型在做兩件事：給結論 X、排除讀者直覺會想到的 Y。 兩者是同一個推理單元、一起出現才完整。為了滿足「正向陳述優先」而把 Y 直接刪掉、剩下的 X 就失去 contrast、變成沒依據的空降斷言。

情境

寫作規範要求「正向陳述優先」、AI 或作者批量改寫舊文時、為了滿足 grep 不是 / 不要 / 避免 等掃描規則、會把句子裡的否定詞機械式刪掉。但很多否定詞承擔的是 contrast 角色、不是冗餘 — 抽掉之後句子在語法上正向了、但語意上失去了推理依據。

具體例子（本 blog compositional-writing skill 的修正過程）：

1原文：拆分依據是**認知負擔與情境匹配度**、不是行數。
2改 1：拆分依據是**認知負擔與情境匹配度**（行數只是表象）。
3改 2：拆分依據是**認知負擔與情境匹配度**。

• 原文：給結論（認知負擔）+ 排除讀者直覺（行數）。Y = 行數是讀者最容易想到的替代答案、明確排除掉這條路才有意義。
• 改 1：把「不是 Y」軟化成「Y 只是表象」、但沒解釋為什麼是表象。讀者讀完不知道「行數為什麼不算依據」、結論依然空降、只是包裝成正向句。
• 改 2：直接刪、結論完全失去 contrast。

兩個改法都比原文差。

理想做法

正向改寫時、先判斷被刪掉的 Y 是哪一類：

Y 是讀者直覺會想到的替代方案 → 保留 contrast

讀者第一直覺會想到 Y、只給 X 不夠。處理方式有三：

1. 保留「X、不是 Y」原句（規則六精神：反例段落要有正向錨點、但反例本身仍存在）— 這不違反「正向陳述優先」、因為「正向陳述優先」要的是「主句承載結論、反例只做對照」、不是「全段沒有否定詞」。「X、不是 Y」這個句型主句仍是 X（正向陳述）、Y 是子句裡的 contrast、結構上符合規範
2. 補解釋：「X、因為 [推理]」 — 用 reasoning 接管 contrast 的角色
3. 升級成對照表：兩欄並列 X 跟 Y、讓 contrast 變結構化呈現、不靠句法

Y 是冗餘否定（讀者不會想到 Y） → 直接刪

例：「使用 LRU cache、不是普通 dict」— 若上下文沒有人會把 dict 當預設、Y 是冗餘、刪掉沒損失。

判別問題：「讀者讀到 X 之前、心裡最可能想到的答案是 Y 嗎？ 是 → 保留 contrast。否 → 安全刪。」

沒這樣做的麻煩

結論變空降斷言、讀者無法驗證

「行數只是表象」這種句子、讀者讀完只能選兩條路：

• 全盤接受（迷信權威）
• 自己腦補理由（每個讀者腦補不同、原則無法統一傳遞）

兩條都讓「教學」失效 — 教學的目的是讓讀者拿到 reasoning、能套用到新情境、不是讓讀者背規則。

規則崩潰：壓力下會回退到刪掉的 Y

機會成本語氣的核心 reasoning 是「絕對主義教讀者規則（壓力下會忘）、機會成本教讀者思考方式」。空降斷言是更糟的「規則」— 連「為什麼是規則」都沒給、讀者壓力下完全無錨點、會回退到自己的直覺（也就是被刪掉的 Y）。

批量改寫無法被 review

改寫成「（Y 只是表象）」「（Y 是次級訊號）」這類軟化措辭時、表面看起來完成正向化、實際上把問題藏起來 — 規範掃描器（grep 不是）不再 catch、人類 reviewer 也容易放過、議題在文章裡持續腐爛。

跟其他抽象層原則的關係

• #67 寫作便利度跟意圖對齊反相關：本卡是 #67 在「寫作規範執行」層的具體案例。批量正向化時、最便利的做法（grep + 機械刪否定詞）跟意圖對齊（保留推理鍊）反向 — 越容易執行、越容易產出空降斷言。
• #82 字面攔截 vs 行為精修：本卡是 #82 在「寫作規則」層的同形 pattern。grep 不是 / 不要 是字面層攔截、看不到那個「不是」承擔的是 contrast 還是冗餘 — 需要 behavioral pass（讀者能否驗證結論）。
• #83 寫作的 multi-pass review：本卡補強 #83 的 frame 設計 — 「正向陳述」這輪掃完之後、要再加一輪「結論可驗證性」掃描、確認被改的句子仍然有推理依據。
• compositional-writing 規則六（反例段落用正向陳述）：規則六說「反例段落要有正向概念當錨點」、本卡補規則六沒覆蓋的反向 case — 正向句也可能因為刪掉對照而失去依據。兩條互補：規則六防止「只有反例沒有錨點」、本卡防止「只有錨點沒有對照」。

判讀徵兆

當你寫下或審閱以下句型時、停下來檢查：

適用範圍與邊界

• 適用：寫作規範執行（規則化掃描 → 批量改寫）、AI 輔助寫作的 review、知識卡片 / 教學文章的論證段落
• 不適用：純 reference 型內容（API 文件、規格表）— 這類內容讀者只查不推理、contrast 不重要
• 邊界：「保留 contrast」≠「保留所有否定詞」— 冗餘否定（讀者不會想到的 Y）仍該刪、判別標準是「讀者直覺會不會想到 Y」

Multi-pass review 的 scope 由『同類風險區』決定、不是『我改過的檔』。 跑某條原則的 pass（例如「結論可驗證性」）、scope 就是「所有可能違反該原則的檔」、不是「我這次改了的檔」。後者是執行便利選擇、不是 review scope 的合法依據 — 同一原則違反通常分布在整個 corpus、改動區只佔小比例。

判別問題：「這次 pass 用的 frame、適用範圍是哪些檔？我的 scope 涵蓋了那個範圍嗎？」答案是「沒有、我只掃了改動區」就需要擴大 scope。

情境

寫了一條新原則卡片（例：#94 結論可驗證性）後、要套回既有寫作做 multi-pass review。預設行為是「掃我這次改過的檔」、原因：

• 改動區是當下 working memory 裡的內容、便利
• 改動區 diff 短、容易跑完
• 改動區是「我剛動過的、所以可能有違規」的直覺對象

這三個理由都是執行便利、不是「review scope 的合法依據」。新原則套回既有 corpus 時、違規通常已經存在於沒被改動的部分（因為原則之前不存在、整個 corpus 都沒按該原則寫過）。只掃改動區會 systematic miss 大部分違規。

具體 case：本 blog compositional-writing skill 的負向表述清理：

1. 寫 #94 結論可驗證性原則（contrast 該保留還是該刪的判別）
2. Multi-pass 跑 6 輪、scope 設為「我改過的 SKILL.md / writing-articles.md / #94 卡片本身」
3. 第二天使用者讀 references/writing-prompts.md、發現「Prompt 的『原子單位』不是『一句話』、而是『一個可被驗收的任務』」就是 #94 該抓的 case
4. 該違規分布廣度：scan 整個 references/ 目錄、相同句型違規共 4 處（writing-prompts / writing-logs / designing-fields / managing-article-collections）、僅 0 處在我改動區內

我的 multi-pass 設計把 4 處違規 100% 漏掉、使用者用肉眼讀就抓到。

理想做法

第一步：定義原則的「適用範圍」

寫一條新原則時、明確標註該原則適用於哪些檔 / section。例：

第二步：Pass scope = 適用範圍 ∩ 待 review corpus

跑該原則的 pass 時、scope 是「該原則的適用範圍」交集「目前要 review 的 corpus」、跟「我改過哪些檔」完全無關。

對 compositional-writing skill 而言：跑 #94 pass 的合法 scope 是 .claude/skills/compositional-writing/**/*.md 全部、不是「我這次 commit 動到的 5 個檔」。

第三步：用 grep 把同類風險區找出來

同類風險常有結構性 signature（句型、詞彙、模式）、可用 grep 把適用範圍縮到具體行。例：

• #94：grep 不是.*而是\|不是.*是\|只是表象\|只是次級訊號 → 候選行
• 規則五：grep ^[^*].*。.*它 → 「X。它不是…」後置定義候選
• Severity 判準：grep severity.*\(嚴重度\|頻率\) → 替代判準誤用候選

把 grep 命中行當 review 起點、再人工判斷是否真違規。

沒這樣做的麻煩

Multi-pass 退化成 self-edit pass

只掃改動區 = 把 multi-pass review 退化成「我剛寫的東西自己再看一次」、這是 #83 「同 frame 重看」的另一種變形 — 表面在跑 N 輪、實際 scope 是同一塊小區。違規率沒下降、只是把改動區內的違規多檢查了 N 次。

既有 corpus 的違規永久累積

每次跑 pass 都只掃改動區、整個 corpus 的既有違規會永久不被處理 — 因為新加的原則只回頭掃改動區、舊內容沒被改的就永遠不過 review。corpus 越大、這個問題越嚴重 — 違規被結構性掩蓋、不是因為沒人看、是因為 scope 預設把它們排除。

違規由使用者眼睛 catch、而不是流程 catch

最終結果是違規被使用者讀到才發現、而不是 review 流程主動 catch。這違反 #82 跟 #72 — 把高 ROI 的 review 工作結構性跳過、靠外部 trigger（使用者抱怨）才執行。

跟其他抽象層原則的關係

• #67 寫作便利度跟意圖對齊反相關：本卡是 #67 在「review scope 設定」層的具體案例。最便利的 scope（改動區）跟意圖對齊（同類風險區）反向 — 越便利、越漏掉違規。
• #82 字面攔截 vs 行為精煉：本卡跟 #82 互補。#82 是「驗證粒度」要對齊、本卡是「驗證範圍」要對齊 — 兩個都是把 review 結構錯位、結果都是 false confidence。
• #83 寫作的 multi-pass review：本卡補強 #83 沒覆蓋的 scope 軸。#83 講「每輪換 frame」（horizontal）、本卡講「每輪 scope 由原則適用範圍決定」（範圍）— frame × scope 兩軸都對齊、multi-pass 才有意義。
• #72 高 ROI 無外部觸發的工作會被結構性跳過：「擴大 scope 跑 corpus-wide review」是高 ROI 但無強制 trigger 的工作、本卡指出該動作預設會被「改動區便利 scope」結構性取代。
• #94 正向改寫要保留對照論據：本卡跟 #94 是同次事故串接 — #94 抓到「改寫違規」、本卡抓到「review scope 漏掉的違規」、兩條一起才是完整的「正向改寫流程」。

判讀徵兆

當你準備 / 正在跑 multi-pass review 時、停下來檢查：

適用範圍與邊界

• 適用：multi-pass review、新原則套回既有 corpus、批量品質檢查
• 不適用：純 syntax / lint check（這類由工具固定 scope 跑全 corpus、無便利退化問題）
• 邊界：「同類風險區」≠「全 repo 全掃」— scope 由原則適用範圍界定、不無限擴大；範圍邊界比較適合寫在原則定義時（一次想清楚、之後直接套用）、勝過 review 時臨時決定（每次都要重判一次、累積成本高）

適用範圍要展開成具體 file enumeration、不能只給口語類型描述。 「所有教學文件」「所有規範文件」這類描述聽起來夠語意化、實際執行 review 時要當場推導「具體哪些檔屬於這個類型」— 推導步驟容易漏。Enumerate 成具體 file list（或可重現該 list 的 grep / find 指令）才是合法的適用範圍形式。

判別問題：「這個適用範圍能 reproduce 出具體 file list 嗎？兩個人各自展開會得到同一個 list 嗎？」答案是「不能」就需要 enumerate。

情境

寫了一條原則卡片（例：#95 multi-pass scope 由適用範圍決定）後、開始套用該原則跑 review。預設行為是讀「適用範圍」描述、心裡推導具體檔、開始掃。推導過程典型遇到的事故：

• 描述用語意層詞彙（「教學文件」「規範文件」）、心裡只想到主檔、忘了 mirror / sibling / 翻譯版
• 描述用 directory 層級（「.claude/skills/」）、忘了 content/skills/ 是同 surface mirror
• 描述用「所有 X」，X 邊界本來就模糊（「所有 Pattern 卡片」— 哪些算 Pattern？）

具體 case：本 blog 跑 #94 + #95 review 時、適用範圍寫「compositional-writing skill 的所有 references」、心裡推導 = .claude/skills/compositional-writing/references/*.md。漏掉的是：

• content/skills/compositional-writing/*.md（同 surface mirror、AGENTS.md Skill 撰寫規範要求「主體相同」）
• 同名檔在兩個物理路徑都存在、語意上是同一份內容

連續兩輪 review（#94 跟 #95）都漏同 5 個 mirror 檔、共 10 處違規透過 mirror 永久躲過 review。Root cause 不是「我忘了」、是「適用範圍沒 enumerate、每次 review 都要重新心算一次具體 list」。

理想做法

第一步：原則定義時 enumerate 適用範圍

寫原則卡片時、適用範圍欄位寫具體 file enumeration（path glob 或 grep / find 指令）、不寫類型描述。例：

1## 適用範圍
2
3- `.claude/skills/compositional-writing/SKILL.md`
4- `.claude/skills/compositional-writing/references/*.md`
5- `content/skills/compositional-writing/*.md`（mirror、AGENTS.md §9 規範同步）
6- `content/report/*.md`（教學卡）

或用可重現的 grep / find 規則：

1# 適用範圍 = 含「## 核心原則」section 的所有教學卡
2grep -rl "^## 核心原則" content/report/ content/skills/

兩種形式擇一、避免「所有 X 類文件」的口語描述。

第二步：Review 開始前先跑 enumeration、確認 list 完整

跑 pass 之前、先 ls / grep 出具體檔列表、貼到 review 紀錄裡、確認沒漏。例：

1$ find .claude/skills/compositional-writing content/skills/compositional-writing -name "*.md"
2.claude/skills/compositional-writing/SKILL.md
3.claude/skills/compositional-writing/references/writing-articles.md
4... (15 files total)
5content/skills/compositional-writing/skill.md
6content/skills/compositional-writing/writing-articles.md
7... (12 files total)

把這個 list 當這次 pass 的 ground truth、跟原則的「適用範圍 enumeration」比對、有 discrepancy（list 多 / 少）就停下來重看適用範圍定義。

第三步：把 enumeration 規則做成工具化檢查

當 enumeration 規則穩定後（例：「.claude/skills/<x>/ 跟 content/skills/<x>/ 永遠是 mirror 關係」）、把它寫成 lint / pre-commit hook：

• mirror 檢查：兩 path 同名檔有 diff → 警告
• enumeration 漂移檢查：原則卡片裡的 path glob 跟實際 ls 結果有差 → 警告

工具化後 enumeration 不再依賴人為紀律、是結構性保證。

沒這樣做的麻煩

Review scope 每次都要重新心算、漏判率隨輪次累積

口語描述的適用範圍 = 每次 review 都要當場推導具體 list。推導步驟有錯漏率、每跑一輪 review 就累積一次。本 blog 跑 #94 / #95 連續兩輪都漏同 5 個 mirror = 推導錯漏率 100%、不是偶發。

Mirror / fork / 副本永遠躲過 review

語意上是同一份內容、物理上不同 path 的檔（mirror / fork / 翻譯版 / SDK 多語言 port），最容易在「所有 X」描述下被漏掉 — 因為心算推導對齊到「主檔」、副本被「以為已包含」漏跳過。連續多輪後副本內容會嚴重 drift、跟主檔失去同步。

Enumeration 缺失等於沒有原則的 SSoT

適用範圍是原則的「作用域 SSoT」、沒寫清楚就等於每個讀者各自解釋一份 — #44 SSoT 違反在「原則作用域」維度的具體形態。讀者 A 跑 review 涵蓋 mirror、讀者 B 不涵蓋、原則套用結果就會 drift。

跟其他抽象層原則的關係

• #95 Multi-pass scope 要蓋同類風險區：本卡是 #95 的下游具體化。#95 答「scope 從哪來 = 適用範圍 ∩ corpus」、本卡答「適用範圍長什麼樣 = enumerated file list」。兩條串起來才是完整 review 流程。
• #82 字面攔截 vs 行為精煉：本卡跟 #82 互補。Enumerate file list 是字面層（具體 path）、enumeration completeness 是行為層的合法性判準（兩個人展開能否得到同一個 list）— 兩層都要對齊、scope 才合法。
• #44 Single Source of Truth：本卡是 #44 在「原則作用域」維度的具體案例。適用範圍口語描述 = 每個讀者各自解釋一次、結果 drift。
• #7 量測值缺一不可：本卡是 #7 在「review 範圍」的同形 pattern — enumerate 漏一個 = sanity 防線有缺口、整組 review 結果不可信。
• #42 2 次門檻是訊號：本卡的觸發來自「同方向漏判 2 次」訊號 — mirror 漏同步在 #94 / #95 review 連續發生、就是 #42 訊號要求抽象的 case。

判讀徵兆

當你寫原則卡片或準備跑 review 時、停下來檢查：

適用範圍與邊界

• 適用範圍 enumeration：
  • content/report/*.md（所有 report 卡片寫適用範圍時）
  • .claude/skills/*/SKILL.md（所有 skill 入口的觸發路由）
  • .claude/rules/**/*.md（所有規範文件的作用域）
• 不適用：純文字創作（散文 / 詩 / 故事）— 這類沒有「原則作用域」議題、enumerate 是 over-engineering
• 邊界：「Enumerate」≠「全 repo 全列」— 適用範圍仍由原則決定、enumerate 只是把該範圍寫成可重現形式；範圍本身的合理性是另一件事（由原則的 trade-off 決定）

寫作 review 的 surface 包含正文與 metadata surface。 Title、description、frontmatter、heading、link label、MOC 索引條都是讀者入口與 grep 入口；它們和正文共同建立讀者第一個概念錨點。正文通過 multi-pass review 只代表 body surface 收斂，metadata surface 仍要跑同一套意圖、語氣、grep-ability 與索引一致性檢查。

判別問題：「讀者看到這篇文章之前，會先看到哪些文字？這些文字有沒有跟正文跑同一輪 review？」

WARP 分析摘要

反向驗證：有些標題可以保留對照句型，條件是正文需要讀者先排除常見誤解，且標題本身同時給出正向概念錨點。這次的正文已能用「資安作為風險路由系統」直接建立錨點，對照句型放在正文的論證段更穩定。

情境

建立 content/backend/07-security-data-protection/security-as-risk-routing-system.md 時，文章責任已經寫成「把資安從檢查項目轉成工程路由語言」。正文段落也使用了正向定義：資安路由系統先判斷風險落點，再選擇控制面。

問題出現在讀者入口：

• Frontmatter title 使用 資安不是 Checklist：它是風險路由系統
• content/backend/07-security-data-protection/_index.md 的索引條沿用同一個 link label
• Review 討論集中在正文與章節內容，title / MOC hook 沒被列為同一輪檢查對象

這個問題的主因是 review surface enumeration 漏列：執行者知道要跑正向陳述檢查，但心中 scope 等於「正文段落」，沒有把 metadata surface 視為同等重要的文字。

理想做法

第一步：先列出本次產出的所有 surface

寫作前先列出本次會產生或修改的文字位置。例：

 1content/backend/07-security-data-protection/security-as-risk-routing-system.md
 2- frontmatter.title
 3- frontmatter.description
 4- body headings
 5- body paragraphs
 6- link labels
 7
 8content/backend/07-security-data-protection/_index.md
 9- table link label
10- table topic
11- table responsibility

這份清單是 review 的 surface enumeration。它補足 #96 適用範圍要展開成 file enumeration 的單檔內版本：#96 先列「哪些檔」，本卡再列「檔內哪些文字位置」。

第二步：每一輪 frame 都掃所有 surface

Multi-pass review 的每輪 frame 都要套到 surface 清單上：

Surface enumeration 讓「我有跑正向陳述 pass」變成可驗證動作，而不只是抽象自我宣告。

第三步：用 grep 補字面層掃描

正向陳述是語意判斷，但第一層候選可以用 grep 找出：

1rg -n "不行|不可以|不是|不要|無法|不能" \
2  content/backend/07-security-data-protection/security-as-risk-routing-system.md \
3  content/backend/07-security-data-protection/_index.md

grep 命中代表「需要判讀」，不代表自動違規。合法的對照句型要回到 #94 正向改寫要保留對照論據 的判準：有正向錨點、有對照原因、有適用情境。

沒這樣做的麻煩

讀者入口會先傳遞舊 frame

Title 與 MOC hook 是讀者先看到的文字。正文即使已經建立正向概念，入口若仍用負向 hook，讀者第一個 mental model 仍會被帶回「排除某種做法」而非「建立某個責任」。入口 frame 會影響後續閱讀方式。

Search surface 會保留錯誤概念錨點

Title、description、link label 是搜尋結果與 grep 最容易命中的位置。metadata surface 沒跑 grep-ability 與 positive wording，錯誤概念會比正文更容易被找到，長期變成知識庫中的主要入口。

Review 報告會產生 coverage illusion

只寫「已跑 positive wording pass」但沒有列 surface，review 報告會暗示整篇文章已覆蓋。實際上只掃 body surface，metadata surface 仍是未驗證區。這是 #95 Multi-pass scope 要蓋同類風險區 在單檔內的同形問題。

跟其他抽象層原則的關係

• #83 Writing 的 multi-pass review：#83 定義 frame 軸，本卡補 surface 軸。Frame 回答「用什麼眼睛看」，surface 回答「哪些文字都要被看」。
• #95 Multi-pass review 的 scope 要蓋同類風險區：#95 處理跨檔 scope，本卡處理單檔內 surface scope。兩者組合成完整 coverage：file scope × surface scope。
• #96 適用範圍要展開成 file enumeration：#96 要求可重現的 file list，本卡要求每個 file 內的 surface list。File enumeration 完成後，還要做 surface enumeration。
• #94 正向改寫要保留對照論據：#94 保留合法對照的推理，本卡定義對照句型出現在 title / MOC hook 時的檢查位置與承接責任。
• #84 Naming 是 iterated artifact：Title、slug、link label 都是命名。它們需要多輪迭代，在生成後持續用 grep-ability 與讀者入口角度收斂。
• #44 Single Source of Truth：正文核心概念與 metadata surface 需要共享同一個概念 SSoT。入口文字與正文語意分裂時，讀者會看到兩個 competing source。

判讀徵兆

當你完成文章或卡片後，看到以下訊號就要補 surface enumeration：

適用範圍與邊界

• 適用：技術文章、report 卡片、知識卡片、README、規格文件、skill reference、MOC / _index.md
• 特別適用：有 frontmatter、sidebar title、SEO description、index table、link label 的內容系統
• 邊界：Metadata surface review 是寫作 pass；它需要語意判讀，grep 只負責提出候選
• 例外：短訊息、一次性草稿、私人 scratch note 可以只保留 title / body 的最小 surface；production 內容與公開知識庫需要全 surface review

可操作檢查

Production 內容交付前，至少跑這三步：

1. 列出這次新增 / 修改檔案的 surface：title、description、heading、body、link label、MOC row。
2. 跑負向詞候選 grep，逐一判讀是否有正向錨點與對照原因。
3. 對照 _index.md 或 MOC，確認索引條、文章標題與正文第一段都指向同一個核心責任。

文章主情境負責教推演，素材庫負責支撐反向驗證。 當一組文章只展示 4-5 個主情境時，素材庫應保留約 2-3 倍的 field cases 或 source cards，讓每個主情境背後至少有 2-3 個來源可回查。

比例設計的判別問題是：「每個主情境背後是否有足夠來源，能支撐反例、變體與下一輪擴寫？」

WARP 分析摘要

反向驗證：素材庫持續擴張也有成本。當每個主情境已有 2-3 個來源、每個 pattern 有 1-2 個支撐案例時，下一步應轉向寫文章、跑 review 或回寫 MOC。

情境

在擴充資安章節時，主文章已經有足夠規模：紅隊案例庫、藍隊章節、素材庫與推演情境都已成形。下一步要決定「是否還要繼續補素材」。

當時有兩個看似相近的問題：

1. 文章讀者實際會看到幾個模擬情境？
2. 作者要保留多少真實案例作為支撐素材？

如果把兩者合併，容易得到「文章只用 4-5 個情境，所以素材也只要 4-5 個案例」的結論。這個比例對文章篇幅合理，對反向驗證偏薄。每個情境只有一個來源時，情境會跟單一事件強綁，後續很難判斷哪些是共通壓力、哪些只是個案細節。

理想做法

第一步：分開設計文章情境與素材庫

文章情境是讀者路徑，數量要少。素材庫是作者與未來文章的驗證基礎，數量可以較多。

第二步：先補來源，再寫情境

Field case 的責任是保存可回溯材料。案例型素材先找來源，再抽出觀察、壓力、控制缺口、判讀訊號與可轉譯情境。

Scenario card 的責任是把來源轉譯成可演練情境。情境可以合成多個來源的壓力點，但每個主要壓力都要能回查到 field case 或 source card。

Pattern card 的責任是歸納。模式可以比單一案例更抽象，但要保留支撐來源、適用邊界、判讀訊號與下一步路由。

第三步：用停止條件控制素材庫膨脹

素材庫需要明確停止條件。停止條件要寫在大綱中，讓作者知道何時從蒐集轉向寫作。

沒這樣做的麻煩

情境會被單一案例綁死

每個情境只靠一個來源時，作者很容易把個案細節當成共通結構。讀者需要拿到的是可搬到自己服務裡的中性情境，而非單一事件改寫。

Pattern 抽象層級會偏高

只有單一案例支撐的 pattern 容易過早抽象。作者會把一個事件中的做法升級成通用模式，缺少第二個來源檢查它是否真的跨情境成立。

後續章節缺少延伸材料

文章當下可完成，但下一輪要寫 incident response、deployment、reliability 或治理節奏時，會重新查資料。素材庫比例不足會讓每次擴寫都回到同一個蒐集成本。

跟其他抽象層原則的關係

• #83 Writing 的 multi-pass review：#83 說寫作要用多輪 frame，本卡補「素材量也要支撐反向驗證 frame」。只有一個來源時，反例 / 邊界 pass 會缺材料。
• #95 Multi-pass review 的 scope 要蓋同類風險區：#95 要求 review scope 蓋同類風險區，本卡把同一精神放到素材庫：source scope 要覆蓋主情境的變體區，並支撐文章會展示的少數案例。
• #96 適用範圍要展開成 file enumeration：#96 要求 scope 具體列出，本卡要求素材庫比例具體列出：主情境數、source card 數、scenario 數、pattern 數。
• #67 寫作便利度跟意圖對齊反相關：素材與文章一比一最方便，但跟「可驗證、可延伸」的意圖不對齊。補足 2-3 倍來源是較高成本但更貼合目標的做法。
• #82 字面攔截 vs 行為精煉：情境數量是字面層，情境是否有足夠變體支撐是行為層。本卡要求用來源覆蓋度判斷推演素材是否足夠。
• #97 Metadata surface 要納入寫作 review 範圍：#97 補 surface 軸，本卡補 material 軸。文章品質不只看正文與入口，也看背後來源是否支撐得住推演。

判讀徵兆

看到以下訊號，就要檢查素材庫比例：

適用範圍與邊界

• 適用：案例驅動文章、事故復盤、資安推演、架構決策素材庫、研究型技術文章、跨多篇 knowledge base
• 特別適用：文章只展示少數情境，但需要真實案例支撐可信度與反向驗證
• 邊界：比例是設計準則，實際數量依主題風險、來源密度與文章規模調整
• 停止條件：每個主情境已有 2-3 個來源、每個 pattern 有 1-2 個支撐案例後，先寫文章與 review

可操作檢查

建立案例型素材庫時，先跑這份檢查：

1. 列出主文章情境數，控制在 4-5 個。
2. 為每個主情境配置 2-3 個 field cases 或 source cards。
3. 檢查每張 scenario card 是否能回查來源。
4. 檢查每張 pattern card 是否至少有 1-2 個支撐案例。
5. 在 MOC 寫明停止條件，避免素材蒐集無限延伸。

本卡的論述基於 1 個 case（dart Stream 事故 的 review 過程）抽出來的假說、不是經過多個獨立 case 驗證的工程原則。具體限制：

• 「成本對稱性 / 可逆性 / 領域先驗」三軸框架借自 yagni 篇的判斷工具、不是 industry standard
• 「hindsight 偏向個人歸因 / 三軸偏向制度歸因」是觀察性分歧、不是必然對立——實際事故報告（aviation / medical incident）也常用 hindsight 同時歸因到制度
• 5 個多面向 case（code review / post-mortem / ADR / retrospective / 寫作）是假設性對比、未驗證真實案例中兩種論述的差異

讀者使用本卡時、把它當「這個 blog 提倡的判定方式」、不當「驗證過的工程原則」。

核心原則

本卡提倡的「設計缺陷」判定方式是「在當下成本對稱條件下選了限制更高的選項」、用以替代依賴結局的 hindsight 判定。

兩種論述讀起來都像在分析「設計缺陷」、但結論不同、可教性也不同。事後諸葛論述需要結局發生、當下三軸論證在當下就能判斷——後者才是 portable 工具。

為什麼 hindsight 不適合做設計缺陷判定

Hindsight 預設了結局、不能在當下使用

事後諸葛論述「StreamController() 被當廣播用了一段時間沒事、加第二個 listener 立刻炸 → 設計缺陷」隱含一個前提：讀者知道後來加了第二個 listener。

但設計者在當下不知道結局。如果讀者用這個論述當判斷工具、他要等到結局發生才知道「自己做錯了」——這不是判斷工具、是事後檢討。

當下三軸論述「在零成本差異 + 強領域先驗下選了限制更高的選項 → 設計缺陷」不需要等結局——讀者拿到的是「現在面對這類選擇、跑三軸、就能判斷」的工具。

把判斷依據放在結局上、會誤判類似情境

「結局是『後來需要多訂閱』 → 當初該選 broadcast」這個推論、套到不同議題會推出反向結論：

Hindsight 把「結局」當判斷依據 → 跟「後來剛好不需要」的 case 推出衝突結論。三軸論述用「當下選項屬性」當判斷依據 → 不依賴結局、可一致應用。

個人歸因 vs 制度歸因（觀察性分歧、不是必然對立）

Hindsight 論述偏向個人歸因——「設計者沒預見」「沒多想」「沒考慮未來」——隱含「個人錯了」。但這不是 hindsight 的必然結果：成熟的事故報告（aviation post-mortem、medical incident report）即使用 hindsight 視角、也常透過 root cause analysis 歸因到系統 / 制度層級。

當下三軸論述把判斷依據放在外部變數（工具預設、領域常識），歸因自然偏向制度層——「工具預設選錯」「領域知識沒內化進團隊規範」。但寫作者仍可選擇用三軸論證後再歸因到個人（「三軸都指向 broadcast、但設計者選了 single」）。

兩種論述在歸因方向上有偏差、但不是排他關係。本卡的主張不是「hindsight = 個人歸因、三軸 = 制度歸因」、而是「三軸論證的歸因預設偏向制度、寫作者要明確選擇歸因層次」。

兩種歸因引導的修補方向不同：

• 個人歸因 → 「下次更仔細」（無法行動的結論）
• 制度歸因 → 「review checklist 加一條」「lint rule 警告」「架構規範禁掉」（可執行）

多面向：跨情境的同個結構（假設性對比）

下面 5 個面向是假設性對比——本卡用相同 framework 推到 5 個情境、但只有面向 5（技術文章寫作）有對應的真實 case（dart Stream review）。其他 4 個面向（code review / post-mortem / ADR / 個人 retro）是 framework 在不同情境的推導、未驗證真實案例中兩種論述風格的差異。讀者套用時、優先在「跟本卡 case 結構接近」的情境使用、其他面向先當「待驗證的擴張」。

面向 1：Code review / PR 審查

事後諸葛 review：「你這段 code 後來在 X 條件下會炸、所以當初該寫成 Y」

當下三軸 review：「在當下、Y 比 X 多打 N 個字元、領域先驗強烈指向 Y、可逆性中等偏高 → Y 是當下三軸對齊的選擇」

差別：reviewer 不需要等到 bug 發生、就能在 PR 階段給出判斷。Hindsight review 需要等 bug、其實是「事後追究」、不是「事前防護」。

面向 2：Post-mortem / 事故檢討

事後諸葛 PM：「Stream 的單訂閱限制在第二個訂閱者出現時暴露、所以是設計缺陷」

當下三軸 PM：「Stream 的單訂閱選擇在當下成本對稱條件下不必要地縮小未來空間、所以是設計缺陷」

差別：第二種論述讓「設計缺陷」這個判定不依賴「結局已發生」、讀者學到的是 portable 判斷工具。團隊裡其他成員看到這份 PM、能套用到沒有相同結局的新議題上。

面向 3：架構決策反思（ADR retrospective）

事後諸葛 retro：「我們選 SOAP、後來生態系全跑去 REST、所以 SOAP 是錯的」

當下三軸 retro：「選 SOAP 在當時的成本對稱性是 ⋯⋯、領域先驗是 ⋯⋯ → 在那個時間點屬於合理選擇 / 屬於設計缺陷」

差別：能區分「真的當時就該避開」vs「環境後來變了」。前者是設計缺陷、後者是健康的演化、兩者修補方向完全不同。

面向 4：個人 retrospective

事後諸葛自我檢討：「上次我沒考慮 X、結果出事 → 下次要考慮 X」

當下三軸自我檢討：「上次的選擇在當下三軸論述下對齊嗎？對齊 → 不算判斷力問題、是環境變化；不對齊 → 找出當時該抓到的訊號是什麼」

差別：避免不必要的自我責備、改善方向更精準。「下次要考慮 X」是 case-bound、套到下一個議題（不是 X）反而沒幫助；「下次跑三軸」是 portable。

面向 5：技術文章寫作

事後諸葛寫作：「[工具] 預設為 [限制版本]、被當 [通用版本] 用了一段時間沒事、後來出問題 → 設計缺陷」

當下三軸寫作：「[工具] 在當下零成本差異條件下選了限制更高的選項、領域先驗指向通用版本 → 設計缺陷」

差別：讀者學到 portable 判斷工具、不只是「這個 case 後來怎樣」的故事。文章的長期價值（被新讀者拿去用在新議題）大幅提升。

識別訊號：什麼時候你正在用 hindsight 論述

訊號 1：論述需要「後來」「最終」這類時序詞

「後來加了第二個訂閱者才炸」「最終發現 plugin 系統不需要」「事故爆發後才知道」——這些時序詞標記論述依賴結局。

修法：把時序詞拿掉、論述還站得住嗎？站不住 → 補當下軸的論證。

訊號 2：歸因落在個人能力 / 預見性

「沒預見到」「沒考慮到」「沒多想」「疏忽」——把判斷錯誤歸給個人能力。當下三軸論述會把歸因放到「工具 / 領域常識」這類外部變數。

修法：把「沒預見到」改成「在當下、工具預設指向 X、領域先驗指向 Y、選擇者選了 Z」——歸因從個人轉到外部結構。

訊號 3：結論無法 portable

「下次要考慮 X」——但「X」是這次的具體議題（多訂閱）、套到不同議題（plugin 系統）反而會推出反向結論。

修法：結論寫成「下次跑三軸」「下次跑 checklist」——是工具、不是 case-specific 規則。

訊號 4：讀者讀完只記得 case、記不住原則

讀者讀完事後諸葛論述、能複述 case、但問他「下次遇到不同議題怎麼判斷」答不出來——因為原則沒被抽出來、case-bound。

修法：在 case 之後補一段「抽象原則」、原則用語不綁定本 case 的具體名詞。

何時 hindsight 論述仍然合理

「設計檢討用當下三軸、不依賴 hindsight」這條原則在大多數工程檢討情境成立、但有合理例外：

判讀：寫之前自問「這份檢討是要產出 portable 判斷工具嗎？」——是 → 嚴格用三軸；否 → hindsight narrative 可接受。

跟其他抽象層原則的關係

判讀徵兆

核心原則：「設計缺陷」是當下成本對稱條件下選了限制更高的選項、不是事後發現需求變了。寫設計檢討時用三軸論證、避免讓判斷依賴於結局已發生——這樣讀者拿到的是 portable 判斷工具、不只是 case 故事。

Self-case：本卡的觸發來源

本卡的觸發是修 Dart StreamController：single-subscription vs broadcast 的事故實錄 時的反思。

文章 v1 寫「StreamController() 預設為單訂閱、被當廣播用了一段時間沒事、加第二個 listener 立刻炸」——典型 hindsight 論述。

讀者反問：「如果只有一個人用沒問題、後來才需要多訂閱、這算設計缺陷嗎？」——這個反問正確 catch 了 hindsight 論述的薄弱處（依賴結局、不依賴當下選擇）。

修補後改寫：「在當下零成本差異條件下選了限制更高的選項」+ 加四格表釐清「需求演化 vs 設計缺陷」的分界——不依賴結局、用三軸論述。讀者拿到 portable 判斷工具、不只是 case 故事。

對應本卡：寫設計檢討時、第一版常常用 hindsight（因為事故已發生、視角自然帶結局）——要刻意 review 改成當下三軸、才會產出 portable 工具。這個 review 不會自動發生、需要 multi-pass review 流程在「規則三 / 規則四對齊」輪刻意檢查。

本卡的論述基於 1 個 case（dart Stream 事故的 review）抽出來的觀察。具體限制：

• Keyword bank 是 starting set、不是 exhaustive list：列出的口語詞（一輩子 / 碰巧 / 撞牆 / 啊原來）都是這次 dart 篇出現過的、不代表「口語修辭的完整詞庫」。新類型出現時要持續擴充
• 「精度 vs 可讀性」是情境化取捨、不是 zero-sum：本卡聚焦「判斷工具型段落」（讀者要從中拿到 portable 工具的論述）、在這類段落精度優先；但 hook / 引言 / narrative 段落口語反而幫讀者進入論述、不適用本卡
• Self-case 的修補有效性未獨立驗證：dart 篇修補後讀起來更精準、但「精準度跟讀者實際理解之間的相關性」沒做使用者測試

讀者使用本卡時、先判斷段落是否屬於「判斷工具型」——是 → 套用；否 → 評估口語跟可讀性的取捨。

核心原則

技術文章的「判斷工具型段落」（讀者用來判斷自己 case 的論述）裡、用詞選擇要能對應到具體技術屬性。口語修辭（「一輩子」「碰巧」「立刻撞牆」「沒事」）讀起來流暢、但在這類段落會稀釋精度——精度標準是「用詞能不能反推到具體機制 / 條件 / 契約」、口語修辭多半不能、寫了等於把判斷工具退化成感性印象。

下面三個層次的稀釋是觀察到的 pattern——不是窮舉、實際違規模式可能更多：

三個稀釋層次的具體 case

層次 1：時間性誇張

口語版：「stream 一輩子只能被 listen 一次」

問題：

• 「一輩子」沒有對應的技術概念——是「整個 process lifetime」？「stream object lifetime」？「listener cancel 之後也算嗎」？
• 讀者要靠猜測決定範圍

精度版：「stream 在整個生命週期內只允許被 listen 一次（StreamController object lifetime；cancel() 之後再 listen() 仍違反契約、要重建 StreamController）」

差別：精度版讓讀者能反推「我這個 case 屬於哪個範圍、會不會踩到」、口語版讀者只能感受「應該很嚴格」。

層次 2：因果模糊

口語版：「碰巧能用掩蓋了設計缺陷」

問題：

• 「碰巧」暗示運氣使然、機制不可解釋
• 但實際上「能用」有明確的機制：訂閱者數量沒達到觸發違反契約的條件
• 用「碰巧」會讓讀者學到「這是運氣問題」、不學到「這是條件未滿足的可預測現象」

精度版：「訂閱者單一時、限制處於沉默狀態」

差別：精度版描述「為什麼沒影響」的具體條件、口語版只描述「結果」。讀者能用精度版去判斷自己的 case 何時會觸發、不能用口語版做同樣的判斷。

層次 3：結局描述代替契約描述

口語版：「新加第二個訂閱者就立刻撞牆」

問題：

• 「撞牆」是視覺意象、不是技術描述
• 讀者拿到的是「發生了不好的事」、不是「為什麼發生」「在哪一層發生」
• 套到不同 case（如「使用 cancelled stream」「使用 closed controller」）會推不出對應的修法

精度版：「新加第二個訂閱者直接違反契約、執行期 throw」

差別：精度版指明「違反的是什麼（契約）」「在哪個時間點（執行期）」「具體後果（throw）」、讀者能 generalize 到其他違反契約的情境。

為什麼口語修辭會出現

技術寫作中口語修辭的出現有三類典型來源：

來源 1：寫的當下感性敘事比技術敘事好寫

「一輩子只能 listen 一次」比「整個 lifecycle 只允許被 listen 一次」少 5 個字、寫起來順、語氣強烈。但精度也差距 5 倍。寫作便利度高的版本通常離精度遠（#67 寫作便利度跟意圖對齊反相關 的同骨——寫得順 ≠ 寫得對）。

來源 2：對讀者「直覺感受」的妥協

「碰巧能用」這類詞讓讀者「立刻有共鳴」、感覺像在讀故事。但技術文章的讀者來這裡找的是判斷工具、不是故事——共鳴感換來精度損失、是錯誤的取捨。

來源 3：誤把「事故當下的反應」當成「論述用詞」

事故當下工程師的內心 OS 確實是「啊原來這個 mutation 路徑沒帶」「進入頁面就炸」——這些是當下的口語反應。寫成正式論述時要把這些反應翻譯回技術描述、保留意圖（驚訝 / 嚴重程度）但不保留口語形式。

識別訊號：什麼時候你在用口語修辭

訊號 1：時間 / 範圍誇張詞

「一輩子」「永遠」「整個炸了」「全部 GG」「直接死」——這類詞沒有對應的技術範圍、用了讀者要靠猜測。

修法：問「具體是哪個範圍 / 哪個生命週期 / 哪個 scope？」、把答案寫進去取代誇張詞。

訊號 2：運氣 / 巧合語氣

「碰巧」「剛好」「湊巧」「運氣好」——這類詞遮蔽了背後的機制。技術系統的行為幾乎都有可解釋的條件、不是運氣。

修法：問「為什麼當下沒發生？是哪個條件沒滿足？」、把條件寫出來取代運氣語氣。

訊號 3：視覺意象 / 動作比喻

「撞牆」「炸了」「鎖死」「卡住」「當機」（口語的，不是技術術語的 hang/freeze）——這些是事件的視覺描述、不是契約 / 機制描述。

修法：問「在哪一層、違反了什麼、執行期表現是什麼？」、把答案寫出來取代視覺比喻。

訊號 4：結局視角的驚訝句

「啊原來」「結果發現」「最後才知道」——這些把讀者帶到「事故已發生、回頭看」的視角、依賴 hindsight。

修法：問「在事前、什麼條件成立時這個 X 才會出現？」、改成事前可判斷的描述。詳細處理見 #110 設計檢討用當下三軸論證、不依賴 hindsight。

訊號 5：「沒事」「沒問題」當成段落結論

「運作正常」「沒事」「沒問題」「一切看起來都好」——這類詞代替了「在哪些條件下沒可見影響」的具體描述、暗示「不需要進一步審視」。

修法：問「沒影響是因為什麼條件沒觸發？換條件會怎樣？」、把條件寫出來取代「沒事」。

訊號 6：「下次 X 時、做 Y」結尾段

「下次看到 X 時、先問 Y」「下次寫 Z 時、想 W」「下次面對 V 時、停下來」——這類段落想給讀者實踐建議、但有兩個結構問題：

1. 前綴是 wrapper、不增加資訊：讀者來讀這段的脈絡通常已經是「正在處理 X」、「下次看到 X 時」對讀者是廢話、把重點推到後面（違反規則五「最重要的話優先說」）
2. 預設讀者會主動回憶：「下次 X 時做 Y」假設讀者下次會自動想起這條建議、實際上讀者多半不會主動 recall——應該寫成「判斷工具」而不是「回憶指令」

修法：把 wrapper 拿掉、把建議改寫成判斷工具的形式：

差別：修補前是「下次 X 時、做 Y」的 hortative 命令；修補後是「遇到 X 訊號時、用 Y 工具判斷」的 reactive 工具。前者依賴讀者主動 recall、後者由訊號觸發判斷。

注意 ≠「描述讀者的具體情境」：

「讀者讀完事後諸葛論述、能複述 case、但問他下次遇到不同議題怎麼判斷答不出來」

這個「下次遇到 X」是描述讀者的測驗情境（檢驗論述是否 portable）、不是給讀者的指令——保留合理。

何時口語修辭仍然合理

「精度優先」這條原則在大多數技術論述情境成立、但有合理例外：

判讀：寫之前自問「讀者拿這段去做技術判斷時、口語修辭會不會讓判斷模糊？」——會 → 翻成精度版；不會 → 口語可接受。

跟其他抽象層原則的關係

判讀徵兆

核心原則：技術文章的用詞要能反推到具體機制 / 條件 / 契約。口語修辭的便利在於寫得順、代價是讀者拿不到判斷工具。寫完每段後跑一次「這個詞對應什麼具體技術屬性？」自問、答不出來的詞就要翻譯。

Self-case：本卡的觸發來源

本卡的觸發是修 Dart StreamController：single-subscription vs broadcast 的事故實錄 的第二輪審查。

讀者指出該文有四處口語化問題：「stream 一輩子只能被 listen 一次」「進入頁面就炸」「現在只要有人訂閱、把它記錄下來，UI 就能用」「碰巧能用掩蓋了設計缺陷」。修補時的觀察是這些不是孤立問題、是「口語修辭代替技術描述」這個共通 frame 在不同句子的展現。

修補後對比：

每一組修補都把「口語視覺意象」翻譯回「技術屬性 + 條件 + 契約」。讀者拿到的是可反推的判斷工具、不是感性印象。

對應本卡：口語修辭的稀釋是字句層級的、容易在第一輪寫作後被忽略——multi-pass review 要在輪 4「Grep-ability / 命名 / 術語」加掃這個 frame、用 grep 找口語詞庫。

本卡的論述基於 1 個 case（dart Stream 事故的 review 中讀者點出「副屏」是中國用語）抽出來的觀察。具體限制：

• 詞庫表是分布偏差、不是絕對對立：「函數 vs 函式」「介面 vs 接口」這類詞在兩岸都有人用、只是分布偏好不同。本卡的「漂移代價」是觀察性敘述、不是嚴格的語言學分類
• 部分詞的判定可能不準：例如「文件」在台灣 IT 圈也常用來指 file（Windows 檔案總管的「文件」資料夾用了二十年）、「視頻」近年也滲透台灣年輕人語料——本卡列為「中國用語」是偏向 IT 業界傳統用法的 heuristic、不適用所有讀者群
• 沒有量化資料支撐「對映成本」：本卡描述「累積性的微秒級對映成本」是直覺論述、未做使用者測試
• 預設台灣讀者：本卡用「對台灣讀者寫作」當預設、實際讀者群可能跨地區、預設單一地區可能 over-narrow

讀者使用本卡時、把詞庫表當「這個 blog 為台灣 IT 工程師讀者預設的用詞偏好」、不當「兩岸標準語料對照表」。

核心原則

中文技術寫作的用詞精度受讀者的地區語料影響——同一個概念在繁中跟簡中可能用完全不同的詞、或用同一個詞但語意稍微偏移。寫作前先確定讀者的中文語料、避免用對方語料中不存在或意思偏移的詞。

技術文章的精度標準是「讀者用自己的語料能正確 parse 你的句子」。用錯地區用語、輕則增加讀者的對映成本（雖然可讀但不順）、重則造成語意誤判（如「文件」當 file 用、繁中讀者預期是 document）。

為什麼地區用語會漂移

來源 1：訓練語料 / 參考材料來源

技術寫作者常從中國技術社群、AI 工具（早期 LLM 的中文訓練資料以簡中為主）、open source 文件抓參考材料。複製時容易帶進原語料的用詞。

來源 2：技術圈的 Stack Overflow 效應

部分技術術語在簡中社群有大量內容、繁中相對少。寫作時搜尋資料、看到簡中版本的解釋、不自覺套用對方用詞。

來源 3：「讀得懂就好」的低估

「副屏 vs 副螢幕、讀者應該都看得懂」——這個假設在「個別詞」層級成立、但在「整篇文章」層級會累積：每個詞累積一次對映成本、整篇加起來幾十個詞、讀者的認知負擔會增加。

來源 4：跨地區團隊的混合語料

跨地區團隊（台灣 + 中國 + 香港 + 馬來西亞）的工程師常混用兩邊用詞。內部溝通沒問題、但寫成對外文章時要選定一個地區的語料對齊。

識別訊號：什麼時候你在用錯地區用語

訊號 1：技術術語有兩個常見譯法

「函式 vs 函數」「介面 vs 接口」「預設 vs 默認」「記憶體 vs 內存」——這類詞兩邊都有用、但分布偏向不同地區。

修法：選定讀者地區的版本、全篇統一。對台灣讀者寫作時用「函式 / 介面 / 預設 / 記憶體」。

訊號 2：硬體 / 業務名詞用了單字版本

「屏」「網盤」「U 盤」「光盤」——簡中習慣用單字、繁中習慣用兩字以上。

修法：「螢幕 / 雲端硬碟 / USB 隨身碟 / 光碟」。

訊號 3:「質量」當品質用

「程式碼質量」「服務質量」——繁中「質量」是 mass、用「品質」較精確。

修法：technical quality → 品質；mass / weight → 質量。

訊號 4：「視頻 / 視屏」用在繁中文章

「教學視頻」「示範視屏」——繁中傳統用「影片」、但「視頻」近年滲透。對 IT 工程師讀者寫作時、用「影片」更貼合主流偏好。

訊號 5：「文件」當 file 用的歧義

「打開這個文件」「保存文件」——繁中的「文件」用法分歧（IT 業界常用「檔案」指 file、但日常 / Windows 檔案總管也用「文件」指資料夾）。寫作時若指 file、用「檔案」更明確。

修法：file → 檔案（避免歧義）；document（公文 / 報告）→ 文件。

何時混用 / 不嚴格對齊仍然合理

「地區用語對齊」這條原則在公開技術文章成立、但有合理例外：

判讀：寫之前自問「讀者地區是否單一？我的用詞是否會讓讀者多花認知對映？」——是 → 嚴格對齊；否 → 混用可接受。

推到「術語選擇」的更上位原則

地區用語對齊是「術語選擇」的子問題。更上位的原則：

每個技術詞、寫之前都該確認「讀者語料是否包含這個詞」。

這個自問適用於：

• 地區漂移：本卡主題（繁中 vs 簡中）
• 學術 vs 業界用詞：「方法論」（學術）vs「做法」（業界）
• 新舊術語：「響應式設計」（舊）vs「reactive 設計」（業界新）
• 中文 vs 英文：技術術語第一次出現要不要保留原文錨點（見 #107 術語翻譯要保留原文錨點）
• 完整名詞頭：壓縮中文術語要保留 head noun（見 #108 中文壓縮術語要保留完整名詞頭）

地區漂移是這個自問的第一層應用——讀者語料的最大差異訊號。

跟其他抽象層原則的關係

判讀徵兆

核心原則：技術寫作的精度標準是「讀者用自己的語料能正確 parse」。地區用語漂移是累積性的閱讀流暢度損失——單一詞對映成本不大、但整篇加起來顯著。寫前先確定讀者地區、寫完跑一次 grep 對齊。

Self-case：本卡的觸發來源

本卡的觸發是修 Dart StreamController：single-subscription vs broadcast 的事故實錄 時、讀者指出「副屏」是中國用語、台灣應該用「副螢幕」。

修補時 grep 全文、發現「副屏」出現 9 處——不是孤立的一個詞、是整篇貫穿的用詞選擇。修補方式是 batch replace。

對應本卡：地區漂移多半不是孤立的、會在整篇文章貫穿——修補要用 grep 而不是逐句改。寫作前先確定讀者地區、寫完跑一次地區用語 sweep。

本卡的論述基於 1 個 case（dart Stream 事故的 review 中讀者指出「事件 payload 第二段」依賴 code 看過）抽出來的觀察。具體限制：

• Scope 限縮在概念說明 / 架構決策 / 設計檢討類文章：教學類、tutorial 類、code walkthrough 類文章的讀者本來就會逐行對映 code、本卡不適用——這幾類文章的論述跟 code 緊密交織是合理 narrative
• 「翻譯成業務角色」也有讀者熟悉度的邊界：用「鏡像訂閱者」「狀態變更 service」這類角色名詞替代「那個 controller」、對熟悉 POS 跟 pub-sub 的讀者通順、對不熟的讀者仍是空名詞。修法是「換 reference 類型」、不是「徹底解決 self-contained」
• 跟規則二（商業邏輯先於 CASE）的關係要精準：規則二講「層次順序」（先商業邏輯後 CASE）、本卡講「論述自包含」（不依賴 code reference）。兩者有重疊但不完全相同——本卡是規則二在「字句層 reference 處理」的子場景、不是規則二的全面延伸

讀者使用本卡時、先判斷文章類型——概念說明 / 架構決策 / 設計檢討 → 套用；教學 / tutorial → 評估「跟 code 交織」是否合理 narrative。

核心原則

概念說明 / 架構決策 / 設計檢討類文章的論述段（不放 code 的段落）要 self-contained——用名詞 / 角色 / 條件描述業務邏輯、不依賴讀者去翻附近的 code block。讀者跳過所有 code block 仍能理解論述、是「商業邏輯先於 CASE」（compositional-writing 規則二）在「字句層 reference 處理」的子場景應用。

self-contained 論述的價值在於論述本身就是完整的、code 是 case 補充而非依賴。讀者用論述就能 reproduce 思考過程、code 提供具體驗證。

為什麼依賴 code 的論述會出現

來源 1：寫的人有 code 在腦中、預設讀者也有

寫作者通常已經看過或寫過 code、所以在論述段用「那個 payload 第二段」這類 reference 對自己沒負擔。但讀者可能：

• 跳過 code 直接讀論述（多數讀者習慣）
• 看了 code 但沒記住具體結構
• 不熟 Dart / 該專案、看 code 也 parse 不出 payload 結構

依賴 code 的論述把這些讀者擋在門外、強迫他們翻 code 對映、認知負擔顯著上升。

來源 2：把對話風格搬進文章

「現在只要有人訂閱、把它記錄下來、UI 就能用」——這是對話風格、預設聽者跟說話者共享 context。寫成文章時要把 context 補進去：「需要新增一個訂閱者讀這段資訊、再把它對應到 UI 上的視覺標記」。

來源 3：論述跟 code 段過於緊密交織

文章在寫「先給 code、然後論述、然後再給 code」的交織結構時、論述容易自然 reference 上面 code 的具體行。讀者跳過 code 就斷掉。

來源 4：誤把「業務邏輯」當成「code 行為」

「業務邏輯」是「為什麼這件事存在 / 服務什麼需求」、「code 行為」是「具體怎麼跑」。依賴 code 的論述把兩者混在一起、讀者難以分離兩個層次。

識別訊號：什麼時候你寫了依賴 code 的論述

訊號 1：論述用「那個」「這個」「剛才的」「上面的」當主詞

「那個 service」「這個 payload」「剛才的 controller」——這類代詞依賴讀者剛才看過 code。

修法：把代詞換成具體名詞 + 角色描述（「狀態變更 service」「事件 payload」「副螢幕鏡像 controller」）。

訊號 2：用 code 結構描述（「第二段」「那個欄位」）

「payload 第二段」「那個 nullable 欄位」「上面 method 的 return value」——這類描述依賴讀者看過 code 的具體結構。

修法:把 code 結構描述翻譯成業務角色描述。「payload 第二段」→「最後變動品項欄位（給需要追蹤單筆變動的訂閱者用）」。

訊號 3：時序連接詞依賴 code 順序

「先…然後…接著…」如果這個時序對應上面 code 的執行順序、論述跟 code 綁太緊。

修法：把時序敘述為「在 X 條件下、Y 動作觸發 Z 結果」、不依賴 code 的具體順序。

訊號 4：論述只有「就好」「就能」「就行」

「現在只要有人訂閱、UI 就能用」「修改一行就好」——這類「就」字句在依賴 code 補足背景條件時有問題。但「修一行就好」如果背景條件已在前文說明、用「就」表達精簡是合理的——區分標準是「沒有 code 也讀得通嗎」、不是字面有「就」就違規。

修法：背景條件不在前文時、把省略的條件補回去；背景條件已在前文時、保留「就」沒問題。「在訂閱端讀取這段資訊、加一個視覺標記的綁定、即可在 UI 上呈現」。

訊號 5：跳過 code block 後段落讀不通

最直接的測試方法：把所有 code block 拿掉、再讀一次論述、看是否仍能理解。

讀不通 → 論述依賴 code、要修補。

修法：把 reference 翻成 self-contained 描述

修法 1：用名詞替代代詞

修補前：

「那個 service 對外發送事件、payload 第二段帶了這次變動是哪筆。」

修補後：

「狀態變更 service 對外發送的事件 payload 包含兩段：當前完整商品列表、最後變動的具體品項。第二段是『最後變動品項』。」

修法 2：用角色替代「位置」

修補前：

「上面 code 第三行那個 listener 拿到的是 nullable。」

修補後：

「副螢幕的訂閱者收到的事件 payload 中、第二段（最後變動品項）可能為 null（移除或清空操作的情境）。」

修法 3：用條件替代時序

修補前：

「先建立 controller、然後 listen、接著 add 事件、再 cancel。」

修補後:

「在 controller 建立後、訂閱者可呼叫 .listen() 註冊；註冊完成後、controller 才能 .add() 事件給訂閱者；訂閱者呼叫 .cancel() 解除註冊後、後續 .listen() 對 single-subscription 仍然違反契約。」

修法 4：把「就好」展開成具體條件

修補前：

「現在只要有人訂閱、把它記錄下來、UI 就能用。」

修補後：

「新需求只要新增一個訂閱者讀這段資訊、再把它對應到 UI 上的視覺標記即可——介面不需要變動、payload 結構不需要調整、實作範圍只限於新增訂閱端。」

何時論述可以依賴 code

「論述要 self-contained」這條原則在概念說明 / 架構決策 / 設計檢討類文章成立、但有合理例外：

判讀：寫之前自問「我的文章是『教讀者怎麼讀這份 code』還是『教讀者一個概念 / 框架』？」——前者可依賴 code、後者要 self-contained。

跟其他抽象層原則的關係

判讀徵兆

核心原則：技術文章的論述要 self-contained——讀者跳過所有 code block 仍能理解論述、是「商業邏輯先於 CASE」的延伸實踐。寫完後跑一次「拿掉 code block 還讀得通嗎」自測、讀不通 → 翻譯成 self-contained 描述。

Self-case：本卡的觸發來源

本卡的觸發是修 Dart StreamController：single-subscription vs broadcast 的事故實錄 時、讀者指出某段論述「重點混淆 + 過於口語 + 預設讀者看過原始碼」。

問題段（修補前）：

「技術上這需求很乾淨：service 早就在事件 payload 第二段帶了『這次變動是哪筆』，現在只要有人訂閱、把它記錄下來，UI 就能用。於是收銀主畫面的 controller 加了第二個訂閱。」

問題分析：

• 「事件 payload 第二段」依賴讀者看過 code 結構
• 「就能用」「就好」省略了具體條件
• 「於是 X 加了 Y」對話風格、不是論述風格

修補後：

「這個需求剛好對應 service 已經備妥但尚未被消費的資訊——service 對外的事件 payload 從原始設計就分兩段：一段是『當前完整的商品列表』、另一段是『這次變動的具體品項』。第二段是當初為『需要追蹤單筆變動的訂閱者』預留的擴充欄位、過去幾個月一直沒被消費。新需求只要新增一個訂閱者讀這段資訊、再把它對應到 UI 上的視覺標記即可——介面不需要變動、payload 結構不需要調整、實作範圍只限於新增訂閱端。」

修補後的論述用「角色描述（『需要追蹤單筆變動的訂閱者』）」替代了「位置描述（『第二段』）」、補回了省略的條件（「介面不需要變動、payload 結構不需要調整、實作範圍只限於新增訂閱端」）。讀者即使跳過所有 code block 也能理解這段論述。

對應本卡：論述依賴 code 是「寫的人有 code 在腦中」的便利選擇——multi-pass review 要在輪 5「反例 / 邊界」加掃 self-contained frame、用「拿掉 code 還讀得通嗎」自測。

本卡的論述基於 1 個 case（dart Stream 事故 的 review 過程跑 4 輪後仍漏 catch 4 類字句層問題）抽出來的假說。具體限制：

• 樣本量極小：「multi-pass review framework 顆粒度盲點」這個結論基於 1 次 review、不是多次跨主題 review 觀察到的 systematic pattern。可能是這個 reviewer（我）有特定盲點、不是 framework 本身的問題
• 三機制有效性未驗證：keyword bank / reader simulation / self-criticism 三機制是 proposed mechanisms、未實際跑下一篇文章驗證能 catch 之前漏掉的問題類型
• 「reader simulation 由同 reviewer 執行」的根本質疑沒解決：拿掉 code block 重讀、聽起來合理、但同一個人是否真能模擬「沒看過 code 的讀者視角」是疑問——記憶不會因為 code block 隱藏而消失。本卡提的修法是 partial fix、不是 root cause solution
• 「同一 reviewer 跑多輪 catch 高度相同」是直覺論述：沒有實證、是直覺推論
• 跟其他卡互相 cross-link 形成迴圈論證：本卡引 #110 / #111 / #113、但這幾張卡都源自同次事件、互相驗證有 selection bias 風險

讀者使用本卡時、把它當「從一次 review 失誤抽出的盲點假說」、不當「驗證過的 review framework 升級方案」。三機制是 starting point、有效性需要後續案例累積驗證。

核心原則

Multi-pass review 用「規則 frame」掃描、有效抓「結構性違反」（規則順序、論述結構、邊界段缺失）、但這次 case 顯示對「字句層的具體訊號」覆蓋不足——同個規則底下有大量具體訊號、reviewer 用記憶 sweep 容易漏掉一部分（這次 1 個 case 觀察、是否 systematic 有待累積）。

關鍵差異是「規則理解」vs「具體訊號比對」：

• 規則理解：reviewer 知道「正向陳述優先」這條規則
• 具體訊號比對：reviewer 要逐句檢查所有可能違反該規則的具體句型

抽象規則 → 具體訊號的轉譯沒做完整、就會 systematic miss 一整類字句層問題。

為什麼「規則 frame」抓不到字句層問題

問題 1：抽象規則沒展開成具體訊號清單

每條規則有大量可能的違反句型——例如「規則五：最重要的話優先說」可能違反句型：

reviewer 用「規則五」這個 frame 掃描、靠記憶找「這段有沒有違反規則五」——多半只 catch「觀察先 / 定義後」這個明顯 case、漏 catch 廢話前綴跟否定先行。

問題 2：缺乏 grep keyword bank

字句層問題有大量可 grep 的具體詞——但 reviewer 沒有 keyword bank、靠肉眼掃。例如：

每輪 review 用 grep 比對固定 keyword list、不靠 reviewer 記憶——能消除「靠記憶找違規」的 systematic miss。

問題 3：reviewer 自我審查的視角盲點

reviewer 讀自己寫的東西、會自動 fill in 上下文、感受不到讀者的真實閱讀體驗。例如：

• 「事件 payload 第二段帶了 X」——reviewer 寫的時候腦中有 code、知道「第二段」是什麼、感覺通順
• 讀者讀的時候沒有 code 在腦中、「第二段」是空的 reference、卡住

這個視角差異是 multi-pass review 的結構性盲點——同一個 reviewer 跑多輪、視角始終是寫作者視角、不是讀者視角。

問題 4：Multi-pass 缺 self-criticism 輪

每輪 review 都是 forward checking（這篇對齊規則嗎？）、沒做 backward critique（規則本身在這個情境是否夠細？有沒有 miss 的 frame？）。

如果規則框架本身不夠細、跑再多輪都掃不到 frame 之外的問題。

多面向：四類 missed 問題的分類

這次跑完 4 輪 multi-pass review、漏 catch 的 4 類問題：

Miss 類型 1：口語修辭（規則七 / 規則五的字句層子場景）

漏 catch 的具體訊號:「一輩子只能 listen 一次」「碰巧能用」「立刻撞牆」「啊原來」「炸了」

為什麼漏：「規則七：機會成本語氣」掃了「應該/必須/不行」、沒掃「一輩子/碰巧/撞牆」這類修辭詞。修辭詞跟絕對主義詞屬於不同 keyword set、reviewer 沒同時掃。

修法：建立「口語修辭 keyword bank」、輪 4「術語精度」加掃。

Miss 類型 2：地區漂移（規則四「術語」的子場景）

漏 catch 的具體訊號：「副屏」（中國用語、繁中應該用「副螢幕」）

為什麼漏：輪 4「術語檢查」聚焦在「中文 / 原文錨點」、沒掃「繁中 / 簡中漂移」。reviewer 預設「讀者地區」是台灣、但沒 explicit 用 keyword bank 比對。

修法：建立「地區用語對齊 keyword bank」（屏 / 默認 / 質量 / 視頻 / 文件 / 函數 / 介面 / 內存）、輪 4 加掃。

Miss 類型 3：依賴 code 論述（規則二商業邏輯先於 CASE 的延伸）

漏 catch 的具體訊號：「事件 payload 第二段帶了 X」「就好 / 就能」

為什麼漏：規則二被理解成「H2 後加商業邏輯導引」、沒延伸到「論述本身不依賴 code」。reviewer 寫的時候腦中有 code、感受不到「依賴 code」的閱讀體驗。

修法：加「reader simulation」frame——拿掉所有 code block、再讀一次論述、看是否仍能理解。

Miss 類型 4：廢話前綴 + 否定先行（規則五 + 規則六的字句層子場景）

漏 catch 的具體訊號：「下次看到 X 時、不要先想 Y」這類 hortative 結尾段

為什麼漏：規則五「最重要的話優先說」被理解成「核心原則先 / 例子後」、沒延伸到「廢話前綴 wrapper 句子」。規則六「正向陳述」被理解成「反例段落補正向錨點」、沒延伸到「『不是 A 而是 B』結構」。

修法：建立「廢話前綴 + 否定先行 keyword bank」、輪 5 加掃。

修補 multi-pass review 框架的三個機制

機制 1：Keyword bank（具體訊號清單）

每條規則展開成可 grep 的 keyword list、每輪 review 用 grep 比對、不靠 reviewer 記憶。

範例 keyword bank（節選）：

 1口語修辭：
 2  一輩子 / 永遠 / 碰巧 / 剛好 / 撞牆 / 炸 / 鎖死 / 啊原來 / 沒事 / 乾淨
 3
 4廢話前綴 / 否定先行：
 5  下次看到 / 下次寫 / 下次面對 / 下次遇到 / 不要先 / 不是 X 而是 Y
 6
 7地區漂移（繁中讀者）：
 8  屏 / 默認 / 質量 / 視頻 / 文件（當 file）/ 函數 / 接口 / 內存 / 視頻
 9
10依賴 code 訊號：
11  那個 / 這個 / 剛才的 / 上面的 / 第 X 段 / 就好 / 就能 / 就行

每篇文章 review 時跑這些 grep、把 hit 列出來、決定保留或修補。

機制 2：Reader simulation 輪

加一輪「假設讀者沒有上下文、能不能讀懂這段論述」、嘗試換視角。具體做法：

• 拿掉所有 code block 後重讀：論述是否 self-contained？
• 跳到段落中間直接讀：不依賴前文、能不能 parse？
• 隨機抽段給陌生讀者讀：cold-read 能不能拿到關鍵資訊？

已知限制：同一 reviewer 即使拿掉 code block、記憶仍在、無法完全模擬「沒看過 code 的讀者視角」。這個機制是 partial fix——能 catch 部分上下文依賴、但不是 root cause solution。最終解法仍需引入外部讀者反饋（cold-read by 真實讀者）。

機制 3：Self-criticism 輪

加一輪「我這份規則本身在這個情境是否夠細、有沒有 miss 的 frame？」、強迫 reviewer 反向審視框架本身。具體 prompt：

• 「我跑的 N 輪、catch 的問題類型有哪些？」
• 「同個規則底下、還有哪些可能違反句型沒被掃到？」
• 「如果讀者報告 X 類問題、是哪輪該 catch 但沒 catch？」
• 「framework 本身是否有 known blind spot？」

self-criticism 輪不是「再跑一次規則 frame」、是「檢視 frame 本身的覆蓋度」。

為什麼這些機制不能被「再仔細一輪」取代

「再仔細一輪」的同 frame 盲點

reviewer 跑同一個 frame 兩次、catch 的東西多半高度相同——因為視角、知識、注意力分配相同。（這是直覺論述、未做受控實驗驗證；但跟「換 frame」的設計動機一致——multi-pass 的核心就是「同 frame 重看 catch 不到新問題」）Multi-pass review 的核心是「每輪換 frame」、不是「同 frame 多跑幾次」。

但換 frame ≠ 換規則——reviewer 可能換規則但用同樣的視角、同樣的記憶 sweep、catch 的東西相同。要真正換 frame、需要：

• 換工具：keyword bank 取代肉眼掃（機制 1）
• 換視角：模擬讀者取代 reviewer 視角（機制 2）
• 換層次：審視 framework 取代套用 framework（機制 3）

三個機制各自處理「同一 reviewer 跑多輪仍 miss」的不同來源。

Hindsight 視角的反向印證

#110 設計檢討用當下三軸論證、不依賴 hindsight 的核心議題是「事後諸葛論述」會混淆「設計缺陷 vs 需求演化」。同樣的 hindsight 風險也存在於 review 流程：

• Hindsight 視角：「讀者反饋了 → 補進規則」——把規則當成「事故後補的 patch」
• 當下三軸視角：「framework 本身是否夠細到 catch 這類問題？」——把 framework 當成預設工具、用 self-criticism 反向審視

兩種視角的差別跟 #110 的差別同骨：前者依賴結局（讀者反饋）、後者用當下框架審視（self-criticism）。

識別訊號：什麼時候你的 review framework 不夠細

訊號 1：讀者反饋的問題類型在 framework 裡找不到對應 frame

讀者指出「廢話前綴」問題、reviewer 翻 framework 找對應 frame——找到「規則五最重要的話優先說」、但這條規則沒展開到「廢話前綴」這個具體子場景。

修法：把問題類型加進 framework 的 keyword bank、下次同類問題能被 grep catch。

訊號 2：跑了 N 輪、相同類型的問題仍重複出現

字句層問題（口語修辭、地區漂移）跑了 4 輪 review 仍漏——表示 framework 沒 catch 這個層次。

修法：加 keyword bank（機制 1）、不靠 reviewer 記憶。

訊號 3：reviewer 自我審查感覺通順、讀者反映卡住

「事件 payload 第二段」對 reviewer 通順、對讀者卡住——視角差異。

修法：加 reader simulation 輪（機制 2）。

訊號 4：相同 framework 跑不同主題、catch 的問題類型差異不大

framework 不會自我批判——跑 100 篇文章、catch 的都是 framework 內的 frame、framework 外的問題永遠看不見。

修法：加 self-criticism 輪（機制 3）、定期審視 framework 本身的覆蓋度。

何時不需要這些補強機制

「multi-pass review 需要 keyword bank + reader simulation + self-criticism」這條原則在 production 教學文章 / 設計檢討文章成立、但有合理例外：

判讀：寫之前自問「這篇文章的讀者群有多大？字句層問題擴散的代價有多高？」——大 / 高 → 嚴格用三機制；小 / 低 → 可放寬。

跟其他抽象層原則的關係

判讀徵兆

核心原則：multi-pass review 用「規則 frame」掃描有效抓結構性違反、抓不到字句層具體訊號。要 catch 字句層、需要把規則展開成 keyword bank、加 reader simulation 視角、加 self-criticism 反向審視 framework 本身——三個機制各自處理同 reviewer 跑多輪仍 miss 的不同來源。

Self-case：本卡的觸發來源

本卡的觸發是修 Dart StreamController：single-subscription vs broadcast 的事故實錄 時、跑了 4 輪 multi-pass review 後仍漏 catch 4 類字句層問題、由讀者點出。

讀者反饋的問題類型：

1. 口語化修辭（「一輩子只能 listen 一次」「立刻撞牆」「啊原來」「碰巧能用」）
2. 地區用語漂移（「副屏」是中國用語、台灣用「副螢幕」）
3. 依賴 code 論述（「事件 payload 第二段帶了」預設讀者看過 code）
4. 廢話前綴 + 否定先行（「下次看到 X 時、不要先想 Y、先問 Z」）

這 4 類問題對應的 frame 在 framework 裡都有（規則七機會成本、輪 4 術語、規則二商業邏輯、規則五最重要的話優先說）——但都沒展開到具體訊號層、所以 reviewer 跑了 4 輪都漏 catch。

對應本卡：framework 的覆蓋度盲點不能靠「再仔細一輪」修補——同一 reviewer 跑同 framework 多輪、catch 的東西高度相同。要真正擴大覆蓋度、需要 keyword bank（換工具）+ reader simulation（換視角）+ self-criticism（換層次）三個機制。

對 multi-pass review framework 的修補方向：把這 4 類問題加進對應 frame 的 keyword bank、加 reader simulation 輪當輪 8、加 self-criticism 輪當輪 9（或在每輪結尾加 self-criticism 子段）。

教材目標要先於決策框架。教學內容的責任是讓讀者建立某個領域的心智模型、操作語意、常見壓力與演進路徑；決策框架的責任是幫讀者在理解過程中抓住風險、成本與取捨。

決策框架是教學工具，教材目標是上位目的。當一套 Backend 教材被描述成「服務能力、風險、成本與決策」時，這個描述能提醒作者補足必要判準；上位目標仍要明確寫成「教讀者理解後端服務如何運作、如何組合、如何演進」。

WARP 分析摘要

反向驗證：決策框架仍然必要。後端服務本身牽涉資料一致性、成本、事故與資安，教材需要同時講概念與取捨，讀者才有可操作判準。本卡的重點是層級排序：教材目標在上，決策框架在內。

情境

Backend 內容已累積到一定規模後，評估方向時容易把現有語言當成目標本身。前一輪評估把 Backend 的原始定位概括成「服務能力、風險、成本與決策」，這個概括抓到了內容中的重要維度，但讀者指出更準確的定位是「教學」。

這個修正揭露了兩層差異：

第一層決定教材方向，第二層服務第一層。

理想做法

先寫教材要讓讀者學會什麼

教材入口要先回答讀者學習成果。Backend 的學習成果應寫成「能看懂一個後端服務問題該交給哪類能力處理，並理解多個能力如何串接」；Redis / Kafka / Kubernetes 的優缺點比較則放在這個學習成果之下。

較穩定的教材目標句是：

Backend 教材教讀者理解後端服務如何承擔資料、流量、交接、觀測、部署、可靠性、資安、事故與容量責任，並學會把這些能力組合成可操作、可演進的 production system。

再放入必要認知框架

服務能力、風險、成本與決策應該保留在每篇文章內，它們是段落責任，系列標題則承擔教材目標。它們回答的是「理解這個服務時有哪些必要判準」。

用內容結構保護教學目標

每個教學模組應先有學習路線，再有服務清單。服務清單是素材，學習路線才是教材。當文章先列 vendor、工具與 migration backlog，讀者會自然把教材理解成產品百科或選型資料庫。

沒這樣做的麻煩

教材會變成決策備忘錄

決策備忘錄能幫已經有背景的人判斷取捨，教材則要幫讀者建立概念。讀者看到大量「何時選 X」與「X 的成本」時，可能知道該問什麼問題，仍需要補上 X 在系統裡承擔什麼責任。

內容會被 vendor 與 migration 慣性帶走

Vendor 頁與 migration playbook 很容易量產，因為每篇都有明確對象。教材目標放在上層時，內容會往「更清楚的學習梯度」收斂；教材目標缺位時，內容會自然往「更多服務、更多遷移」擴張。

讀者學習路線會被能力地圖取代

能力地圖對作者有用，因為作者已知道整體結構。讀者需要的是先後順序：先理解什麼，再看什麼，遇到哪種問題跳到哪裡。缺少學習路線時，讀者會在能力地圖中自行找路，學習成本變高。

跟其他抽象層原則的關係

判讀徵兆

核心原則：教材要先定義學習成果，再放入決策框架。服務能力、風險、成本與決策是理解 Backend 的必要工具，但教材的上位目標是教讀者建立後端服務的心智模型與操作語意。

教材完整性要用讀者旅程驗證。章節數、案例數、vendor 頁數與 knowledge card 數量能證明素材充足；完成設計的教材還能回答不同讀者「我該從哪裡開始、按什麼順序讀、讀完能做什麼」。

讀者旅程是教材的 routing layer。它把素材庫、主章、案例、實作與進階專題組成學習路線，讓讀者直接取得順序，而非從內容地圖中自行推導。

WARP 分析摘要

反向驗證：讀者旅程與完整目錄各有責任。完整目錄仍是查閱與維護入口；讀者旅程是學習入口。兩者分工是「目錄服務作者與回查，旅程服務學習」。

情境

Backend 內容已經具備大量材料：主章、案例庫、vendor 頁、migration playbook、knowledge cards 都很完整。若只用內容覆蓋判斷，很容易得到「教學內容已經完成」的結論。

對照 LLM 與 Go 後，真正差異浮現：

Backend 的能力分類正確；下一層要補讀者旅程。

理想做法

第一步：先列讀者旅程

教材入口應先列 3-5 條讀者路線，每條路線都要有起點、順序與完成狀態。

Backend 可用的路線範例：

這些路線主要重組現有內容，把內容地圖整理成讀者可走的路。

第二步：為每條路線定義讀完能做什麼

學習路線要有完成判準。只列「讀 A、讀 B、讀 C」仍像目錄；加上「讀完能判斷什麼」才是教學設計。

第三步：用旅程檢查內容缺口

內容缺口要從旅程反推。若某條路線中間需要讀者自己跳轉，就代表教材設計有洞。

沒這樣做的麻煩

內容越多，讀者越難開始

素材量增加會讓作者覺得教材完整，但讀者面對大量章節時需要的是順序。沒有讀者旅程時，內容量越大，入口成本越高。

作者會誤把 backlog 完成當成教材完成

Vendor backlog、migration backlog 與案例庫都有清楚項目，很容易形成完成感。教學完成感應該來自「讀者能走完一條路線」；作者清單完成只是素材面的進度。

Review 會偏向覆蓋率，不看學習梯度

審查時若只問「哪些主題還沒寫」，會自然補更多主題。讀者旅程 frame 會改問「這些主題排列後，讀者是否能從低負擔走到高負擔」。

跟其他抽象層原則的關係

判讀徵兆

核心原則：教材完整性由讀者旅程驗證，內容覆蓋率只是一個輸入。成熟教材能讓不同目的的讀者找到起點、順序與完成判準；內容地圖服務查閱，讀者旅程服務學習。

服務型教材需要貫穿式案例作為教學骨架。資料庫、快取、queue、觀測、部署、可靠性、資安、事故與容量都可以獨立成章，但讀者真正需要學會的是這些能力如何在同一個服務裡交接、互相約束並共同演進。

貫穿式案例是一條可重播的服務演進路徑，而非單一大型專案手冊。它用同一個中性服務情境反覆穿過多個模組，讓讀者看到每個模組處理的是同一個系統在不同壓力下的責任切面。

WARP 分析摘要

反向驗證：貫穿式案例要維持中性、簡化、可替換，並明示它是教學載體；讀者理解案例所需的背景要由文章提供，而非內部專案知識。

情境

Backend 已有多篇服務路徑示範，例如 schema migration evidence、cache migration rollback、queue retry replay、checkout API evidence package、release gate、credential rotation 與 incident decision log。這些文章各自能說明一段能力，但它們在入口層還沒有被明確收斂成一條「讀者可以跟著走」的服務演進路線。

對照 Go 與 LLM：

Backend 的內容特性更需要貫穿式案例，因為它處理的是多個外部服務的協作教材，範圍大於單一語言或單一工具。

理想做法

第一步：選一個中性服務作為載體

貫穿式案例應該選讀者容易理解、又能自然觸發多個 Backend 模組的服務。較穩定的候選是 checkout / order / payment / notification 類流程。

這條服務路徑可承接：

第二步：把案例拆成多個可重播 episode

貫穿式案例要避免寫成一篇巨文。較穩定的做法是拆成 episode，每個 episode 對應一個模組責任。

Episode 讓讀者看到「同一服務在不同壓力下需要不同模組」，同時保留單篇文章的原子性。

第三步：讓每章都回到同一條服務路徑

每篇主章不需要都重述整個案例，但要能指出它在貫穿案例中的位置。這樣讀者可從任一章回到主線，也可按主線依序讀。

最小寫法：

1本章在貫穿式 checkout 案例中處理 E3：訂單事件 consumer 失敗後，如何判斷投遞、處理與恢復語意。

這句話把章節放回教學骨架，避免單章漂成孤立知識點。

沒這樣做的麻煩

章節各自正確，但整體難學

資料庫、快取、queue、觀測與事故章節都可以各自寫得正確。讀者看過它們如何在同一條服務路徑交接後，平行知識才會組成 production system 的整體模型。

案例庫會停在素材層

大量 case 能支撐反向驗證，但 case 本身不會自動形成學習路線。貫穿式案例的責任是把素材庫轉成讀者可重播的主情境。

Vendor / migration 內容會太早成為主角

讀者在還沒理解服務交接前讀 vendor 或 migration，容易把具體工具當成主線。貫穿式案例能先建立「問題如何跨模組流動」，再讓 vendor / migration 成為進階專題。

跟其他抽象層原則的關係

判讀徵兆

核心原則：服務型教材要有貫穿式案例。能力分類讓作者整理內容，讀者旅程讓讀者知道怎麼讀，貫穿式案例讓讀者看到多個能力如何在同一個 production service 中交接與演進。

服務頁教材合約的責任是把「某個服務是什麼」寫成「讀者能學會什麼」。服務頁可以討論 PostgreSQL、SQLite、MongoDB、Redis、Kafka、Kubernetes、Okta 或 k6，但文章目標應是教讀者理解該服務承擔的系統責任、服務對象、操作語意、失敗訊號與替代邊界。

服務頁教材合約把 vendor profile 升級成可教學的單篇文章。Vendor profile 描述功能、價格、適用場景與競品；服務頁教材還要讓讀者取得一個可遷移的心智模型，讀完後能把同一套判讀方式帶到相鄰服務。

這份合約約束的是教學功能，不約束章節模板。Go 目錄提供的是討論細節、漸進教學、操作判讀與邊界意識的成熟度參照；Backend 服務頁要達到同等教學深度，但 SQLite、MongoDB、PostgreSQL、Redis、Kafka 或 Okta 的章節順序可以完全不同。

WARP 分析摘要

反向驗證：章節統一會傷害服務頁。Go 目錄的價值是提供成熟教材的功能檢查，Backend 服務頁仍依自己的服務責任、讀者對象、案例壓力與操作比例安排標題。

情境

Backend 已完成總體教學設計、checkout episode map、vendor index audit 與各分類服務順序同步。下一步評估時，讀者提出更高標準：每個服務的探討內容與教學量級，應接近一篇成熟技術教材，讓選型摘要與 vendor backlog 成為教材材料。

這個標準指向教學深度，而不是統一章節。SQLite 服務的讀者可能在意 embedded state、local-first、測試資料與低操作成本；MongoDB 服務的讀者可能在意 document shape、schema governance、index 與 transaction boundary。兩篇都要達到成熟教材深度，但學習路線應由服務對象決定。

這個提醒揭露了三種不同完成度：

服務頁若只停在第一層，讀者會看到很多服務名稱；若能到第三層，讀者會理解服務能力如何在 production system 中承擔責任。

服務頁教材功能合約

教學功能先於章節格式

服務頁教材合約約束的是功能而不是格式。成熟服務頁要具備學習目標、核心概念、操作形狀、判讀訊號、替代邊界、案例回寫與下一步路由；這些功能可以出現在不同標題、不同順序與不同敘事密度中。

章節名稱要服務該服務的學習路線。SQLite 可以先談「正式狀態能否在單機成立」，MongoDB 可以先談「document shape 與 schema governance」，PostgreSQL 可以先談「SQL baseline 與 transaction」，這三篇不應被壓成同一套段落順序。

學習目標要先於服務介紹

服務頁開頭要先說讀者讀完後能做什麼判斷。產品名稱與服務定位很重要，但學習目標決定文章是否是教材。

成熟服務頁至少要回答：

• 讀者能辨識這個服務承擔哪類 backend 責任。
• 讀者能知道這個服務解哪種壓力，承擔哪種操作成本。
• 讀者能用訊號判斷服務健康、退化或失配。
• 讀者能知道何時改走相鄰服務。

概念段要建立服務專屬心智模型

概念段的責任是建立讀者能帶走的模型。Redis 頁不只教 Redis command，還要教「可重建副本如何保護 origin」；Kafka 頁不只教 topic，還要教「event log、consumer progress 與 replay window」；Kubernetes 頁不只教 YAML，還要教「workload lifecycle、readiness、traffic 與 rollback contract」。

服務專屬心智模型要貼近服務對象。SQLite 面向小型正式狀態、local data、edge 與測試資料；MongoDB 面向 document model、聚合查詢、索引與 schema governance；PostgreSQL 面向 SQL baseline、transaction、query boundary 與 schema evolution。三者同屬 database，教學路線仍可完全不同。

操作段要服務判讀

操作段的責任是讓讀者理解日常決策形狀。指令、設定、console 或 CLI 範例可以存在，但每個例子都要回到訊號、風險或下一步判斷。

較穩定的操作段功能包含：

替代邊界要讓服務回到能力地圖

服務頁要寫「何時改走其他服務」。這段把服務放回能力地圖：正式狀態回 database、可重建副本回 cache、durable replay 回 queue、traffic lifecycle 回 deployment、release evidence 回 reliability、identity control 回 security、協作交接回 incident。

案例回寫要提供情境壓力

案例回寫的責任是讓服務頁有真實壓力來源。案例要提供流量形狀、資料形狀、組織能力、失敗代價或回退路徑；案例只停在「某公司使用 X」時，對教材幫助有限。

沒這樣做的麻煩

服務頁會變成產品百科

產品百科容易累積功能、版本、價格與競品資訊，讀者可以查到很多答案，但仍難以建立系統責任模型。服務頁教材合約要求每個資訊都回到教學責任。

統一模板會抹平服務對象

統一模板會把同分類服務壓成相同讀法，讓服務對象消失。SQLite、MongoDB、DynamoDB、PostgreSQL 都在 database 分類，但它們回答的讀者問題不同；用同一套章節順序處理，會讓 embedded state、document model、access pattern 與 SQL transaction 的差異變成表格欄位，而不是學習路線。

內容會被選型語氣帶走

選型語氣會問「什麼情境選 X」，但教材還要問「X 在系統中承擔什麼責任」。只寫選型，讀者能做局部選擇；補上教材合約，讀者能理解整個 backend 能力地圖。

大量服務頁會產生完成錯覺

服務頁數量增加會帶來覆蓋感，但覆蓋不等於完成。125 個服務頁如果只有入口與摘要，仍是素材庫；每篇具備學習目標、操作判讀與案例回寫後，才是教材。

跟其他抽象層原則的關係

判讀徵兆

核心原則：服務頁完成的標準是讀者能透過單篇文章學會一個服務能力。成熟服務頁要同時提供學習目標、概念模型、操作判讀、替代邊界、案例回寫與下一步路由。

當批量 A 跟批量 B 是 sibling（同類 vendor / 同類角色 / 應有對等 coverage）、但 A 後寫卻超過 B、心智模型容易 collapse 到「A 是 reference template / B 是 baseline」的角色分配、忽略 B 才該 ≥ A coverage 的對稱性 priority。Priority 列表往往跳過 B、列其他「新領域擴張」選項。

問題不在 推某個 vendor、在 priority 評估維度漏掉 sibling symmetry。

Case：MySQL 18 篇 vs PG 11 篇後的 priority 列表

時間線：

1. PG 11 篇先寫完（autovacuum-tuning / declarative-partitioning / patroni-ha / pgbouncer-config / pitr-wal-archiving / logical-replication-debezium + 5 migration playbook）
2. MySQL 從 0 開始、user 要求「第一個示範服務、儘量都寫」、寫到 17 篇 deep article + migration playbook + 既有 migrate-to-postgresql = 18 篇 / 5715 行
3. 推薦下一步 priority 時、列「DynamoDB / Aurora / SQLite / MongoDB / CockroachDB / Spanner / Cosmos DB」、PG 不在列表
4. User 問：「為什麼這裡列的選項沒有 PG？我們做完了嗎？」

實際盤點：

• PG 11 篇 vs MySQL 18 篇、PG 缺 7 個 MySQL sibling deep article（replication-topology / online-schema-change-tools / query-optimization / lock-contention / vitess-sharding 對應 Citus / group-replication 對應 BDR / modern-sql-features 反向視角）
• PG 還缺 4 個 PG-only 議題（JSONB deep dive / Extension ecosystem / Full-text search / Replication slot management）

User 直覺 catch 到 coverage asymmetry、但我 priority 列表沒提供這個視角。

機制：為什麼會忽略

至少 5 個 priority bias 共同貢獻：

1. 「先存在就 mature」隱性假設

PG 11 篇先存在 → 直覺映射「PG 已 mature」。沒做 cross-sectional 對比：

• PG 11 篇 vs MySQL 18 篇、絕對量比較
• 議題覆蓋對應：MySQL 有哪些 deep article、PG 對應的是否都有

「11 篇」這個絕對數字 看起來合理、但跟 MySQL 18 篇對比後 結構性不足。心智模型把「合理」當成「mature」、跳過了相對性 audit。

2. 「新領域擴張」優於「既有領域對齊」的 progress bias

Priority 列表時、DynamoDB / Aurora / SQLite 等 vendor 看起來進度感強 — 從 0 推到 N、新領域擴張。PG 補齊看起來 重複勞動 — 從 11 推到 18、改善舊領域。

實際上：

• 新領域擴張 增加 surface area、但不改善既有結構
• 既有領域對齊 修補 baseline、是 reference template 成立的前提

當 baseline 跟 reference template 不對稱時、後者作為 示範服務 的價值打折扣 — 「MySQL 怎麼寫 vendor article」沒法 fully 套到 PG、因為 PG 本身不對稱。

3. Priority 評估維度漏 sibling symmetry

我用的 priority 評估維度：

• T1 vs T2 vendor 分類
• 領域重要度
• 已有量
• 新領域 vs 既有領域

漏掉的維度：

• Sibling vendor 對稱性（A 跟 B 同類、A 寫完後 B coverage 是否對齊）
• Reference template 跟 baseline 的關係（後寫的 reference template 應 ≤ baseline）

「Sibling 對稱性」這個維度不在預設 priority 評估清單、就被自動忽略。

4. Reference template vs Baseline 角色混淆

寫 vendor article 時、哪個是 baseline、哪個是 reference template 的心智模型可能反轉：

• 直覺：「先寫的 = baseline、後寫的 = reference / extension」
• 真實：「baseline 應 ≥ reference template coverage、不該倒過來」

MySQL 18 篇是 user-driven 要求 — user 明說「第一個示範服務、儘量都寫」。所以 MySQL 寫得多不是錯。但 PG 沒對齊到同水準 才是漏掉的紀律。

當 MySQL 寫到 reference template 規模、PG 還在 11 篇、心智模型容易 collapse 到「MySQL 是新 baseline、PG 是 legacy partial」、其實是 baseline 應該升級到 reference template 水準。

5. Sequential vs cross-sectional coverage 評估

寫作過程是 sequential —寫 MySQL 17 篇是一段時間、寫完看 git diff stat 確認進度、然後 priority 下一步。Coverage 評估是 point-in-time 的：

• Point-in-time（sequential）：「我這 batch 寫了多少」
• Cross-sectional（symmetric）：「我寫的這個跟 sibling 是否對齊」

寫 MySQL 第 17 篇時 self-cross-check：「PG 對應有沒有？」是 cross-sectional 行為、不是預設行為。

Priority 列表階段沒回頭跑 cross-sectional audit、就把 PG 排除。

修法

1. Priority candidate list 必須跑 sibling symmetry audit

提 priority 列表時、強制 cross-check：

• 列出該批量影響的 sibling vendor / sibling role
• 對比每個 sibling 的 coverage（篇數 + 議題覆蓋 mapping）
• 若有 asymmetry、把「補齊 sibling」加進 priority 列表 跟新領域並列

2. Vendors/_index「內容覆蓋進度」表加對稱性視角

當前內容覆蓋進度只列「已寫 / 未寫」、不列 sibling 之間相對進度。改善：

• 加 「跟 sibling 對應」欄：每個 article 標 sibling vendor 是否有對應
• 加 總計篇數 + sibling 對比 欄：直觀看到 asymmetry

3. 「先 mature baseline、再擴張」紀律

寫 vendor batch 時、紀律：

• 確認 baseline vendor 對齊到 reference template 水準、再推下一個 vendor
• 例外：user 明確要求先擴張某 vendor 時、加註 baseline 待對齊 為 known limitation

4. Audit dimension list 加 Coverage symmetry

跟 Data Topology as Audit Dimension 同型 —audit 維度可擴張。把 sibling coverage symmetry 加進 priority audit 維度：

• 既有維度：T1 / 領域 / 已有量 / 新 vs 既有
• 新增維度：sibling 對稱性（A 跟 B 同類時、coverage 對齊度）

跟既有原則的關係

• Data Topology as Audit Dimension：本卡是 priority 評估維度漏一個、同型但不同 axis
• Collapse is Implicit Default：priority 評估 collapse 到「新領域擴張」維度、是其變體
• Multi-Pass Review Frame Granularity Blindspot：multi-pass review 漏 catch 的同型、但本卡是 priority assessment 漏 catch、不是 review 漏 catch

反向驗證

不該誤用本卡：

• Sibling vendor 對稱性 不等於 每個 vendor 都該寫到同篇數。MySQL 18 篇對 PG 合理（兩大 SQL OLTP baseline），但 SQLite / DynamoDB / Spanner 各 18 篇不合理（領域窄 / niche audience）
• 對稱性 audit 是 對 baseline / reference template 雙方適用、不是擴張到所有 sibling
• 真正 niche vendor（如 Spanner / Cosmos DB 對小團隊）可以 明確 backlog 標記 minimum coverage、不必對齊 baseline

觸發再評估

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

• 寫第二個 baseline pair（02 cache Redis vs Memcached / 03 queue Kafka vs NATS 等）時、是否同樣踩 asymmetry blindspot
• 多 reviewer audit 是否能 catch coverage asymmetry（4-reviewer 沒設計這軸、之後 batch 可加 reviewer E coverage symmetry）
• Sibling 對稱性 audit 進工具化（vendors/_index 自動產 asymmetry warning）後是否解決

當寫 sibling vendor batch（A 跟 B 是同類角色的 vendor）、cross-link 容易單向：

• A 是後寫 batch、提 B 多次（「跟 PG sibling 對比」「PG 的 X 行為跟 MySQL 不同」）
• B 是先寫 batch、預設沒提 A（寫的時候 A 還不存在）
• 結果：A → B 有 9 條 link、B → A 有 0 條 link

讀者從 B 進入、看不到 A 的存在；只有從 A 進入才知道兩者並列。

問題不在 單向 link 本身錯、在 vendor batch 結束沒跑 bidirectional audit、就以為「cross-link 已建立」。

Case：MySQL ↔ PostgreSQL cross-link asymmetry

4-reviewer audit（Reviewer B）finding：

• MySQL 18 篇對 PG sibling 的 cross-link：9 條（vs PostgreSQL 對比段 / 連到 PG vendor page / 連到 PG sibling article）
• PG 11 篇對 MySQL 的 cross-link：0 條

讀者站 PG pgbouncer-config 不會跳到 MySQL proxysql-config；站 MySQL proxysql-config 直接看到「跟 PG pgBouncer 對比」段。Navigation asymmetric。

機制：為什麼會單向

1. 寫第二個 batch 時 reference 第一個 batch 是自然行為

寫 MySQL replication-topology 時、PG patroni-ha 已存在、自然連去做對比。寫 PG patroni-ha 時、MySQL replication-topology 還不存在、不可能 link。

這是 sequential 寫作的時間性結構性、不是疏忽。

2. Bidirectional link audit 不在預設寫作流程

寫完 batch B 後、預設 audit：

• lint / cards
• emoji / 裸 URL
• 跨檔一致性

沒有 向上回補 sibling A 的 cross-link 這一步。

3. Sibling A 寫好後、不會自動 trigger A 的更新

寫 vendor batch B 完成時、A 的內容不變、沒人 trigger「現在 sibling B 存在了、A 應該加 cross-link 回 B」。

修法：Bidirectional cross-link audit

Audit 步驟

寫完 vendor batch B（B 跟 sibling A 存在對應）後、跑：

1# 1. Count A → B link
2rg -c "\]\(/path/to/B/" content/path/to/A/*.md
3
4# 2. Count B → A link
5rg -c "\]\(/path/to/A/" content/path/to/B/*.md
6
7# 3. 對比
8# 若 A→B 顯著少於 B→A、補 A 端 cross-link

補 A 端 cross-link 的位置

每個 A article 應該在：

1. 「相關連結」段 — 列對應 sibling B article
2. 「跟其他 vendor 的取捨」段（若有） — 提到 sibling B 的對應
3. 「下一步路由」 / 「替代路徑」段 — 列 B 作為 alternative

Audit cadence

• 每個 sibling vendor batch 寫完、跑一次 bidirectional audit
• 不只寫完 第二個 batch、寫完 第三 / 第四個 也跑（A↔B↔C 三方對稱）
• vendors/_index 內容覆蓋進度表加 link_density 欄、揭露 asymmetry

跟既有原則的關係

• Sibling Coverage Asymmetry Blindspot in Priority：本卡是 cross-link asymmetry、那卡是 coverage asymmetry、同型但不同 axis
• Cards as Living System Iteration：cross-link 維護是 living system 部分、不是 one-shot

反向驗證

不該誤用：

• Sibling vendor 限同類角色（PG / MySQL 都 SQL baseline）、不是任意兩個 vendor。MySQL 沒必要 link Spanner（不同類）
• 雙向不等於 對稱數量 — A 18 篇可能有 9 條 link、B 11 篇有 6 條 link 是合理（不是 9 對 9）
• Migration playbook 結構性單向（A → B 是遷移、不是 B → A）— 對 migration playbook 是 單向結構、不適用本 audit

寫 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）

字句層 review 有兩個獨立步驟：偵測（這句有沒有命中可疑訊號）跟判定（這個命中是不是違規）。keyword bank 解的是偵測、判定仍是一個獨立的語意認知步驟。 reviewer 拿到 grep 命中後、傾向把它合理化成「這個 case 可以接受」而放行 — 偵測成功、判定失敗、違規一樣留在稿件裡。

#114 把字句層 review 的失敗歸到偵測層（沒 keyword bank、靠記憶 sweep）。本卡補它沒覆蓋的另一層：就算 grep 命中、reviewer 仍可能判錯。命中只是候選、不是判決。

情境

寫作規範「正向陳述優先」（主要敘述用正向句建立概念、反例只做對照）的 review、跑 grep 不[行可是要能]|無法|沒[做有]|而非|而不是。這個 bank 會命中兩類完全不同的句子：

• 建立概念的否定：「高階函式不是『用了比較高級』、而是特定場景的自然解」 — 用否定當核心概念的開場、違反正向陳述。
• 反例對照的否定：「對照反例：假設一個只有單一布林設定的 controller…既沒有共用流程、也沒有開放的變化點」 — 在明示的反例段落裡、否定是對照本身、規範允許。

兩者 grep 命中長得一樣、語意角色相反。reviewer 掃命中清單時、若用「這裡有對照意味、應該算反例」的寬鬆預設、會把第一類也放行 —— 這正是本卡的 case：grep 命中了「不是…而是」、被判成「正向對照修辭、OK」、由讀者再次 feedback 才 catch。

另有一類問題連命中都沒有：訴諸群體的安撫贅語（「很多人卡在…」「大家都會搞混…」）。這類句子沒有固定關鍵詞（「很多人 / 大家 / 不少開發者 / 初學時」表面形式發散）、keyword bank 結構上抓不到、只能靠語意 pass。

理想做法

否定句構命中後、用「概念位置」判定、不用「有沒有對照意味」判定

判別問題從「這句有對照意味嗎」（太寬、幾乎都 yes）換成 「這個否定在建立核心概念、還是在明示的反例段落裡做對照」：

關鍵修法是正向直述 B：「X 不是 A、而是 B」→「X 是 B」、把 A 的排除留給上下文或反例段。把「不是 A」翻成「而非 A」只是換個負向詞、仍違規。

這條判定準則剛好夾在兩張既有卡之間：#94 警告「別過度刪對照（刪掉承擔 reasoning 的 Y 會讓結論空降）」、正向陳述優先要求「別保留建立概念的否定」。判別線就是上表的「概念位置」—— 概念開場的否定該刪、反例段落的對照該留。

沒有關鍵詞的贅語、靠 reader-simulation 補

訴諸群體的安撫贅語抓不到固定關鍵詞、改用「換視角」pass：假裝讀者、問每一句「這句給了新資訊、還是只在安撫我（讓我覺得不是只有自己不會）」。教學文的責任是把概念講清楚、不是安撫讀者情緒 —— 安撫句一律刪、保留有教學價值的聚焦（「要分清什麼」）。

沒這樣做的麻煩

規範掃描器顯示「乾淨」、違規仍在

跑完 grep、把命中逐條判成「可接受」、回報「字句層 clean」 —— 這個 clean 是 judgment 放水的結果、不是真的沒違規。比「沒跑 grep」更危險：沒跑還知道沒查、跑完誤判會產生「已經查過」的虛假信心。

違規類型有系統性偏移

被合理化放行的是特定一類（建立概念的否定句構），有系統性偏移。同一個寬鬆預設會在每篇文章放行同一類違規 —— 跨稿件累積成 systematic miss、跟 #114 的偵測層 systematic miss 同構、只是發生在判定層。

keyword bank 越長、judgment 放水越隱形

bank 補得越完整、命中越多、reviewer 越依賴「快速掃過命中清單」、每條停留判定的時間越短、越容易用寬鬆預設批次放行。偵測能力提升反而稀釋判定品質 —— 兩層要分開要求、不能假設「有 bank 就會判對」。

跟其他抽象層原則的關係

• #114 Multi-pass review 的 frame 顆粒度盲點：#114 解偵測層（把規則展開成 keyword bank、不靠記憶 sweep）。本卡是它的下一層 —— 就算 bank 命中、判定仍可能放水。#114 的 keyword bank 範例已收「不是 A 而是 B」、但收進 bank 只保證命中、不保證判對；本卡補「命中後怎麼判」。訴諸群體贅語則是 #114 bank 該補的新 coverage（無固定關鍵詞、靠 reader-simulation）。
• #94 正向改寫要保留對照論據、不能空降結論：#94 跟本卡是同一判定軸的兩極。#94 防「過度刪 —— 刪掉承擔 reasoning 的對照 Y、結論變空降」；本卡防「過度留 —— 保留建立概念的否定、用『這是對照』當藉口」。兩卡合起來才是完整判定準則：以「概念位置」區分該刪（概念開場）還是該留（反例段落 / reasoning 對照）。
• #147 規範化跟自審是兩種認知任務：#147 講「立了規範 ≠ 能在自己稿件辨識實例」。本卡是更細一層 —— 連 grep 命中（自審的最強形式、已經指到具體句子）都可能因判定放水而失效。#147 的三層機制（grep / checklist / reviewer in-stream）裡、本卡聚焦 grep 那層的「命中之後」缺口。
• #82 字面攔截 vs 行為精修：grep 命中是字面層攔截、看不到那個否定承擔的是「建立概念」還是「反例對照」 —— 需要 behavioral pass（讀者讀到這句、是拿到正向概念還是被否定句卡住）才能判。本卡是 #82 在「字句層 review 判定」的具體實例。

判讀徵兆

適用範圍與邊界

• 適用：正向陳述優先這類「同一訊號命中、語意角色相反」的字句層規範 review；AI 輔助寫作的 self-review（最容易在判定層放水）；keyword bank 已建立、但 review 回報品質仍不穩的情境。
• 不適用：偵測本身就漏（關鍵詞不在 bank）的問題 —— 那是 #114 的偵測層、先補 bank 再談判定。
• 邊界：判定收緊 ≠ 一律刪否定。明示反例段落的對照（#94 的 reasoning Y）該留；判別線是「概念位置」、不是「有沒有否定詞」。收太緊會退回 #94 警告的「空降斷言」。

Self-case：本卡的觸發來源

本卡觸發於 review 為什麼這個場景適合用高階函式 時。流程是先跑 3 個 frame 的 multi-round review + 字句層 grep keyword bank：

1. grep 命中了核心議題句「高階函式不是『用了比較高級』、而是特定場景的自然解」跟小節開場「不是『能用就用』、而是…三個特徵」。
2. 我把這些命中判成「正向對照修辭、OK」、回報「字句層大致乾淨」。
3. 讀者 feedback 指出這仍違反正向陳述 —— 偵測成功、判定失敗。
4. 修正後讀者再指出「很多人卡在…」是訴諸群體的安撫贅語 —— 這類連 grep 都沒命中（無固定關鍵詞）。

對應本卡：keyword bank 命中是候選、不是判決。第一類（命中誤判）揭露判定層盲點、第二類（無命中）揭露 coverage 仍需 reader-simulation 補。兩者共同說明：字句層 review 的偵測（grep）跟判定（語意）是兩個步驟、不能假設「跑了 bank 就會判對、就會抓全」。

本卡的論述基於 1 個 case（HOF / typedef 可讀性文章的 review、一次抓到 3 種對讀者喊話的形式）抽出來的觀察。具體限制：

• 三 sub-case 是 starting set、不是窮舉：安撫 / 第二人稱 / 祈使是這次出現過的、不代表「對讀者喊話的完整形式庫」。新形式（反問句「想想看為什麼？」、預告「接下來你會看到」）出現時要持續擴充。
• 「中性 vs 親近」是情境化取捨、不是 zero-sum：本卡聚焦「判斷工具型 / 概念建立段」的喊話；hook / 引言 / narrative 段落的輕度第二人稱反而幫讀者進入論述、不適用本卡。
• 修補有效性未獨立驗證：改成中性陳述後讀起來更聚焦、但「register 跟讀者實際理解之間的相關性」沒做使用者測試。

讀者使用本卡時、先判斷段落是否屬於「概念建立 / 判斷工具型」——是 → 套用；否（hook / narrative）→ 評估親近感跟中性的取捨。

核心原則

教材的責任是把概念講清楚、不是管理讀者的情緒或閱讀節奏。 對讀者喊話的句子讀起來親近、但承載的是「對話 stance」而非概念內容 —— 把讀者當成要被安撫、被代入、被指揮的對象，多出來的是資訊負擔、拖慢進入正題。

下面三種形式是觀察到的 pattern —— 不是窮舉、實際形式可能更多：

關鍵是這三種精度都沒問題 —— 「你天天寫的 int count」指涉完全正確、「先讀懂這個簽章」語意清楚。違反不在用詞精度、在 register/stance：教材該是「陳述概念」、喊話是「對讀者說話」。

三種形式的具體 case

形式 1：安撫情緒 / 訴諸群體

喊話版：「很多人卡在『這串到底哪裡是型別、哪裡是名字』。」

問題：「很多人」沒有資訊量 —— 讀者不會因為「別人也卡」而更懂型別跟名字怎麼分。它的功能是情緒安撫（你不孤單）、不是概念傳遞。教材的價值在講清楚概念、讀者的情緒不是它的責任。

中性版：「這個簽章的關鍵是分清『哪裡是型別、哪裡是名字』。」

差別：中性版第一句就是概念聚焦（要分清什麼）、喊話版前半句純安撫、讀者要跳過它才到正題。

形式 2：第二人稱代入

喊話版：「順序跟你天天寫的 int count、Color color 一樣」

問題：「你天天寫的」把讀者拉進句子當主詞、預設讀者的日常（萬一讀者沒天天寫 Dart？）。它想營造親近感、但概念（int count 是 型別 名字 順序）不依賴「誰寫的」。

中性版：「順序跟常見的 int count、Color color 一樣」

差別：中性版用「常見的」指涉同一組例子、不預設讀者身分、概念一樣到位。

形式 3：祈使控制閱讀

喊話版：小節標題「先讀懂這個簽章的每個部分」、「先釐清：什麼是 X」

問題：「先讀懂 / 先釐清」是對讀者下閱讀指令、控制節奏。標題的責任是標示這段在講什麼（讓讀者自己決定讀不讀）、不是指揮讀者「先做什麼」。

中性版：描述性名詞標題「簽章的型別與名字拆解」、「什麼是『函式型別裸寫在簽章』」

差別：名詞標題讓讀者掃目錄就知道內容、祈使標題把目錄變成指令清單。

沒這樣做的麻煩

資訊負擔累積、稀釋概念密度

每句喊話都是「非概念」的字 —— 安撫、代入、指令本身不傳遞知識。教材裡散佈喊話、讀者要持續過濾「這句給資訊還是在跟我說話」、概念密度被稀釋。

預設讀者身分、對不上就失效

「你天天寫的」「很多人卡在」都預設了讀者的背景 / 經驗 / 困難。對不上的讀者（沒天天寫、第一次就懂）會感到突兀、甚至被排除 —— 跟 AGENTS 原則六「讀者定位用內容體現、不貼標籤」同源的失效。

Keyword bank 抓不到、靠語意 pass

第二人稱（你 會誤命中 code 註解）跟祈使（句式發散、無固定詞）沒有穩定關鍵詞、grep keyword bank 結構上抓不到 —— 這類問題只能靠 reader-simulation 語意 pass（「這句在給資訊、還是在指揮 / 安撫讀者？」）。正是 #149 講的 coverage gap。

跟其他抽象層原則的關係

• #111 口語化修辭會稀釋技術精度：兩卡是字句層的 sibling、但軸不同。#111 是「精度」軸（用詞能不能反推機制 / 條件 / 契約）；本卡是「register/stance」軸（陳述概念 vs 對讀者說話）。「你天天寫的 int count」精度完全正確、卻是錯 register —— #111 抓不到、要本卡。兩卡共享同一個情境邊界：hook / narrative 段落都放寬。
• #149 keyword bank 命中是候選、不是判決：本卡是 #149 的 content 對偶。#149 是 review-process（偵測≠判定、怎麼審）、本卡是 content 原則（prose 該怎麼寫）。#149 把「安撫贅語」當 coverage-gap 的舉例、本卡把它確立成 content 原則。產生情境不同：#149 源於 reviewer 誤判 grep 命中、本卡源於寫作當下 prose 對讀者喊話。
• #114 Multi-pass review 的 frame 顆粒度盲點：本卡的三形式裡、第二人稱跟祈使沒有固定關鍵詞、是 #114 keyword bank 機制的已知盲區 —— 補強的是 #114 的 reader-simulation 機制（換視角）、不是 keyword bank（換工具）。
• AGENTS 原則六（讀者定位用內容體現）：兩者相鄰但機制不同。原則六禁「貼標籤」（叫讀者『新手 / 新人』）、本卡禁「稱呼 / 指揮」（你 / 先讀懂）。可以不貼標籤卻仍在喊話（「你天天寫的」沒叫讀者新手、仍是第二人稱代入）—— 本卡補原則六沒覆蓋的 stance 維度。

判讀徵兆

適用範圍與邊界

• 適用：概念建立段、判斷工具型段落、小節標題 —— 這些地方的責任是傳遞概念 / 標示內容、喊話純屬負擔。
• 不適用：hook / 引言 / narrative 開場 —— 輕度第二人稱（「假設你在維護一個…」）能幫讀者進入情境、跟 #111 的 hook 例外同理。
• 邊界：中性化 ≠ 消滅所有「你」。判別線是「這句在傳遞概念 / 標示內容、還是在管理讀者（安撫情緒 / 代入身分 / 指揮閱讀）」—— 後者才刪。protocol 型文件（操作步驟、checklist）的祈使是合理 stance、不適用本卡。

Self-case：本卡的觸發來源

本卡觸發於 review 為什麼這個場景適合用高階函式 時、由讀者連續指出三種對讀者喊話：

1. 安撫：「很多人卡在『哪裡是型別、哪裡是名字』」—— 訴諸群體、讓讀者覺得不孤單。
2. 第二人稱：「順序跟你天天寫的 int count 一樣」「你天天在用 map」—— 把讀者拉進句子。
3. 祈使：小節標題「先讀懂這個簽章的每個部分」「先釐清：什麼是 X」—— 指揮閱讀順序。

三者在 grep keyword bank 的表現不一（安撫有部分關鍵詞「很多人」、第二人稱跟祈使幾乎無固定詞）、但共享同一個違反 —— 教材在對讀者喊話、而非中性陳述概念。修法統一：安撫句刪、第二人稱改中性指稱、祈使標題改描述性名詞標題。

對應本卡：對讀者喊話是獨立於精度（#111）跟 review-process（#149）的 content register 議題 —— 一個句子可以精度完全正確、grep 完全乾淨、卻因為 stance 錯（在跟讀者說話）而不該留在教材裡。

本卡的建卡判準是教學需求、不是出現頻率（對應 AGENTS 知識卡片規範段：建卡看「讀者缺這個知識會不會難以理解教材」、出現頻率只是補充訊號）。具體限制：

• 觸發 case 只有 1 個實例：這次 review 的 HOF 文章只出現一處「教科書級」。建卡的正當性來自「自評誇飾在技術寫作裡是常見 pattern」這個教學需求、不是這篇的頻率。單篇頻率低不影響值得建卡。
• 誇飾詞是 starting set、不是窮舉：列出的（教科書級 / 堪稱 / 完美 / 漂亮地）是觀察到的、不代表完整詞庫。新誇飾（神級 / 教科書式 / 無懈可擊）出現時持續擴充。
• 跟 #111 誇張家族部分重疊：本卡跟 #111 同屬「誇飾」大類、靠「評價對象」區分（見關係段）。邊界可能在某些句子模糊、需個案判斷。

核心原則

教材的責任是給出「為什麼這樣設計 / 為什麼適配」的技術理由，不對方案下品質評價。 自評誇飾（「X 是教科書級的適配」「堪稱經典」「完美契合」）讀起來像作者在替自己的方案打分數 —— 它傳遞的是作者的滿意度、不是讀者能用的概念。

更深的問題是品質評價會頂替技術理由：寫了「X 是教科書級的適配」、就佔掉了本該寫「X 為什麼適配」的位置。讀者拿到一個 verdict（這方案很好）、但拿不到 reasoning（好在哪、適配條件是什麼、邊界在哪）。誇飾是「評價空降」—— 給結論不給依據。

具體 case

誇飾版：「當『共用流程』與『變化點』能這樣切乾淨時，HOF 是教科書級的適配：把固定流程寫死在 update 裡，把變化點抽成函式參數 transform 由呼叫端帶入。」

問題：

• 「教科書級」是品質評價、不是技術內容 —— 讀者無法反推「適配到什麼程度、什麼條件下成立、邊界在哪」。
• 它頂替了理由的位置：冒號後面的「把固定流程寫死、把變化點抽成參數」其實才是真正的適配理由、但被「教科書級」這個 verdict 搶了焦點。
• 沒有教學會說某寫法是「教科書寫法」—— 這句話的語氣是個人檢討在誇方案、不是教材在講概念。

修法版：「當『共用流程』與『變化點』能這樣切乾淨時，HOF 正好對上這個結構：把固定流程寫死在 update 裡，把變化點抽成函式參數 transform 由呼叫端帶入。」

差別：「正好對上這個結構」是中性的適配陳述、把焦點交給冒號後面的具體機制；「教科書級」是 verdict、把焦點留在作者的評價上。

沒這樣做的麻煩

讀者拿到 verdict、拿不到可遷移的判準

「教科書級的適配」讀完、讀者只知道「作者覺得這很適配」、無法判斷自己的 case 適不適配。教學的目的是讓讀者拿到能套用到新情境的 reasoning —— 品質評價給不了這個。這違反 AGENTS 原則七（每段要有可操作判準、不能只做評價）。

評價會掩蓋「理由其實沒寫」

誇飾讀起來很有說服力、容易讓作者跟 reviewer 都以為「這段講清楚了」。實際上 verdict 佔了版面、理由可能根本沒展開 —— 跟 #94 的空降斷言同構：包裝成肯定句、但依據是空的。

語氣從教材滑向個人檢討

「教科書級 / 堪稱經典」是回顧視角的自我評價（我這方案選得好）。教材是面向讀者講概念、不是面向自己總結成果 —— 語氣一滑、整段的 register 就從「教學」變成「炫耀 / 自評」。

跟其他抽象層原則的關係

• #111 口語化修辭會稀釋技術精度：兩卡同屬「誇飾」大類、靠評價對象區分。#111 的誇飾誇張的是技術屬性（「一輩子」誇張時間、「整個炸了」誇張嚴重度）—— 是對技術事實的不精確描述。本卡的誇飾評價的是方案品質（「教科書級」評價設計好壞）—— 根本不在描述技術事實、是 verdict 頂替 reasoning。#111 修法是「翻譯回技術屬性」、本卡修法是「換成技術理由」。
• #150 教材用中性陳述、不對讀者喊話：兩卡是 register/stance 議題的 sibling。#150 的違反是「管理讀者」（安撫 / 代入 / 指揮）、本卡的違反是「評價方案」（替自己的設計打分數）。兩者都背離「教材中性陳述概念」這個上層 stance、但對象不同（讀者 vs 方案）。
• #94 正向改寫要保留對照論據、不能空降結論：本卡是 #94「空降斷言」在「品質評價」維度的變體。#94 處理「刪掉對照 Y → 結論 X 變空降」、本卡處理「誇飾 verdict 頂替理由 → 評價變空降」。兩者共享同一個失敗：給結論不給依據、讀者只能選擇相信或腦補。
• AGENTS 原則七（每段要有可操作判準）：誇飾直接違反原則七 —— verdict 不是判準。本卡是原則七在「自評誇飾」這個具體違反形式上的展開。

判讀徵兆

適用範圍與邊界

• 適用：概念建立段、設計理由段、適配性論述 —— 這些地方該給機制 / 條件、不該給品質評價。
• 不適用：純 narrative / 復盤型內容（work-log 的事件回顧、retrospective）—— 這類內容本就含作者視角的評價、誇飾是合理 register。
• 邊界：中性化 ≠ 禁止一切「適配 / 適合」字眼。判別線是「這句給的是可遷移的判讀條件（三條件齊備時 HOF 比列舉更省）還是品質 verdict（教科書級）」—— 前者是判準該留、後者是評價該換。帶條件的適配陳述不是誇飾。

Self-case：本卡的觸發來源

本卡觸發於 review 為什麼這個場景適合用高階函式 時、讀者指出「HOF 是教科書級的適配」這句 —— 「這比較像個人檢討、沒有教學會說這是教科書寫法」。

關鍵判讀：這句精度沒問題（HOF 確實適配這個結構）、grep 也不一定命中（「教科書級」不在口語修辭 keyword bank）、但 register 錯了 —— 它在評價方案品質、不在陳述技術理由。修法是把「教科書級的適配」換成「正好對上這個結構」、讓焦點回到冒號後面的具體機制。

建卡的正當性來自教學需求、不是這篇的頻率：自評誇飾在技術寫作裡是常見 pattern、讀者 / 作者都容易把「verdict 讀起來有說服力」誤當「理由講清楚了」。這篇只有 1 個實例、但 pattern 普遍 —— 對應 AGENTS 知識卡片規範段「建卡看教學需求、出現頻率只是補充訊號」。

本卡的論述基於 1 個 case（HOF / typedef 文章的「更新的本質天生就是一個函式」）抽出來的觀察、建卡判準是教學需求（本質主義框架在技術寫作、尤其 LLM 生成內容裡是高發 pattern）。具體限制：

• 必然性詞是 starting set：天生 / 本質就是 / 必然 / 唯一 / 註定 是觀察到的、不窮舉。新形式（生來 / 理所當然 / 不可能不）持續擴充。
• 跟 compositional-writing 原則三（機會成本語氣）部分重疊：本卡是原則三的一個 subtype、靠「絕對的形式」區分（命令式 vs 必然式、見關係段）。原則三未獨立成 report 卡、本卡補這個缺口的必然性維度。
• 「設計 vs 必然」的界線本身是判斷：某些陳述介於「被上游選擇逼出來的後果」跟「真正的自然必然」之間（見邊界段）、需個案判讀。

核心原則

設計選擇要講成選擇 —— 說明它在什麼條件下成立、為什麼比替代方案好，而不是用「天生 / 本質就是 / 必然」把它講成自然法則。 必然性框架抹掉設計能動性：讀者拿到「這本來就這樣」、卻不知道「這是一個選擇、有前提、有替代」。

這是「機會成本語氣 vs 絕對主義」違反的一個 subtype，但比命令式絕對更隱形：

必然式更該防 —— 它不說「你該怎麼做」（讀者會審），而說「事情本來就這樣」（讀者直接接受）、把一個 trade-off 藏進「自然」的外衣。

具體 case

必然版：「更新的本質天生就是一個 (current) => next 的函式 — 拿舊值算出新值。」

問題：

• update 是設計出來的方法、不是與生俱來的東西、「天生」語義場（生物性 / 本能）對不上設計產物（表層症狀）。
• 更深：update 以 (current) => next 形式呈現、只在「選了不可變模型」之後才成立。不可變本身是設計選擇（@immutable + copyWith）—— 「天生」把這個前提條件跳過、讓條件性結論變成無條件真理。
• 最深：牴觸文章自己的論點。這篇通篇論證 HOF 是條件性適配（「三條件齊備才划算」「場景不對時硬用是過度設計」）—— 唯獨這句用「天生」把它講成必然、局部破壞了文章自己的條件性紀律。

修法版：「不可變模型下的更新，在語意上就是一個 (current) => next 的函式 — 拿舊值算出新值。」

差別：修法版用「不可變模型下的」把前提條件講出來、用「就是」取代「天生」—— 結論還在、但還原成「在某前提下成立」、不再偽裝成自然法則。

沒這樣做的麻煩

讀者學到「規則」而非「思考方式」

必然框架告訴讀者「事情本來就這樣」、讀者拿到一條沒有條件的規則。換個情境（可變模型、需要 persist 的場景）規則就不適用、但讀者不知道邊界在哪 —— 因為「天生」沒給條件。機會成本語氣的核心就是「教思考方式（能遷移）而非規則（壓力下會忘）」、必然框架直接違反。

局部牴觸自身論點、瓦解可信度

一篇講「看條件、不是必然」的文章、出現一句「天生 / 必然」、細心的讀者會發現矛盾 —— 到底是條件性還是必然？這比單純用詞不當更傷：它瓦解文章整體論證的一致性。本質主義框架的高發處正是「作者其實知道是條件性、但順手用了必然語氣」。

偽裝成事實、躲過 review

「應該用 X」這種命令式主張、reviewer 會審「憑什麼應該」。「X 天生就是 Y」偽裝成事實陳述、reviewer 容易直接接受 —— 跟 #151 誇飾、#94 空降斷言同構：把需要依據的東西包裝成不需要依據的形式、躲過檢查。

跟其他抽象層原則的關係

• compositional-writing 原則三（機會成本語氣優先）：本卡是原則三的 subtype。原則三主要談命令式絕對（「應該 / 正確做法是 / 替代方案不足」）、本卡補必然式絕對（天生 / 本質就是 / 必然）這個更隱形的維度。原則三未獨立成 report 卡 —— 本卡是它在「必然性框架」這個具體形式上的 report 化。
• #151 教材給技術理由、不替方案下品質評價：兩卡是「空降家族」的 sibling、都把需要依據的東西包裝成不需要依據。#151 是品質 verdict 空降（教科書級頂替理由）、本卡是必然框架空降（天生頂替條件）。差別在頂替的東西：#151 頂替「為什麼好」、本卡頂替「在什麼條件下成立」。
• #94 正向改寫要保留對照論據、不能空降結論：#94 是空降家族的源頭（刪掉對照 Y → 結論 X 空降）。本卡跟 #151 都是 #94 在不同維度的變體 —— 三者共享「給結論不給依據、讀者只能相信或腦補」的失敗。
• #111 口語化修辭會稀釋技術精度：「天生」在表層也是一種用詞精度問題（語義場對不上指涉對象）—— 但本卡聚焦的是它的框架效果（把設計絕對化）、不是精度。#111 抓表層用詞、本卡抓深層框架、可疊加。

判讀徵兆

適用範圍與邊界

• 適用：設計理由段、概念建立段、適配性論述 —— 凡是在講「某設計 / 某結構為什麼成立」的地方。
• 不適用：物理 / 法律 / 合規 / 數學事實（per 原則三的例外）—— 「雜湊碰撞必然存在」「GDPR 規定必須 X」這類是真必然、可用必然語氣。
• 邊界：條件性後果 vs 真必然的判別線是「這個必然有沒有上游的設計選擇當前提」。「不可變模型下、更新是 current → next」是條件性（前提=選了不可變）、要講出前提；「任何雜湊函式都有碰撞」是真必然（不依賴任何設計選擇）、可直接斷言。被上游選擇逼出來的後果、不是天性。

Self-case：本卡的觸發來源

本卡觸發於 review 為什麼這個場景適合用高階函式 時、讀者指出「更新的本質天生就是一個函式」—— 「不會有天生這件事、update 也是設計出來的、中文語義上不可能說這叫天生」。

第一輪我把它定性成單純的語義錯置（天生=生物性、對不上設計產物）、讀者要求用 WRAP 再想一次。WRAP 揭露三層遞進：(1) 表層語義場錯置；(2) 中層把設計選擇講成必然、抹掉設計能動性；(3) 深層牴觸文章自己的條件性論點（通篇論證 HOF 是條件性適配、唯獨這句講成天生）。

對應本卡：必然性框架不是用詞問題、是框架問題 —— 把「設計」講成「天性」。它比命令式絕對（#151 / 原則三主談）更隱形、因為偽裝成事實陳述躲過讀者跟 reviewer 的審查；它的高發訊號是「局部牴觸作者自己在別處的條件性立場」。建卡正當性來自教學需求（LLM 寫作高發）、非本 case 頻率（1 實例）。

本卡是一次 review 失誤的 self-retrospective（用 WRAP 的 Consider the Opposite 反向檢驗自己的 review 過程）抽出。具體限制：

• 樣本是 1 次 review、1 個 reviewer（我自己）：「design gap vs execution gap」這個二分基於單次自我檢討、不是跨多次 review 觀察到的 systematic pattern。
• 「自我歸因」有 self-serving 風險：reviewer 檢討自己漏抓時、可能傾向把責任推給「框架不足」（design gap）而非「我偷懶」（execution gap）—— 本卡的價值正是強迫拆開這兩者、但拆的人就是當事人、客觀性有限。
• 修法有效性未驗證：診斷後的修法（改框架 vs 改執行）是否真能讓下次 catch 到、未經後續 review 驗證。

讀者使用本卡時、把它當「review 失誤歸因的一個檢查步驟」、不當「驗證過的 review 流程」。

核心原則

Review 漏抓某類問題時，先分清是 design gap 還是 execution gap，再決定修法 —— 兩者修法相反。

• Design gap：框架根本沒有對應的 frame / keyword 去 catch 這類問題。修法是改框架（補 frame、補 keyword bank、補 lens）。
• Execution gap：框架有對應 frame、但 reviewer 這次沒跑（跑了子集、跳過該跑的輪）。修法是改執行（真的跑完該跑的輪），改框架沒用。

同一次漏抓常常兩者都有 —— 要分別處理、不能只修一邊。

具體 case

這次 review 一篇技術教材、跑了「3 個臨時擬的 agent frame + 一次字句層 grep」、回報「字句層大致 clean」。結果使用者分多輪 catch 出 register/stance 類問題（安撫讀者 / 第二人稱 / 自評誇飾 / 必然框架）。用 WRAP Consider the Opposite 反向檢驗，發現兩種 gap 都有：

Execution gap（我沒跑完整框架）

multi-pass review 框架定義了輪 9（reader simulation）、輪 10（self-criticism），但這次我根本沒跑 —— 只跑了我臨時擬的 3 個 agent frame + grep。如果跑了輪 9（用讀者視角讀「這段在跟我說話嗎」），喊話類當場會 catch。這部分不能怪框架、是我跑了子集。

Design gap（框架本身的 frame 不夠）

但即使跑了輪 9、現有定義是「拿掉 code block 看論述能不能 parse」（聚焦自包含性）、沒有 register lens（這段在管理 / 評價 / 絕對化讀者嗎）。而且 register 類有兩個結構特性讓 keyword bank（輪 8）抓不到：

• 無穩定關鍵詞：第二人稱「你」誤命中 code 註解、祈使句式發散、訴諸群體形式多。
• 最依賴外部 cold-read：這次正是**使用者（外部讀者）**才抓到 —— 同一 reviewer 模擬讀者視角有限（per multi-pass 自承的 partial fix 限制）。

這部分要改框架：輪 9 擴入 register lens、標明 register 類「reader-sim 主、keyword bank 輔」。

沒這樣做的麻煩

只改框架：framework bloat、execution 習慣沒解

漏抓後直覺反應是「加 keyword / 加 frame」—— 因為這看得見、像進步。但若真正成因是 execution gap（沒跑輪 9）、加再多 keyword 都沒用（那些輪還是沒跑）。框架越加越胖、reviewer 還是偷跑子集。

只改執行：漏掉的整類永遠 catch 不到

反過來、若把 design gap 誤判成「我下次認真跑就好」、但框架根本沒有對應 frame —— 認真跑現有的輪也 catch 不到、同類問題每次都漏。

「加 keyword」是最誘人的假修法

加 keyword bank 條目成本低、立即有「補上了」的感覺。但它只解 design gap 的一個 sub-type（偵測層、且限有穩定關鍵詞的類）。對 execution gap（沒跑輪）、對 register 這種無關鍵詞的 design gap、它都無效 —— 容易讓人以為修好了、其實沒。

跟其他抽象層原則的關係

• #114 Multi-pass review 的 frame 顆粒度盲點：#114 處理的是 design gap 的一個面向（frame 不夠細、抽象規則沒展開成具體訊號）。本卡是上位 —— 在「改 frame 顆粒度」之前、先問「這次漏抓到底是缺 frame（design）還是沒跑 frame（execution）」。#114 預設問題在框架、本卡先驗證這個預設。
• #147 規範化跟自審是兩種認知任務：#147 是 execution 側的 sibling —— 「立了規範 ≠ 自己稿件能辨識」講的就是「有 frame 不等於有跑」。本卡把它一般化成「有 frame 不等於有跑（execution gap）」、並跟「根本沒 frame（design gap）」對立起來。
• #149 keyword bank 命中是候選、不是判決：#149 是另一個「兩層別混」的 pattern（偵測 vs 判定）。本卡（design vs execution）跟 #149（偵測 vs 判定）都在拆「review 失效的成因層」—— 修法都依賴先分層、再對症。
• #150-152 教材 register / framing 卡：這三張是本卡的觸發 case（漏抓的具體內容）。本卡是它們揭露的 review 流程層 教訓 —— 內容卡講「該怎麼寫」、本卡講「review 為什麼沒抓到、該改框架還是改執行」。

判讀徵兆

適用範圍與邊界

• 適用：review 流程的 retrospective（漏抓後檢討）、framework 演進決策（要不要加 frame / keyword）、self-review 品質檢討。
• 不適用：一次性短文 review（沒有「框架」可言、談不上 design vs execution）。
• 邊界：兩者不互斥、常同時存在 —— 本卡要的不是「二選一」、是「分別診斷、分別修」。誤把它當 either-or 會只修一半。

Self-case：本卡的觸發來源

本卡觸發於對 HOF / typedef 文章 的 review 失誤做 WRAP 檢討。使用者問「多輪審查設定是否需要調整」，WRAP 的 Consider the Opposite 步驟揭露：失敗不全是框架缺陷 —— 一半是我只跑了臨時子集、跳過框架既有的輪 9/10（execution gap）、一半是輪 9 定義聚焦自包含性、缺 register lens、且 register 類無穩定關鍵詞（design gap）。

對應本卡：若沒做這個拆分、最可能的反應是「再加幾個 keyword」（只解 design gap 的偵測 sub-type）、既沒解 execution gap（下次還是偷跑子集）、也沒解 register 的 reader-sim design gap。拆開後修法清楚：execution gap 靠「review 時真的跑完該跑的輪」（紀律、不改框架）、design gap 靠「輪 9 擴 register lens + 標明 external-reader 依賴」（改框架、下一步執行）。

本卡的論述源於 1 個觸發 case（git stash -u 筆記的 review、使用者指出尾端「重點」段沒有必要）、再以 1 次 content/ 全站掃描（309 個總結型段落、Go 模組 53 章樣本、見下方「blog 樣本掃描」段）驗證與擴充。具體限制：

• 「重點段」是這次出現的形式、不是唯一形式：同類補丁還有「一句話總結」「TL;DR」「小結」「劃重點」。判準不在標題名稱、在「這段是否只是重述前文已講過的內容」。
• 不是所有 summary 都是補丁：長篇 / 多章模組的導覽型 summary（串連各章、給路由）有獨立價值、不適用本卡。本卡針對的是「單篇短文尾端重述自己」這種發散善後。
• 修補有效性未獨立驗證：刪掉總結段後讀起來更聚焦、但「有沒有總結段」跟「讀者實際記憶留存」之間沒做使用者測試。

讀者使用本卡時、先判斷該 summary 段是「重述前文」還是「跨段路由 / 導覽」—— 前者套用、後者保留。

核心原則

教材把概念講清楚的責任落在正文、不落在尾端的總結段。 若一篇文章要靠「重點」段重述才能讓讀者記住、那訊號不是「需要總結」、是正文發散 —— 概念沒在它該出現的位置一次講清、被攤散在各段、所以尾端要再收一次。正確的回應是重組正文、不是補一個總結段替發散善後。

判準很簡單：刪掉總結段、看正文站不站得住。

• 站得住 → 總結段本就冗餘、刪掉是淨減負擔。
• 站不住 → 問題在正文組織、該重拆段落、不是靠總結救。

兩種結果都指向「不該留總結段」。總結段唯一看似合理的存在理由（怕讀者沒記住），恰好是正文設計不佳的徵兆 —— 用補丁掩蓋了該修的結構。

處理總結段內容：先分「提醒 vs 概念」

刪總結段的第一步是辨識段內每一條的性質，決定併回正文還是直接刪：

關鍵動作是「併回」而非「丟棄」：總結段裡常混著真正屬於正文卻被擠到尾端的概念（例如某設計選擇的理由）。把它移回該概念出現的段落、既刪了補丁、又補強了正文的「核心原則先行」。

沒這樣做的麻煩

補丁掩蓋結構問題、發散持續累積

留著總結段、等於接受「正文可以發散、尾端再收」。下一篇繼續發散、繼續補總結、文章組織能力不會進步。總結段是止痛藥、不是治療 —— 它讓「正文沒講清」這個真問題不痛、於是沒人去修。

讀者付兩次成本讀同一概念

重述型總結讓讀者讀第二遍已經懂的內容。懂的人覺得冗、沒懂的人靠重述也補不上（重述不會比正文講得更清）。兩種讀者都沒得到淨價值、只多付了 token。

概念價值被埋在補丁裡、正文反而缺角

總結段常混著本該在正文的概念（設計理由、邊界條件）。塞在尾端、正文對應位置反而缺了這塊 —— 讀者讀到正文時概念不完整、要讀到最後才補上。這違反「核心原則先行」、把該前置的概念後置成總結。

跟其他抽象層原則的關係

• #64 Feature 操作要跟 Source 同層合成：本卡是該原則在寫作層的同構。#64 講「filter / 操作要在 source 同層或更上游做、不在下游補」、本卡講「概念要在正文（source）講清、不在尾端總結（下游）補」。兩者共享「修在源頭、不在下游打補丁」的骨架 —— 總結段就是寫作版的 post-source patch。
• #150 教材用中性陳述、不對讀者喊話：兩卡常在同一段命中、但軸不同。#150 是字句層 / stance（「養成習慣」是祈使喊話）、本卡是結構層（整個總結段是組織補丁）。一個總結段可能同時是 #150 的喊話載體跟本卡的結構補丁 —— 修法也不同：#150 改句子 register、本卡刪整段並重組正文。
• #151 教材給技術理由、不替方案下品質評價：兩卡都在問「這段內容該不該留在教材」。#151 砍的是「自評誇飾」（不傳遞概念的品質 verdict）、本卡砍的是「重述總結」（不傳遞新概念的結構補丁）。共同判準：不貢獻新概念的內容、不論它讀起來多像收尾、都是負擔。
• #153 Review 漏抓先分 design gap 與 execution gap：本卡的「刪總結 vs 重組正文」是 diagnose 先於修法的同類動作。看到總結段別直接刪了事 —— 先用「刪掉正文站不站得住」診斷：站得住是冗餘（execution-side、刪即可）、站不住是正文發散（design-side、要重組）。診斷錯就會「刪了總結、發散的正文還在」。

判讀徵兆

適用範圍與邊界

• 適用：單篇文章 / 卡片尾端「重述自己」的總結段 —— 重點、小結、一句話總結、劃重點、TL;DR。這些地方若只是把前文再講一遍、就是發散善後。
• 不適用：跨章模組 / 長篇的導覽型 summary（串連各章、給下一步路由、列模組地圖）—— 它傳遞「結構關係」這個正文沒有的新資訊、不是重述。report/ 的 _index.md 路由段、教學模組的章節導覽都屬此類。
• 邊界：判別線是「這段傳遞新資訊（含結構 / 路由關係）、還是重述已講過的內容」。前者保留、後者刪。長度不是判準 —— 短文也可能有合理的路由段、長文也可能塞冗餘總結。
• 位置反轉的例外：前置摘要不是尾端重述：放在文首的摘要（frontmatter description、開頭一段 abstract）跟尾端重述性質相反 —— 它服務「讀者決定要不要讀、先建立全局框架」、在讀者還沒讀正文時提供導航價值。尾端重述則是在讀者讀完之後把已知內容再講一次、無導航功能。同樣一句「本文講 X 的三個取捨」、放文首是合理摘要、放文尾就是重述補丁。判別不只看「是否重述」、還看「相對正文的位置決定它服務的是導航還是回顧」。

blog 樣本掃描：三種變體與外科式修法

對 content/ 掃「小結 / 總結 / 結論」當標題的段落、309 個檔案命中。Go 教學模組是密度最高的樣本：53 章每章一個 ## 小結、但只有 10 個含「下一章」路由、其餘 43 個是純重述章節核心原則。這不是偶發、是模組層級的系統性習慣 —— 也讓「總結段=補丁」這個判讀有了規模證據。

樣本分成三種變體、各自修法不同：

兩個從樣本提煉的補充、修正了「整段刪」的過度簡化：

• 真實世界最常見的是混合型、不是純補丁：一段重述包著一句路由。對混合型套用本卡、修法是外科式（切重述、留路由 / 綜合關係）、不是整段刪。判別線下沉到「段內每一句」、不是「整段留或刪」。

• 系統性出現時在模組層級統一決定、不逐章補丁：當整個模組每章都有小結（Go 53 章），逐章判斷會反覆做同一決定。該在模組層級先定義「小結的責任」（只放跨章路由 / 跨章綜合、不放單章重述）、再一次套到全模組 —— 否則就是本卡反對的「為發散補補丁」在模組尺度重演。

  升格條件（候選獨立卡）：「smell 系統性出現 → 在模組 / 政策層級統一修、不逐實例補丁」這條、語意上正交於「總結=發散」、且可泛化到 cadence 同骨化（#122）、emoji、任何系統性寫作 smell —— 是 #64「修在 source」往「修法尺度要匹配問題尺度」的泛化。目前只有 1 個 instance（Go 小結）、按 #42 兩次門檻暫不抽卡（避免過早抽象 / framework bloat）。當第二個系統性寫作 smell 出現同樣「逐實例 vs 模組政策」張力時、即有 2 instance、抽成獨立卡。

• 綜合關係型是導覽型例外的近親、但要語意驗證：「三者層級不同」這種並置、若正文從未在同一處講過這個關係、就是新資訊（傳遞結構）、不是重述。判別問「這句陳述的關係、正文有沒有在某段一次講過」—— 沒有則保留、有則仍是重述。

Self-case：本卡的觸發來源

本卡觸發於 review git stash -u 筆記 時、由使用者指出尾端「重點」段沒有必要：

重點這一塊是沒有必要的、如果讀者需要他可以自己回頭確認、不用預設讀者需要重新提醒。如果我們的文章一定要寫重點才能讓讀者記住、表示我們的文章內容太過發散、這時候要考慮的是重新拆分組織文章內容、而不是為了自己文章的設計不佳又多補一個重點章節。

該「重點」段有三條：

1. 「開新功能幾乎一定有 untracked 檔案、要養成順手加 -u 的習慣」 —— 純提醒（養成習慣）、且跟「問題情境」段已講的重複。刪。
2. 「為何 Git 預設不收 untracked」 —— 有概念價值、解釋了 -u 為何要明確表態。併回「-u 是什麼」段、放在表格之後、讓設計意圖在概念位置一次講清。
3. 「記憶法：-u = untracked、-a = …」 —— 跟表格重複的重述。刪、把 -a 的範圍差異併進前述設計意圖段。

刪掉「重點」段後、正文（問題情境 → -u 是什麼含設計意圖 → 正確流程 → 替代做法取捨）仍完整、且因為概念併回正文反而更聚焦 —— 證明總結段本就是補丁、不是必要結構。

對應本卡：總結段的存在價值（怕讀者沒記住）恰好是正文發散的徵兆 —— 修法不是保留總結、是重組正文、把該前置的概念前置、該刪的提醒刪掉。

寫作規範的違規分兩類、判定性質根本不同。形式違規（emoji、編號、broken link、裸 URL、frontmatter 缺欄）可完全機械判定、命中即違規、該進工具鏈。register / 品味違規（核心概念前置、否定起手、喊話、誇飾、口語修辭）的判定有不可消除的品味核心、偵測可機械化但判定不可。

「不是 X、而是 Y」是 register 違規裡最隱蔽的一種、因為它的偵測可機械化（句型明顯、grep 抓得到）、這個「偵測可機械化」偽裝成「判定也可機械化」。被這個偽裝誤導、就會無限投入更精緻的判定方法（補 grep → 概念位置判準 → 行為測試）、而判定（這個否定在建立概念還是做對照）本質是品味判斷、始終在品味側、始終放水。

後續校正（見 #166 重點優先陳述是跨語言的資訊結構原則）：「不是 X、而是 Y」這個子集後來被釐清為資訊結構問題（重點後置）、不是純品味 —— 判定其實可操作（核心概念第一次正面出現在不在句首）、主解是強制執行重點位置判準、異源視角降為補充。本卡論的「品味核心 / 同源上限 / 異源為真防線」對喊話、誇飾這類無單一重點位置的 register 仍成立、但對「重點優先」這個可操作子集是過度推論。

為什麼 register 違規的判定不可機械化

判定要回答「這個句子讀起來對不對」、這是品味問題、品味需要一個會讀的主體去感受、沒有可機械化的判準能取代。「不是 X、而是 Y」的判定要區分兩種角色：

• 建立核心概念的否定（違規）：「外包一塊能力不是二元、而是有深度的」—— 核心概念「有深度」被擠到「而是」之後、句首先丟一個被否定的錯誤理解。
• 反例對照的否定（合規）：在明示反例段落裡、否定就是對照本體（見 #94）。

兩者 grep 命中長得一樣、語意角色相反。要判對、reviewer 得讀懂段落結構、感受核心概念的位置 —— 這是品味判斷。任何想把它機械化的嘗試都只是換個地方做品味判斷：「概念位置判準」要判斷哪句是概念句、「刪除測試」要判斷剩下的概念完不完整、終點都回到「這讀起來對不對」。偵測的可機械化掩蓋了這個事實。

同源自審的結構上限

更深一層的原因、解釋了為什麼再多輪 LLM 審查都跨不過：產出 register 違規的主體跟審查它的主體共享同一套文體直覺。「不是 X、而是 Y」是 LLM 高頻自產的定義句型、LLM reviewer 讀到它「讀起來自然、權威」、違規感不觸發 —— 作者的盲區跟 reviewer 的盲區是同一個。

這讓 register 違規的同源自審有結構上限。加 reviewer 數量、加審查輪次、換 frame、都在同一套文體直覺內打轉、跨不過盲區。要看出 register 違規、需要一雙「不共享作者文體」的眼睛。

這條上限是 #149（命中後判定會放水）跟 #147（立規範不等於自審執行）的共同根因：#147 的修法是「立規範當下轉 grep + sweep」、#149 的修法是「命中後用概念位置判定」、兩個修法都還在自動化側、對 register 違規都攔不住、因為判定的品味核心要異源的眼睛才感受得到。

理想做法

把違規先分類、再配對應的防線。

第一步：分類 —— 這個違規在哪一側

問一個判別問題：「這條規則的判定、是命中即違規（確定性）、還是要讀懂句子讀起來對不對（品味）？」確定性的進工具鏈、品味的進異源審查。emoji、編號、broken link 在確定性側；概念前置、否定起手、喊話、誇飾在品味側。

第二步：register 違規 —— 偵測機械化、判定靠異源

偵測仍用 grep、但定位是「曝光候選給異源視角抽查」、產出不是「自動判定違規」。判定交給文體異源的眼睛：

第三步：接受 100% 自動 catch 不可能

把 register 違規的審查目標設成「曝光候選 + 異源抽查」、而不是「自動判定 clean」。回報時誠實標「register 層靠異源抽查、未做窮舉自動判定」、不把同源自審的 clean 當成真 clean。

沒這樣做的麻煩

在錯的一側無限用力

把 register 違規當成自動化側問題、就會持續投入「更好的檢查方法」（補 grep、寫判準、做測試）、每次都改進一點、每次都還是放水 —— 因為判定始終在品味側。投入的努力跟結果脫節、看起來在進步、實際在原地。

同源 clean 製造虛假信心

跑完多輪 LLM 審查、回報「字句層 clean」、這個 clean 是同源盲區的產物、不是真 clean。比沒審更危險：沒審還知道沒查、同源審完誤以為查過了、register 違規帶著「已審查」標籤留在稿件裡。

規範卡越多、越以為夠了

blog 累積了 #94 / #147 / #149 一整套 register 審查原則、看起來防護很完整、反而讓人以為「照卡片做就夠」。這次的失敗證明：原則齊備、修法齊備、同源執行仍跨不過上限。原則的數量不等於防線的強度。

跟其他抽象層原則的關係

• #149 字句層 review：keyword bank 命中是候選、不是判決：#149 揭露「命中後判定會放水」這個現象、本卡是它的上層 —— 揭露放水的根因（判定在品味側、同源自審有結構上限）跟結構解（異源視角、不是更好的判定準則）。#149 的「概念位置判準」是好的判準、但它仍要同源 reviewer 執行品味判斷、本卡指出這一步有上限。
• #147 規範化跟自審是兩種認知任務：#147 講「立規範不等於自審執行」、修法是轉 grep + sweep。本卡補它沒覆蓋的：對 register 違規、grep + sweep 命中了、判定仍跨不過同源盲區。#147 解「自審有沒有做」、本卡解「自審做了、為什麼對 register 仍失效」。
• #82 字面攔截 vs 行為精修：本卡把 #82 的「字面 vs 行為」推到極限 —— 對 register 違規、連「行為精修」（讀者能不能驗證）都還是品味判斷、需要異源的讀者才感受得到。形式違規停在字面層即可、register 違規連行為層都需要異源。
• #95 Multi-pass review scope 要蓋同類風險區：#95 解 scope 軸（同類違規要 corpus-wide grep）、本卡解 source 軸（同類違規的判定要文體異源）。兩個一起才完整：grep 把候選掃出來（#95）、異源的眼睛判它違不違規（本卡）。這次三個 surface 鏡像內容共享同一違規句型、grep 掃得到、但同源判定全放行 —— scope 對了、source 沒換。
• #114 Multi-pass review 的 frame 顆粒度盲點：#114 解偵測層（展開成 keyword bank）、本卡指出對 register 違規、偵測層做好了、判定層仍需異源 —— frame 顆粒度再細、同源 reviewer 對品味違規仍有盲區。

判讀徵兆

適用範圍與邊界

• 適用：register / 品味類寫作規範（正向陳述、概念前置、喊話、誇飾、口語修辭、文體）的 review 流程設計；AI 輔助寫作的 self-review（最容易在 register 層同源放水）；multi-round-review 的 frame 與資源配置。
• 不適用：形式違規（emoji、編號、broken link、frontmatter）—— 這類確定性判定、進工具鏈即可、不需異源、本卡的「同源上限」不適用。
• 邊界：「同源自審有上限」不等於「同源自審無用」 —— 同源 reviewer 仍能抓形式違規、抓部分明顯的 register 違規；上限指的是「對 register 違規無法做到窮舉可靠」、所以要補異源、不是廢掉同源。也不等於「只能靠人」 —— 偵測機械化、對抗文體 reviewer、reader-simulation 都能降低對純人工的依賴、只是接受殘餘要異源抽查。

Self-case：本卡的觸發來源

本卡觸發於一次 backend 章節 + skill 的四輪 multi-round-review。流程是 12 個 LLM reviewer、4 輪、frame 涵蓋規範遵循 / 技術 / 一致性 / cadence / reader-simulation / title / self-application / steelman / outbound / cold-read / misuse / regression。Round 1-A 與 Round 3-A 都跑了 compositional-writing 的正向陳述 grep keyword bank、命中了三個 surface 的「不是 X、而是 Y」、全部判成「合規對照」放行、回報「字句層 clean」。

四輪結束、三個 PR 合併之後、使用者讀稿件、一眼指出「外包一塊能力不是二元、而是有深度的」是否定句型 + 概念後置違規。同一個違規在 0.22 章節、知識卡、skill principle 卡三個 surface 都存在、12 個 LLM reviewer 全漏、使用者一眼抓到。

對應本卡：register 違規的判定在品味側、12 個 LLM reviewer 共享文體直覺、同源自審跨不過盲區；使用者是文體異源的眼睛、所以一眼看到。這次失敗證明 #147 的「轉 grep + sweep」、#149 的「概念位置判定」、補 grep keyword bank —— 三個自動化側的修法疊起來、對 register 違規仍跨不過同源上限。結構解是把異源視角寫進流程、不是再疊第四個自動化側修法。

正向陳述優先的本質是資訊結構效率：讀者拿到核心概念的認知步驟越少越好。「不是 X、而是 Y」表達能力差、是因為它讓讀者先處理一個被否定的錯誤理解 X、才拿到正確的 Y —— 重點後置、多繞一步。問題的根本在資訊結構、不在中文特有的句型、也不在主觀品味。

這個校正很重要、因為它決定了解法的方向：把問題定位成「中文句型」、會去抓句型變體或換語言；定位成「品味」、會去靠主觀判定或異源視角；定位成「資訊結構效率」、才會去檢查「核心概念在不在最前」這個跨語言、可操作的判準。

證偽過的反例假設：「換語言能打破」

一個自然的假設：如果「不是 X、而是 Y」是 LLM 中文訓練語料的高頻行為、那換英文或日文思考就能打破。這個假設值得驗、但證偽了。

LLM 在三種語言都從語料學到對應的高頻版本、換語言不打破、英文甚至可能更嚴重。

這個證偽的價值不在「結論是否定的」、在它把問題釘到正確的層：如果這個句型跨語言都在、那本質就不在「某種語言的句型」、而在所有語言共享的資訊結構偏好（重點後置讀起來「優雅」、但效率次優）。

判別線：重點位置統一了對照句的判定

核心概念在不在句首、是判別對照句合不合規的單一判準：

判別是「核心概念在不在最前」、不是「否定的角色」（#149 的「概念位置」其實就是這個、本卡正名它為資訊結構的重點優先）、不是「對照刪不刪」（#94）、不是「句型」。一個資訊結構判準涵蓋全部對照句、且涵蓋所有重點後置變體（與其 X 不如 Y、不只 X 更 Y），而句型 grep 永遠枚舉不完。實證在這次的 POS lint pattern：連接詞清單擴了兩次（而是 → 加「— 是」→ 加「不在…而在」）、每次擴完就暴露下一個變體、仍漏第四個「不是 X、是 Y」頓號版；而「、是」頓號版誤判率高（「不是 A、是 B」多為正常列舉）、刻意不補進 pattern —— 正是判準（重點位置）優於窮舉（連接詞）的活證明。完整修法軌跡見 #167 修法是新違規的來源、且常引入同類變體。

這個判準可操作：對每個定義句、找核心概念第一次正面出現的位置、在句首就合規、被擠到「而是」之後就違規。它比「判斷這個否定是建立概念還是對照」客觀得多。

為什麼 LLM 系統性放水：高頻偏置

LLM 從語料學到「不是 X、而是 Y」是高頻、讀起來優雅的表達、於是它的「表達能力評價」把這個句型評為好。問題在高頻不等於資訊結構優 —— 這個句型高頻、是因為它在修辭上有對照張力、好寫好讀；它效率次優、是因為重點後置。兩件事獨立、而 LLM 的評價把前者（高頻 / 優雅）誤當後者（資訊結構好）。

這個偏置跨語言、且作者與 reviewer 共享（都是 LLM、學同一類語料）。所以 LLM reviewer 讀到這個句型覺得「自然、好」、跳過重點位置判準、走「讀起來優雅就放行」的捷徑。歸因是訓練語料的高頻偏置、比「文體盲區」這個說法更具體可檢驗。

主解：強制執行重點位置判準、異源為輔

本質可操作、所以主解是把重點位置判準變成不可跳過的機械步驟、不是靠品味、也不是只靠異源視角。

異源視角是補充、不是唯一解。它補兩種殘餘：強制判準仍漏的、以及無單一重點位置的 register 類（喊話、誇飾 —— 這類回到 #165 的同源上限）。對「重點優先」這個可操作子集、強制執行判準就能抓大部分、不必先跳到「不可機械化、只能靠人」。

存量候選的漸進判讀

把重點位置判準升進工具鏈（mdtools lint 的 POS-negation-lead 警告層、見 markdown-writing-spec 否定起手候選掃描段）之後、全 content/ 約 300 個重點後置候選一次曝光 —— 它們之前 silent、靠 review 記憶才偶爾 catch。曝光本身就是價值（候選在每次 lint 持續可見、不再靠記憶）、判讀則漸進進行：

• 不一次清倉：300 裡多數是合法對照（核心概念已先行、「不是 X、而是 Y」只是補充）或 meta / 引用（講此句型的卡與規範），真違規只是子集 —— 一次性全判 ROI 遞減。
• changed-set scoped 漸進：規則讓候選在每次 lint 持續可見、碰到含 POS 警告的檔時用上面三類判準順手判、真違規改重點先行。這是 markdown-writing-spec 位置引用掃描段與否定起手掃描段的存量處理原則。
• 本卡承擔這個漸進工作的 backlog：判讀協議（重點位置 + 三類處置）寫在這、未來遇到候選的人讀本卡就知道怎麼判、不需要另開記錄文件。report 卡比單純的記錄文件更有條理 —— 原則、判讀協議、落地狀態收在同一處。

沒這樣做的麻煩

在語言層找解、治不了跨語言的問題

把問題定位成「中文句型」、就會去補 grep 抓句型變體、或想換語言打破。句型 grep 枚舉不完、換語言不打破（證偽過）—— 兩條都在語言層用力、而問題在跨語言的資訊結構層。

把可操作問題誤診成品味上限

把「重點位置」這個可操作判準、誤診成「不可機械化的品味、只能靠異源」（#165 的過度推論）、就會放棄判準、過度依賴異源。實際上強制執行重點位置判準就能抓大部分 —— 這是把 execution gap（有判準沒執行）誤判成 design 上限（判準不存在）、正是 #153 警告的診斷錯誤。

高頻偏置讓「優雅」變成放行藉口

reviewer 用「這句讀起來優雅 / 自然」當放行理由、等於用高頻偏置覆蓋資訊結構判準。優雅與效率是兩件事、要分開問。

跟其他抽象層原則的關係

• #165 register 違規：偵測可機械化、判定要靠文體異源：本卡是 #165 的上層、並校正它兩個過度推論。#165 揭露「同源 LLM 漏 register 違規」這個現象、有價值；但它把解過度歸到「判定不可機械化、異源是唯一結構解」。本卡指出「不是 X、而是 Y」這個子集的本質是可操作的資訊結構判準（重點位置）、主解是強制執行、異源降為補充。#165 對喊話 / 誇飾這類無單一重點位置的 register 仍成立、本卡聚焦「重點優先」這個可操作子集。
• #149 keyword bank 命中是候選、不是判決：#149 的「概念位置判定」其實就是重點位置、本卡把它正名為「資訊結構的重點優先」、並指出它跨語言、可操作。#149 停在「用概念位置判定」、本卡補「為什麼判定會跳過（高頻偏置）」與「怎麼強制執行」。
• #167 修法是新違規的來源、且常引入同類變體：本卡是靜態原則（句型枚舉不完、判準是重點位置）、#167 是它的過程面 —— 修法 / 補 pattern 的動作反覆暴露同類變體（這次 POS pattern 連接詞清單擴兩次仍漏第四個的軌跡），收斂靠本卡的重點位置判準、不靠窮舉連接詞。
• #94 正向改寫要保留對照論據：本卡統一 #94 與 #149 的判別線。#94 的「X、不是 Y」是重點先行（合法）、#149 的「不是 X、而是 Y」是重點後置（違規）—— 兩者的判別線是同一個「重點位置」、不是兩條獨立規則。
• #153 Review 漏抓先分 design gap 與 execution gap：本卡是 #153 的一個實證 —— #165 把「reviewer 有判準（概念位置）卻沒執行」（execution gap）誤診成「判定不可機械化」（design 上限）。本卡校正回 execution + 可操作判準。
• #82 字面攔截 vs 行為精修：重點位置是行為層判準（讀者拿到核心要幾個認知步驟）、比字面層（grep「不是…而是」句型）更本質、且跨語言。grep 抓字面句型、重點位置判讀者的認知成本。

判讀徵兆

適用範圍與邊界

• 適用：對照句 / 定義句的重點位置（不是…而是、與其…不如、不只…更）；跨語言寫作；技術 / 教學文（重點優先最該成立的 surface）。
• 不適用：敘事 / 懸念類寫作（先鋪陳後揭重點是設計、不是缺陷）；無單一「重點」的純列舉。
• 邊界：「重點優先」是可操作判準、但「哪個是重點」仍需理解內容 —— 可操作指「一旦識別重點、位置判定客觀」、不是「全自動無需理解」。對喊話 / 誇飾這類非重點位置的 register、回到 #165 的異源補充。

Self-case：本卡的觸發來源

本卡觸發於 #165 寫完之後、使用者的追問：如果「不是 X、而是 Y」是 LLM 中文訓練出來的行為、換英文或日文思考能不能打破？這個假設的證偽（英 / 日文同樣高頻、英文修辭傳統尤甚）、把問題從「中文句型」釘到「跨語言資訊結構」。使用者並指出真需求是「正面語境描述 + 重點優先陳述」、本質是這個句型表達能力差（重點後置）、不是對抗特定句型。

這校正了 #165 的兩個過度推論：本質可操作（重點位置、跨語言）、不是不可機械化的品味；主解是強制執行重點位置判準、不是異源唯一。記錄這次「把可操作問題誤診成品味上限」的校正 —— 它跟同批 retrospective 第一輪「把問題過度工具化（補 grep）」對稱、兩次都偏離中道（一次過度工具化、一次過度玄學化）、由使用者連續追問拉回（見 memory root-cause-over-toolification）。

本卡是一次 multi-round-review 漏抓的 self-retrospective 抽出。限制：樣本為 1 次 review（til/terms 14 卡），「知情 vs 冷讀」二分基於單次觀察；修法（補冷讀 frame）的有效性已由同批內容的後續冷讀驗證初步確認，但未跨多批驗證。讀者把它當「review 讀者模擬的一個必查維度」，不當已驗證流程。

核心原則

多輪審查模擬讀者時，要區分兩種讀者，分開跑：

• 知情讀者（旅程 frame）：讀完全部、依學習路線走，看入口判讀與內容門檻。
• 冷讀者（零脈絡單卡落地 frame）：假裝經搜尋或他人貼連結，直接落在單一篇章，沒讀過其他篇與索引。

關鍵差別：知情 reviewer 會自動腦補脈絡，因此結構性看不見「洩漏撰寫者預設前提的行話」——未定義就出現的「家族」「上述」「如前所述」「本文前面提到」。只有零脈絡冷讀者會立刻問「這裡突然冒出的 X 是什麼」。

原子化 / Zettelkasten / glossary / 任何可被直連或搜尋單獨抵達的內容，冷讀 frame 為必備，不可只靠旅程 frame。

情境

til/terms 是一組 14 張互連的術語卡。經 3 輪多輪審查（含「讀者旅程」frame），三個 reviewer 全給 A、零必修。但每張卡都用「連到家族 / 概念家族」這個只有撰寫者懂的詞——讀者從搜尋落在單卡時，根本不知「家族」指什麼。知情 reviewer 讀完全部後腦補了「這是一組詞」，沒察覺這個洩漏。

理想做法

把 Reader simulation 拆成兩個子 frame：旅程（知情讀者走路線）與冷讀落地（單卡零脈絡）。冷讀 frame 逐篇問三件事：我知道為何讀這篇嗎？有沒有未在本篇定義的預設脈絡詞？我能不能從這篇找到回路？原子內容兩個 frame 都要跑。

沒這樣做的麻煩

只跑旅程 frame，知情 reviewer 全 A 放行，行話會留到讀者冷讀單卡時才卡住——而那時內容已發佈，回報後得回頭改全部卡。把「讀完全部的 reviewer 覺得通順」當成「冷讀者也通順」，是把 informed 的腦補誤當成內容自包含。

判讀徵兆

• 內容是原子 / 可被搜尋或直連單篇落地（術語卡、glossary、知識卡）。
• reviewer 是「讀完全部」才判讀旅程，沒人模擬「只讀這一篇」。
• 文中出現「家族 / 本盒 / 上述 / 如前所述 / 前面提到」這類需要前文才懂的詞。

本檢討已回饋到 multi-round-review skill（Round 2 新增 B′ 冷讀 frame）。寫作順序上 skill 修改先於本報告，屬例外；正序是報告（來源）→ skill 改進 → 下游。

本卡抽自一次術語卡撰寫的檢討（til/terms 14 卡）。限制：單一案例、單一內容類型（跨領域術語）；「議題 hub + 原子卡」兩層結構對其他內容類型的適用性未驗證。與既有 教材完整性要用讀者旅程驗證 區分——那談課程級的學習路線，本卡談單張原子筆記的進入動機與其上層議題。

核心原則

承載知識的原子筆記不是字典條目。字典回答「這個詞是什麼」；承載知識的卡要回答「你在討論什麼、撞到什麼問題，才需要這個知識」。

撰寫者有預設的情境與前提，讀者沒有。所以每張原子卡（或它的上層）要提供進入動機：從情境進入，而非劈頭給定義。具體做法是建一層議題 hub——以讀者會遇到的問題為標題（「測試紅燈不一定是真的壞」「告警太多反而沒人看」），討論議題、再分流到底下的術語卡；術語卡頂部回指它出自哪個議題，讓搜尋直接落地者也有回路。

情境

til/terms 的術語卡初版，每張都從定義開頭：「alert fatigue 指誤報太多、人對告警麻木……」。內容正確，但讀者不知道自己為什麼會需要這個詞、何時會撞到——卡片成了字典。

理想做法

為每個分支建議題 hub（情境入口），從「你遇到什麼問題」進入、再導向該讀的術語卡；術語卡頂部加一行回指議題（「這個詞出現在『X』這個問題裡」）。形成「議題 hub（情境）→ 原子卡（定義）」兩層，讀者由動機而非定義進入。

沒這樣做的麻煩

卡淪為字典：讀者沒有觸發點，搜尋落地後讀完仍不知這對他有何用，知識無法在「對的時機」被取用。承載知識的內容若只有定義層、缺議題層，就退化成可被任何字典取代的條目，失去 blog 累積知識的價值。

判讀徵兆

• 卡片開頭是「X 指……」的定義句，沒有情境鋪陳。
• 問「讀者為什麼要讀這張卡」答不出來，或答案是「為了知道定義」。
• 一組原子卡彼此互連，卻沒有上層的議題導讀帶讀者進入。

本卡抽自一次三篇 macOS 系統管理文章的多輪審查。審查修完 32 項 finding 後，作者發現 description 雖符合格式規範（30-150 字、非空），語意卻只是摘要——未來回顧列表時無法判斷「何時該重讀」。限制：單一案例（操作型文章），其他類型（教學模組、report 卡、知識卡）的 description 可能有不同的 recall 結構。

核心原則

文章的 description 欄位是寫給未來自己的 recall trigger，不是寫給搜尋引擎的摘要。它要回答的問題是：「我在什麼情境下、遇到什麼問題，會需要回來讀這篇？」

類比：Claude Code skill 的 description 讓系統在對話中自動判斷「要不要載入這個 skill」。文章的 description 讓未來的自己在掃列表時自動判斷「要不要進去讀」。兩者目的相同——降低 recall 的認知成本。

摘要式 description 只回答「這篇在講什麼」（內容索引）；recall trigger 回答「你在什麼情境下需要這篇」（情境索引）。前者是被動的——搜尋命中後才看；後者是主動的——掃列表就能決定。

情境

三篇 macOS 文章（新機設定 / 磁碟診斷 / App 佔用報告）的 description 寫法：

• 原本：「從一台 30G 餘裕在幾小時內歸零的 Mac，記錄一套先看快照、再用實際佔用排查的磁碟診斷順序……」
• 問題：這是內容摘要——讀者已經知道要找「磁碟診斷」才會搜到它，description 只重述他已預期的內容，沒有增量資訊。
• 理想：description 應該告訴未來的自己「你什麼時候會需要回來」——例如「磁碟莫名滿載時的排查起手順序、避開 sparse 假大小陷阱、以及用 tmutil 判讀快照是否為元兇的方法」。

理想做法

description 撰寫時問自己三個問題：

1. 我未來會在什麼情境下需要這篇？（觸發條件）
2. 這篇給我的關鍵判讀 / 操作是什麼？（帶走的能力）
3. 不讀這篇我會踩什麼坑？（省下的試錯）

三者至少涵蓋一個。格式不重要，重要的是 description 讀完後能判斷「現在要不要進去」。

反例——以下句型通常是摘要不是 trigger：

• 「記錄了 X 的過程」（日記式）
• 「介紹 X 的做法」（教科書式）
• 「從 X 事件整理出 Y」（報告式）

這些句型把 description 當後設描述（meta-description of the article），而不是情境描述（description of when you need it）。

寫法準則：精準、無假設、無修辭

description 給人判斷也給機器（AI）判斷，每個 token 都要有資訊量。三個不要：

1. 不要操作細節——指令、參數、具體步驟留在內文。description 幫人決定「要不要點進去」，不是把文章壓縮塞進來。
2. 不要假設前提——「想不起來」「卻發現」「卻不確定」「不知從何下手」這些描述讀者的困境，不是資訊。直接說用途。
3. 不要情緒修辭——「別被騙」「打架」「空轉」「踩坑」這些不精準。用事實陳述取代。
4. 不要內嵌數字——「三項基礎建設」「6 段結構」「兩個陷阱」把成員數烤進 description，內文增刪就要同步改。description 描述文章的功能（解什麼問題），不描述文章的結構（幾段幾項）。理想的 description 無論內文怎麼調整都不用變動。同 #156 集合命名不內嵌數量。

對比：

150 字上限不是要塞滿的配額。短能到位就短。

沒這樣做的麻煩

• 列表頁的 description 變成一片「記錄了…」「整理出…」的重複句型，掃不出差異，每篇都要點進去才知道需不需要
• 日後同類情境再發生時，想不起來自己寫過、重新搜或重新踩坑
• blog 的知識累積效益被 recall 成本吃掉——寫了等於沒寫

判讀徵兆

• description 的主詞是「本文 / 這篇 / 記錄」→ 可能是摘要不是 trigger
• description 刪掉後，只看 title 就能猜出 description 的全部內容 → 沒有增量
• 掃列表時無法在 3 秒內判斷「這篇跟我現在的問題有沒有關」→ trigger 失敗

跟其他原則的關係

• #169 原子筆記要有向上的議題入口：同根因——讀者（含未來的自己）需要「情境入口」而非「定義入口」。#169 談卡片正文的進入動機，本卡談 frontmatter description 的進入動機，是同一原則在不同 surface 的體現。
• #131 教材完整性要用讀者旅程驗證：讀者旅程的第一站是列表頁的 description——旅程驗證如果從「已進入文章」開始，就跳過了「要不要進入」的判斷點。
• #159 入口分流要放在詞彙牆之前：description 是文章的入口分流欄位，分流依據應是讀者的情境而非文章的內容結構。

定義型文件（規則、規格、常駐名單——陳述「什麼成立」的文件，相對於報告、日誌這類記錄「當時發生什麼」的文件）中的冗餘列舉和描述性數字是撰寫過程中的推理殘留——作者需要先計算範圍和數量來確認定義正確，但這個計算過程不該留在最終文件裡。判斷標準：如果拿掉列舉或數字，讀者對定義的理解不受影響 → 刪除。

下面兩個層次的殘留是觀察到的 pattern：

列舉在定義型文件中也有合理用途：當列舉本身就是定義（封閉 enum、有限狀態機的狀態集、HTTP 方法集），列舉本身就是被定義的對象。區分方式：列舉是在重述已由其他機制決定的範圍（冗餘）、還是在建立範圍（定義）。

同理，數字分兩種：描述性數字報告現狀（「目前有 9 個函式」），程式碼一變就過時；規範性數字規定目標值（「P99 < 200ms」「委員固定 7 人」「MAX_DEPTH=3」），是被定義的對象，該保留。

論述基礎與限制

本卡的論述基於 2 個 case（parallel-evaluation SKILL.md 常駐委員定義 + W3-008 分析報告）抽出來的觀察，每個子論點（列舉 / 數字）各只有 1 個 case 支撐。具體限制：

• 「列舉」指的是定義型文件中的冗餘列舉（如「所有情境（A-G）」），不包含報告格式範本中的 placeholder（如「情境: [A-G]」）——後者是填空欄位、不是定義；也不包含本身就是定義的封閉列舉（如 enum 成員清單）
• 「數字」指的是描述性計數（如「9 個函式」「428 行」），不包含規範性數字（如「MAX_DEPTH=3」「P99 < 200ms」）——後者是設計決策或 SLA 目標、不是統計快照
• 推理殘留不限於 AI 寫作：兩個 case 都來自 AI 生成的文件、AI 的生成順序可能讓這類殘留更常出現（見下方觀察），但人類作者在撰寫定義時同樣會先列舉確認再寫結論、忘了刪除中間產物

觸發案例

Case 1：常駐委員定義的冗餘列舉

parallel-evaluation SKILL.md 常駐委員表格寫了「所有情境（A-G）無條件加入」。「所有情境」已是完整定義，「（A-G）」在語意上重複——拿掉後讀者理解不受影響。留在文件裡則變成維護債務：新增情境 H 時「（A-G）」過時，讀者可能誤判 H 不含。

修正：刪除「（A-G）」。「所有情境無條件加入」自動涵蓋未來新增的情境。

Case 2：分析報告的數字快照

W3-008 分析報告寫了「duplicate_detection 群組 9 個函式、428 行」。這是分析時的統計快照、作為報告紀錄合理。但如果這些數字被寫進 ticket 驗收條件（「duplicate_detector.py 含 9 個函式」「create.py 行數減少約 428 行」），重構過程中任何函式增減都會讓驗收條件失效。

判讀：分析報告中的數字 → 保留（紀錄）。驗收條件中的描述性計數 → 改用結構性斷言（「所有 duplicate 相關函式已移至新模組」「既有測試通過」）。

AI 生成的順序觀察

兩個 case 都來自 AI 生成的文件。AI 的生成順序是先推理 → 再生成文字——模型在寫「所有情境無條件加入」之前，內部已驗證了 A 到 G 都涵蓋，列舉是推理的副產物被寫進生成的文字裡。同理，AI 在寫函式列表時傾向先數數量再列內容（「9 個函式：_tokenize, …」），數量是為了自我驗證完整性，但讀者只需要函式列表本身。

人類作者在撰寫定義時也會先列舉確認涵蓋範圍、AI 是否讓此模式更頻繁出現仍待更多樣本驗證（見限制段）。無論成因，判準相同：拿掉後讀者理解不受影響 → 刪除。

判斷決策表

驗收條件的判斷依據是被測屬性是否隨重構變動。函式名稱清單在重構後仍可驗證（名稱沒變、只是搬家），但行數和函式計數會因任何增減而失效——改用結構性斷言（「所有 X 相關函式已移至新模組」）讓驗收條件跟重構過程解耦。

真實文件常混合定義段與分析段（如 SKILL.md 同時有規則定義和設計紀錄），分類單位是段落而非整份文件——同一份文件內的定義段套用刪除判準、分析段保留數字。範本 placeholder 同理，它是填空欄位、不是定義。

跟其他原則的關係

• 讀者不需要知道的資訊不該出現在最終文件 — 同根原則的兩種表現：該卡處理 meta 動機殘留（「為什麼寫這篇」）、本卡處理推理過程殘留（列舉和數字）。兩者共用「拿掉後讀者體驗變不變差」的判準
• 適用範圍要展開成 file enumeration — 鏡像關係：該卡主張「適用範圍要 enumerate」、本卡主張「定義型文件的冗餘列舉要刪」。取決於文件型別——scope 文件需要 enumeration 確保執行時不遺漏、定義型文件的範圍已由定義本身表達
• 集合命名用角色、不內嵌數量 — 同原則在不同層面：前者處理命名層（「六大原則」的數字是成員清單的衍生值）、本卡處理正文定義層（「9 個函式」的數字是程式碼的衍生值）。兩卡共享「外部凍結數字可留」的邊界（前者的 SOLID / OWASP 對應本卡的 SLA / 設計常數）
• 便利驅動的寫法會偏離意圖 — 上位原則：列舉殘留是「寫的時候方便（先算再寫）、讀的時候多餘」的具體實例

本卡抽自 infra 教學模組的寫作 retrospective。21 篇文章初稿完成後，入門層文章（「個人專案到團隊服務」「一台機器到三個環境」）和溝通層文章（「給非工程人員的 infra 說明」）採用了宣導式框架（故事線導入、辦公室比喻、「跑得好好的」語氣），經作者 review 判定不適合目標讀者，重寫為「補足專業人士經驗缺口」的框架。限制：evidence 來自單一教學模組的一次重寫週期，跨領域適用性未驗證。

核心原則

技術教材的讀者是在特定領域缺乏經驗的專業人士，不是完全不懂的外行人。他們有系統思考能力、理解風險與成本、能處理抽象概念，只是沒有經歷過這個領域的具體情境。

寫法的差別在於進入方式：

情境

infra 教學模組的入門層文章原本採用宣導式框架：

• 「一台機器跑得好好的」— 預設讀者沒想過為什麼需要多環境
• 「個人專案到團隊服務：infra 在哪裡出現」— 用 side project 故事引導讀者「發現」infra
• 「用辦公室理解 infra」— 用辦公大樓、門禁卡、資產清冊比喻 VPC、IAM、state

這些框架的問題是它們預設讀者既不知道 infra 存在、也無法理解技術概念。但教材的目標讀者是專業工程師（缺 infra 經驗但有系統思考能力）和專業決策者（缺技術細節但懂營運風險）。宣導式語氣對這兩類讀者都是失配。

理想做法

對工程師讀者

直接描述情境和操作需求，不用故事線包裝。不說「跑得好好的、直到有一天…」，而說「單機環境在需要測試環境時會遇到三個操作問題」。讀者有能力從情境描述中自行判斷這跟自己的關聯。

每個概念用「它解什麼問題、不管理時的後果」框架帶入，不用「你可能沒注意到，其實你已經在用…」的發現式框架。後者暗示讀者對自己的工作環境不熟悉。

對非工程決策者

減少專業術語、讓討論的情境從簡單到複雜遞進，而非大量使用比喻。比喻的問題是它只傳遞形狀、不傳遞嚴重性 — 「VPC 像辦公大樓」讓人理解隔離的概念，但不讓人理解隔離失敗時的商業代價。從管理層面解釋「會發生什麼事、為什麼要避免、發生了怎麼處理」比從技術層面解釋「這個元件是什麼」有效。

決策者需要的資訊是：這個風險的量級（影響多少客戶、停多久、多少錢）、補救的成本曲線（現在做 vs 半年後做的差距）、以及投入的時間框架。這些都是他們熟悉的決策維度，用這些維度講就好。

沒這樣做的麻煩

宣導式寫法的具體代價：

• 可信度損失：工程師讀到「你可能不知道」時，如果他其實知道（只是沒做過），教材在他心中的權威性立刻下降。一旦開頭失去信任，後面的技術判準也會被打折。
• 比喻阻礙深度理解：讀者記住了「VPC 像辦公大樓」，但當他需要判斷 CIDR 該切多大、需不需要跟其他 VPC peering 時，比喻反而成為思考的障礙 — 辦公大樓沒有地址空間的概念。
• 推動失效：infra 推不動的原因是「提案語言跟決策者語言對不上」，不是「決策者太笨聽不懂」。把溝通問題歸因成理解力問題，會導致越比喻越多、越比喻越離題。

判讀徵兆

寫教材時如果發現自己在用以下句型，代表可能掉進了宣導式框架：

• 「你可能沒注意到…」「你可能不知道…」— 預設讀者無知
• 「想像一下…」「把 X 想成 Y…」— 用比喻替代直接說明
• 「跑得好好的」「聽起來很複雜」— 用語氣管理讀者情緒
• 「其實很簡單」「說穿了就是」— 降低複雜度的假象

替代方式：直接描述情境、列出操作需求、說明不做的後果。讀者有能力從事實中得出判斷。

跟其他抽象層原則的關係

• → #165 register 違規需要跨文體視角：宣導語氣是一種 register 問題 — LLM 自然傾向「對讀者友善」的語氣，自審時很難察覺它已經偏向宣導
• → #166 重點先行是跨語言的資訊結構：宣導式框架常把重點藏在故事線之後（「跑得好好的…直到…」），經驗補足式直接把操作需求放句首
• → 教材用中性陳述、不對讀者喊話：宣導語氣跟喊話是相鄰問題 — 都源自「讀者需要被管理」的隱含假設

本卡抽自 infra 教學模組的管理層視角掃描。22 篇技術文章完成三輪審查後，掃描「管理層會問什麼」發現 10 處缺口，集中在成本量級和時程估算。限制：evidence 來自單一教學模組；成本數字（AWS 定價）有時效性，寫入教材後需要維護。

核心原則

技術教材的讀者通常需要向上彙報：為什麼要做這件事、要花多久、花多少錢、做完怎麼知道有效果。如果教材只講技術機制（怎麼寫 HCL、怎麼設 IAM），讀者學會了做法卻沒有素材向管理層說明，結果是做法正確但推不動——因為管理層沒拿到他們決策需要的資訯。

管理層需要的資訊有四類，跟技術段落的位置關係明確：

情境

infra 教學模組的 22 篇文章完成三輪寫作審查（compliance / cadence / steelman）後，從管理層視角掃描發現：

• NAT per-AZ vs 共享的段落講了可用性取捨，但沒說每個 NAT Gateway 月費約 $32——管理層看不到這筆錢的量級
• 環境拆分的 retrofit 路徑講了操作步驟，但沒給時程估算——管理層問「要多久」時工程師得另外估
• tagging 講了為什麼要標，但沒說怎麼量化進度——管理層沒有可追蹤的指標
• 跨帳號策略講了 SCP 怎麼設，但沒標記這是需要 CTO 對齊的決策——工程師可能自己決定了影響全組織的設定

這些缺口的共同模式是：技術內容本身完整，但缺少讓讀者「帶出去用」的彙報素材。

理想做法

在技術段落旁邊嵌入管理層資訊，用 1-2 句帶過量級，不獨立成段。嵌入而非集中的理由是：工程師讀到技術取捨時，同時拿到彙報素材，不需要翻到另一篇文章去找對應的商業論證。

成本用量級而非精確數字。「每個 NAT Gateway 月費約 $32」比「$31.54/月」有用——量級讓管理層判斷這是百元級、千元級還是萬元級的決策，精確數字會隨定價調整而過時。

時程用範圍而非單點。「1-2 週」比「10 天」誠實——infra 工作的時程變數主要來自 stateful 資源的數量和 drift 的嚴重度，這些在動工前無法精確預估。

進度用可查詢的指標。「缺 tag 資源數 / 總資源數」比「我們在做 tagging」可追蹤——管理層需要的是趨勢線，不是狀態報告。

沒這樣做的麻煩

• 推動卡在溝通：工程師學會了怎麼做 IaC，但在預算會議上說不出「導入要 2-3 天、第一個里程碑是一條指令重建環境」，管理層聽到的是一個沒有時間框架的技術提案
• 成本決策沒有量級感：multi-AZ RDS 費用翻倍、NAT per-AZ 三倍固定費——這些取捨在技術上有道理，但管理層需要知道「翻倍是從 $50 到 $100 還是從 $5000 到 $10000」才能判斷值不值得
• 進度不可見：infra 工作的中間產出（state 設好了、第一批資源 import 了）對管理層不可見，看起來像「花了兩週什麼都沒產出」。有量化指標（覆蓋率從 40% 到 70%）才能讓進度可追蹤

判讀徵兆

寫技術教材時，對每個取捨段落問兩個問題：

• 「讀者的老闆會問什麼？」——如果答案是「多少錢」或「多久」而段落裡沒有，就是缺口
• 「這個決定影響範圍多大？」——如果影響跨團隊或跨帳號，標記為需簽核的決策點

成本數字寫入教材後要標明是量級參考而非精確報價，避免讀者直接拿去做預算。雲端定價會變，量級通常穩定——$30/月級的服務不太會跳到 $300/月。

跟其他抽象層原則的關係

• → 讀者是缺經驗的專業人士、不是外行人：本卡是該原則的延伸——讀者是專業人士，他們的工作流程包含向上彙報，教材應該支援這個流程
• → 跨專業溝通用情境遞進、不用比喻堆疊：管理層資訊用量級和範圍表達，不用比喻——「月費約 $32」比「大約一頓飯的錢」精確且專業
• → infra 投資的商業論證：該文集中處理商業論證，本卡講的是把商業素材分散嵌入技術段落，兩者互補

本卡抽自 infra 教學模組的完整生產週期 retrospective。43 篇文章 + 21 張知識卡經歷三輪多輪審查（compliance / cadence+冷讀 / steelman+outbound），審查通過後使用者連續指出六個 review 未 catch 的問題，每個都導致大量修改。限制：evidence 來自單一教學模組的一次完整週期，盲點清單可能不窮盡。

核心原則

多輪審查框架的所有 frame 從「已寫的內容」出發（inside-out）：字句層看已寫的字、cadence 看已寫的結構、fact-check 看已寫的事實、steelman 看已寫的論述。缺的是從「讀者的完整需求」出發的 frame（outside-in）：讀者是誰、讀者從哪裡來、讀者讀完後要做什麼、讀者搜尋什麼問題。

inside-out 能保證已寫內容的品質，outside-in 才能發現「應該寫但沒寫」的缺口。兩者的盲區正交：inside-out 的盲區是缺口（看不到不存在的東西），outside-in 的盲區是細節（看不到已寫內容的字句問題）。完整的審查需要兩者交替。

六個盲點

一：宣導語氣通過三輪審查

三輪審查判定文章 clean，使用者指出「一台機器跑得好好的」「辦公大樓比喻」是對專業讀者的失配後，14 處需要重寫。

keyword bank 的設計對象是字面違規。宣導語氣的問題在 register——用教導外行人的姿態對專業人士說話，字面上每個字都合規。reviewer 跟作者共享同一套文體直覺，都覺得「用故事帶入」是好的教學手法，同源盲區讓整批宣導語氣被合理化放行。

缺的 frame：reader-persona register 適配——指定具體讀者角色，問「這個人讀到這段會覺得被低估嗎」。

二：管理層彙報資訊缺失

所有 reviewer 檢查了技術正確性和寫作規範，沒有一個問「讀者讀完後能不能跟老闆說明為什麼要做、要花多久」。使用者提出後掃描出 10 處成本/時程缺口。

review frame 全部從「內容品質」出發，沒有從「讀者的下游任務」出發。技術文章的讀者不只要「學會怎麼做」，還要「能向上彙報為什麼做」——後者是讀者的工作流程，品質導向的 review 結構性看不到。

缺的 frame：downstream-task 審查——問「讀者讀完後的下一個動作是什麼？他需要什麼素材？」

三：接手 vs 自建是不同情境

模組負一定位為「還沒有 infra 的手動環境」，所有 reviewer 都接受了這個前提。使用者指出「接手前人的專案」是完全不同的操作情境後，獨立成一個橫切模組。

review 的 scope 是「已寫的內容對不對」，不質疑結構本身的覆蓋範圍。steelman reviewer 問的是已有文章的論述有沒有漏洞，不是教材的讀者群有沒有被遺漏的情境。

缺的 frame：persona-coverage 審查——列出目標讀者可能進入教材的情境，檢查每個情境是否有對應入口。

四：操作步驟缺工具指引

文章寫「拍下現況」「匯出資料庫」，reviewer 確認了邏輯正確性。使用者問「用什麼拍？怎麼拍？」後才發現停在 WHAT 層、沒到 HOW WITH WHAT 層。

fact-check reviewer 驗證「描述是否正確」，不是「描述是否可執行」。「用 FTP 下載整站存進 Git」事實正確，但讀者照做時需要知道用哪個 FTP client、大檔案怎麼處理。

缺的 frame：executable-walkthrough 審查——假裝讀者從零照做，每步問「下一個動作是打開什麼軟體、輸入什麼指令」。

五：概覽級深度不拆分

350 行文章涵蓋四個面向，reviewer 認為「結構完整」。使用者指出「資料庫備份和安全管理其實都是大問題」後拆成 5 篇。後續又在 8 個模組發生同樣的拆分。

reviewer 評估「這篇文章本身好不好」，不是「搜尋特定問題的讀者能不能找到足夠深度的內容」。一篇涵蓋四面向的文章通讀體驗良好，但搜尋「共享主機 MySQL 備份」的讀者需要專題文章。

缺的 frame：search-landing 審查——列出讀者可能搜尋的具體問題，檢查每個問題能不能落在聚焦的文章上。跟 cold-read (B’) 相關但不同——B’ 看「落地後讀不讀得懂」，這裡看「能不能落地到足夠聚焦的內容」。

六：讀者定位未預設

「讀者是缺經驗的專業人士」這個原則在文章寫完、審查完、使用者反饋後才抽出來。它影響了語氣、比喻策略、管理層溝通——幾乎所有後續大修都源自這個原則。但它不在任何 reviewer prompt 裡。

寫作規範定義了「怎麼寫」的規則，沒有定義「寫給誰」——讀者定位被當成隱性決定。LLM 預設用「教外行人」的姿態寫教學內容，這個預設不被 review 挑戰，因為 reviewer 也共享同一個預設。

這不是 review frame 的問題——是生成端的前提缺失。每個教學模組在第一篇文章生成前就應該顯式聲明讀者定位。

理想做法

在現有 inside-out review 框架之外，補五個 outside-in frame：

生成端的修正：每個教學模組在撰寫前顯式聲明「讀者定位文件」（一段話描述目標讀者的背景、已有能力、缺的經驗），讓生成和 review 都有可檢查的基準。

沒這樣做的麻煩

六個盲點的修法總工程量遠超預防成本：14 處宣導語氣重寫 + 10 處管理層資訊補充 + 11 篇接手維運新文章 + 全模組工具補充 + 12 篇子文章拆分 + 3 篇入門/溝通層重寫。如果讀者定位在第一篇文章前就聲明、outside-in frame 在 Round 1 就跑，多數修改可以在初稿階段就避免。

判讀徵兆

review 完成後如果使用者的第一個反饋是關於「內容缺口」而非「內容品質」，代表 review 框架偏向 inside-out。inside-out 的 review 報告 clean 只代表「已寫的內容沒問題」，不代表「該寫的都寫了」。

跟其他抽象層原則的關係

• → 讀者是缺經驗的專業人士、不是外行人：盲點一和六的直接修法
• → 技術教材要內嵌管理層可彙報的資訊：盲點二的直接修法
• → 跨專業溝通用情境遞進、不用比喻堆疊：盲點一的溝通層修法
• → #148 跨輪 review 停止訊號：本卡揭露的是「停止訊號齊備但覆蓋不完整」的情境——frame 涵蓋度的判斷要包含 outside-in frame
• → #153 Review 漏抓先分 design gap 與 execution gap：六個盲點全部是 design gap（框架缺 frame），不是 execution gap（有 frame 沒跑）
• → #168 多輪審查要有冷讀者 frame：cold-read 是 outside-in 的一個實例（從零脈絡讀者出發），本卡把這個方向擴展到五個 frame

本卡抽自 infra 接手維運模組的兩次使用者反饋。第一次：文章寫「拍下現況」「建立本地環境」，使用者問「用什麼拍？非 Docker 怎麼做？」——補了 FTP client、本地環境工具選型表、備份自動化指令。第二次：文章寫「拍下完整現況（不動 prod）」，使用者問「如果不是在 container 上運作，怎麼取代拍下來的動作？」——補了 phpinfo 擷取、cron 記錄、AMI 快照、系統軟體清單。兩次反饋的根因相同。限制：evidence 來自單一教學模組。

核心原則

操作型教材的一個動作（「拍下現況」「匯出資料庫」「建立備份」）在不同執行環境裡對應完全不同的工具路徑：

只寫動作不寫工具路徑，等於把「選工具」的認知負擔轉嫁給讀者。讀者知道該做「拍下現況」，但坐在電腦前不知道該打開什麼軟體。

情境

infra 接手維運模組的文章經過三輪多輪審查（compliance / cadence / steelman），所有 reviewer 都判定操作步驟邏輯正確、順序合理。使用者兩次指出同一個缺口：

第一次：「用什麼拍？怎麼拍？非 Docker 的環境怎麼做？」——三篇文章各補了 15-20 個工具提及，總修改量 138 行。

第二次：「如果不是在 container 上運作，怎麼取代拍下來的動作？」——兩篇文章各補了環境設定的拍照方法（phpinfo、cron、SSL、AMI 快照、系統套件清單），總修改量 87 行。

兩次的操作步驟在邏輯層都通過了 fact-check（「拍下現況」這個動作描述正確）和 steelman（「先拍後改」的順序合理）。問題出在「正確」跟「可執行」之間的落差——動作正確不代表讀者能執行，執行需要知道用什麼工具、在什麼環境限制下、有什麼替代方案。

理想做法

操作型教材的每一步至少帶一條環境專屬的工具路徑。如果教材涵蓋多種環境（container / VM / 共享主機），每一步要按環境分列工具，或明確標示「本篇的工具路徑適用於 X 環境、Y 環境的做法見另一篇」。

寫操作步驟時的自測問題：「讀者坐在電腦前、打開這篇文章，下一個動作是啟動什麼軟體或輸入什麼指令？」如果答案是「看情況」，就要把「情況」展開成環境分支。

生成端的檢查清單（寫完每一步後問）：

• 這一步的工具是什麼？有沒有寫出來？
• 這個工具在目標環境可用嗎？（共享主機沒有 SSH、沒有 CLI）
• 如果不可用，替代工具是什麼？
• 工具的操作有沒有環境限制？（phpMyAdmin 的 timeout、FTP 的非原子上傳）

沒這樣做的麻煩

• 兩次同根因的返工：同一個缺口（動作缺工具）被使用者指出兩次、修了兩輪，因為第一輪只補了「用什麼工具」沒補「在不同環境怎麼替代」。如果第一次就按環境分列工具路徑，第二次不會發生。
• 審查結構性盲區：fact-check 驗「正確性」、steelman 驗「完整性」，兩者都不驗「可執行性」。操作型文章的品質門檻比概念型文章多一層——除了正確和完整，還要可執行。這層門檻需要 executable-walkthrough frame（見outside-in reader frames report）。

判讀徵兆

操作型文章裡出現以下動詞但沒有跟著工具名稱或指令，就是候選缺口：

「拍下」「匯出」「備份」「部署」「掃描」「盤點」「監控」「還原」

這些動詞描述的都是需要工具才能完成的操作。概念型文章用這些動詞是在描述能力（「IaC 的責任是讓環境可重建」），操作型文章用這些動詞是在指引行動——行動需要工具。

跟其他抽象層原則的關係

• → 多輪審查缺 outside-in 讀者 frame：本卡是該卡盲點四（操作步驟缺工具指引）的具體展開，補充了「為什麼同根因會被指出兩次」的機制
• → 技術教材要內嵌管理層可彙報的資訊：工具路徑跟管理層資訊是同一類缺口——都是「讀者的下游任務需要但文章沒給的素材」
• → 讀者是缺經驗的專業人士、不是外行人：專業人士缺的不是概念（「要備份」），而是特定環境下的操作經驗（「共享主機沒有 mysqldump 時怎麼備份」）

本卡抽自 infra 教學模組的知識卡建卡過程。最初建了 14 張卡（IaC、VPC、subnet 等雲端 infra 概念），後續補了 7 張（route-table、SCP 等進階概念），但 legacy 環境的工具（phpMyAdmin、FileZilla、.htaccess、.env）一直沒建卡——作者和 reviewer 都覺得「這些是常識、不需要建卡」。使用者指出「現代工程師不一定認識這些老工具，接手的工程師不一定是寫 PHP 的」後才意識到這是建卡判準的盲點。限制：evidence 來自單一教學模組。

核心原則

知識卡的建卡判準是「目標讀者群裡最不熟悉的那個人能不能理解」，不是「作者覺得這個術語夠不夠常見」。

常識是相對於背景的：

作者的盲點是：寫某個領域的教材時，作者已經熟悉該領域的術語，把自己的熟悉度投射成「讀者也知道」。reviewer 如果跟作者背景相似（同源），會有相同的盲點。

情境

infra 接手維運模組的文章大量使用 phpMyAdmin、FileZilla、.htaccess、.env、cPanel 等術語。三輪多輪審查（compliance / cadence / steelman）都沒有指出這些術語需要知識卡——因為 reviewer 跟作者都把它們當成「寫過 PHP 就知道的東西」。

使用者指出：「接手的工程師不一定是寫 PHP 的，他只是被叫來接專案。」這句話揭露了建卡判準的錯誤假設——教材的讀者不是「寫 PHP 的人」，而是「被指派接手一個 PHP 專案的任何背景的工程師」。後者的術語熟悉度遠低於前者。

理想做法

建卡判準用「最不熟悉的目標讀者」而非「作者的熟悉度」：

1. 定義目標讀者群的背景光譜（接手維運的讀者可能是 PHP / Node / Go / Python / 前端背景）
2. 對每個術語問：「光譜裡最不熟悉的那端，看到這個詞能理解嗎？」
3. 如果答案是「部分讀者需要查」，就建卡——卡的成本很低（40-50 行），但缺卡讓讀者卡住的成本很高（關掉頁面去 Google、可能找到不準確的解釋）

建卡的邊際成本判斷：一張 40 行的卡花 5 分鐘寫，讀者搜尋到一張不存在的卡花 10 分鐘去外部找答案（可能不準確）。建卡的 CP 值幾乎總是正的——除非術語真的只在一篇文章出現一次且已有完整 inline 解釋。

沒這樣做的麻煩

• 讀者流失：非 PHP 背景的工程師讀到第三個不認識的術語（phpMyAdmin → .htaccess → opcache）後放棄，因為教材假設了他沒有的背景知識
• 外部搜尋的風險：讀者離開教材去 Google「什麼是 .htaccess」，找到的解釋可能跟教材的上下文不一致（例如 Google 結果講的是 Apache 2.2 的語法，教材用的是 2.4+）
• review 結構性漏抓：同源 reviewer 跟作者有相同的「常識」盲點，加再多輪也抓不到——這是 outside-in 的 reader-persona frame 才能 catch 的問題

判讀徵兆

寫教材時如果某個術語「不需要解釋」的直覺反應來得太快，問自己：「一個完全不同背景的專業人士看到這個詞，能理解嗎？」如果要想超過三秒才能回答，建卡。

另一個徵兆：如果教材的目標讀者群跨越多個技術背景（如「任何被指派接手 legacy 專案的工程師」），幾乎所有領域特定的術語都需要建卡——因為沒有任何一個術語對所有背景都是常識。

跟其他抽象層原則的關係

• → 讀者是缺經驗的專業人士、不是外行人：讀者有系統思考能力、缺的是特定領域的術語和經驗。知識卡補的正是這個缺口——給他一個 40 行的快速入口，讓他回到教材繼續讀
• → 多輪審查缺 outside-in 讀者 frame：「作者覺得是常識」是 inside-out 盲點的又一個實例——inside-out 從內容看品質（術語用得對不對），outside-in 從讀者看缺口（讀者認不認識這個術語）
• → 原子筆記要有向上的議題入口：知識卡從情境進入（「你在接手 legacy 專案時會遇到這個工具」），不是字典定義

本卡抽自四篇方法論文章同時塞 SOP 和驗證紀錄、導致兩種讀者都服務不好的分類檢討。limitation：evidence 來自同一個 blog 的四篇文章，都是寫作方法論主題。

核心原則

操作步驟（SOP：結構模板、流程 checklist、怎麼做）和演化紀錄（retrospective：批次驗證數據、實際跑出來學到什麼）服務不同讀者。混寫本身不一定失敗（SRE 手冊和 postmortem 模板都成功交織兩者），但在本 repo 的場景下會造成兩個具體問題：

1. SOP 同時存在於 skill 和文章裡，改 skill 時文章沒同步更新、兩處內容分歧。這是主要痛點。
2. 沒有清楚的分節標示時，讀者要跳過大量「不是給我看的」段落。

情境

四篇 posts/ 文章的共通症狀：

前三篇的共通模式：文章開頭像方法論手冊（SOP 感），中段突然變成「第一輪 demo 驗證」「第二輪 batch 對照」（retrospective 感），讀者在兩種模式之間切換的認知成本高。

第四篇 ci-silent-hang 是不同問題 — 它不是功能混合，是資料夾歸類錯（debugging case study 放在 posts/ 而非 work-log/）。

理想做法

功能拆分到對應的 surface：

拆分後的文章只保留 retrospective 段（去掉跟 skill 重複的 SOP 步驟），開頭引用 skill 路徑建立 context。去掉 SOP 後文章若不能獨立成篇（冷讀者讀不懂、或只剩表格沒有判讀），降級成 content/skills/ 鏡像。

已有先例：case-first-agent-team-review-workflow 已經走這條路 — 文章是方法論敘事、skill 是操作步驟、兩者共存互連。

沒這樣做的麻煩

• 機器讀者找不到步驟：Claude runtime 透過 skill 觸發操作流程；SOP 埋在文章的 retrospective 段落裡，觸發路徑不通
• 人類讀者跳著讀：讀者進來看「migration playbook 怎麼寫」，要跳過三輪 batch 驗證表才找到 6 type 結構模板；或者進來看「為什麼三輪 batch collapse 率不同」，要跳過 diff dimension audit 步驟才到驗證段
• 維護雙份：SOP 同時存在於 skill 和文章裡（migration-playbook 已發生），改 skill 時文章沒同步更新，兩處內容分歧
• 新文章不知道放哪：下一篇方法論文章也會自然累積 SOP + retrospective，如果沒有拆分慣例，就會繼續混寫

判讀徵兆

寫方法論文章時，如果文章裡同時出現以下兩類段落，就是功能混合的訊號：

1. 步驟型段落：「Step 1 → Step 2 → Step 3」、結構模板、checklist、「照這個跑」
2. 證據型段落：「第 N 輪 batch 驗證」、「N/N collapse 率」、「跨兩輪對照」、「self-aware limitation update」

另一個徵兆：文章已有對應的 skill（或適合建 skill），但文章裡仍重複 skill 的 SOP 內容。

本徵兆適用 posts/ 方法論文章。report/ 卡片的修法步驟 + case 證據並存是正常形態（report 卡格式本就含情境 + 原則 + 修法）。

跟其他抽象層原則的關係

• → #142 文章主體要對齊標題承諾：#142 處理「章節內容偏離標題」，本卡處理「整篇文章功能定位混合」— #142 是段落層、本卡是文章層，同屬「內容要對齊承諾」家族
• → #122 cadence 同質化：本卡四篇文章中的 retrospective 段大量引用 #122 的 cadence 概念；拆分後 retrospective 段落成為 #122 的 evidence 文件，SOP 進 skill 不再重複
• → #154 教材的重點/總結段是內容發散訊號：#154 說「刪掉總結段看正文站不站得住」，本卡的對應操作是「刪掉 SOP 段看 retrospective 站不站得住」— 同類「減法測試」判準
• → AGENTS.md 跨 surface 內容處理原則：本卡的拆分動作跨 .claude/skills/ 和 content/ 兩個 surface，各自獨立、不交叉引用

本卡抽自 #199 論述基礎段的修改。原稿寫了「四篇文章在寫作時自然累積了兩種內容、發表後讀起來沒頭沒尾不好讀、用 WRAP 完整模式分析後確認問題出在功能定位混合」— 包含發現問題的經過、使用的分析工具、主觀感受。修改後只留「本卡抽自四篇方法論文章同時塞 SOP 和驗證紀錄、導致兩種讀者都服務不好的分類檢討」。limitation：evidence 來自單一 report 卡的修改，但同模式在多張卡的論述基礎段出現過。

核心原則

Report 卡的「論述基礎與限制」段承擔兩個功能：告訴讀者 evidence 從哪來（來源）、以及 evidence 的邊界是什麼（limitation）。不承擔第三個功能：告訴讀者這張卡怎麼被發起的（過程）。

過程是作者的工作紀錄（「讀起來沒頭沒尾」「用 WRAP 分析」「用結構化決策分析」），結論才是讀者需要的判讀前提（「四篇文章混寫 SOP 和 retrospective」「evidence 來自同一個 blog」）。

情境

#199 的論述基礎段原稿：

四篇文章在寫作時自然累積了「怎麼做」（SOP）和「跑出來學到什麼」（retrospective）兩種內容，發表後讀起來「沒頭沒尾不好讀」。用結構化決策分析後確認：問題出在功能定位混合，跟寫作品質無關。

三個問題：

1. 「自然累積了」「讀起來沒頭沒尾不好讀」是發起檢討的觸發描述、不是 evidence 邊界
2. 「用結構化決策分析後確認」是作者使用的工具、讀者不需要知道用了什麼工具才信任結論
3. 「跟寫作品質無關」是排除診斷的過程、結論段的「SOP 跟 retrospective 服務不同讀者」已經涵蓋

理想做法

論述基礎段只寫兩件事：

1. Evidence 來源：「本卡抽自 X」— X 是具體的 case / 事件 / 文章 / 批次
2. Evidence 邊界：「limitation：Y」— Y 是樣本量、適用範圍、已知盲區

不寫：

• 怎麼發現問題的（「讀起來不好讀」「review 時發現」）
• 用了什麼分析工具（「用 WRAP」「跑了三輪 review」）
• 排除了什麼診斷（「跟 X 無關」）
• 主觀感受（「沒頭沒尾」「覺得怪」）

沒這樣做的麻煩

• 論述基礎段膨脹：過程描述比結論長，讀者要翻過「怎麼來的」才看到「邊界是什麼」
• 工具名耦合：寫了「用 WRAP 分析」，讀者不知道 WRAP 是什麼就卡住（冷讀者行話洩漏）
• 過時風險：過程描述綁定當時的工具和對話脈絡，卡片長期維護時過程段最先過時

判讀徵兆

寫完論述基礎段後，問兩個問題：

1. 「如果我把這段貼給一個沒參與這次檢討的人，他能從中知道 evidence 的來源和邊界嗎？」— 能 → 合格
2. 「這段有沒有只有參與者才懂的脈絡？」— 有 → 刪掉那些脈絡

跟其他抽象層原則的關係

• → #199 一篇文章只承擔一種功能：本卡的 trigger case；#199 論述基礎段的修改揭露此原則
• → #154 教材的重點/總結段是內容發散訊號：#154 說「刪掉看正文站不站得住」，本卡的對應操作是「刪掉過程描述看論述基礎段站不站得住」
• → 讀者不需要知道的資訊不該出現在最終文件：過程描述是 meta 資訊、服務作者不服務讀者，同根原則在 report 卡 surface 的體現

1. 語氣：經驗分享，不是教人

不要用「你應該」「要記得」這種由上往下的口氣。這是在記錄自己的經歷，不是在寫教材。

2. 語氣：陳述事實，不帶情緒

避免用強調語氣、反問、或帶有自責/誇張的措辭。平鋪直敘地描述發生了什麼。

3. 用功能描述，不要用函式名稱

文章的讀者不一定看過這份程式碼。如果只寫函式名稱，只有自己看得懂。函式名稱可以出現在程式碼範例裡，但前後的解說要用功能語言。

程式碼區塊裡的函式名稱不需要替換——那是具體的範例，讀者看到程式碼會理解。要替換的是程式碼區塊外的描述文字。

4. 敘事角度：不是每件事都是「犯錯」

有些問題不是自己造成的，不需要用自責的角度來寫。例如第三方 library 的 bug 本來就存在，能觸發它代表前面的工作都做對了。

5. 每個案例要有脈絡：發現 → 找因 → 修復

只說「問題是 X，改成 Y」不夠。讀者需要知道完整的脈絡：是怎麼意識到有問題的、怎麼一步步定位原因的、最後怎麼修的。

修改前

測試名稱是「品項分派邏輯」，但分派邏輯沒有被執行。後來改成從入口方法開始呼叫，Bug 隨即被發現。

修改後

怎麼發現的： 實機上兩台廚房印表機只有一台收到品項，另一台完全沒動。但測試裡的分派測試是通過的。

怎麼找到原因的： 回頭看測試程式碼，發現測試裡的分派結果是手動寫死的，不是由分派邏輯算出來的。測試驗證的是「把結果存進去再讀出來」，但品項分派的程式碼從頭到尾沒有被執行過。

怎麼修的： 改成從入口方法開始呼叫，讓品項分派的邏輯實際跑一遍。跑完之後 Bug 就出現了——分派邏輯的 fallback 條件寫錯，所有品項都被送到同一台。

6. 不要用特定產品/SDK 名稱

具體的產品名稱（如某個 SDK 的名字）讓文章變成只適用於特定情境。著重描述問題的結構，而非特定技術。

例外：第三方 library 的名稱可以出現在「最終修復」等技術細節區段，因為那是給自己未來查閱用的。

檢查清單

寫完經驗分享文章後，對照這些問題：

1. 有沒有「你應該」「要記得」「教訓是」這類由上往下的用語？→ 改成描述自己做了什麼、發現了什麼
2. 有沒有情緒化的措辭（搞砸、偷懶、炸了、根本沒）？→ 改成陳述事實
3. 程式碼區塊外的函式名稱，不看程式碼的人能理解嗎？→ 用功能描述替代
4. 每個案例有完整的脈絡嗎？（怎麼發現 → 怎麼找因 → 怎麼修）
5. 有沒有把不是自己造成的問題寫成自己的錯？→ 用適當的角度描述
6. 有沒有出現特定產品/SDK 名稱？→ 除了技術細節區段外，用功能描述替代