本章寫 eval 設計的座標系：三個 binary 軸、八個象限、每個象限對應什麼工具、軸選錯的訊號怎麼識別。這層 framing 是 meta、不是具體 eval 方法——具體方法在 4.14 benchmarking 跟 4.21 LLM-as-Judge。

本章目標

讀完本章後你能：

1. 把任何 eval 需求放到三軸座標、定位象限。
2. 對每個象限選對應的 eval 工具。
3. 識別軸誤選的訊號、避免「工具對、軸錯」的常見坑。
4. 規劃 eval 路線：初期該做哪幾個象限、規模化後再補哪些。
5. 把 eval 設計跟 4.14 benchmarking / 4.20 tracing / 4.21 LLM-as-Judge 串成完整 pipeline。

三軸

Eval 設計的三個正交軸：

軸 1：Objective ↔ Subjective

• Objective：有明確 ground truth、檢驗可以寫成 deterministic check（金額對不對、SQL 跑得通不通、JSON schema 合不合法）。
• Subjective：沒有單一正確答案、需要評分或比較（語氣好不好、解釋清楚不清楚、推薦的 trip 合不合用戶）。

判讀訊號：「能不能用 Python 函數判定對錯」、能 → objective、不能 → subjective。

軸 2：Component ↔ End-to-End

• Component：測單一元件、孤立評估（retrieval 拿對 chunk 沒、tool call 參數對沒、prompt 抽出正確 entity 沒）。
• End-to-End：測完整流程、user 視角結果（user 問題有沒有被解決、訂單有沒有完成、conversation 滿意度）。

判讀訊號：「失敗時你想知道是哪一段壞掉」→ component；「你只在乎最終體驗」→ end-to-end。

軸 3：Quantitative ↔ Qualitative

• Quantitative：產出數字（accuracy / latency / cost / pass rate）、可以追蹤、可以比較、可以 alert。
• Qualitative：產出觀察（error pattern、user 抱怨、reviewer 註記）、無法直接 aggregate、但能引導 hypothesis。

判讀訊號：「結果能算平均嗎」→ quantitative；「結果是讀完才知道」→ qualitative。

三軸的正交性

這三軸是正交的、不是同義詞：

• 「Objective + component + quantitative」典型是 unit test（function 返回對不對）。
• 「Subjective + end-to-end + qualitative」典型是 user 訪談（user 整體滿意度）。
• 中間象限存在多種混合、各有對應工具。

八象限

3 個 binary 軸 = 8 象限。每個象限的常見對應工具：

不是「八個都要做」、是「先看你的問題在哪個象限、用對應工具」。

兩個最容易誤判的象限展開：

Subjective + Component + Quantitative（這個 step 輸出評分）：對應工具列「LLM-as-judge pairwise / rubric、human rating」、但 pairwise 是首選、不是 rubric——pairwise 比較讓 judge 的偏差更可控（兩個答案放在一起比、誰好誰差比較好判）、rubric 容易受 verbosity / position bias 影響。Rubric 留給「需要絕對分數而非相對排序」的場景（如要追蹤絕對品質漂移）。詳見 4.21 LLM-as-Judge 的 bias 緩解段。

Objective + Component + Quantitative（元件對嗎）：這象限最容易做、cost 也最低——deterministic check 配 component test、CI 跑、production trace 隨抽即驗。Production AI 系統若這象限沒覆蓋、bug 永遠靠 user 抱怨才發現、debug 跟 incident review 成本高。對應反例：把這象限的測試交給 LLM judge（見軸誤選一）。

軸誤選的訊號

軸選錯時、工具會給出「看起來合理但其實沒用」的訊號。三個常見軸誤選：

誤選一：用 subjective 工具測 objective 行為

例：訂單金額計算對不對、找 LLM judge 來看「這個金額合理嗎」。

• 問題：金額計算有 ground truth、應該 deterministic check（assert order.total == expected）。LLM judge 對「合理」的判斷有偏差、會放過明顯錯誤、會挑剔正確但不直觀的答案。
• 訊號：你發現自己在寫「judge prompt」描述「什麼樣的金額是合理的」、但其實該行為有客觀標準。
• 修正：把 judge prompt 翻成 deterministic check。

誤選二：用 end-to-end 工具測 component bug

例：整套系統 success rate 從 90% 掉到 80%、追了一週、結果是 retrieval 漏 chunk。

• 問題：E2E metric 告訴你「有問題」、不告訴你「在哪」。Component eval 缺失時、debug 從 trace 倒推、耗時。
• 訊號：incident 後 root cause analysis 經常超過一天、查到的東西其實 component eval 該秒抓。
• 修正：對 critical component（retrieval、tool 調用、parse 階段）加 component eval、production 持續跑。

誤選三：用 quantitative 工具找 qualitative 訊號

例：user 滿意度從 4.2 掉到 4.0、團隊看數字盯一週、不知道發生什麼。

• 問題：Quantitative metric 只告訴你「有變化」、不告訴你「為什麼」。Qualitative 訊號（user 抱怨內容、抽樣 conversation）才能浮現 hypothesis。
• 訊號：團隊看 dashboard 看了很久、卻沒人去讀 actual user feedback。
• 修正：quantitative trigger（指標漂移）、qualitative 跟進（讀樣本、找 pattern）。

Eval 演化路徑

不同階段的 LLM 應用、該優先補哪些象限不同。

階段 0：MVP（沒任何 eval）

問題：「能不能 demo 一下就好」、行為對不對全靠手測。

• 第一個該補的：Objective + End-to-end + Quantitative。最少跑 10 個 representative case、能看「跑得起來率」就好。
• 不該太早做：subjective eval、需要 judge / human rating 的東西。MVP 階段先讓系統穩定運行。

階段 1：有 user 在用

問題：production 偶爾有 bug、user 偶爾抱怨、不知道哪些是 systematic、哪些是 random。

• 第二個該補的：Objective + End-to-end + Qualitative。讀 incident、讀抽樣 trace、找 pattern。
• 第三個該補的：Objective + Component + Quantitative。對 critical component（retrieval / tool call / parse）加 component-level eval、production 跑。
• 不該做：完整 subjective rubric。先把 objective 失敗修了再說。

階段 2：要持續優化品質

問題：objective 部分已經穩、user 抱怨主要在 subjective 層（語氣、helpful 程度、推薦合不合用）。

• 第四個該補的：Subjective + Component + Quantitative。用 LLM-as-judge 給每個 step 評分、做 A/B test 比較 prompt 變動。
• 第五個該補的：Subjective + End-to-end + Quantitative。CSAT、thumbs up/down、appeal rate。
• 要做的：Subjective eval 跟 qualitative review 必須配合進行——quantitative 給出方向、qualitative 給出修法 hypothesis。

階段 3：規模化、跨團隊

問題：多個產品 / 團隊用同一套 LLM infra、eval 要 cross-cutting。

• 要做的：標準化 eval pipeline、把象限 1-7 都 cover、qualitative review 進入 ritual（每週 incident review、每月抽樣 trace 讀）。
• 重點不是「全部都有」、而是「每個象限的 owner 清楚」。

Eval 跟 Trace 的閉環

Eval 不是孤立的——它跟 4.20 LLM tracing 形成閉環：

 1[Production traffic]
 2       ↓
 3   [LLM trace]  ← 每次 call / agent step / tool 都記錄
 4       ↓
 5   ├── 即時 monitoring（latency / cost / error rate）
 6   ├── 抽樣進 eval set（人工標 + LLM judge）
 7   └── failed case 進 regression set（防止改 prompt 又壞同樣 case）
 8       ↓
 9   [Eval pipeline]
10       ↓
11   ├── Component eval（單元件 accuracy）
12   ├── E2E eval（整套 success rate）
13   └── Subjective eval（judge / human rating）
14       ↓
15   [Insights]
16       ↓
17   ├── Quantitative：metric 漂移 alert
18   └── Qualitative：error pattern → hypothesis → 修 prompt / tool / RAG
19       ↓
20   [改動進 production]
21       ↓
22   [回到 production traffic、看 metric 收斂]

Production trace 不只是 debug 工具、是 eval set 的活泉。Trace + eval 閉環的設計細節見 4.20。

跟其他 Eval 章節的分工

讀法建議：先讀本章建立座標系、再依當前痛點往對應章節展開。Subjective eval 痛點 → 4.21；自家 benchmark 設計 → 4.14；production observability → 4.20。

有效 eval 系統的四個設計條件

Eval 系統要持續產生有用訊號、必須滿足四個條件。每個條件對應一個常見退化模式、可同時當 checklist 用。

條件一：Judge 只用在 subjective 軸

LLM-as-judge 留給沒 ground truth 的 subjective 行為（語氣、helpful 程度、解釋清楚）、objective 行為（金額、JSON schema、API 參數）用 deterministic check。Judge 的 cost 比 deterministic check 高 1-2 個數量級、精度反而不如、明顯不划算。

對應反例：「全部 eval 都做成 LLM judge」——judge 被誤用在 objective 行為、cost 翻倍、精度反降。

條件二：每個 metric 有 owner、threshold、action

每個 production metric 都要明確：誰負責看（owner）、什麼數字觸發 alert（threshold）、alert 後做什麼（action）。沒這三項的 metric 是 noise。

對應反例：dashboard 上 50 個 metric 圖、沒人定期看、bug 還是靠 user 抱怨才知道。

條件三：Eval set 跟 production traffic 同步

Production trace 持續抽樣補進 eval set、每季 review eval set 跟 traffic 分佈是否一致。

對應反例：eval set 是兩年前定的、production traffic 已經漂得很遠、eval 通過不代表 user 滿意。

條件四：保留 frozen baseline

Frozen baseline 是把某個特定 prompt + 特定 model 跑 production 一段時間後 freeze 起來、每次新版本跟它比、定期 refresh 並標明時點。漂移看得見才能管理。

對應反例：每次 A/B 都跟「最新版本」比、長期累積漂移完全不可見、「整體變好了沒」無從回答。

何時過時 / 何時不過時

不會過時的部分：

• 三軸座標（objective / component / quantitative 三個 binary 軸）。
• 八象限對應工具的結構分類。
• 三類軸誤選的識別訊號跟修正。
• Eval 演化路徑（MVP → user → 優化 → 規模化）。
• Eval / trace 閉環的設計。
• 有效 eval 系統的四個設計條件。

會變的部分：

• 具體 eval framework（OpenAI Evals、Promptfoo、Braintrust、Langfuse 等會持續演化）。
• LLM-as-judge 的具體 prompt 模板跟 bias 緩解技巧。
• 各 benchmark 的權威性（半年一換）。

下一章

下一章：4.14 Benchmarking 與評估方法論、把座標系落到具體 benchmark 設計。Subjective eval 的工具見 4.21 LLM-as-Judge、production trace 怎麼接 eval 見 4.20 LLM tracing、跟 fuzzy engineering 典範的關係見 0.8（fuzzy 行為的測試本質就是 distribution metric）。

這份紀錄整理 backend/03-message-queue 模組 6 vendor case 庫採集的實作經驗、量化 main context 節省效應、給未來類似任務作為設定參考。

採集任務的特徵

backend/03 模組需要為 6 個 vendor（Kafka / RabbitMQ / NATS / Redis Streams / SQS / Pub/Sub）採集 5-10 個公開 case。任務特徵：

• 各 vendor 獨立、無相互依賴
• 每個 vendor 需要 WebSearch 找候選 + WebFetch 驗證 URL + 抽 finding、多步驟
• 每個 agent 任務時長 4-7 分鐘（含 WebFetch 多次往返）
• 採集回報是清單形式、易於主 context 整合

Background agent 平行的執行方式

每個 agent 用 subagent_type: general-purpose、run_in_background: true、prompt 含：

1. 採集目標（5-10 案例）
2. 硬閘門（WebFetch 驗證）
3. 排除清單（已有案例 / vendor 自家 marketing）
4. 對齊大綱（該 vendor 的進階主題列表）
5. 回傳格式（清單、含 source / observation / finding / 對應章節）

主 context 一個 message spawn 6 個 agent、然後等通知。

量化結果

主 context 節省效應 ~80%：每個 agent 報告約 2KB summary、6 個總 12KB；若主 context 直接做、每次 WebFetch 取回的 markdown 約 10-30KB、累積後容易 > 100KB。

適用場景判斷

Background agent 平行適用：

• 多個獨立子任務（不互相依賴 input / output）
• 每個子任務需要多步驟 tool use（WebFetch / WebSearch / Bash / Glob）
• 子任務回報是結構化清單 / summary、不是 raw transcript
• 主 context 需要節省 token 做後續工作（如寫檔、整理 index）

不適用：

• 線性依賴（任務 B 需要任務 A 結果）
• 短任務（單一 WebFetch、串行直接做更快、平行 overhead 不划算）
• 需要主 context 即時介入決策的任務

跟其他 agent 用法的對比

backend 模組過去用過的其他 agent 用法：

三種都用 background、都節省主 context、但目的跟回報格式不同。Stage 0 採集回報是「清單 + 捨棄候選」、Stage 3 review 回報是「issue list + severity」、Explore 回報是「file path + match」。

設定參考

spawn 平行 agent 的 anti-pattern：

• 不寫硬閘門：「找 5-10 case」沒明示 WebFetch 驗證 → agent 編造 URL
• 不列排除清單：「找 Kafka 案例」沒列既有案例 → agent 重複採集
• 要求 raw transcript 回報：「把找到的內容貼給我」→ 主 context 爆炸
• 單一巨大 agent：「找所有 6 個 vendor」串行做 → 失去平行優勢
• 平行過頭：spawn 20+ agent 但實際只有 6 個獨立任務 → 不必要的協調成本

跟 case-first 流程的關係

這個方法已寫入 .claude/skills/case-first-module-workflow/references/stage-0-case-collection.md、成為 case-first 流程的 stage 0 採集標準執行範式。但實際適用範圍超出 case 採集、適用所有「多獨立子任務 + 多步驟 tool use」場景。

下一步該追蹤的議題

1. 平行 agent 數量上限：6 個跑 OK、20+ 是否會撞到 rate limit 或協調成本？實作上限是多少？
2. Agent context 跑滿後的恢復策略：若某個 agent context 跑滿、其他 agent 繼續但該 agent 失敗、要不要 retry？怎麼接續？
3. 跨 agent 共享 cache：6 個 agent 都 WebSearch 同一個 vendor 主頁、有沒有 cache 共享機制可省 token？目前每 agent 獨立、可能重複 fetch

凡是教做事方法的東西（SKILL、playbook、methodology document、checklist）— 如果你認為 multi-pass refinement 是必要的、就要把它放在核心結構層（pillar、principle、step）、不是放在附帶段（appendix、tips、reminder、see also）。

放在 appendix = 結構暗示「optional、看心情選擇」 = 在 #72 高 ROI 無觸發 的結構壓力下、永遠被跳過。Pillar 層 = 結構性必跑、用結構強制行為、不靠紀律。

為什麼 pillar / appendix 的位置決定執行率

讀者看 SKILL / methodology 時、認知資源分配：

• Pillar / Core Principles：必讀、會內化、實作中會回想
• Steps / Reference：實作中翻
• Tips / Appendix / “See also”：第一次讀掃過、之後忘記

把 multi-pass review 放 appendix = 結構暗示「這是進階、可選」。即使內容寫得很詳細、結構訊號蓋過內容。

對比放 pillar：每次接觸 SKILL、第一眼看到 4-5 個 pillar 中包含 “Multi-pass Refinement” — 結構性提示「這跟其他 pillar 同樣重要」。

各 methodology 的 pillar / appendix 切分

實際 methodology 文件的 pillar 應該包含 multi-pass、appendix 應該避免：

每個 methodology 的設計都該檢查：multi-pass 是 pillar 還是 appendix？

如何識別「該升 pillar 但被當 appendix」

訊號：

每個訊號都是 multi-pass 的位置太低、結構壓力把它當作 optional。

升 pillar 後的設計：四個必要元素

把 multi-pass 升成 pillar、需要含這四個元素才完整：

1. 明示「第 1 輪不追求完美」

寫在 pillar 內容、第一句就講：「第 1 輪不要追求 perfect、預期會有未發現問題、設計第 2 輪去 catch」。

去掉「第 1 輪該寫對」的隱含預設、釋放認知資源。

2. 列出 N 輪的 frame 清單

每輪用什麼 frame、catch 什麼。例：

1輪 1：生成 — idea → 字
2輪 2：對意圖 — 跟原意對齊嗎
3輪 3：機會成本語氣 — 絕對主義詞翻成 trade-off
4輪 4：grep-ability — 關鍵字前置嗎
5輪 5：反例 / 邊界 — 何時不適用寫了嗎

3. 何時可跳輪

不是所有情境都跑全輪。寫清楚「跳輪的合理情境」、避免「跑全輪 = 過度工程」的反彈。

4. 跨 frame 的不可替代性

明示：輪 N 不能用「再跑一次輪 N-1」取代 — 不同 frame 才能 catch 不同層。重複同 frame = 同類錯一直 miss。

反模式：「我自己會 review」當 pillar 替代

1不該寫：「請務必在送出前自行 review。」
2應該寫：「此 methodology 的第 N 個 pillar 是 Multi-pass Review、含 1-5 輪 frame：⋯⋯」

「自行 review」= L1 紀律（#72）= 預期失敗。

「列入 pillar + 列輪次 + 列 checklist」= L3-L5 結構性對策 = 結構強制執行。

套用到本系統的具體 case

Case 1：requirement-protocol skill

• 現況：3 大支柱 + 6 大原則、multi-pass 散在「2 次門檻」「漸進驗證」「revert checkpoint」三條原則裡、沒明示
• 應該：升第 4 支柱「Multi-pass Refinement」、把散落的多輪意涵集中

Case 2：compositional-writing skill

• 現況：3 大支柱 + 5 大原則、各 reference 結尾有「self-check」段（部分 multi-pass 跡象）
• 應該：升第 6 原則「Re-read Pass」、引用 #83 的 5 輪 frame、各 reference 加「第 2 輪 review checklist」

Case 3：frontend-with-playwright skill

• 現況：「漸進驗證」原則含 multi-pass、但跟「dogfood / 多輪測試」沒串連
• 應該：補抽象層原則段、明示 multi-pass 跨「漸進驗證 → playwright dogfood → production observation」是同一條 spiral

跟其他抽象層原則的關係

判讀徵兆

核心：Methodology 設計的 pillar / appendix 切分不是內容深淺問題、是執行率問題。Pillar 層必跑、appendix 層不跑。把 multi-pass 視為「附帶」= 結構性確保它不被執行。真正必要的東西要升結構、不能藏在末尾。

以 Zettelkasten（卡片盒筆記法）為核心的寫作方法論。將每段文字視為可重複組合的原子卡片，讓人類讀者與 AI 代理人都能以最小認知負擔找到答案。

Core Pillars（核心支柱）

Core Principles（核心原則速查）

讀者能在本區塊完成快速複習；需要具體應用時，依下方「觸發路由」讀對應情境 reference。

1. 原子化（Atomization）

一張卡一個概念：能獨立理解、可跨情境重用。拆分依據是認知負擔與情境匹配度 — 讀者要同時記住的概念數、以及這張卡是否符合讀者當下的情境需求。常見的誤判依據是「行數」（卡太長就拆）、行數只反映表面字數、不反映概念數：一張 200 行的卡可能只講一個概念、一張 30 行的卡可能塞了三個概念。判別問題是「讀者要同時 hold 幾個概念才讀得懂這張卡」、超過 7 個就要拆。

拆分判準的核心問題：「這張卡聚焦在什麼問題、議題切完整了嗎？」— 判準是 focus 完整度。常見的次級訊號是「卡之間是否衝突」「邊界是否清晰」、兩者都不夠：兩張卡互不衝突、仍可能各切了一半同樣議題；一張卡邊界清晰、仍可能塞了兩個獨立議題。focus 完整度問的是「這張卡有沒有把它聲稱要解決的議題講完」、是 contrast 上面那兩個訊號抓不到的死角。

2. 索引建立（Indexing）

用 MOC（Map of Content）、tag 層級與反向索引把卡片串成可導航的網。入口文件只做路由、把細節留給目標卡；引用深度最多一層、讓讀者一跳就到答案（避免 A→B→C 的多層跳躍）。

引用錨點用語意標題、不用位置編號：引用另一個章節 / 階段 / 條列項時寫「見核心問題」、不寫「見 Stage 3」— 編號是結構排列的 derivation、結構重排時引用句字面完好、語意 silent 指向錯的內容（比 broken link 難偵測：連結斷掉會報錯、編號錯位會成功解析到錯的東西）。對應要求是每個結構單位的標題要承載核心意義（「Stage 3：核心問題」、編號只作排序前綴）、引用取語意半邊；發布方凍結的編號（RFC 段號 / 法條）是 fact、可引用。詳見 reference-by-semantic-title-not-number。

語意錨用單一字串、引用他卡用對方的詞彙：同一個結構單位的語意名稱只能有一個 canonical 字串（取標題語意半邊）— 同義雙名（標題「決策記錄 + scaffold 建議」、引用「決策收斂階段」）讓 grep 掃 A 漏 B、重排修復退回人腦對應。引用另一張卡並描述它的內容時、寫之前把被引卡重新打開、用它自己的分類詞彙轉述 — 記憶存概念不存 taxonomy、憑印象轉述會把對方明確分開的類別併掉、每條關係宣告要找得到被引卡的支撐句。

集合命名用角色、不內嵌數量：標題要當穩定錨、就得先是純 fact —「核心七問」「成長六階段」「四大支柱」把成員數烤進名字、數量是成員清單的 derivation、加一問名稱先失真、所有複製過名稱的地方跟著過期。命名只承載角色與層級（核心問題 / 撞牆階段 / 支柱）、數量讓清單自己呈現；外部凍結品牌（SOLID 五原則 / OWASP Top 10）跟概念閾值（兩次門檻）的數字是 fact、可留。詳見 name-collections-by-role-not-count。

3. 意圖顯性與層級貼合（Explicit Intent & Layer Alignment）

寫作前先標記本文所在抽象層級（實作 / 工具 / 協作 / 認知 / 架構）、論述停在該層。素材取自哪個層級、論述就收斂在哪個層級 — 因為跨層提升等於用 X 層的詞彙描述 Y 層的議題、讀者拿到規則但對不到自己當下的情境。要把實作層素材抽象到認知層、先補對應抽象層的支撐文件（讓論述有對應層的詞彙跟 case 可引用）、再做跨層提升。

寫「為什麼」和「要達成什麼」、把「程式碼在做什麼」留給程式碼自身（程式碼讀一次就知道做什麼、寫進註解只是冗餘）。主詞與動詞直接、段落開頭即表達意圖。TODO / placeholder 留給 inline 註解、文件本體只放當前契約 — 因為文件常被當成「契約 SSoT」引用、混入未完成事項會讓讀者誤判契約範圍。同一篇文字貼合它在系統裡的抽象層級、把下層實作藏在介面後面。

機會成本語氣優先：程式設計大多是多目標取捨、討論的是「在什麼情境下哪個選項較划算」。把絕對二元語氣（「正確概念是 X / 替代方案不足 / 應該這樣做」）翻成情境化敘述：「比較好的做法是 A、因為 [情境] / B 在 [其他情境] 合理 / D 的成本特別高、只在 [極端情境] 才划算」。機會成本教讀者「思考方式」（能套用到新情境）、絕對主義教讀者「規則」（壓力下會忘）— 所以前者是預設語氣。例外保留給物理 / 法律 / 數學事實（安全性、數據完整性、合規、雜湊必有碰撞）。絕對二元語氣有兩種形式：命令式（「應該做 X」）讀者聽得出是主張、會審；必然式（「X 天生就是 Y / 本質就是 / 必然」）偽裝成事實陳述、更隱形 — 把設計選擇講成自然法則時尤其要 catch、還原成「在選了某前提後 X 才以此形式成立」。判別線：這個必然有沒有上游設計選擇當前提（有=條件性、要講前提；無=真必然、可斷言）。詳見 teaching-prose-neutral-register。

選項數由議題本身的合理選項數決定：機會成本的精神是「教思考方式」 — 議題有幾個合理選項就寫幾個（2 個寫 A/B、3 個寫 A/B/C、4 個寫 A/B/C/D）。強湊到固定數量會把「教思考」退化成「填格式」、生出「實務上幾乎不存在」的低品質假反模式。真正的反模式直接標「D：反模式 — 違反 X 原則」、給讀者明確的「為什麼這條路該避開」、保持誠實。

讀者定位聲明（生成端前置步驟）：每個教學模組在第一篇文章生成前，顯式聲明讀者定位——一段話描述目標讀者的背景、已有能力、缺的經驗。這份聲明是後續所有生成和 review 的可檢查基準。缺少顯式聲明時，LLM 預設用「教外行人」的姿態寫教學內容，這個預設不被 review 挑戰（reviewer 共享同一個預設），導致宣導語氣通過多輪審查。per outside-in reader frames report

讀者定位：缺經驗的專業人士、不是外行人：技術教材的讀者是在特定領域缺乏經驗的專業人士，不是完全不懂的外行人。寫法是補足經驗缺口（直接描述情境與操作需求），不是從零科普（故事線導入、比喻堆疊、宣導語氣）。宣導式語氣（「你可能沒注意到」「把 X 想成 Y」「跑得好好的」）預設讀者無能、降低教材可信度。詳見 audience-is-professional-not-layperson。

跨專業溝通用情境遞進、不用比喻堆疊：向非本領域的專業人士（管理層、決策者）解釋技術議題時，減少術語並從簡單情境遞進到複雜情境。比喻傳遞形狀但不傳遞嚴重性、在細節處崩解、且隱含「對方聽不懂」的預設。用決策者熟悉的維度（影響範圍、恢復時間、成本量級）表達。詳見 cross-expertise-scenario-not-analogy。

技術教材內嵌管理層可彙報的資訊：技術段落旁嵌入成本量級、時程估算、進度指標與決策簽核點（各 1-2 句），讓讀者學完技術做法的同時拿到向上彙報的素材。成本用量級不用精確數、時程用範圍不用單點、進度用可查詢指標。詳見 management-reportable-info-in-technical-content。

知識卡建卡判準用「最不熟悉的讀者」：知識卡的建卡判準是「目標讀者群裡最不熟悉的那端能不能理解這個術語」，不是「作者覺得夠不夠常見」。常識是相對於背景的——.htaccess 對 PHP 工程師是常識、對 Node.js 工程師完全陌生。跨背景讀者群的教材裡，幾乎所有領域特定術語都需要建卡。建卡的邊際成本低（40-50 行）、讀者缺卡的代價高（離開教材去 Google、可能找到不一致的解釋）。per 常識是相對於讀者背景的。

操作步驟帶環境專屬工具路徑：操作型文章的每一步至少帶一條工具路徑（用什麼軟體、輸入什麼指令）。同一個動作在不同環境（container / VM / 共享主機）的工具路徑可能完全不同——「拍下現況」在 container 是 docker commit、在 VM 是 AMI 快照、在共享主機是 FTP mirror + phpinfo。文章涵蓋多種環境時、每一步要按環境分列工具、或標明適用環境。自測問題：「讀者坐在電腦前，下一個動作是打開什麼軟體？」答不出來就是缺口。per 操作指引要帶環境專屬工具路徑。

Case 引用段落的三段式結構：三段式是案例引用段落的順序紀律 — 把「概念 → 案例 → 操作」三層分開承擔（段首給概念定義、case 引用居中、通用工程知識展開）、讓段落結構跟讀者學習新概念的認知順序對齊。LLM 從 case 反推內容容易把 case 揭露當概念出發點、實證觀察 11/12 段都犯這個錯。詳見 case-citation-three-part-structure。

原子筆記要有向上的議題入口：承載知識的原子筆記（Zettelkasten 卡 / glossary / 術語條目）不是字典條目 — 字典答「這個詞是什麼」、承載知識答「你在討論什麼、撞到什麼問題、才需要這知識」。撰寫者有預設情境讀者沒有、所以每張卡（或其上層）要從情境進入而非劈頭給定義：建議題 hub（以讀者遇到的問題為題）討論再分流到原子卡、卡頂回指議題、讓搜尋直接落地者也有回路。沒這層卡淪字典、讀者沒有觸發點、不知何時用。詳見 atomic-note-needs-situational-entry。

4. 可查詢性（Searchability）

關鍵字前置、使用可 grep 的分隔符（: | → ==）、欄位名稱使用 regex 友善格式。命名讓 AI 能以單次 grep 命中，不需要語意推理。

5. 欄位設計（Field Design）

同一份文件的不同欄位，從不同角度觀察同一件事，不重複撰寫。what 描述動作、why 陳述動機、acceptance 定義可驗證條件；混淆欄位會讓讀者在多處讀到相同內容。

6. 多輪 Re-read Pass（Multi-pass Review）

完稿即進入 review 階段。一次寫對全部維度違反 working memory、實際結果是「每維度都做一半」。設計 N 輪 re-read、每輪用不同 frame：

Surface enumeration 是 multi-pass 的固定前置步驟。寫作產物包含 body surface 與 metadata / navigation surface：title、description、tags、heading、link label、MOC / index entry、slug / filename。每輪 frame 都掃這份 surface 清單，讓正文與讀者入口共用同一個概念錨點。description / hook 對規則做壓縮時、可以丟細節、不可以改模態 — 把本體的「條件允許（可延後但要記錄）」壓成「絕對禁止（不可跳過）」、讀者依摘要行動就會偏離本體；摘要讀起來比本體「更有力、更乾脆」就是失真訊號、模態詞跟主詞動詞同級、最後砍。實測一批七份文檔有四份的 description 出現模態漂移 — 這個檢查每批都要跑。

核心：「再仔細一次」≠ multi-pass — 同 frame 重看 catch 不到新問題。每輪換 frame、才能 catch 不同層。各 reference（writing-articles / writing-code-comments / writing-documents / writing-prompts）依 output 類型有特化的輪次組合。

Naming 是這條原則最容易跳的子場景 — 第一版命名幾乎不對、四輪 review（第一版 / grep / cross-call-site / impl 洩漏）才收斂、見 naming-as-iterated-artifact 跟 writing-code-comments 的 naming review 段。術語是 naming 的高歧義子場景：翻譯術語第一次出現保留原文錨點，中文壓縮術語保留完整名詞頭，中文名詞頭要保留來源中的概念角色，見 terminology-keeps-original-anchor、compressed-chinese-terms-need-head-noun 與 translation-must-preserve-concept-role。

高 stakes 內容追加輪 E（epistemic rigor、conditional opt-in）：reader 照做後錯誤不可逆的內容（資安 / concurrency 正確性 / distributed consistency / financial / medical）在 5 輪基本 frame 之外、追加 stakes 軸的 epistemic rigor pass——比照學術 peer review 跑 claim / evidence / method / threats / citation 五個 sub-check、加上 audit recommendation tier（accept / minor / major / withdraw）。一般內容 5 輪夠、不跑輪 E；高 stakes 內容兩軸都跑。詳見 references/auditing-articles.md 跟 /report/writing-multi-pass-review/ 的「stakes-conditional 追加輪」段。

Production 教學文章追加輪 8-10（字句層 catch、跑 N 輪仍漏時觸發）：跑了 5 輪基本 frame 仍系統性漏 catch 字句層問題（口語修辭 / 廢話前綴 / 地區漂移 / 依賴 code / 裝飾符號 emoji / 對讀者喊話 / 自評誇飾 / 必然性框架 / 恐嚇式語氣 / 歸因語氣）時、追加三個換軸機制——輪 8 keyword bank（換工具、含 emoji / 裝飾 unicode 掃描）、輪 9 reader simulation（換視角、四 lens：自包含性 + register/stance + meta 殘留 + AI 歸因過度）、輪 10 self-criticism（換層次、審視 framework 本身覆蓋度）。短文 / 即時 note 不需要、production 教學文章在跑 5 輪後仍漏同類問題時 opt-in。keyword bank 命中是候選、不是判決——grep 命中後仍要一個語意判定步驟（這個命中是建立概念的違規、還是合規的反例對照 / hook），reviewer 容易把違規合理化放行；偵測（bank）跟判定（語意）是兩個認知步驟。register/stance 類（喊話 / 誇飾 / 必然）無穩定關鍵詞、keyword bank 抓不到、輪 9 reader-sim 是主 keyword bank 是輔、且最依賴 external cold-read。漏抓後補機制前先分 design gap（框架缺 frame、改框架）vs execution gap（框架有 frame 但只跑了臨時子集、改執行不是改框架）——「加 keyword」對 execution gap 跟無關鍵詞的類都無效。詳見 multi-pass-review-frame-granularity、decorative-symbols-keyword-bank、teaching-prose-neutral-register 跟 references/writing-articles.md 輪 8-10 段。

批量 sibling 寫作的生成端輪替：一次寫多份同類文檔時、cadence 同質化會在六個層發生（title 形式 / 開場句式 / 章節標題 / 敘事骨架 / 條目形態 / 跨檔引用句）、單份 review 全部抓不到、且 review 端抓過的同骨會在下一批復發 — 同類 finding 第二次出現、就把規則升到生成端：寫之前排好開場 frame 輪替（規則先行 / 後果先行 / 動作先行 / 反差先行）、條目形態輪替、敘事視角輪替、引用句去重。詳見 cadence-homogenization。

Instance 軸：跨 reviewer instance 隔離：Instance 軸是 multi-pass review 的另一條擴展軸 — N 個獨立 reviewer instance 各自獨立 context、各自跑 background、解「單一 reviewer 同時看多維度容易維度盲點 + context 污染」的問題。Instance 指獨立 reviewer 程式實體（如 agent tool spawn 出的 subagent）、跟同一 reviewer 換輪次 frame（frame 軸）正交可疊加。適用 production 教學文章 / 高 stakes 內容 / 跨章節教學模組這類維度複雜度高的審查場景。詳見 agent-team-context-isolation。

詳見 Writing 的 multi-pass review、Methodology 的 multi-pass 該 embed 在 pillar、Metadata surface 要納入寫作 review 範圍、False sense of security 是高 stakes 寫作的主要失敗模式、Risk-asymmetric audit standard、colloquial-rhetoric-erodes-technical-precision、prose-self-contained-without-code-reference、regional-terminology-alignment、multi-pass-review-frame-granularity、design-flaw-by-current-axes-not-hindsight、agent-team-context-isolation、decorative-symbols-keyword-bank、teaching-prose-neutral-register。

When to Consult This Skill（觸發路由）

每份 reference 自包含：以該情境為核心，把核心原則翻譯成可直接套用的檢查項與範例。閱讀任一 reference 不需要回來看其他 reference。

Success Criteria（M1-M2 認知負擔類）

詳細量測方式與自評表見 references/meta-metrics.md。M3-M5（token 類）保留未定，待實際範例累積後補足。

跟特化寫作流程的分工

本 skill 是 單篇 寫作的基礎方法、覆蓋 articles / comments / logs / prompts / fields 等 surface。當寫作對象是 跨多章節的教學模組（5+ 章、有案例庫支撐、跨章引用密集）、屬特化情境、有專屬的 跨章節生產流程：案例庫 audit 抽 findings、SSoT 對應規劃、agent team 平行 review、跨檔修正循環、跨章 polish pass。

兩類流程的分工：

兩類流程互補疊加 — 教學模組的每章內部寫作仍套本 skill 6 原則、case 引用段落用 case-citation-three-part-structure、agent team review 用 agent-team-context-isolation。當下游專案沒有跨章節教學模組需求、本 skill 即可獨立運作；當有需求、教學模組生產流程是本 skill 的擴展層、不取代本 skill。

跟 multi-round-review 的協同

寫多篇章節 / report 卡 / knowledge card 後做多輪 agent reviewer audit 時、本 skill 應該跟 multi-round-review skill 同時啟動。觸發詞「多輪審查 / Round 1/2/3 / batch review / 寫作 audit」會同時啟動兩個 skill：

• multi-round-review 規劃 frame 切換結構（Round 1 compliance / Round 2 cadence / Round 3 self-application）跟跨輪 finding 整合工作流
• 本 skill（compositional-writing） 提供每輪 frame 的字句層 keyword bank — Round 1-A 寫作規範 reviewer 必須跑：
  • 正向陳述優先 grep：rg "不[行可是要能該支對符夠必]|無法|沒[做有]|而非|而不是"、加上否定起手定義句（原 pattern 漏「而是」、抓不到「不是 X、而是 Y」的後半）：rg "不是.{0,30}而是|不是.{0,20}、是|與其.{0,20}不如|不只.{0,15}更" — 主要敘述要正向、反例對照的少量負向可保留；判別在「核心概念第一次正面出現在句首、還是被擠到『而是』之後」
  • 口語修辭 grep：rg "其實|實務上|真的|碰巧|立刻撞牆|沒事"
  • 地區用語 grep：rg "集群|默認|質量|視頻|函數|文件夾|接口"
  • 廢話前綴 grep：rg "值得注意的是|需要說明的是|實際上|基本上|事實上"
  • 裝飾符號 grep：rg "✅|❌|⚠️|🚨|🟡|🟢|⭐|📌|✓|✗"
  • 對讀者喊話 grep：rg "很多人|大家|不少人|你天天|你會|你可能|先讀懂|先釐清|別搞混|別被" — 教材中性陳述、不安撫情緒 / 不第二人稱代入 / 不祈使控制閱讀（hook / narrative 段落輕度第二人稱可留）
  • 自評誇飾 grep：rg "教科書級|堪稱|可謂|完美|經典|範本級|大師級|漂亮地|優雅地|最佳實踐|best practice" — 品質 verdict 頂替技術理由、換成機制 / 條件
  • 必然性框架 grep：rg "天生|與生俱來|本質就是|本來就是|必然|唯一|註定|理所當然" — 把設計選擇講成自然法則、還原成條件性（物理 / 法律 / 數學事實除外）
  • 歸因語氣 grep：rg "承認|暴露了|證明了失敗|被迫" — 描述系統行為用「信號」「反映」「顯示」等中性觀測詞、避免「承認」「暴露」等責任歸因詞；「被迫」在描述外部強制約束時可保留
  • 宣導語氣 grep：rg "你可能沒注意|你可能不知道|想像一下|把.{1,5}想成|跑得好好的|聽起來很|其實很簡單|說穿了就是|等於拆未爆彈|乾瞪眼|延遲引爆" — 預設讀者無知或用情緒管理取代事實陳述；讀者是專業人士、直接描述情境與後果
  • 泛用詞濫用 grep：rg "坑|東西|搞|弄|處理一下|情況" — 同一個泛用詞蓋過不同具體情境時、依情境換精確詞（意外 / 陷阱 / 出問題 / 發生狀況）；命中密集且各指不同事才算違規、真泛指 / 引號引用 / 輕度 hook 合規；「坑」另有地區偏移面（某些地區高頻、某些少用）。見 avoid-overused-generic-words
  • 這些 grep 曝光候選、不做自動判定：命中後要不要算違規有品味核心；且 LLM reviewer 跟作者共享文體、同源自審對 register 類（否定起手 / 喊話 / 誇飾 / 概念前置）有結構上限 ——「不是 X、而是 Y」這種 LLM 高頻自產句型最容易全員放水。grep + 同源判定只負責曝光候選、register 層的真防線是文體異源視角（human cold-read 或 prompt 採「挑剔否定起手 / 概念後置」對抗姿態的 reviewer）、同源回報的「clean」不可當真

詳細各維度的判讀規則跟修法、見對應 reference（writing-articles / writing-documents 等）跟 references/principles/ 內的 cadence-homogenization / colloquial-rhetoric / regional-terminology / decorative-symbols / multi-pass-review-frame-granularity 等卡。

協同要點：

• 單獨用 multi-round-review、容易漏字句層 — reviewer prompt 列「規範遵循」但漏 grep 具體 pattern
• 單獨用本 skill、容易漏跨輪 frame 規劃 — 知道要檢查字句層、但缺「Round N+1 用什麼新 frame」結構
• 兩個 skill 一起啟動 — multi-round-review 給結構、本 skill 給每輪的 grep checklist

寫作對象是「單篇 + 完稿前自己 review」時、用本 skill 第 6 原則（多輪 Re-read Pass）的 5 輪 frame 即可；寫作對象是「跨多篇 + agent reviewer 平行 audit」時、multi-round-review 接手結構規劃、本 skill 在 reviewer prompt 內被引用作為檢查清單。

Directory Index

 1compositional-writing/
 2├── SKILL.md                              # 本檔：核心原則速查 + 觸發路由
 3└── references/
 4    ├── writing-code-comments.md          # 情境 1：程式碼註解
 5    ├── writing-documents.md              # 情境 2：文件撰寫
 6    ├── writing-logs.md                   # 情境 3：log 輸出
 7    ├── writing-prompts.md                # 情境 4：prompt 撰寫
 8    ├── writing-articles.md               # 情境 5：完整長篇技術文章
 9    ├── source-to-teaching-analysis.md     # 情境 5a：外部分析材料 → 教學型分析文章
10    ├── translation-review.md             # 情境 5b：文章翻譯 / 轉譯的句內邏輯 review
11    ├── managing-article-collections.md   # 情境 5c：跨多篇文章的結構（三層、素材庫比例、MOC、Pattern 卡片）
12    ├── designing-fields.md               # 情境 6：欄位設計（含六欄位角度總表）
13    ├── designing-fields-ticket-6w.md     # 六欄位詳細範例：正確 + 混淆共 12 項（按需讀取）
14    ├── meta-metrics.md                   # 品質量化驗收（M1-M5）
15    ├── reference-authoring-standards.md  # Skill reference 撰寫品質規範
16    ├── dry-run-guide.md                  # Skill 發布前語意層驗收（Phase 2 dry-run 流程）
17    └── principles/                       # Skill 內部支撐型原則卡（含 terminology / naming / review / case-citation / agent-team 等原則）

Reading Order（建議閱讀順序）

1. 第一次接觸 → 從本 SKILL.md 的「核心支柱 + 核心原則」讀起
2. 進入實際寫作情境 → 依觸發路由讀對應 reference（只讀一份）
3. 想驗證成果 → 讀 meta-metrics.md 做自評

Last Updated: 2026-06-25 Version: 0.18.0 — 輪 9 reader-sim 加第四 lens「AI 歸因過度」（AI 生成內容系統性把通用 pattern 框為 AI 特有、縮窄適用範圍且背上無法證實的舉證負擔；判準：「AI」換成「作者」論點仍成立 → 改通用觀察）；提交自檢清單加第 4 個生成端自問句（AI 歸因測試）。

Version: 0.18.0 — 新增「泛用詞濫用」字句層 frame（讀者回饋觸發：反覆用「坑」把不同情境壓成同一模糊標籤、繁中少用）：keyword bank 加 rg "坑|東西|搞|弄|處理一下|情況"、新增 principle 卡 avoid-overused-generic-words（依情境換精確詞、跟 colloquial/regional/cadence 三卡的軸區分）、writing-articles 輪 8 清單同步；命中密集且各指不同事才違規、真泛指 / 引號 / 輕度 hook 合規 Version: 0.17.0 — keyword bank 新增歸因語氣 grep + 否定起手定義句 pattern；輪 8-10 描述補恐嚇式語氣 / 歸因語氣；移除 comment-qa-hook / worklog-format-check hook（職責已由其他機制覆蓋）；references 更新（atomic-note / teaching-prose / writing-articles / writing-documents）。

Version: 0.16.0 — 從工具 opinion 文章的三輪審查 + 使用者回饋回流 6 張 report 卡（WRAP 分析後選混合方案）：(1) keyword bank 加歸因語氣 grep（承認|暴露了|證明了失敗|被迫）— 唯一有穩定關鍵詞的新 design gap；(2) teaching-prose-neutral-register 加第四類「恐嚇式語氣」（把讀者放在被警告位置、判別線是「你→我們」替換測試）；(3) writing-articles 輪 9 reader-sim 加第三 lens「meta 資訊 vs 內容」（涵蓋 meta-commentary 殘留 + 主題偏移兩個 gap）；(4) writing-articles 提交自檢清單加 3 個生成端自問句（恐嚇式 hook / meta 刪除測試 / 歸因語氣）。不新增 principle 卡（27 張已夠、新議題融入現有卡）、不增 SKILL.md 主體段落（密度飽和、改動集中在 keyword bank 一行 + 下游 reference）。

Last Updated: 2026-06-11 Version: 0.15.0 — 對七張同批 report 卡（#157-#163 主題：語意錨 / 決策表 / 入口分流 / 跨 surface / 摘要模態 / 引用詞彙 / 欄位契約）跑三 reviewer audit 後的回饋：(1) 新增 principle 卡 cadence-homogenization（同時修復 SKILL.md 長期 dangling 的引用）— 六個同骨層實測清單 + 生成端輪替規則 + 「同類 finding 第二次出現升生成端」的升級原則（觸發：上一輪抓過的「判準句同模」在本批復發、擴到 4/7）；(2) 原則 6 surface enumeration 補 description 模態檢查（實測 4/7 份 description 模態漂移、其中一份把同批另一張卡才立的「候選」壓成「證據」）；(3) 原則 6 補批量 sibling 生成端輪替段；(4) 原則 2 補「語意錨單一字串 + 引用他卡用對方詞彙」段（關係宣告 28 條核對抓到 2 條：被引卡沒漏的宣稱成漏、對方的 navigation surface 被轉述成 metadata surface）。

Last Updated: 2026-06-11 Version: 0.14.0 — multi-round review Round 1 的 self-application 修正：兩個 reviewer 從不同 frame 獨立抓到本 skill 自身殘留 count-bearing 名稱（convergence 訊號）。(1) 「Core Pillars（三大支柱）」→「（核心支柱）」、「Six Principles（六大原則速查）」→「Core Principles（核心原則速查）」、「五階段流程」→「case-first 流程」；(2) references 內「五大原則」全改「核心原則」— 這批字串在原則從 5 個長到 6 個之後就已經全部過期（SKILL.md 寫六大、references 寫五大）、是 name-collections-by-role-not-count 卡描述的失效模式在本 skill 的實證；(3) reference-by-semantic-title-not-number 卡的 ISO 邊界限定到版本年份（跨版改版會重編條款）。後續 Round 3 self-application sweep 抓到本條宣稱的漏網（writing-code-comments 的「五大寫作原則」）與另兩處 count 殘留（「五大 surface」「三大正交 axis」）、已一併清除；兩張新 principle 卡依 steelman 補強（#155 卡補「標題改名 vs 編號位移」斷裂等級差、#156 卡補數字記憶價值的誠實對沖與「內部宣告凍結」邊界）。

Last Updated: 2026-06-11 Version: 0.13.0 — 0.12.0 的同日延伸：使用者指出「核心七問」「成長六階段」是另一層問題 — 引用端修好了、但錨點名稱本身內嵌成員數（七 / 六 是 membership 的 derivation）、加一問名稱先失真、所有複製過名稱的地方跟著過期；0.12.0 的原則 2 新段自己就用「見核心七問」當正面範例而未察覺、證明命名端與引用端是獨立檢查維度。(1) 原則 2 補「集合命名用角色、不內嵌數量」段；(2) 新增 principle 卡 name-collections-by-role-not-count（self-contained、含三種可留數字的邊界：外部凍結品牌 / 概念閾值 / 緊鄰清單行內計數、含命名端掃描 regex）；(3) reference-by-semantic-title-not-number 卡補 sibling 連結、0.12.0 三處「核心七問」範例全改「核心問題」；(4) writing-documents Principle 2 補命名端段落。

Last Updated: 2026-06-11 Version: 0.12.0 — 從一份多階段訪談 skill 的階段重編號事故回流：跨檔引用寫成「Stage 3」「Stage 1-3」、流程從四階段改六階段後十多處引用 silent 錯位（字面完好、語意指向錯的階段）、grep 只能抓字面、人工逐處判讀仍漏修兩處。(1) 原則 2（索引建立）補「引用錨點用語意標題、不用位置編號」段 — 編號是結構排列的 derivation、misdirected 比 dangling 難偵測、標題要承載可被引用的語意、凍結編號（RFC / 法條）是 fact 例外；(2) 新增 principle 卡 reference-by-semantic-title-not-number（self-contained、含重排 commit 的引用面掃描 regex）；(3) writing-documents Principle 2 cross-reference 段補同主題小節 + anti-pattern 表加「See Stage 3 指向活文件」列。同一問題第二次出現（v0.9.1 曾修過「Stage 1-5」→「五階段流程」的 portability leak）、符合兩次門檻立卡。

Last Updated: 2026-06-01 Version: 0.11.0 — 從一篇技術教材 review 抽出三類字句層 register/framing 問題回流：(1) keyword bank 加 3 類（對讀者喊話 / 自評誇飾 / 必然性框架）、同步 description、協同段 grep、輪 8-10 段、writing-articles 輪 8；(2) 原則三補「絕對二元語氣的命令式 vs 必然式」subtype（必然式偽裝成事實、更隱形）；(3) 新增 principle 卡 teaching-prose-neutral-register（涵蓋三類、self-contained）；(4) multi-pass-review-frame-granularity 補「偵測之後：keyword bank 命中是候選不是判決」判定層段（偵測 vs 判定兩步驟、clean 可能是判定放水）。跟 multi-round-review Round 1-A 同步加 3 grep + 判定指引。

Last Updated: 2026-05-27 Version: 0.10.0 — 從 13 張 knowledge cards 批量改寫負向表述的經驗回流：(1) description 加觸發詞「多輪審查 / multi-round review / batch review / 寫作 audit / 正向陳述 / 口語修辭 / 字句層 grep」、明示「也在 multi-round-review 啟動時觸發」；(2) 新增「跟 multi-round-review 的協同」段、列出 Round 1-A 寫作規範 reviewer 必須跑的 5 個 grep pattern（正向陳述 / 口語修辭 / 地區用語 / 廢話前綴 / 裝飾符號）、明示兩 skill 垂直協同關係；(3) 修正 multi-round-review 漏抓字句層的盲區、跟 multi-round-review v1.1 同步 cross-trigger 設計 Version: 0.9.2 — 從 business case-analyses 演變回流：新增 source-to-teaching-analysis.md 路由，處理外部分析文章 / 產業評論 / 投資人備忘錄到教學型分析文章的轉換；新增三張 principle（external-analysis-source-layering / cross-domain-reader-level-alignment / analysis-rewrite-delivers-transferable-framework），把 source 分層、跨領域讀者降層、可遷移框架交付從 blog report 抽成 portable 規則。 Version: 0.9.1 — Stage 4 修正 3-reviewer 抓的 33 issue：(1) #120 mirror 縮 scope 解過載（移除四 axis 表 / 句構分流 / polish pass 段、聚焦三段式結構 axis）+ 結論段首改概念定義句解 dogfooding 失敗；(2) #121 mirror 結論表三欄重設計（設計選擇 / 解決問題 / 失敗模式）+ 實作 pattern 縮成 abstract pattern；(3) 兩 mirror 角色段引用點改措辭（移除虛假引用宣告）；(4) SKILL.md 原則 3/6 兩補強段段首改概念定義句、原則 6「詳見」list 補新 mirror、Directory Index 補；(5) Portability leak 修：「Stage 2 自查清單」→「寫稿後段落自查清單」、「Stage 1-5」→「五階段流程」；(6) 五大 / 六大原則 drift 對齊（line 105 / 160）；(7) 既有 principles（writing-multi-pass-review / multi-pass-review-frame-granularity / ease-of-writing-vs-intent-alignment）補回引新 mirror、形成雙向 cross-link Version: 0.9.0 — 從跨章節教學模組生產經驗回流：原則 3 補「Case 引用段落三段式結構」段（詳見 case-citation-three-part-structure）；原則 6 補「Instance 軸：跨 reviewer instance 隔離」段（詳見 agent-team-context-isolation、跟 frame 軸正交可疊加）；新增「跟特化寫作流程的分工」段（明示本 skill 是單篇基礎方法、跨章節教學模組生產流程是擴展層）；principles/ 新增兩張 mirror 卡（case-citation-three-part-structure / agent-team-context-isolation）、自包含、不引用外部 skill 或 blog content Version: 0.8.1 — 第 6 原則同步 writing-articles v0.8.1：補「Production 教學文章追加輪 8-10」段（換工具 / 換視角 / 換層次三機制處理「跑 N 輪仍漏」字句層問題）；「詳見」連結加 5 張新 principle（colloquial-rhetoric / prose-self-contained / regional-terminology / multi-pass-review-frame-granularity / design-flaw-by-current-axes） Version: 0.7.4 — 新增 translation-review.md 路由：翻譯 / 轉譯文章時，用句內邏輯檢查譯名是否跟主詞、動詞、修飾語、因果與讀者追問方向對位。 Version: 0.7.3 — managing-article-collections 補「素材庫比例」路由：多篇文章需要案例 / source / scenario / pattern 支撐時，主文章情境維持少量、素材庫保留 2-3 倍來源做反向驗證 Version: 0.7.2 — 補 multi-pass 的 surface 軸：review 先列 body / metadata / navigation surface（title、description、tags、heading、link label、MOC hook、slug / filename），每輪 frame 都掃同一份 surface 清單；新增內部 principle metadata-surface-in-writing-review.md Version: 0.22.0 — 原則 3 加「知識卡建卡判準用最不熟悉的讀者」；常識是相對於讀者背景的、跨背景讀者群幾乎所有領域特定術語都需要建卡 Version: 0.21.0 — 原則 3 加「操作步驟帶環境專屬工具路徑」（同動作在 container/VM/共享主機的工具不同） Version: 0.20.0 — 原則 3 加「讀者定位聲明」生成端前置步驟；從 infra 模組 retrospective 抽出（讀者定位未預設導致宣導語氣通過三輪審查） Version: 0.19.0 — 新增三張 principle 卡（audience-is-professional-not-layperson / cross-expertise-scenario-not-analogy / management-reportable-info-in-technical-content）、原則 3 加讀者定位與跨專業溝通子原則、keyword bank 加宣導語氣 grep；從 infra 教學模組的寫作 retrospective 抽出 Version: 0.7.0 — Phase B1 結構升級：加第 6 原則「多輪 Re-read Pass」（明示 5 輪 frame）、引用 #83 / #84 / #85 multi-pass 系列。後續 Phase B2 會把各 reference 結尾加「第 2 輪 review checklist」段 Version: 0.6.0 — 從 references 過載的反思：writing-articles.md 從 780 行瘦身到 ~530 行（拆分判準 / 三類 structure 模板搬到 managing-article-collections.md、focus 集中在「單篇文章內部」）；新增規則八「自我應用 (dogfooding)」（教某條規則的段落本身遵守該規則）；managing-article-collections.md 整合「拆分判準」+「三層 structure 詳細對照 + 模板」；meta-metrics.md M2 加 dogfooding 失敗訊號 Version: 0.5.0 — 從批量改寫 35 篇的經驗回流：原則 3 補「選項數由議題決定、不強湊」（避免 A/B/C/D 強迫症與「實務上幾乎不存在」的假反模式）；writing-articles.md 新增規則九（三類文章 structure 模板）；managing-article-collections.md 新增「跨篇引用 idiom 庫」與「三層 structure 對照」 Version: 0.4.0 — 新增 managing-article-collections.md（跨多篇文章結構：三層、MOC、Pattern 卡片）；強化原則 1「原子化」（focus 是議題完整度、不是邊界清晰）；強化原則 3「意圖顯性」（機會成本語氣、不用絕對主義） Version: 0.3.0 — 新增 dry-run-guide.md 於 Directory Index 與觸發路由（Skill 發布前語意層驗收 Phase 2 dry-run）

寫教學文章時、純靠 LLM 自生內容會踩到兩個系統性盲點：

1. Scope 盲點：內容停在「教科書級」結構、漏掉真實事故才會浮現的失敗模式跟設計取捨。
2. 準確性盲點：把通用 best practice 包裝成「[case] 揭露」、把案例沒講的細節寫成案例事實。

本文整理在 backend/01 至 backend/07 batch 1 七個模組撰寫過程中浮現的五階段流程：

1. 完整閱讀案例庫、抽 findings — 用案例驅動「該寫什麼」、不只是 LLM 自生
2. 基於 findings 建立內容 — findings 分布到章節、避免硬塞模板
3. Agent team 平行多輪審查 — 用 3 個專責 reviewer 補 LLM 自盲點
4. 修正循環 — 按檔案批次修 high + 重要 medium、reviewer 抓出問題各章節對應修
5. Polish pass — 跨檔系統性 pattern 集中處理（負向骨架掃描、編號漂移、用語不一、cross-link 補漏）

實作數據：7 個模組（backend/01-07 batch 1）、~45 章 / 385 個 review issue、case fidelity 落在 70-93% 區間、修正後品質升至 0 critical 編造、cross-link 全綠、規範違反 polish pass 後降到單位數低 issue。06 模組後方法論工具化為可觸發 skill、stage 1-5 流程跟 reviewer prompt template、self-scan regex 都封裝成可重用元件。07 模組驗證下「章節已有 routing layer skeleton」的特殊處理（在現有結構內補 case-driven 深化段、不擴成厚重章節）。

問題：LLM 自生內容的兩個盲點

純靠 LLM 寫教學章節、容易產出兩種品質風險：

Scope 盲點：LLM 從訓練資料抽出的內容偏 普遍性、是「教科書 + 部落格 + 文件」的綜合。但真實工程議題的判讀條件常常來自 特定事故揭露、不是普遍知識。例：

• 「DynamoDB GSI 在 backfill 完成前查不到完整資料」這種具體陷阱
• 「Super Bowl +50% no sweat 的工程意義是 headroom 提前預留、不是 vendor 神奇」這種反直覺判讀
• 「99.99% → 99.999% 是指數成本、遠超直覺的 10x 線性想像」這種規模對照

純技術知識推導不出來、要看真實案例才會浮現。

準確性盲點：LLM 寫到「對應 [case]」時、容易把通用 best practice 包裝成案例事實、或把案例沒提到的細節擴寫成「案例揭露」。例（從本文討論的實作中抓出的真實 issue）：

• Snowflake 案例描述「異常查詢偵測維度（query 體積 / IP / 跨 schema scan）」、LLM 自生內容寫成「query 體積從 1MB / 天跳到 10GB / 天、來源 IP 從 office network 變 unknown VPS」— 具體數字是 LLM 加上去的、案例沒寫
• Tixcraft 案例策略段建議「composite key」、LLM 自生內容寫成「Tixcraft 用 user_id 分散、不是 event_id」— 案例沒揭露 Tixcraft 實際 partition key 設計

這兩類盲點都不容易在 self-review 時抓到、因為 LLM 看不出自己內容是否真的對應案例。

階段 1：完整閱讀案例庫、抽 findings

為什麼要完整閱讀、不能只看 title + description

只看 title + description 能做 承接（建立 link）、但無法做 scope 擴展（揭露 LLM 不會自生的議題）。case 的 findings 通常埋在 body 的「判讀」段、不在 description 裡。

實作中的對照：第一輪 audit 6 個 case、每 case 平均揭露 2.3 個 finding；其中約 7 成是 description 跟 title 看不到、要讀完整 body 才能抽出。例如 DraftKings 案例的「讀寫雙峰錯位」（比賽中讀爆量、payout 時寫爆量）— description 只說「financial ledger」、要讀「核心負載形狀」段才看到雙峰結構。

邊際遞減的判斷

不是所有 case 都要讀。實作中觀察到的遞減曲線：

第三輪開始 純新議題 比例下降、重複 frame 出現（vendor dogfood 在 3 個 case 都揭露、benchmark 對照基準在 3 個 case 都揭露）。這是停止 audit 的訊號。

判讀條件：

• 繼續 audit：每 case 至少 1.5 個純新議題、且重複 frame 不超過 30%
• 停止 audit：純新議題 < 1 個 / case、重複 frame > 50%、累積 finding 數已涵蓋目標章節主要議題

實作中 11/94 cases（~12%）時邊際遞減訊號明顯、16/94 cases（~17%）時停止 audit、抽出 ~42 個 unique findings、足以支撐 6 個章節的 scope 擴展。

Findings 抽取方法

讀 case 時、把每個段落看成可能的 finding 來源、問三個問題：

1. 這段揭露什麼判讀條件？（是不是純技術推導不易浮現的議題）
2. 這段揭露什麼數字 / 設計細節？（規模、percentile、partition key 數量、replication lag 量級）
3. 這段揭露什麼失敗模式？（事故當下會出什麼問題、有什麼反直覺結論）

寫進 findings 列表時、要附上 case 來源 跟 該對應到哪個章節。例：

Finding: 線性擴展是 OLTP 設計最高目標、coordinator 是傳統 OLTP 的擴展瓶頸 來源: 9.C10 Spanner 案例「2 nodes → 45K reads/sec, 4 nodes → 90K reads/sec」段 章節: 1.11 全球分散式 OLTP

不寫來源跟章節定位、findings 會變成抽象列表、寫稿時用不上。

Case 類型的承接策略

不同 case 類型適合不同承接深度、誤判類型會引發 over-extrapolation 問題。實作中觀察到的兩類 case：

Rich case（典型：09/07 案例庫中含具體數字、設計細節、遷移路徑的長篇 case）：

• 內容深度：50-200 行、含具體數字、業務情境、引用源
• 承接方式：可直接引用為事實、case 揭露的具體數字（RPS、延遲、TPS、stale window）可放進章節
• 例：9.C5 Amazon Ads「90M RPS + 5M writes/sec + 99.999%」可直接寫進 1.10 KV 章節
• 例：9.C6 Tinder「4700 萬 MAU 配對引擎、cache 是主要服務面」可直接做為 2.1 high-concurrency 的判讀依據

Medium case（06 模組新發現的類別、典型：模組內部 case 庫中含結構化「決策機制」+「可觀測訊號」表、但無具體數字的中篇 case）：

• 內容深度：30-50 行、結構化 5 段（問題場景 / 決策機制 / 可觀測訊號 / 常見陷阱 / 下一步路由）、含 mechanism + 訊號名稱、但不給具體數字
• 承接方式：用 case 直接列出的 mechanism 名稱 精準引用、比 skeleton 精準、但比 rich 保守
• 承接句型：「對應 [case]：揭露 N 個機制 — A、B、C、D」
• 例：6.C1 Amazon Shuffle Sharding 揭露 cell boundary / shuffle sharding / static stability / constant work 四機制、可直接引用機制名稱、但不擴寫到「具體 shard 數量」「具體 cell 大小」等 case 沒提的實作細節

Skeleton case（典型：模組內部 N.Cx 案例庫中只有 frame、無具體數字的短篇 case）：

• 內容深度：10-30 行、只給方向、無具體數字 / taxonomy
• 承接方式：作為「視角 / 方向」、可引用為「case 揭露 X 議題」、但不引用為「case 揭露 X 具體場景數量」
• 例：2.C1 Meta Cache Consistency 只有「promotion、shard move、故障恢復」三個方向、不引用為「具體 inconsistency window 數字」
• 例：3.C9 反例只給「依賴特定 offset / 重試節奏 / idempotency」三個方向、不引用為「4 個具體誤配場景」

判讀條件：

• 看 case 行數 + 內容密度判斷類型
• skeleton case 的 finding 寫成「對應 [case] — 揭露 X 方向、以下展開基於通用工程知識補充」
• medium case 的 finding 寫成「對應 [case]：揭露 N 個機制 — A、B、C、D」、用 mechanism 名稱精準引用
• rich case 的 finding 可寫「對應 [case] — XXX 具體數字 / 設計」

實作中（01/02/03 三個模組驗證）、skeleton case 寫成 rich case 對應是 case fidelity reviewer 抓出 over-extrapolation 的主要來源（02 / 03 各 3-4 個 critical 編造都來自此陷阱）。誤判類型 → 編造 case 沒寫的細節 → reviewer 抓出 → 修正成本高。stage 1 抽 findings 時就要 標明 case 類型、stage 2 寫作時依類型決定承接深度。

Rich case 引用的反向風險（04/05 模組新發現）：rich case 雖然可以引用具體數字、但 case 內常含「觀察層」（具體 fact）跟「判讀層」（作者推論）兩段、引用時要分開處理。05 模組驗證時 case fidelity reviewer 抓出 4 個 high issue 都來自把「判讀層作者推論」寫成「case 揭露的 fact」：

• 9.C12 Riot Games：5.2 寫「揭露 35ms latency 反推 region 部署」、實際 case 的「35ms」是觀察層、「反推 region 部署」是作者判讀層
• 9.C34 GCP 130K：5.2 寫「揭露 Spanner 替 etcd 才是 K8s 規模極限的關鍵」、實際 case 用更保守的「control plane 極限取決於 storage backend、GCP 用 Spanner 替換 etcd」分兩個點寫
• 9.C12 Riot：5.2 引用「single-tenant per game 的多 cluster 策略」、漏掉 case 揭露的關鍵歷史轉折「從 multi-tenant cluster 模型改成 single-tenant per game」

修法：rich case 引用時、用「揭露 X 觀察 + 作者判讀 Y」分層標明、避免把推論寫成 fact。或在引用後補一句「（case 中 X 屬作者判讀層、本章引用此推論）」明示分層。

兩類 case 的引用紀律可總結成一個 fact vs derive 分層原則：

• Skeleton case：絕大多數內容是 derive（方向 / 議題）、引用時不擴寫成 fact
• Rich case：含 fact（具體數字 / 設計）跟 derive（作者判讀）、引用時分層標明、避免把 derive 升級成 fact

階段 2：基於 findings 建立內容

Findings 分布到章節

抽完 findings 後、按章節主題分類、看哪個章節缺口最大、哪個 finding 該寫去哪。實作中的分布：

• 1.1 高併發：7 findings
• 1.5 紅隊：8 findings
• 1.9 reconciliation：4 findings
• 1.10 KV：6 findings
• 1.11 全球分散式：10 findings（最大缺口）
• 1.6+1.12 migration：5 findings

涉及多軸取捨的章節（1.11 一致性 / 可用性 / 成本 / 延遲）暴露最多缺口、純流程章節（1.9）暴露最少。這是 章節結構性質 的差異、不是寫得好壞。

Stage 2 寫作前先定 SSoT 對應

當同一 finding 或 frame 在 多個章節 都有用、要在開始寫之前 先定 SSoT 對應、否則 case-driven 擴章必然出現 frame 重複展開。

實作中觀察到的反例（02 / 03 模組都遇到過）：

• 02 cache：「cache 角色變化」frame 在 2.1 主寫但實際屬模組層級、應在 _index；Tubi 案例在 2.1 / 2.2 / 2.8 三章各自展開 mini-finding；Snap KeyDB 在 2.1 / 2.7 / 2.8 三章重複
• 03 message-queue（最嚴重）：「三層語意（delivery / processing / recovery）」在 3.4 / 3.6 / 3.8 三章各自定義；「Slack Kafka+Redis 拓樸」在 3.4 跟 3.8 兩章逐字重複；「規模對照（小 / 中 / 大型）」在 3.4 / 3.6 / 3.8 三章拆用、結論散落讀者拼不出總圖

SSoT 對應的判讀順序：

1. 列出所有 cross-chapter findings（出現在多章的 frame）
2. 每個 frame 指定 一個 主寫章節（SSoT）
3. 其他章節 只 link、不展開
4. SSoT 章節要有完整論述、被引用章節保留簡述跟 cross-link

SSoT 選擇標準：

• frame 涉及 跨模組層級概念 → 寫進 _index.md
• frame 涉及 單章核心責任 → SSoT 為該章
• frame 涉及 跨章交接點 → 選最相關章節為 SSoT、其他章節 link

漏掉這步、reviewer 跨章一致性會抓出 5-10 個 frame 重複 issue、修正成本高（要把已展開內容收斂回 SSoT）。Stage 2 前花 30 分鐘做 SSoT 對應、能省下 Stage 3 數小時的重構工。

避免硬塞模板

最大的反模式是把多個 findings 硬塞成同一個 table、每 row 一短語、失去情境敘事。

實作中的反例：1.9 章新增「Dual-track IC 5 個角色表」、本來想用表格整齊呈現、但 reviewer 抓出「5 角色平鋪、責任只一行、未展開每角色在真實事故的決策樣態」。修正後拆成：

• 主表格（5 個角色快速對照）
• Overall IC 跟 Tech IC 的差異獨立段（300 字）
• Data IC 的特殊角色獨立段（300 字、含「為什麼不能讓 Tech IC 兼任」的失誤對照）
• 事先準備 4 項各自延伸（不只列項目、解釋失效樣態）

這樣 每個項目都是情境 而非 硬塞的欄位、符合 AGENTS.md「表格不是終點」原則。

情境敘事的判讀條件

每段內容寫完後、問三個檢查問題：

1. 首句是不是核心原則？（不是「某 case 揭露 X」、是「X 是什麼、承擔什麼責任」）
2. 是不是用否定句主導？（「不是 X」「不只 X」開段要回到正向陳述）
3. 這個 finding 在不同情境下是否會變義？（一個 finding 套到多個情境、要分情境寫、不是套同模板）

案例引用的準確性

寫「對應 [case] — XXX」時、要回 case 原文驗證 XXX 是否真的出現。實作中常見的失分：

• 把 case 沒提到的數字補進去（「30-90 天 baseline」、「1MB→10GB / 天」）
• 把通用 best practice 寫成案例事實（「Snowflake 之後改為預設強制 MFA」— case 只說「資料平台應預設強制 MFA」、不是描述後續行動）
• 公開事實但 case 沒寫（「MOVEit 跨上百家客戶」、「LastPass master password 弱可被離線爆破」）

寫稿當下不容易抓、要靠階段 3 的 case fidelity reviewer 對照。

階段 3：Agent team 平行多輪審查

為什麼要 agent team、不能交給單一 reviewer

單一 reviewer 有兩個限制：

1. 維度盲點：一個 reviewer 同時看寫作規範、案例準確性、跨章一致性、容易 維度互相干擾、最後每個維度都看不深
2. Context 污染：reviewer 讀完整 commit + 所有案例 + 所有章節後、自身 context 就被佔滿、給的建議會 對應主 context 也跟著沉重

解法是用 3 個專責 reviewer、平行 background 跑、各自獨立報告、主 context 只看精煉摘要。

三個維度 reviewer 分工

實作中使用的三個 reviewer：

Reviewer A：寫作規範審查（AGENTS.md 核心原則）

• 對照核心原則先行、正向陳述優先、商業邏輯先於 case、表格不是終點、情境優先於模板、可操作判準等八原則
• 找首句用否定句切入、表格 / bullet 平鋪沒延伸、表格項硬塞模板等
• 實作中抓出 25 個 issue

Reviewer B：案例引用準確性

• 對照原始 case 內容、驗證「對應 [case] — XXX」斷言是否真的來自案例
• 識別編造數字、過度推論、把通用 best practice 寫成案例事實
• 實作中抓出 9 個 issue、包含 3 個 critical 編造

Reviewer C：跨章一致性

• 跨多章找重複 frame、矛盾說法、失效 cross-link、章節邊界錯位
• 識別「該在 A 章卻寫在 B 章」、「frame 重複展開沒整併」
• 實作中抓出 13 個 issue

平行 background 跑、不佔主 context

關鍵設計是 3 個 reviewer 並行、各自 background、各自寫 output file、不污染主 context：

• 主 context 只看到「啟動 reviewer」跟「reviewer 完成的彙整報告」
• Raw output 跟 reviewer 的 deep dive 留在 output file、需要時 SendMessage 繼續對話
• 3 個 reviewer 完成時間 ~5-15 分鐘、可以同時跑、不必等

實作中 3 個 reviewer 平均 2-3 分鐘完成、主 context 增量 ~3K tokens（彙整 + 47 issue 清單）、相比把所有案例跟章節塞進主 context 做 review 節省 ~80% context。

Reviewer issue 數量的 baseline

7 個模組（01 / 02 / 03 / 04 / 05 / 06 / 07 batch 1）驗證後、每模組 reviewer 抓到的 issue 數量在 standards reviewer 抓 pattern 越來越細的趨勢下持續擴大、可作為流程預期：

模式觀察：

• 每模組 issue 數隨 standards reviewer 抓 pattern 越來越細而擴大：01-03 穩定在 47-55、04/05 推到 51-59、06 推到 71、07 batch 1 回到 52（章節已有 routing skeleton、擴章規模小）。趨勢來自 standards reviewer 抓的 pattern 越來越廣（從負向骨架 → 「核心責任不是」變體 → 「沒有 X 會 Y」鏈式 → 「case 引用段首」框架 → 「case 引用句構同質化」）。
• Case fidelity 準確率分布更廣：04 的 92.9% 來自 skeleton case 嚴守「揭露方向、通用補充」紀律；05 的 80% 因引用 09 rich case 加入「fact vs derive 分層」新失分模式；06 的 88% 屬 medium case 紀律首次套用、揭露「實作層擴寫過頭」失分；07 batch 1 的 81% 揭露「跨 case 合成 frame」新失分類型（reviewer B 2 high 都屬此類）
• Consistency reviewer 抓到的 frame 重複跟章節數成正比：02 / 03 / 04 都有 ~13-18 個一致性 issue、05/06 跨模組 cross-link 密度高仍維持在 baseline 內、07 batch 1 因 7 章規模、issue 13 個落在 baseline 下緣

Stage 3 修正成本估算：

• Critical（編造、矛盾）：~每個 5-10 分鐘修正、佔 0-5 個（04/05 都 0 critical、紀律已成熟）
• High（重複 frame、章節邊界、判讀層 vs fact）：~每個 10-20 分鐘修正、佔 5-14 個
• Medium / Low（規範細節、cross-link 補）：~每個 2-5 分鐘修正、佔 35-45 個
• 總計 ~1.5-2.5 小時 / 模組

Stage 4 修正後仍會有 ~30-40% issue 殘留（low / medium 的 cross-link、編號漂移、用語不一）、屬於系統性 pattern、適合在 Stage 5 polish pass 集中處理（見後段）。

為何要多輪 review、不是一次到位

第一輪 review 的目的是 找問題、不是 修問題。問題清單列出後、要做兩件事：

1. 分類優先序：critical / high / medium / low、按嚴重度跟修改成本排序
2. 修正循環：批次修正、避免一個一個改散開、修完再跑驗證

修正後可選擇性做第二輪 review、檢查：

• 修正本身有沒有引入新問題
• 之前 reviewer 漏掉的維度（例：教學性、讀者路徑、實作可行性）
• 跨 commit 一致性

實作中第一輪足夠處理 47 個 issue、第二輪沒進行、留到未來模組（02 cache、03 message queue）累積經驗後再評估是否必要。

修正循環的執行原則

47 個 issue 分布到 6 個章節、修正時 按檔案批次、不是按 issue 編號順序。每個檔案一次修完所有相關 issue、減少切換成本：

• 1.5 紅隊章（12 issue）：含 2 個 critical 編造、優先處理
• 1.10 KV（7 issue）：含 1 個 critical 編造
• 1.11 全球分散式（5 issue）
• 1.12 大規模遷移（10 issue）：表格密度最高、最多延伸
• 1.1 高併發（4 issue）
• 1.9 reconciliation（5 issue）

每個檔案修完後跑一次 mdtools fmt --fix + mdtools cards + mdtools lint、確認該檔內部一致、再進下一檔。最後跑一次跨檔驗證、確認 cross-link 全部對齊。

階段 5：Polish pass（04/05 模組後新增）

Stage 4 修完 high + 重要 medium 後、仍有 ~30-40% 的 low / medium 殘留、屬於系統性 pattern（負向骨架、編號漂移、cross-link 缺漏、模板化）。這些 issue 不適合按章節批次修、適合用「跨檔系統性掃描」處理 — 這是 polish pass 的核心責任。

Polish pass 的觸發條件

Stage 4 後出現以下任一訊號、就該排 polish pass：

• Standards reviewer 抓出的「不是 X、而是 Y」段首結構超過 5 處（屬寫作習慣、單章修改無效率）
• Consistency reviewer 抓出「編號漂移」「失效 link」「用語不一」多處（屬跨檔規範問題）
• 自掃描漏掉的 pattern 出現在 reviewer report（例：04 自掃描說 pass、reviewer A 抓出 31 個 issue、暴露自掃描 regex 不夠寬）

Polish pass 不該做的事

• 不重寫章節結構：polish pass 是把現有內容修得更貼合規範、不是重新組織。重寫的觸發條件應該回到 stage 2、不是 polish pass。
• 不擴大 scope：原本 4.20 / 5.4 等不在擴充範圍的章節、polish pass 也不動。Polish pass 邊界 = stage 4 修改過的章節集合。
• 不追求 0 issue：reviewer 抓的 ~15 個 low 通常可保留為下次擴章節時自然處理。Polish pass 處理「系統性 pattern」、不處理「孤立 issue」。

Polish pass 的標準工序

按系統性 pattern 分批處理、每批跑一次自掃描確認：

1. 負向骨架掃描修正：用更寬泛的 regex 不是 |而不是|沒有.*[，、]會 掃描、把「不是 X、而是 Y」「而不是 X」改成正向陳述 + 後置邊界提醒。技術約束敘述（「多人共用 IP 無法區分」）保留。
2. 編號漂移統一：把 04.X 風格 plain text 改成 [4.X title](url) markdown link、跟 _index 對齊。
3. 表格延伸段補強（關鍵段）：選 2-3 個最高 impact 表格（判讀訊號表的爭議列、Buffer / Sampling 等選型表）補延伸子段、不全部補（避免擴展超出 scope）。
4. 模板化拆敘事（代表性段）：選 1-2 個最明顯的「四步驟模板套不同情境」段、拆成情境化敘事、其他保留為下次。
5. Cross-link 補漏 + ownership 邊界補強：reviewer C 報告的所有 cross-link 缺漏一次補完、用同一個批次跑 mdtools 驗證。
6. 用語不一統一 + 失效 link 修正：簡轉繁、/knowledge-cards/ vs /section/ URL 統一、失效 link 改規劃中或正確路徑。
7. 最終驗證 + commit：跑 mdtools fmt --fix && mdtools cards && mdtools lint、確認全綠、commit。

Polish pass 的實作成本

實作中（04 / 05 polish pass 合併 commit 1072087）：

• 處理範圍：11 個檔案、+44 / -29 行
• 修正項目：~35 個 issue（10 個負向骨架、2 個模板化、3 個編號漂移、3 個表格延伸段、3 個 cross-link、1 個 case 引用結構）
• 時間：~30-45 分鐘（不重寫、只 pattern match）
• 剩餘 ~15 個 low 保留下次

Polish pass 的 ROI 來自「系統性 pattern 一次處理 vs 散在各章一個個改」的效率差異。每個 pattern 在多章重複出現時、用 grep / rg 跨檔修一輪比每章單獨修快 3-5 倍。

自掃描盲點更新

04 流程暴露了一個 self-scan 盲點：原 regex 不行|不可以|不要|無法|不能 漏掉「核心責任不是 X、而是 Y」這個變體段首。修正建議：

• 加 ^[^|].*責任(不是|並非) 抓「核心責任不是 X」變體
• 加 ^[^|].*[，,]而是 抓「X、而是 Y」結構（已是正常陳述、但段首位置仍是負向骨架）
• 加 ^[^|].*[，,]不是 抓「X、不是 Y」結構

把自掃描 regex 視為持續演進的工具、每個 reviewer 抓出新 pattern 就更新一次、避免在下個模組重蹈覆轍。

適用情境跟限制

適用情境

• 長期累積的教學模組：6+ 章、跨章引用密集、規範遵循重要
• 有現成 case 庫：07/09 累積的 100+ 案例是這套流程的前提、沒案例庫做不到 case-first
• 品質高於速度：完整三階段約 3-4 小時 / 模組（stage 2 寫作 ~1.5-2hr + reviewer ~15 分鐘 + stage 3 修正 ~1.5-2hr）、適合長期累積的內容、不適合 one-off 文章
• 主 context 容量敏感：reviewer 平行 background 是節省 context 的關鍵設計

不適用情境

• 新主題沒案例庫：要先建案例庫、不能直接套這流程
• 單篇短文：流程的固定成本（讀案例 + 跑 reviewer）對短文 ROI 低
• 快速迭代原型：流程偏向 寫一次寫好、不是 快速修改
• Routing layer / 導讀性質章節：已含完整 threat scope + 引用標準 + 問題節點表、case 庫不對應或缺位、應跳過本流程、用標準引用 + 通用工程知識補充承接（07 LLM / 治理章節驗證）
• Standard framework 比 case 庫成熟的領域：見下段「Standard-driven 取代 case-driven」

Standard-driven 取代 case-driven（07 LLM 章節驗證）

在標準框架比 case 庫成熟的領域、case-driven 不是預設選擇。LLM 安全章節跑完 5 章驗證後浮現一個 finding：當該領域的 標準框架（如 OWASP LLM Top 10 2025 / NIST AI RMF 1.0 / MITRE ATLAS）已涵蓋 threat 分類、且 case 維護半衰期短於 standard、章節應 用 standard-driven 取代 case-driven。Standard-driven 跟 case-driven 是平行選項、依領域特性選用 — 兩者沒有退化 / 進階關係。

判斷該用哪種策略的四維度：

典型對照：

• Case-driven 領域：分散式系統 / 安全控制面 / 可靠性 / 訊息佇列（backend/01-07 batch 1 都屬此類、案例公開充分、半衰期 5+ 年）
• Standard-driven 領域：LLM 安全（OWASP LLM Top 10 / MITRE ATLAS 已成型、案例 6 個月過時）、新興 compliance（NIST AI RMF）、cloud-native 標準（CNCF baseline）

Standard-driven 章節的寫作策略：

1. 章節對齊 standard framework 分類：用 framework 章節 ID 標明（如 OWASP LLM01 / NIST AI-1.1）取代「對應 [case] —」斷言
2. 加 Last reviewed cadence：每 quarter 重評估 standard 版本跟章節對應、寫進 frontmatter
3. 「案例觸發參考」段標明「公開案例累積中、值得追蹤的方向」：不寫「對應 [case] 揭露」斷言、避免引用源不穩定
4. 引用標準時用版本號：OWASP LLM Top 10 2025 / NIST AI RMF 1.0 / MITRE ATLAS continuous — framework 改版要 trigger 章節重審

實證：07 LLM 章節 5 章已套用 standard-driven 策略：

• 章節 113-137 行、含完整 threat scope + 問題節點表 + 風險邊界
• 引用 OWASP LLM Top 10 + NIST AI RMF + MITRE ATLAS 取代個別 case 引用
• 加 Last reviewed: 2026-05-12 cadence
• 「案例觸發參考」段寫「公開案例累積中、值得追蹤的方向」+「事實查核註」
• 完全不寫「對應 [case] —」斷言、不存在 case fidelity reviewer 該抓的準確性問題

對照 backend/01-07 batch 1 的 case-driven 章節、LLM 章節是 用不同方法達到同樣品質 — scope 涵蓋真實 production 議題（KV cache 跨租戶、shared prefix optimization、batch 推論順序敏感）、不停在教科書級內容。

何時要從 standard-driven 轉回 case-driven：

• 該領域累積 5+ 個高可信度 case（vendor disclosure + academic paper + CVE 三來源交叉）
• 跨章 frame 重複出現、case-driven mechanism 深化能解 SSoT 衝突
• 出現「等級類似 SolarWinds」的 incident、案例本身夠重、單一 case 即可支撐章節擴章
• 讀者反饋章節太抽象、需要具體 case 才能理解 mechanism

不滿足任一條件時、繼續走 standard-driven、不勉強建 case 庫。

對 case-first-module-workflow skill 的補強：

skill 之前的「不適用情境」寫「沒 case 庫的新主題（要先建 case 庫）」— 這暗示缺 case 庫一定要先補。07 LLM 章節驗證了第三條路：用 standard-driven 取代、適用 standard framework 比 case 庫成熟的領域。這個 finding 已補進 skill 的「不適用情境」段。

限制

• Reviewer 維度有限：當前 3 個 reviewer 沒覆蓋「教學性」「讀者路徑」「實作可行性」、若主題需要這些維度、要加 reviewer
• 修正可能引入新 issue：第一輪 review 後修正、修正本身可能違反規範、若大量修正最好做第二輪
• Case 庫品質決定 findings 品質：case 寫得淺、findings 也淺；case fidelity reviewer 也只能驗證「跟 case 一致」、不能驗證「case 本身對不對」
• 依賴 LLM agent 平台能力：流程預設可平行跑 background agent、不是所有 LLM 平台都支援

7 個模組驗證後的反覆陷阱

01 / 02 / 03 / 04 / 05 / 06 / 07 七個模組執行下來、以下陷阱在 多數模組都重複出現、屬於 LLM case-driven 寫作的系統性失分點。本流程下次套用前要 主動防範、不能依賴 stage 3 reviewer 補救（雖然 reviewer 都會抓到、但修正成本高）。

陷阱 1：Skeleton case 擴寫成 case 事實

當 case 內容簡短（10-30 行、只有 frame 沒有具體數字 / taxonomy）、LLM 寫作時容易把通用知識（具體數字、攻擊向量列表、設計細節）寫成「對應 [case] —」斷言。實際 case 沒寫的。

實證：

• 01 紅隊：Snowflake「30-90 天 baseline」編造、Tixcraft「partition key 用 user_id」編造
• 02 cache：Tubi 三層 cache 具體 latency（L1 < 1ms、L2 < 10ms、L3 10-100ms）編造、Redis「100K-200K ops/sec」無來源、KeyDB「5-10x throughput」其實是 case 判讀段非引用源
• 03 messaging：PayPay「broker 寫入 3K msg/sec」實際 case 寫的是「DynamoDB 寫入 3K msg/sec」（PayPay 用 DynamoDB 不是傳統 broker）、3.C9 case 三個方向被擴寫成「4 個誤配場景」、3.C10 case 「大型服務 DLQ 是診斷入口」完全編造

防範：

• Stage 1 抽 findings 時 標明 case 類型（rich vs skeleton）
• Stage 2 寫 skeleton case finding 時、用「對應 [case] — 揭露 X 方向、以下展開基於通用工程知識補充」這種 fact vs derive 標記
• 不要為了「整齊的 4 個攻擊面」「3 個攻擊向量」「5 個誤配場景」這種數字感、把 case 沒寫的 taxonomy 寫成 case 揭露

陷阱 2：Frame 重複展開（SSoT 不清）

同一概念在多章 case-driven 擴章時各自展開、形成 frame 重複。讀者跨章讀會踩到重述、結論散落拼不出總圖。

實證：

• 01：容量三口徑 frame 在 1.1 跟 1.12 重複展開、storage / compute 分離 frame 在 1.1 跟 1.11 重複
• 02：cache 角色變化 frame 在 2.1 主寫但屬模組層級、應在 _index；Tubi 案例在 2.1 / 2.2 / 2.8 三章 mini-展開
• 03（最嚴重）：三層語意（delivery / processing / recovery）在 3.4 / 3.6 / 3.8 三章各自定義；Slack Kafka+Redis 拓樸在 3.4 跟 3.8 兩章逐字重複；規模對照在 3.4 / 3.6 / 3.8 三章拆用

防範：

• Stage 2 寫作前花 30 分鐘做 SSoT 對應（見前面「Stage 2 寫作前先定 SSoT 對應」段）
• 列出 cross-chapter frames、指定唯一主寫章節、其他章節只 link
• 寫每章前問「這個 frame 主寫在哪？我現在寫的是主寫還是 link？」

陷阱 3：負向陳述 + 模板化（規範系統性失分）

「不是 X、是 Y」推進論證、L1/L2/L3 三層平鋪、三選一表格、四步驟流程。這兩個原則違反在每模組都重複出現、是 LLM 寫作的反覆模式、stage 3 standards reviewer 每模組會抓 10-20 處。

實證：

• 01 規範 violation：表格不延伸（7 處）、負向陳述（5 處）、首句結構（4 處）
• 02 規範 violation：原則 8 模板化（6 處）、原則 2 負向陳述（6 處）、原則 4 表格不延伸（4 處）
• 03 規範 violation：原則 2 負向陳述（12 處最嚴重）、原則 1 首句結構（5 處）、原則 6 用語節制（2 處）
• 04 規範 violation：原則 2 負向陳述（12 處最嚴重、含「核心責任不是 X、而是 Y」變體段首）、原則 1 首句結構（9 處）、原則 4 表格不延伸（9 處）
• 05 規範 violation：原則 2「不是 X、而是 Y」+「沒有 X、會 Y」（10 處）、原則 8 四步驟 / 四層並列模板（7 處）、原則 3 case 引用框架取代商業邏輯先行（6 處）

防範：

• Stage 2 寫完後 寫稿端就跑掃描、不等 reviewer：
  • rg -n "不行|不可以|不要|無法|不能" <module-path> 找負向骨架（技術約束敘述例外）
  • rg -n "^[^|].*責任(不是|並非)" <module-path> 找「核心責任不是 X」變體段首（04 模組新發現的 pattern）
  • rg -n "^[^|].*[，,]而是|^[^|].*[，,]不是" <module-path> 找對比骨架開段
  • 自查表格：每個 bullet 是否有後文延伸？
  • 自查首句：是否「核心原則先行」而非「對應 [case] 揭露」
• 模板化（L1/L2/L3、三選一）出現時、先問「這三項是真的對等？還是業務情境不同？」— 不同情境的話拆敘事段、不用表格

陷阱 4：Rich case 判讀層被當 case fact 引用（04/05 模組新發現）

引用 09 / 07 等 rich case 時、case 內常含「觀察層」（具體 fact）跟「判讀層」（作者推論）兩段。LLM 寫作時容易把兩層壓縮成「揭露 X」、把作者判讀升級為 case fact。

跟陷阱 1（skeleton case 擴寫成 case 事實）的差別：

• 陷阱 1：case 沒提的細節（具體數字、taxonomy）被寫成 case 揭露
• 陷阱 4：case 有提、但屬作者判讀層的內容被寫成 case fact

實證：

• 05 / 9.C12 Riot：5.2 寫「揭露 35ms latency 反推 region 部署」、實際 case 的「35ms」是觀察層、「反推 region 部署」是作者判讀層
• 05 / 9.C34 GCP：5.2 寫「揭露 Spanner 替 etcd 才是 K8s 規模極限的關鍵」、實際 case 用更保守的「control plane 極限取決於 storage backend、GCP 用 Spanner 替換 etcd」分兩個點寫、章節壓縮 + 強化成硬性結論
• 05 / 9.C12 Riot：漏掉 case 揭露的關鍵歷史轉折「從 multi-tenant cluster 模型改成 single-tenant per game」

防範：

• 引用 rich case 前、先把 case 內的「觀察段」跟「判讀段」分開讀、抽 finding 時各自標明來源層
• 引用時用「揭露 X 觀察 + 作者判讀 Y」分層寫、或在引用後補一句「（case 中 X 屬作者判讀層、本章引用此推論）」
• 避免使用「才是 / 必須 / 一定」這類強化詞、保留 case 原文的條件性表述
• Stage 3 case fidelity reviewer 的 prompt 要特別點出「判讀層 vs 觀察層」的分界、把這當作 high 級 issue 抓取

陷阱 5：自掃描盲點累積（04/05/06 模組持續顯現）

自掃描的 regex 跟 reviewer 抓的 pattern 會逐漸脫節。每個模組 reviewer 會發現新 pattern、self-scan regex 跟著演進、但 reviewer 仍會發現下一個。

實證：

• 04 自掃描用 不行|不可以|不要|無法|不能 跟「不是 X、是 Y」掃描通過、但 reviewer A 抓出「核心責任不是 X、而是 Y」變體段首（佔 12 處）
• 05 自掃描通過、但 reviewer A 仍抓出「沒有 X、會 Y」鏈式負向句構 + 「四步驟模板」+ 「case 引用框架取代商業邏輯先行」三類新 pattern
• 06 self-scan 加了「不是 X、而是 Y」變體 + 「沒有 X 會 Y」、仍漏掉「對應 [case]：揭露 N 個機制」段首取代核心概念句的 pattern（reviewer A 抓 45 issue、其中 11/12 新段都犯這個錯）

防範：

• 每個模組 reviewer 抓出新 pattern 後、回頭更新 self-scan regex
• 把 self-scan 視為持續演進的工具、不是固定 checklist
• Stage 5 polish pass 是處理自掃描盲點累積的標準入口（見前段）
• 06 模組後 self-scan 加 rg -n "^對應 \[" <module-paths> 抓段首 case 引用框架

陷阱 6：Case 引用段首取代核心概念句（06 模組新發現）

LLM 從 case 反推內容時、容易把 case 揭露當概念出發點、寫成「對應 [case]：揭露 N 個機制 — …」段首結構。讀者尚未理解概念就被丟入案例細節、且跨章讀同句構會感同質。

實證：

• 06 模組 12 個新段中 11 個用「對應 [case]：揭露 N 個機制」相同句構作為 section 第二段
• 概念定義句被推到第二段或更後、商業邏輯先於 case 的原則被推翻

防範：

• 把 case 引用視為「三段式」結構：概念定義句 → case 引用 → 通用展開
• 寫每段時、先確認段首是「該概念是什麼、承擔什麼責任」、case 引用退到第二位置
• Case 引用句構應變化：寫多章時刻意避免同句構連續超過 3 次
• 詳見 skill 內部原則卡 principles/case-citation-three-part（對應檔案 .claude/skills/case-first-module-workflow/references/principles/case-citation-three-part.md、屬 skill 內部 reference、不對外暴露）

陷阱 7：Medium case 實作層擴寫過頭（06 模組新發現）

Medium case（30-50 行、結構化但無具體數字）首次套用時、容易把 case 沒提的具體實作層擴寫進章節、把通用工程知識掛到 case 名下。

實證：

• 06 模組 6.12 idempotency-replay 從 S1「key 設計要跟業務邊界一致」一條方向擴寫成「key 來源 / TTL / fallback / 偽造防護 / 5 個 observability 欄位」5 條實作判讀、case 沒提這些細節
• 06 模組 6.14 dependency-reliability-budget 從 M1 region failover 擴寫成「thundering herd」機制名 + 「先恢復核心 region 最小集合」具體步驟、case 沒提這兩個

防範：

• Medium case 引用用 mechanism 名稱 精準引用、不擴寫到 case 沒提的具體實作細節
• 引用後若要展開實作層、用「以下實作層判讀屬通用工程知識展開、case 本身只給 X 方向」明示分層
• Case fidelity reviewer 的 prompt 要特別點出 medium case 的「實作層擴寫」失分類型

陷阱 8：跨 case 合成 frame 升級成 case 揭露（07 模組新發現）

當段落把多個 case 的失效訊號抽象為更高層 frame（如「跨工具回查壓力」「平台責任切分」）、LLM 會把章節合成的 frame 包裝成 case 揭露。讀者回查 case 時會發現章節說的「case 揭露 X」實際是章節 derive、不是 case 原文框架。

跟陷阱 1（skeleton case 擴寫成 case 事實）跟陷阱 4（rich case 判讀層當 fact）的差別：

• 陷阱 1：case 沒提的細節（具體數字、taxonomy）被寫成 case 揭露
• 陷阱 4：case 有提、但屬作者判讀層的內容被寫成 case fact
• 陷阱 8：case 單獨 寫的訊號被章節 跨 case 合成 抽象為更高層 frame、frame 本身不在任一 case 原文

實證（07 batch 1 reviewer B 抓的 2 個 high issue）：

• 7.7 跨工具回查壓力：Uber 失效控制面寫「告警串接不足」、Slack 寫「訊號未匯流」— 都是單工具內訊號、章節合成「跨工具回查」axis
• 7.7 平台責任切分：SolarWinds 失效控制面寫「更新來源信任過於單點」「行為監測難以區分合法元件」— 都是供應鏈信任議題、章節合成「平台 vs 產品 audit 責任分離」frame

防範：

• 段落把多 case 抽象為更高層 frame 時、要 explicit 標明「frame 是本章合成、case 原文沒有此 frame」
• 修法範例：「兩個案例分別在 X 層揭露同類失效訊號 — A case 標明 B、C case 標明 D。本章把兩者抽象為『XXX』是 YYY 視角的合成 frame、非 case 原文框架。」
• Stage 3 reviewer B prompt 要明示「跨 case 合成 frame 必須標為本章合成」是 high 級 issue 抓取項

陷阱 9：Case 引用句構同質化（07 模組新發現）

即使遵守 case 引用三段式紀律、跨章節 case 引用仍會出現句構同質化。13 處 case 引用 11 處用同一句構「揭露 N 層失效控制面 — A、B、C。案例『可落地檢查點』標明 mechanism 為 X、前提是 Y」。讀者跨章連讀時、會把 case 引用當儀式而非論證。

實證：07 batch 1 reviewer A 抓出 systemic medium issue (Issue 8.1)、13 段 case 引用 11 段用相同句構。Stage 5 polish pass 主動分流 4 處後狀況改善。

防範：

• 句構選擇要 跟著 case 類型走、不是隨機變化（case 直接列 N mechanism → 「揭露 N 層」；case 揭露單一壓力 → 「補的失效訊號是 X」；case 揭露對比 → 「揭露兩個層次的對照」）
• Stage 5 polish pass 加句構分流為標準工序之一（跟負向骨架同層級）
• 自掃描 regex ^對應 \[ 抓不到此類問題（這是符合三段式的引用、只是句構單一）、要靠 stage 5 主動 scan：rg -c "揭露[^。]*失效控制面" <module-paths> 看同句構出現次數、超過 5 處要分流

「章節已有 routing skeleton」的特殊處理（07 模組新發現）

07 模組跟 06 / 09 不同之處：章節在 stage 2 前已有完整 routing layer 結構（threat scope / 從本章到實作 / 問題節點表 / 風險邊界 / 案例觸發 / 路由）— stage 2 是在現有結構內補 case-driven 深化段，而非空白擴章。

這個情境下：

• SSoT 衝突更容易發生：新段落要跟既有章節結構協調、不只是新增內容。07 batch 1 三個 H issue（C-H1/H2/H3）都是 frame 跟既有章節 / 其他章節新增段衝突
• 章節寫作邊界要先確認：補強段聚焦在「現有問題節點表的 mechanism 深化」、不擴成厚重 case-driven 章節（避免章節結構失衡）
• Cross-link 密度顯著上升：補強段要明示「本節聚焦 X 視角、canonical 在 Y 章」、否則 reviewer C 會抓 frame 重複展開

判讀條件：

• 章節已有 threat scope / 問題節點表 / 案例觸發段 → 走「補強段」策略、不空白擴章
• 章節是 routing layer / 導讀性質、不適合 case-driven 深化 → 跳過本流程
• 章節有 case 庫但 case 主要是 skeleton 型（30 行 frame） → 補強段嚴守「揭露 X 方向、通用補充」紀律、不擴寫實作層

衍生 insight：reviewer 維度沒覆蓋的部分

3 個模組跑下來、發現現有 3 reviewer 維度（規範 / 案例準確性 / 跨章一致性）有未覆蓋的問題：

• 教學性 / 讀者路徑：章節之間的閱讀順序是否合理？讀者讀完 A 章能不能銜接 B 章？目前沒 reviewer 檢查
• 判讀條件可操作性：寫了判讀訊號、但實際工程師能不能用這些訊號做決策？沒 reviewer 驗證
• 實作可行性：建議的設計是否真的能落地？跨團隊協調是否現實？需要懂業務的 reviewer

未來 6 / 7 / 8 模組執行時、可以考慮加第 4 個 reviewer 維度（教學性 + 實作可行性）。

跟其他寫作流程的差異

跟「LLM 自生 + 人工 review」比、本流程的差異：

跟「LLM 自生 + 自我 review」比：

• 自我 review 抓不到自生內容的盲點（self-blindness）
• Agent team 是 不同 instance、不共享 context、能扮演獨立 reviewer

下一步

本流程在 backend/01 至 backend/07 batch 1 七個模組驗證後（共 ~45 章 / 385 review issue / case fidelity 70-93% 區間）、方法論已工具化為 case-first-module-workflow skill（內部檔 .claude/skills/case-first-module-workflow/、含 stage 1-5 流程、reviewer prompt template、self-scan regex 跟 5 個原則卡）、後續套用到：

• backend/07 batch 2 LLM 安全：case 庫缺位（OWASP LLM Top 10 + agent injection 公開事件未累積成模組 case）、要先建 LLM case 庫再走 case-first
• backend/07 batch 3 治理章節：routing 層 / 導讀性質、case-driven 深化適用度低、做標準 polish pass 即可
• backend/08 incident response：跟 04 / 06 / 07 cross-link 密度最高、SSoT 對應規劃壓力最大
• 其他模組依此類推

06 模組是首次套用工具化 skill 的模組、驗證 skill 對 stage 1-2 加速有效、但 reviewer A 仍抓出 45 issue（高於 05 之前 baseline 20-30、推動 v1.2 把 standards reviewer baseline 擴大到 20-45）— 揭露 skill 改進方向（self-scan regex 需要持續演進、case 引用段首結構是 LLM 系統性傾向）。

07 batch 1 驗證下「章節已有 routing skeleton」情境的處理策略：補強段不擴成厚重 case-driven 章節、聚焦 mechanism 深化 + cross-link 對齊。揭露兩個新陷阱（跨 case 合成 frame 升級成 case 揭露、case 引用句構同質化）、補進 skill 跟方法論。

流程本身會在每個模組後 retrospective、看 reviewer 維度是否該調整、findings 抽取方法是否該強化、polish pass 處理 pattern 是否該擴充。目前已知改進方向：

• 加 reviewer：教學性審查（讀者路徑是否清楚、判讀順序是否合理）
• 強化 findings 抽取：標註 finding 的 泛化程度、避免把 case-specific 細節推為通用結論
• Rich / Medium case 引用紀律：把「fact vs derive」分層 + 「mechanism 名稱精準引用」寫進 stage 1 抽 findings 模板、stage 3 case fidelity reviewer prompt 也明示此分界
• 自掃描 regex 持續演進：每個模組 reviewer 抓出新 pattern 後、回頭加進 self-scan 工具、避免在下個模組重蹈覆轍。06 模組後加 ^對應 \[ 抓段首 case 引用框架。07 模組後標明 ^對應 \[ 在三段分離結構下會 false positive、要靠 awk 看 prev line context
• Case 引用三段式：把「概念定義 → case 引用 → 通用展開」當段落結構紀律、避免段首被 case 引用取代（06 模組最大宗 systemic 違規）
• Case 引用句構分流：07 模組後 stage 5 polish pass 加句構分流為標準工序、避免跨章 13+ 段同句構讀感儀式化
• 跨 case 合成 frame 紀律：07 模組後 reviewer B prompt 明示「跨 case 合成 frame 必須標為本章合成」是 high 級 issue
• 加修正後自動 lint：修完不只跑 mdtools、加跑「找首句否定句」「找表格沒延伸」「找模板化並列點」「找段首 case 引用」的自動掃描

跟其他寫作協議的整合：本流程跟 compositional-writing skill 互補（後者管 單篇 寫作的原子化跟意圖、本流程管 跨章模組 的 scope 跟一致性）、跟 requirement-protocol skill 互補（後者管 對話協議、本流程管 內容生產）。

核心命題：source code doc 寫給「未來的讀者」，commit message 寫給「想了解過去發生什麼的考古者」。兩者是不同文件，內容該分開。 設計原則：時序敏感的資訊（為什麼這次改動、考慮過什麼方案）放 commit；持續適用的資訊（當前契約、不變量）放 source。

本篇是 函式文件分層設計 反模式 3「過去式 doc」的展開——把「source 跟 commit message 的時序職責邊界」拉成獨立主題討論。

起點：兩份文件的職責容易被混在一起

Source code doc 的職責是「描述當前 code 的契約跟行為」、commit message 的職責是「描述某次改動做了什麼跟為什麼做」——兩者讀者不同、時序屬性不同、本該各歸各家。實務上這兩份文件的職責經常被混在 source code doc 一處：source 變成所有歷史的垃圾桶、commit message 反而沒人認真寫。

實務上常看到的污染：

1/// 修了 issue #123 的 race condition
2/// 從 v2.3 開始改用 lock-free 結構
3/// TODO: @alice 之後可能要改用 SkipList
4void process() { ... }

這段 doc 混了三類資訊：

1. 過去發生什麼（修了 issue #123）→ 屬於 commit message
2. 過去做過什麼決定（v2.3 開始改用 lock-free）→ 屬於 commit message / changelog
3. 未來可能要改什麼（TODO @alice 改用 SkipList）→ 屬於 issue tracker / TODO 系統

沒有一條是「未來讀者讀這份 code 需要的資訊」——三條都凍結在過去某一刻、source 卻被當成歷史快照在用。要釐清這個問題、得先想清楚兩種文件各自的讀者與時間性。

時序差異：當前狀態 vs 狀態轉移

關鍵差別是時間性：

• Source code doc 描述「現在這份 code 在做什麼」——只要 code 不變，doc 就持續有效
• Commit message 描述「那一刻為什麼要改 code」——commit 完成的那一秒就成為歷史

把過去式的內容塞進 source code doc，會讓 doc 變成「凍結在某個歷史時點的快照」，而不是描述當前狀態。

該寫在 commit message 的內容

Commit message 的核心職責是回答「這次改動做了什麼、為什麼做」——所有「凍結在某次提交時點」的資訊都應該住在這裡、而不是被塞進 source 變成過時快照。下面四類是最常被誤放進 source 的內容：

1. 改動的動機（為什麼這次要動）

1fix: prevent double-charge on payment retry
2
3Payment gateway 對同一個 transaction_id 會回傳 200 但實際扣款兩次
4（incident #4521）。在 client 端加上 idempotency_key，gateway
5看到重複的 key 直接回 cached response。

「為什麼動」幾乎永遠屬於 commit message。source code 只需要描述「現在的行為是什麼」，不需要解釋「過去為什麼變成這樣」——除非那個「為什麼」對未來呼叫者仍是必須知道的限制（見後面段落）。

2. 評估過的替代方案（why not X）

1refactor: replace stream with reactive value
2
3考慮過三個方案：
4- A. 改成 broadcast stream：最 minimal，但保留同樣的 payload 語義模糊問題
5- B. 加新 broadcast stream 平行存在：兩條 stream 容易不同步
6- C. 拆成 reactive value（採用）：與系統其他 service 一致、消除多訂閱問題
7
8選 C 因為與 codebase 其他 service 風格對齊，雖然改動範圍最大。

「考慮過 A、B、C，選了 C」這類資訊對 reviewer 重要，對未來讀 code 的人多半不重要——他們看到的是 C 的結果，不關心你考慮過 A、B。這類資訊屬於 commit message / PR description，不屬於 source code doc。

3. Migration / 部署相關步驟

1feat: migrate user_profile from int_id to uuid
2
3注意：
4- 跑 migration 0042 之前先確認所有 client 已升到 v3.2 以上
5- migration 預估 2 小時（10M rows），建議週末執行
6- rollback：reverse migration 0042 然後 redeploy v3.1

部署時序與步驟是當下發布動作的一部分，commit / release notes 該寫；source code 不該背這個負擔。

4. Bug 號、ticket 連結、incident 紀錄

1fix: handle empty cart in checkout button visibility
2
3Closes #1234
4Related: incident-2026-04-12 (button stuck enabled)

把 ticket 號 / issue 連結寫在 commit message，git blame 出來的 commit 直接帶你去原始討論。寫在 source code 反而會 outdated（issue 關了、tracker 換了、URL 改了）。

該寫在 source code doc 的內容

Source code doc 的核心職責是描述「當前 code 的契約跟行為」——只要 code 不變、doc 就持續有效。下面四類是「持續適用」的資訊類別、屬於 source 的家：

1. 當前對外契約

1/// 從本地購物車移除指定商品
2///
3/// 找不到對應品項時不做事；不會拋例外。
4void removeFromLocalCart(CartItem item);

這是「現在這個 function 對 caller 承諾什麼」——持續適用，跟「上週為什麼加這個 function」無關。

2. 隱性需求 / 必要的呼叫順序

1/// 必須在 [init] 之後呼叫；否則 throw `StateError`。
2void process() { ... }

「呼叫順序」是當前 code 的契約限制，未來呼叫者必須遵守。屬於 source code doc。

3. 對未來讀者仍然重要的「過去原因」

少數情況下，「為什麼以前這樣決定」對未來讀者仍是必要資訊——典型是「這個寫法看起來怪，但有非顯然的原因」：

1void processPayment(Payment p) {
2  // 刻意不 retry —— payment gateway 是非冪等，retry 會造成重複扣款
3  // （見 incident-2026-04-12）。失敗一律拋給上層人工處理。
4  return _gateway.charge(p);
5}

這條註解兼具「歷史原因」和「持續適用的限制」——未來維護者看到這段 code 會想「為什麼沒 retry？」，這條註解防止他「順手加上」。這類兼具兩種性質的內容是少數該留在 source 的歷史相關 doc。

判斷標準：「未來讀者不知道這條歷史會做錯決定嗎？」

• 是 → 留 source
• 不是 → 留 commit

4. 不變量 / invariant

1class CircularBuffer {
2  /// 元素數量永遠在 [0, capacity] 之間
3  int get length => ...;
4}

不變量是「這個型別永遠成立的事實」，是契約的一部分，屬於 source。

反模式

反模式 1：把 commit message 內容塞進 source

正向概念：source code doc 描述「現在的行為」、git log 才是「歷史演進」的家。兩者各自有對應的工具（IDE 看 doc、git log 看演進）、各司其職就能讓兩邊都精準。

 1// 反：寫成歷史紀錄
 2/// 2024-01-15 加上 retry 邏輯
 3/// 2024-03-22 改用 exponential backoff
 4/// 2024-07-08 加上 jitter 避免 thundering herd
 5Future<Response> fetch(String url) { ... }
 6
 7// 正：source 只寫當前行為
 8/// 自動 retry 失敗的請求，使用 exponential backoff + jitter
 9Future<Response> fetch(String url) { ... }
10// 演進歷史在 git log 看

把所有歷史塞進 source 等於在 source code 重做一份 git log——但 git log 已經存在、且結構化、可搜尋、有 author / timestamp。重做一份在 source 只會 outdated（下次再加邏輯時忘了補日期就破功）、而 git log 永遠是同步的。

反模式 2：commit message 只寫 “update” / “fix”

正向概念：commit message 是給未來考古者的線索——git blame 跳到一個 commit 時、message 是讀者拿到的第一份資訊。寫得清楚、考古路徑就短；寫得模糊、考古者得繼續挖 PR / 找原作者問。

1- update
2- fix
3- wip
4- final
5- final v2
6- final v2 真的

這類 commit message 當下就沒人看得懂、半年後 git blame 把人帶到 message 寫 “update” 的 commit、等於把讀者帶到死巷。合理 commit message 的最小單位是 <type>: <one-line summary>、例如 fix: handle empty cart in checkout——一行就好、但要說清楚做了什麼。

反模式 3：source code doc 寫滿 TODO / FIXME

正向概念：「想未來改但還沒改」屬於 issue tracker——issue tracker 有優先序、有 owner、有 due date、能被排程。source code 的 TODO 沒有這些屬性、會被慢慢遺忘。

1/// TODO: refactor to use streams
2/// FIXME: handle null case
3/// HACK: temporary workaround for issue #234
4/// XXX: this is broken under high load
5void doSomething() { ... }

這些都是「想未來改但還沒改」的事——把它們留在 source 有三個問題：

• TODO 在 source 不會被 prioritize（產品 / 專案管理工具看不到 source 內的 TODO）
• FIXME 在 source 容易被忽略（讀的人會想「不是我寫的不是我的問題」）
• HACK / XXX 警告只在第一次讀時有效、第二次讀的人會麻木

問題嚴重需要立刻處理 → 開 ticket、commit fix；不嚴重可以等 → 開 backlog ticket、source 別寫。把待辦項從 source 搬到 issue tracker、會被真正當成「待辦」處理。

反模式 4：把 PR description 抄一份進 source

正向概念：PR description 是「這次提交的時空快照」、source code doc 是「持續適用的當前契約」。兩者描述的是同一段 code 在不同時序下的不同切面、各自有對應的家。

1/// 這個 function 是為了支援新的 multi-currency 結帳流程。
2/// 詳細需求見 PR #4521 與設計文件 https://wiki.../...
3/// 業務需求：客戶可以混合多幣別商品結帳，結帳當下統一換算成 settlement currency。
4/// QA 已驗證 5 種主要幣別組合 + 邊界 case。
5void multiCurrencyCheckout() { ... }

PR description 該寫的內容（業務脈絡、設計連結、QA 範圍）抄進 source、會讓 source 凍結在「這次新增時的時空狀態」——半年後 PR 已經是歷史、連結可能失效、QA 範圍可能擴展、但 source 還停在那一刻。PR description 留在 PR、source 只寫 function 當前的對外契約。

Git blame archaeology workflow

當 source code doc 跟 commit message 各司其職時，考古工作流會變得清晰：

 1讀者看到一段 code 不懂為什麼這樣寫
 2  ↓
 3先看 source code doc
 4  ↓
 5不夠 → 跑 git blame
 6  ↓
 7找到引入這段 code 的 commit
 8  ↓
 9讀 commit message
10  ↓
11不夠 → 點進去看完整 PR / issue

這個工作流要能順利跑，前提是：

1. commit 顆粒度合理——一個 commit 一個邏輯改動，不要「fix typo + refactor + add feature」混在一起，否則 blame 出來看到一個改 50 個檔案的 commit，message 寫 “stuff”，等於沒線索
2. commit message 寫清楚動機——不是「changed X」（git diff 看得出來），而是「changed X because Y」
3. 重大決定用 PR 描述補充——commit message 太長不適合塞長文，PR description 是放長文的地方

如果這三點做到，未來讀 code 的人有一條清楚的考古路徑，不必逼 source code doc 背所有歷史。

一個分配工具

決定一條資訊放哪時，問三個問題：

1. 「未來讀者不知道這條會做錯決定嗎？」
   • 是 → source code doc
   • 不是 → commit message
2. 「這條描述的是當前的行為，還是某次轉移？」
   • 當前行為 → source code doc
   • 某次轉移 → commit message
3. 「Code 改了，這條會不會 outdated？」
   • 不會（描述當前狀態）→ source code doc
   • 會（描述特定時間點）→ commit message

三個問題收斂到同一個直覺：「凍結在過去」屬於 commit、「持續適用」屬於 source。

邊界：什麼時候 source 還是該帶歷史脈絡

「歷史進 commit、契約進 source」是預設、但有些情境 source 還是該保留歷史脈絡——共通特徵是「未來讀者不知道這段歷史會做錯決定」：

• 看似怪、但有非顯然原因的寫法：「刻意不 retry、payment gateway 是非冪等」——下個維護者順手加 retry 會出事
• 跟非預期外部行為對齊的 workaround：「拆兩步 query 避開 SQLite 32-bit Android 的 integer overflow（issue #1234）」——讀者重構時會想「為什麼不一次查」
• 保留某段 code 的合規 / 法務原因：「依 GDPR 留 30 天可恢復、不是直接刪」——縮短到 7 天會違反法規
• 效能調優的非顯然參數：「batch size = 32 是 production 跑出來的甜蜜點、改大會 OOM」——下次 review 看到「為什麼不開大」時得知道過去的實驗結果

判斷標準：「未來讀者不知道這條歷史就會做錯決定嗎？」答「是」就留在 source、答「不是」就留在 commit。

一句話 heuristic

把整個討論濃縮：

Source code doc 寫給「正要動這段 code 的人」、commit message 寫給「想知道為什麼當初這樣寫的人」。

寫東西之前先問：我寫這段，是要幫正要動 code 的人做對決定，還是要幫回顧歷史的人理解某次改動？兩個讀者要找的資訊不同，分成兩處寫，雙方都受惠。

收束：兩份文件協同，源頭就要分清楚

很多團隊抱怨「source code doc 太亂、commit message 沒人寫」，本質是這兩份文件的職責沒分清楚。Source 想包辦所有事就會充滿過時內容；commit message 沒人寫是因為「反正歷史會寫進 source」變成預設。

把兩者的職責分清楚，兩份文件都會變健康：

• source 變短、變精準：只寫當前契約，doc 不會 outdated
• commit message 被認真寫：因為它是某些資訊的唯一家
• 考古路徑清楚：blame → commit → PR 是可預期的回溯路徑

寫 doc / 寫 commit 是同一個技能的兩面。不要把任何一邊當成另一邊的替代品。

核心命題：doc 是塑造使用者決策的工具——寫不好的 doc 會反向誤導使用者選錯路。 設計原則：把資訊放在能表達它的最低層次（名稱 / 型別 / 介面 doc / 實作 doc / 範例與測試）、上層留給「下層表達不了的剩餘」。

起點：doc 是塑造使用者決策的工具

API 設計者常忽略一件事：文件本身會塑造使用者的決策——讀者依照 doc 給的資訊選預設值、選呼叫方式、選用途，所以 doc 寫不好就會反向誤導使用者選錯路。

幾種常見的誤導模式：

• 把「需要明確選擇」的東西做成「最少打字的預設」（例如某些 stream / channel API 預設是單訂閱、多數 SQL column 預設 nullable）——使用者讀不到「該選什麼」的資訊，跟著預設走就出包
• 註解重複型別已說明的事，反而讓讀者懷疑「型別是不是不夠精確」
• 介面 doc 描述「目前實作怎麼做」而非「契約承諾什麼」——讓未來新實作以為要照抄
• 用憑想像的業務動機補完，後人讀了當真，反向影響其他相關決策

這些問題不是「沒寫 doc」，而是「寫了誤導的 doc」。要寫出不誤導的 doc，得先想清楚每個位置該放什麼資訊。

設計原則：資訊應該存在最低能表達它的層次

讀者讀一個 function 的閱讀順序：

1. 看簽章（名稱、參數、回傳型別）
2. 讀 doc comment
3. 跳進實作
4. 找範例 / 測試

每往下一層，閱讀成本就高一級。設計 doc 的原則：

能用上層表達的資訊，就不要往下層放。

對應的職責劃分：

把資訊放在能表達它的最低層次，能讓上層 doc 更精簡、更精準。

Layer 1：名稱與型別簽章

強型別語言下，型別是文件的一部分。很多 doc 內容本來就該由型別承擔。

用型別取代「參數說明」

1// 弱：依賴 doc 警告
2/// [quantity] 必須為正整數
3void increase(int quantity) { ... }
4
5// 強：型別本身就限制
6void increase(PositiveInt quantity) { ... }

1// 弱：String flag，靠 doc 說明可選值
2/// [mode] 可選值：'manual', 'auto', 'hybrid'
3void setMode(String mode) { ... }
4
5// 強：用 enum
6enum Mode { manual, auto, hybrid }
7void setMode(Mode mode) { ... }

當型別能表達約束時，不要用 doc 重複表達——doc 是約束的弱形式（編譯不檢查、IDE 補全不提示），把 doc 當主要 enforcement 等於放棄型別系統的力氣。

用命名取代「這個參數做什麼」

1// 弱：positional argument，靠 doc 解釋
2/// [a] 是基準值，[b] 是新值
3void update(int a, int b) { ... }
4
5// 強：named argument 自說明
6void update({required int from, required int to}) { ... }

update(from: 5, to: 10) 的呼叫端比 update(5, 10) 清楚得多，且不需要任何 doc。

用回傳型別表達失敗模式

1// 弱：可能失敗，靠 doc 說「失敗時回傳 null」
2/// 找不到時回傳 null
3User getUser(String id) { ... }
4
5// 強：型別本身表達 optionality
6User? getUser(String id) { ... }
7
8// 更強：分清 null 跟 error
9Result<User, NotFoundError> getUser(String id) { ... }

簽章已經表達清楚的事，doc 不必再寫。

命名要表達意圖，不是實作

1// 弱：implementation-leaking 命名
2List<Item> getCachedItems() { ... }
3
4// 強：意圖命名
5List<Item> getItems() { ... }

「Cached」這個字洩漏實作（用了 cache）。如果之後改成不 cache，名字就要改、所有 caller 也要改——但業務語義並沒變。命名應該反映「呼叫者想要什麼」，不是「實作怎麼做」。

展開閱讀：型別取代 doc 的收益曲線——整理 null safety / enum / wrapper / Result / typestate 各自能消除哪類 doc、以及型別表達不了的剩餘部分（業務動機、性能、副作用、時序契約）。

Layer 2：介面 doc

介面 doc 是契約（contract）——對所有實作的承諾。它的讀者有兩類：

1. 使用者：「我呼叫這個會發生什麼？需要注意什麼？」
2. 實作者（包括寫 mock、寫新版實作的人）：「我必須遵守哪些規則？」

兩類讀者都不該為了讀懂契約而去讀任何單一實作。

該寫的：契約承諾、行為保證、隱性需求

• 何時 throw / 回傳特殊值：「找不到時 throw NotFoundException」
• 副作用：「呼叫後 currentUser 會被清空」
• 同步 / 非同步保證：「呼叫後資料庫立即一致；快取要等下一次 refresh」
• 執行順序保證：「listener 觸發順序不保證」
• 業務規則（只在有實際業務需求時寫，且要有來源）：「會員價只能用 wallet 付款」

容易誤入介面 doc 的內容（屬於型別、實作或他處）

介面 doc 的職責是契約描述——所以「型別簽章已說的事」「特定實作怎麼做」「沒來源的業務動機」分屬其他層次（型別、實作 doc、issue tracker）、寫進介面 doc 反而稀釋契約本身的能見度。三個典型誤入：

1. 型別已表達的內容（屬於型別簽章）

1// 冗：
2/// 回傳 User，找不到時為 null
3User? findUser(String id);
4
5// 簡：型別已說明，doc 留白或寫業務動機
6User? findUser(String id);

2. 當前實作的細節（屬於實作 doc）

1// 冗：洩漏實作
2/// 內部用 HashMap 存儲，O(1) 查詢
3User? findUser(String id);
4
5// 簡：純契約
6User? findUser(String id);

實作細節寫在介面 doc 會誤導實作者「這個契約規定要用 HashMap」。如果未來有人寫一個用 B-tree 的實作，是合法的，但讀 doc 會以為違反契約。

3. 憑想像補完的業務動機（屬於 issue tracker / 不寫）

1// 冗（且可能錯）：
2/// 為了符合 PCI-DSS 規範，這裡不能 log 完整 cardNumber
3String maskCardNumber(String cardNumber);
4
5// 簡（沒來源就只寫可觀察事實）：
6/// 回傳遮罩後字串，僅保留尾 4 碼
7String maskCardNumber(String cardNumber);

業務動機要有來源（規範文件、PM 決策、incident 紀錄）才寫；猜的不要寫。猜的動機被當真會反向影響後續決策——讀者拿這條沒來源的猜測當依據、推到「既然是因為 PCI-DSS、那 X 也要這樣處理」、就把錯誤論述擴散到下游。

介面 doc 越精簡越能被讀完

很多人覺得「寫得詳細才負責任」，結果介面 doc 三段五行，讀完也記不住。好的介面 doc 通常只有 2-4 行：

1/// 從本地購物車移除指定商品
2///
3/// 找不到對應品項時不做事；不會拋例外。
4void removeFromLocalCart(CartItem item);

第一行說 what、第二行說 edge case。寫到這就停。「指定商品」怎麼比對？無關契約，去看實作。

Layer 3：實作 doc

實作 doc 的職責跟介面 doc完全不同：

• 介面 doc：對外契約，所有實作共通
• 實作 doc：這個實作特有的細節

該寫的：實作特有的 invariant、workaround、tradeoff

 1// 該寫：實作特有的 invariant
 2@override
 3void increaseItemQuantity(CartItem item) {
 4  // 順序關鍵：先 set lastChangedItem 再動 list，
 5  // 因為訂閱 localCartItems 的 worker 會在 list 變動時讀 lastChangedItem
 6  lastChangedItem.value = item;
 7  localCartItems[index] = ...;
 8}
 9
10// 該寫：bug workaround
11// Workaround for SQLite issue #1234: integer overflow on 32-bit Android,
12// 拆成兩步 query 避開
13final ids = await db.rawQuery('SELECT id FROM ...');
14return await db.query('items', where: 'id IN (${ids.join(",")})');
15
16// 該寫：性能 tradeoff
17// 用 LinkedHashMap 而非普通 Map：插入 1k 次後查詢效能差 3-5 倍
18final cache = LinkedHashMap<String, Item>();

這些都是**讀實作 code 也看不出「為什麼要這樣」**的決定，需要 doc 解釋。

契約只寫一處：實作不重複介面已寫的規則

實作 doc 的職責跟介面 doc 互補——契約描述歸介面層、實作層只補「該實作的特殊性」。同一條契約規則寫第二次（在實作層複述介面已寫的承諾）會破壞「契約只寫一次」原則：規則改的時候要同步兩處、少改一處就出現自相矛盾的文件、讀者看到也分不清以哪份為準。

1// 不該寫：介面 doc 已寫的規則，實作不再重複
2@override
3// 移除不視為「最後變更」，不更新 lastChangedItem
4void removeFromLocalCart(CartItem item) {
5  localCartItems.remove(item);
6}

「移除不更新 lastChangedItem」是契約、介面層已寫。

如果擔心未來維護者誤以為「作者忘了寫」，留一個指向介面的最小提示比複述整條規則更安全：

1@override
2// 行為見 ICartService.removeFromLocalCart
3void removeFromLocalCart(CartItem item) {
4  localCartItems.remove(item);
5}

不重複規則，只指向真相來源。

Negative-space documentation

實作 doc 偶爾要寫「為什麼這裡刻意沒寫某段程式」。這類 doc 防的是「未來維護者順手補上」：

1void processPayment(Payment p) {
2  // NOTE: 這裡刻意不 retry —— payment gateway 是非冪等，
3  // retry 會造成重複扣款。失敗一律拋給上層人工處理。
4  return _gateway.charge(p);
5}

沒這條註解，下個維護者看到網路 retry 是常見做法，可能會「順手加上」造成事故。

negative-space doc 用得好可以避免事故；用得多會變成處處防禦性註解，閱讀體驗變差。原則：這個「刻意沒做」的決定，是不是違反讀者的合理直覺？ 違反才寫。

Layer 4：範例與測試

複雜 API 的最後一層 doc 是可執行範例。

何時用 example：

• API 有多個正交參數，組合起來很多種用法
• 抽象描述比看程式碼難懂
• 邊界 case 用文字描述模糊（「如果 collection 是空、且 timeout 為 zero、且 retries 為 0…」）

何時不用 example：

• API 用法只有一種、簽章已說清
• 用法跟名稱字面意義一致

測試也是 doc。命名好的測試比 example 更有價值——不會 outdated（測試會跑、example 不會），且涵蓋 edge case。

1test('returns null when item not in cart', () { ... });
2test('decreases quantity when item exists with quantity > 1', () { ... });
3test('removes item when quantity reaches 0', () { ... });

讀者看 function 不確定行為時，跳到對應 test file 比讀冗長 doc 快——測試案例的命名直接告訴你支援哪些 case，並且每個案例都有可執行的具體輸入輸出。

展開閱讀：測試命名作為文件——測試是少數會自我驗證的文件、把命名寫成可執行 spec 條目就能取代不少 doc 的職責。

常見反模式

反模式 1：用 doc 取代不好的命名

正向概念：命名是契約的最強形式、doc 是命名表達不了的剩餘部分的家。命名先到位、doc 才有空間寫真正重要的事。

1// 反：靠 doc 補救命名
2/// 處理訂單，但只在訂單狀態為 pending 時做事
3void handle(Order o);
4
5// 正：命名表達意圖
6void handlePendingOrder(Order o);

把 doc 當成命名失敗的補丁有兩個問題：(1)「需要讀 doc 才能用對」的 function 在 IDE 自動補全 / 快速瀏覽時看不到 doc、誤用機率高；(2) 命名其實沒變、別人改 code 時 doc 會跟不上、補丁本身又 outdated。「需要 doc 才能用對」通常是命名沒到位的訊號。

反模式 2：過度註解

正向概念：doc 是稀缺資源——讀者注意力的預算有限、把 doc 留給「值得花注意力讀」的事項。

 1// 反：句句都是 noise
 2class User {
 3  /// User 的 ID
 4  String id;
 5  /// User 的名字
 6  String name;
 7  /// User 的 email
 8  String email;
 9}
10
11// 正：欄位名清楚就不寫
12class User {
13  String id;
14  String name;
15  String email;
16}

「User.name 是 User 的名字」屬於命名已表達的訊息、寫進 doc 只是 redundant noise。整份 code 充斥這類 doc 會稀釋訊號——讀者習慣性 skip 所有 doc 之後、連真正重要的 invariant 跟 edge case 也會被一起跳過。

反模式 3：過去式 doc

正向概念：source code doc 描述「現在這份 code 在做什麼」、commit message 描述「那一刻為什麼要改」。兩種讀者要找的資訊不同、各歸各的家。

1// 反：寫給歷史
2/// 修了 issue #123 的 race condition
3void process() { ... }
4
5// 正：寫給未來讀者（保留 fix 的關鍵 invariant 即可）
6void process() {
7  // 必須在持有 lock 內 call observer，避免 observer 看到中間狀態
8  ...
9}

「修了什麼 bug」凍結在過去某一刻、屬於 commit message / changelog；「目前必須持有 lock」是契約限制、屬於 source code doc。把過去式直接塞進 source 等於用 source 重做一份 git log——但 git log 已經存在、且結構化、可搜尋、有 author / timestamp。

展開閱讀：Commit message vs source code doc——時序敏感的資訊（為什麼這次改、考慮過什麼方案）放 commit、持續適用的契約放 source、配合 git blame 工作流讓考古路徑清楚。

反模式 4：同一條規則多處寫

正向概念：契約由介面層獨家承載、其他層引用即可。規則只有一個 SSoT（Single Source of Truth）、修改成本才可控。

1// 反：規則寫三處
2// 介面：「取消訂單後 3 天內不能重新下單」
3// 實作：「取消後 3 天內不能重新下單」
4// 測試：「驗證取消後 3 天內不能重新下單」
5
6// 正：規則寫一處（介面），其他指向
7// 介面：「取消訂單後 3 天內不能重新下單」
8// 實作：（無 doc）
9// 測試：test('cannot reorder within 3 days of cancellation')

一條規則複製到三處看起來保險、但會在改規則時暴露代價：要同步修三處、漏改一處就出現自相矛盾的 doc、讀者讀到不一致的版本反而會懷疑「以哪份為準」。把規則收斂到單一介面、其他層指向（測試命名 / 實作註解 // 行為見 ...）就夠了。

反模式 5：把語法選擇當成 doc 內容

正向概念：doc 描述業務目的跟行為契約——讀者要的是「這個 function 做什麼」、不是「為什麼用這個語法寫」。

 1// 反：寫實作層次的選擇細節
 2/// 用 Dart 3 的 record pattern destructure，比 .$1 / .$2 可讀
 3void handle((int, int) event) {
 4  final (a, b) = event;
 5  ...
 6}
 7
 8// 正：寫業務動機 / 行為契約
 9/// 處理 (timestamp, value) 對的批次更新
10void handle((int, int) event) { ... }

「為什麼用某語法」屬於 commit message / PR review 的討論記錄、不屬於 source code doc——換個語法寫法、業務行為沒變、但 doc 卻會 outdated。語法選擇的 why 在 git log / PR description 找得到、不需要 source 背這份歷史。

反模式 6：用 doc 警告使用者「請別這樣用」

正向概念：能用型別 / API 設計禁掉的誤用、把它編進型別系統；doc 警告留給型別表達不了的使用情境（時序、跨方法 invariant、執行環境）。

1// 反：靠 doc 警告
2/// **不要**直接修改回傳的 list，會造成內部狀態不一致
3List<Item> getItems();
4
5// 正：型別 / API 設計阻止誤用
6List<Item> getItems() => List.unmodifiable(_items);
7// 或回傳 Iterable / immutable 集合型別

doc 警告的執行力靠使用者「願意讀並且記住」、型別約束則是編譯期強制——當失敗成本高（內部狀態被破壞）、保護機制就值得從 doc 升到型別。型別表達不了的使用情境（例如「必須在 main isolate 呼叫」）才是 doc 警告該守的範圍。

API 設計層面：doc 之外的塑造工具

doc 寫得再好，API 設計本身會更直接塑造使用者行為。要讓使用者選對，從設計層下手比寫 doc 有效。

預設值要選「多數情況下對的」

1// 預設導向受限選項：使用者忘了選通用版本就出錯
2StreamController<int> ctrl = StreamController();  // single
3
4// 預設導向通用選項：忘了選受限版本不會出錯
5StreamController<int> ctrl = StreamController.broadcast();
6// 受限版本要顯式選 .singleSubscription()

當預設造成的失敗成本高、失敗模式又不易察覺、把多數人實際需要的選項變成預設、能消除整類「忘了選」的事故。doc 警告的執行力靠「使用者讀到並記住」、規模一大就守不住——把保護從約定升到結構。

把選擇從 default 取消（用型別禁掉）

1// 弱：靠 doc 說「不該直接呼叫，請用 X」
2@protected
3void internalMethod() { ... }
4
5// 強：型別系統禁掉
6class _InternalImpl { void method() { ... } }

能用 visibility / sealed / private 收掉的「請別這樣用」、把它收進型別系統——比起 doc 提示、語言層級的禁用是無條件強制的、且不會在大型重構時被遺漏。

Builder / fluent API 取代多參數

1// 弱：positional / named 多參數，靠 doc 解釋
2Request build(String url, [Map<String, String>? headers, Body? body, int timeout = 30]);
3
4// 強：fluent API 自說明
5Request.builder(url)
6  .header('Accept', 'json')
7  .body(payload)
8  .timeout(Duration(seconds: 30))
9  .build();

fluent API 的 method 名直接表達意圖，不需要 doc 解釋每個參數做什麼。

寫 function doc 的 checklist

寫一個 function doc 前，跑這個 checklist：

• 這條資訊型別能不能表達？ 能 → 改 type，不寫 doc
• 這條資訊命名能不能表達？ 能 → 改名，不寫 doc
• 這條資訊是契約還是實作細節？ 契約 → 介面 doc / 實作 → 實作 doc
• 這條規則是不是已經寫在介面 doc？ 是 → 實作不重複
• 這個業務動機有沒有來源？ 沒有 → 不寫，只寫可觀察事實
• 這個 doc 在描述什麼時候出問題？ 是 → 寫得明確（throw / null / edge case）
• 沒有這條 doc，讀者會誤判嗎？ 不會 → 不寫
• 同一條規則我寫了第二次嗎？ 是 → 砍一處，留一處

過完 checklist 留下的 doc 通常很短——這是好現象。

一句話 heuristic

把整個討論濃縮：

doc 是「型別、簽章、命名、結構都表達不了的剩餘資訊」的家。

寫 doc 之前先問：

• 能用型別表達嗎？
• 能用命名表達嗎？
• 能用結構（fluent API、enum、sealed class）表達嗎？

三題都答「不能」、而且使用者不知道會出錯——這時才需要 doc。

這個原則的 corollary：型別系統越強的語言、function doc 也越能寫得短。如果發現 Dart / TypeScript / Rust 的 function doc 寫得跟 Python 一樣長、多半有東西可以下移到型別。

何時 doc 還是該寫得詳細

「能少寫就少寫」是預設、但有些情境 doc 必須寫得詳細——這些是型別跟結構覆蓋不到的場景：

• 跨方法 protocol：「呼叫 reserve 之後必須在 X 內呼叫 commit 或 release」——typestate 能部分表達但寫法繁瑣、多數情況靠 doc 是合理的
• 時序契約：「寫入後最多 1 秒內 read replica 可見」「retry 5 次後放棄」——跨呼叫、跨時間的契約、型別表達不了
• 副作用 / 對外部系統的影響：「會寫入 audit log」「會發 webhook」——caller 需要知道才能規劃整體流程
• 業務規則 + 有來源：「會員價只能用 wallet 付款（業務需求 #1234）」——有出處的業務動機要寫、避免後人誤刪
• 效能契約：「O(log n) 查詢；不適合在熱迴圈呼叫」——caller 要根據這個資訊選用法

「短」不是目標、「精準」才是。把該下移的下移到型別、剩下的就值得詳細寫。

收束：doc 設計就是 API 設計

回到開頭——doc 寫不好會誤導使用者。但更深一層的觀察是：「需要寫很多 doc 才能用對」本身就是 API 設計的紅旗。

好的 API 用最少的 doc 就能讓使用者用對：

• 命名直接表達意圖
• 型別表達合法輸入與失敗模式
• 結構（enum、sealed、builder）防止誤用
• 預設值導向多數情況下正確的選擇
• 殘餘的契約與 edge case 用簡短介面 doc 說明
• 實作特有的 invariant 用簡短實作註解說明

寫 doc 的時候同時問「這條 doc 想說的事，是不是該由 API 設計本身承擔？」——這個問題能讓你的 doc 跟 API 同時變更好。

核心命題：型別系統強化等於 doc 表達力轉移——很多 doc 內容應該下移到型別。 設計原則：能用型別表達的限制，不要用 doc 表達；doc 是型別表達不了的剩餘資訊的家。

本篇是 函式文件分層設計 的 Layer 1（名稱與型別簽章）展開——把「型別承擔哪些原本寫在 doc 的內容」拉成獨立主題討論。

起點：型別越強、doc 的職責範圍就越窄

「型別系統越強、function doc 也越能寫得短」——這是個普遍但不被刻意利用的現象。

當你看到一個 Dart / TypeScript / Rust 的 function doc 寫得跟 Python / JavaScript 一樣長、多半有東西可以下移到型別。把可下移的內容下移、doc 表面變短、實質上的好處更深：

• 編譯期被檢查——型別說的事不會 outdated（doc 會）
• IDE 補全提示——使用者看到型別就懂、不用切到文件頁
• 重構時連動——改型別會逼所有 caller 跟著改、doc 改了沒人逼你檢查

這篇整理：哪些常見的 doc 內容能被型別取代、哪些下移了會破壞別的東西、以及型別越加越強時要怎麼平衡 ergonomic 跟表達力。

可被型別取代的常見 doc 內容

下面 8 類 doc 內容、共通特徵是「可以從 doc 約定升級成型別約束」——升級之後、保護從「靠使用者讀並記住」變成「靠編譯器強制」、執行力跟一致性都比 doc 強。每類列出弱（doc 約定）vs 強（型別約束）的對比。

1. 「必須是正整數」「必須非空」「必須在範圍內」

 1// 弱：依賴 doc 警告
 2/// [quantity] 必須為正整數（>= 1）
 3void increase(int quantity) {
 4  if (quantity < 1) throw ArgumentError(...);
 5}
 6
 7// 強：refinement type / value object
 8class PositiveInt {
 9  final int value;
10  PositiveInt(this.value) {
11    if (value < 1) throw ArgumentError(...);
12  }
13}
14void increase(PositiveInt quantity) { ... }
15
16// 最強（語言支援的話）：refinement types
17void increase(int quantity) where quantity > 0 { ... }

Dart 沒有 native refinement type，但用 wrapper class 一樣能達到「呼叫端要顯式建構合法值才能呼叫」的效果。validation 從「呼叫進入 function 後才檢查」前移到「建構 value object 時檢查」，contract 變成型別系統的一部分。

2. 「可能為 null」「找不到時回傳 null」

 1// 弱（前 null safety 時代）：
 2/// [name] 可為 null，[email] 不可為 null
 3class User {
 4  String? name;
 5  String email;
 6}
 7/// 找不到時回傳 null
 8User getUser(String id);
 9
10// 強（null safety）：
11class User {
12  String? name;       // 型別已說可為 null
13  String email;       // 型別已說不可為 null
14}
15User? getUser(String id);  // 型別已說可能找不到

Dart / TypeScript / Kotlin / Swift 的 sound null safety 把「可為 null」從 doc 約定升級成型別約定——升級之後、「[X] 可為 null」這類 doc 變成 redundant noise（型別已經精準說了、重複寫只是稀釋訊號、改型別時忘了同步 doc 還會誤導讀者）。

3. 「會 throw 某 exception」

 1// 弱：靠 doc
 2/// 找不到時 throw [NotFoundException]
 3/// 網路錯誤時 throw [NetworkException]
 4Future<User> getUser(String id);
 5
 6// 強：用 Result / Either / sealed class
 7Future<Result<User, GetUserError>> getUser(String id);
 8
 9sealed class GetUserError {}
10class NotFoundError extends GetUserError {}
11class NetworkError extends GetUserError {
12  final int statusCode;
13}

Result / Either pattern 把 error 從「invisible exception」升級成「型別簽章可見的回傳值」。Caller 必須處理（編譯不過 if not handled），不會漏掉 error path。

代價：寫法比 throw 多一些；不是所有 codebase 都採用這個 pattern。但對核心 service 介面值得。

4. 「合法值是 A、B 或 C」

1// 弱：String flag + doc
2/// [mode] 可選值：'manual'、'auto'、'hybrid'
3void setMode(String mode);
4
5// 強：enum
6enum Mode { manual, auto, hybrid }
7void setMode(Mode mode);

String flag 是「doc 約束代替型別約束」的最常見例子。改用 enum 之後：

• IDE 自動補全
• 拼錯立刻編譯錯
• 新增 / 刪除 mode 時所有 caller 編譯出錯（迫使你檢查每個地方該怎麼處理）

5. 「狀態 X 才能呼叫」

 1// 弱：靠 doc + 執行期檢查
 2/// 必須在 [open] 之後、[close] 之前呼叫；否則 throw [StateError]
 3void write(String data);
 4
 5// 強：typestate / phantom types（Rust 友善，Dart 較吃力）
 6class OpenConnection { void write(String data) { ... } }
 7class ClosedConnection { /* no write method */ }
 8
 9OpenConnection open() { ... }
10ClosedConnection close(OpenConnection conn) { ... }

typestate 把「必須在某狀態下才能呼叫」變成「那個狀態才存在那個方法」。Rust / Haskell 寫起來最自然；Dart / Java 可以用建構子分流模擬，但 ergonomic 較差。

對核心 lifecycle（connection、transaction、stream subscription）值得用；一般 service 不必。

6. 「兩個參數互斥」「某參數有時必填」

 1// 弱：positional args + doc
 2/// 同時提供 [token] 和 [credentials] 會 throw
 3/// 至少要提供一個
 4User auth(String? token, Credentials? credentials);
 5
 6// 強：sealed class 表達互斥
 7sealed class AuthMethod {}
 8class TokenAuth extends AuthMethod { final String token; }
 9class CredentialsAuth extends AuthMethod { final Credentials creds; }
10
11User auth(AuthMethod method);

「至少一個 / 至多一個 / 互斥」這類條件用 sealed class / discriminated union 表達。caller 看到型別就知道兩條路擇一，不需要 doc 說明組合規則。

7. 「這個 collection 是 read-only / 不要修改」

 1// 弱：靠 doc 約定
 2/// 不要修改回傳的 list
 3List<Item> getItems();
 4
 5// 強：immutable collection 型別
 6List<Item> getItems() => List.unmodifiable(_items);
 7// 或：
 8Iterable<Item> getItems() => _items;  // Iterable 不暴露 mutation
 9// 或（用 built_collection）：
10BuiltList<Item> getItems();

「請別修改」doc 警告靠的是「使用者願意讀且記住」，型別約束是強制的。

8. 「測量單位」（公里 vs 英里、秒 vs 毫秒）

1// 弱：靠 doc 標單位
2/// [timeout] 單位：毫秒
3void setTimeout(int timeout);
4
5// 強：用語義型別
6void setTimeout(Duration timeout);
7setTimeout(Duration(seconds: 30));  // 不需要記得是哪個單位

混淆單位是真實事故來源（Mars Climate Orbiter 級別的）。Duration / Money / Distance 等領域 wrapper 型別把單位編進型別系統，呼叫端不會傳錯。

型別表達不了的部分（doc 仍是該寫的家）

把可下移的下移之後，doc 還剩什麼？這些是型別表達不了的：

1. 業務動機 / 為什麼這個契約存在

1/// 會員價只能用 wallet 付款
2/// （業務規則：會員價是 wallet 餘額的折扣回饋）
3void chargeMemberPrice(Member m);

「為什麼只能用 wallet」是業務規則，不在型別系統的射程內。這類有來源的業務動機仍然要寫 doc——但要有來源，不是憑想像。

2. 性能特性

1/// O(log n) 查詢；插入 O(n)
2T find(int id);

Big-O / 延遲特性 / 記憶體 footprint 等性能契約，型別表達不了。如果這個性能特性是 caller 需要知道才能正確選用（例如「這個 method 不適合在迴圈裡呼叫」），就要寫進 doc。

3. 對外部系統的副作用

1/// 寫入 audit log（第三方系統，可能延遲到資料庫）
2void recordTransaction(Tx tx);

跟外部系統的互動（log、analytics、cache invalidation、cloud sync）是型別表達不了的副作用。caller 需要知道這些副作用才能規劃整體流程。

4. 時序契約（eventually consistent、retry 行為）

1/// 寫入後最多 1 秒內所有 read replica 會看到新值
2Future<void> updateProfile(Profile p);

「最多多久內 consistent」「失敗多少次後放棄 retry」「某事件多久觸發一次」——這類跨呼叫、跨時間的契約，型別系統無法表達。

5. 使用情境的限制（threading / isolation）

1/// 必須在 main isolate 呼叫；否則 throw `IsolateError`
2void registerPlatformChannel(String name);

「哪個 thread / isolate / context 才能呼叫」這類資訊，多數型別系統無法強制（Rust 的 Send/Sync 是少數例外）。

6. 跨方法 invariant

1/// 跟 [withdraw] 配對使用：每次 [reserve] 之後必須對應一次
2/// [withdraw] 或 [release]，否則餘額會被 reserved 卡住
3void reserve(Decimal amount);

「呼叫了 X 之後必須在 Y 時間內呼叫 Z」這類跨方法的 protocol，typestate 能部分表達但寫法繁瑣，多數情況靠 doc 是合理的。

各語言實際範例

Dart：null safety 的影響

Dart 2.12 引入 sound null safety 後，至少消除了 30% 的 doc 內容——不再需要寫「可為 null」「不可為 null」「null 時的行為」。

升級前後對比：

 1// 前（Dart 2.10）
 2/// [name] 可為 null
 3/// 找不到時回傳 null
 4class User {
 5  String name;  // 實際可能為 null，doc 提醒
 6}
 7User findUser(String id);  // 實際可能為 null
 8
 9// 後（Dart 3.x）
10class User {
11  String? name;  // 型別說明
12}
13User? findUser(String id);  // 型別說明

如果你的 Dart codebase 升了 null safety 但 doc 還在寫「可為 null」之類字句，說明還沒充分利用型別系統的成果。

Rust：ownership 與 borrow 消除一整類 doc

1// C 風格：靠 doc 警告
2/// 注意：caller 必須在 buffer 釋放前完成讀取
3/// 不要把 buffer 傳給其他 thread
4fn process(buffer: *const u8, len: usize);
5
6// Rust：型別表達
7fn process(buffer: &[u8]);  // borrow，編譯期保證 lifetime
8fn process_owned(buffer: Vec<u8>);  // own，move 後 caller 不能再用
9fn process_shared(buffer: Arc<[u8]>);  // 跨 thread 安全共享

Rust 的 ownership / borrow 系統把記憶體管理 / 並發安全相關的 doc 幾乎完全變成型別。寫 Rust 的 function doc 多半短得驚人——大部分 contract 已經編進簽章。

TypeScript：discriminated union 取代條件 flag doc

 1// 弱：靠 doc 解釋 flag 之間的關係
 2/**
 3 * @param type 'success' or 'error'
 4 * @param data 當 type='success' 時必填，否則為 null
 5 * @param error 當 type='error' 時必填，否則為 null
 6 */
 7interface Response {
 8  type: string;
 9  data?: any;
10  error?: string;
11}
12
13// 強：discriminated union
14type Response =
15  | { type: 'success'; data: ResponseData }
16  | { type: 'error'; error: string };
17
18// 使用時 TypeScript narrowing：
19if (response.type === 'success') {
20  console.log(response.data);  // 型別已知是 ResponseData
21} else {
22  console.log(response.error);  // 型別已知是 string
23}

discriminated union 把「flag 跟其他欄位的關聯」編進型別。這比 doc 警告強多了。

收益曲線：什麼時候強型別開始邊際遞減

把所有可下移的 doc 都下移，是不是型別越強越好？不是。型別強化有邊際成本：

實務 sweet spot 通常落在 1-4 之間。5-6 在 systems / safety-critical 程式碼有意義，一般 app 加進去 ergonomic 變差，回收不到。

一個 review 的問題：「這條 doc 能變型別嗎？」

review code 看到 doc 時，問三個問題：

1. 這條 doc 描述的是輸入合法範圍嗎？
   • 是 → 能不能用 wrapper type / refinement / enum 表達？
2. 這條 doc 描述的是回傳的可能性（null、error、特殊值）嗎？
   • 是 → 能不能用 nullable / Result / sealed class 表達？
3. 這條 doc 描述的是「這時候才能呼叫」嗎？
   • 是 → 能不能用 typestate / 不同型別的方法分流表達？

任一答案是「能」、先試型別。如果型別寫起來 ergonomic 不好（例如 wrapper class 太多、call site 變難讀）、再退回 doc——「先試型別」比「預設寫 doc」更能逼出可下移的部分。

一句話 heuristic

把整個討論濃縮：

doc 是「型別表達不了的剩餘資訊」的家——型別越強、剩餘越少。

寫 doc 之前先問「能用型別表達嗎」。能 → 改型別。不能 → 寫 doc，但只寫那條型別表達不了的部分（業務動機、性能、副作用、時序契約、跨方法 protocol）。

收束：型別系統升級是文件設計升級的契機

每一次語言升級（Dart 2 → 3、TypeScript 加新型別功能、Rust 穩定新 lifetime feature），都是重新檢視既有 doc 的機會：

• 哪些 doc 可以下移到新引入的型別功能？
• 下移之後，剩下的 doc 是不是更精準了？
• 是不是有新的型別組合能表達以前只能靠 doc 的契約？

把語言升級當成 doc 整理的契機，不只是「換個編譯器」。程式碼品質的關鍵改善往往來自把約定升級為約束——doc 是約定，型別是約束。約定靠人記住，約束靠工具強制。每次升級都是一次「把約定變約束」的機會窗口。

寫到「三行 doc 解釋一個 function 的合法輸入範圍」這個訊號時、自問：「這三行能不能變成型別簽章？」——多半可以。

核心命題：YAGNI 不是「永遠選最受限選項」的原則，是「不為未來投入額外成本」的原則。 判斷工具：成本對稱性、可逆性、領域先驗——三軸框架。

起點：一個常見的工程爭論

「最早的設計者沒考慮到多個監聽需求，這算設計瑕疵，還是避免過度設計？」

這類問題在 code review、事故檢討、技術選型討論裡反覆出現。指控太重會打擊個別工程師的判斷力信心，放任又會讓同類事故反覆發生。

要釐清這個爭論，得先回到 YAGNI 原則的真實定義——很多被當成 YAGNI 的例子根本不在它的射程內。

YAGNI 的真實範圍

YAGNI（You Aren’t Gonna Need It）的原意是：不要投入額外成本去蓋你尚未需要的東西。它防的是這類情境：

• 「我先寫個 plugin 系統，未來可以擴充」（成本：協議設計、抽象層、擴充點測試）
• 「我先做多語系，未來會國際化」（成本：i18n 框架、所有字串外移）
• 「我先支援多資料庫」（成本：repository 抽象、SQL 方言處理）
• 「我先建多租戶切割」（成本：資料 schema 加 tenant 欄位、所有 query 加過濾）

這些選擇的共通特徵是：為了未來付出當下的具體成本——抽象層、額外測試、複雜配置、學習負擔。YAGNI 說：別付，等真正需要再付，因為很可能你永遠不需要。

但很多被指控為「過度設計」的選擇其實沒有 upfront cost 差異。例如：

• Stream 工具用單訂閱版本還是廣播版本：建構子多打 11 個字元
• var 還是 final：3 個字元
• ID 用 int 還是 String（UUID）：抽象層成本一樣
• API 設計成同步還是 async：簽章只差 Future<> 包裝
• Class 預設可繼承還是 sealed：一個 modifier
• Database column 預設 nullable 還是 NOT NULL：一個 keyword

這些不在 YAGNI 的射程內。把它們當成 YAGNI 來防禦會選錯方向。

真正的判斷軸：成本不對稱性

判斷「該不該選更通用的選項」，跑三個軸。

軸 1：成本對稱性

「選擇 A 比選擇 B 多付出多少當下成本？」

• 對稱（成本相當、差幾個字元、無新概念）：選未來更可能需要的那個——這不是過度設計，是合理 default
• 不對稱（一邊明顯較貴、要多寫框架、多加抽象、多學概念）：YAGNI 適用，選便宜的，需要時再升級

軸 2：改變決定的成本

「如果選錯了，未來修正要付出什麼？」

• 可逆（一行改完、無 API 契約變動、無資料遷移）：YAGNI 適用，先選簡單的
• 不可逆 / 修正昂貴（牽動 API 契約、資料庫 schema、客戶端版本相容性、第三方 integration）：偏向預先選擇通用的

軸 3：領域先驗（domain prior）

「這個領域裡、這個模式發生的機率有多高？」——「先驗」（prior）借自 Bayesian 統計、用來指「在沒看到具體證據前、我們對某事發生機率的合理預期」。在工程領域、這個機率來自累積的領域知識（多視角同步、retry、併發、認證⋯⋯這些 pattern 的歷史發生率）。

• 強先驗（教科書級別）：多視角狀態同步是廣播、有用戶系統一定有 logged-in / anonymous 兩種、長時間運行服務一定會有 retry 需求、有交易就會有併發
• 弱先驗（純臆測）：「未來可能會有 plugin 機制吧」「未來可能要換資料庫吧」「未來可能要支援其他平台吧」

三軸的綜合判斷

任一軸顯著偏向「該選通用」，YAGNI 就不適用。

選通用不是過度設計，是對工具屬性與領域常識的尊重。

案例對照：兩個極端

案例 A：Stream 預設選錯

某個事件廣播 service 用了 StreamController() 預設建構子（單訂閱）。當下只有一個訂閱者，運作正常數個月。後來加第二個訂閱者，瞬間 throw Bad state: Stream has already been listened to。

跑三軸：

• 成本對稱性：對稱（差 11 個字元、零認知負擔）
• 可逆性：中等偏高（事故必須在 production 暴露才會發現，要審所有訂閱方、改實作 + mock）
• 領域先驗：強（pub-sub / 事件廣播場景天生多訂閱）

三軸都指向廣播版本。這是設計瑕疵——不是因為「沒考慮多訂閱」，而是在三軸都不利於單訂閱的情況下選了單訂閱。

完整事故重現、單訂閱 vs broadcast 的程式碼對比、修復決策過程：Dart StreamController：single-subscription vs broadcast 的事故實錄。

案例 B：建立 plugin 系統

「我先建個 plugin 系統，未來功能模組可以動態擴充」——典型的 over-engineering 焦慮表現。

跑三軸：

• 成本對稱性：嚴重不對稱（plugin 系統需要設計協議、加載機制、版本管理、隔離測試）
• 可逆性：可逆（之後要做的話成本跟現在做差不多）
• 領域先驗：弱（多數應用程式不會有第三方擴充需求）

三軸都指向「先別做」。這是 YAGNI 的標準適用情境。

兩個案例的對比

兩者表面看都是「未來可能需要」，但三軸框架告訴你它們是完全不同類別的決定。一概而論「該/不該為未來準備」會兩邊都做錯。

為什麼這類瑕疵「可被原諒」

要老實講：指出某個選擇是設計瑕疵，不等於把責任全部推給個別工程師。

同類型瑕疵在實務上極常見，原因往往是系統性陷阱。

1. 語言 / 工具的預設值誤導

很多語言把「需要明確選擇」的東西做成「最少打字的預設」：

• Dart 的 StreamController() 是 single-subscription
• 多數 SQL 的 column 預設 nullable
• JavaScript 的 == 預設寬鬆比對
• 多數語言的 class 預設可繼承
• HTTP 預設不加密
• 多數語言的 mutable 是 default

這些預設都把多數人推向「比較容易出錯但不立即爆」的選項。API 設計把成本均衡的選擇做成「便宜便輸出受限」vs「貴一點輸出通用」是 framework 設計的責任轉嫁——把跨用例的判斷成本丟給用戶。

2. 領域知識需要被觸發過才會內化

很多事是遇過一次才會記得。「stream 預設是單訂閱」「nullable column 之後加 NOT NULL 要 backfill」「同步 API 之後改 async 是 breaking change」——這些不是經驗少的問題，是這些事實需要遇到才會內化進直覺判斷。

新人讀文件不會看到、code review 不會自動 catch、靜態分析不會主動警告——只能等某次遇到。

3. 失敗模式的低調性掩蓋風險

很多設計瑕疵的失敗模式只在特定觸發條件下顯現：

• Stream 多訂閱限制只在第二次 listen() 時暴露
• Mutable shared state 的 race condition 只在高併發下爆
• Cache 失效邏輯只在 cache miss 模式變化時出問題
• API 沒做 idempotent 只在重試時出現重複

平常測試跑都過，給人「沒問題」的錯覺。沒有立即反饋的設計瑕疵 = 隱形的技術債。

4. 工具替代品掩蓋知識需求

有些底層概念被高層框架封裝後，使用者根本不會碰到，所以「應該知道」的知識沒有被反覆強化。例如：

• Flutter 開發者多用 GetX / Riverpod / Bloc，極少碰 raw StreamController
• ORM 用戶多不寫 SQL，極少思考 query plan
• 雲端 SDK 用戶多不思考 retry / backoff，極少接觸底層 HTTP

當有一天必須繞過框架直接用底層工具時，那個事故就會發生。

結論

設計者只承擔最後一棒。要把同類瑕疵變少，修補方向在制度層面。

制度層面的補強

要把「該選通用 default 但選了受限預設」的錯誤變少，個人記憶不可靠，要靠三層機制。

機制 1：介面層的 review checklist

把容易出錯的 default 列入 PR review 檢查清單。例如：

• Service 對外暴露 Stream<T> 時、預設用 broadcast；用 single 要在註解寫明理由
• 資料庫 column 預設用 NOT NULL；nullable 要在註解寫明業務理由
• 公開 API 預設用 async；sync 要寫明理由
• 公開類別預設用 sealed / final；可繼承要寫明理由
• HTTP 預設用 HTTPS；plain HTTP 要寫明理由

把「需要記得」變成「review 強制檢查」。Checklist 不需要多，每個項目對應一個遇過的事故。

機制 2：架構規範把選擇從 default 取消

更徹底的做法是用工具或規範禁掉問題 default：

• App 層 service 禁用 raw StreamController，強制用框架的廣播原語
• 用 lint rule 警告 StreamController() 的無參數呼叫
• DB schema migration 工具預設產出 NOT NULL，nullable 要明確指定
• API gateway 預設 deny，要顯式 allow 才放行

這把選擇從「需要記得」變成「不需要選，做錯會被擋」。是最高效的補強。

機制 3：領域先驗清單

每個團隊應該維護一份「我們的領域裡這些事一定會發生」的清單。範例：

POS 系統：

• 一台主機要服務多視角（多顯示螢幕、多通知模組）
• 會員身份會即時切換
• 有離線運作需求
• 多分店不同設定

電商：

• 商品價格會變動，歷史訂單要保留下單當時的價格
• 庫存會超賣，需要 reserve / commit 機制
• 退款是必然發生的，不是 edge case
• 客戶會有多個收件地址

新功能設計時對照清單——強領域先驗就直接設計進去，不必每次重新評估。新進團隊成員也能快速吸收領域常識。

一個能套到無數情境的 heuristic

把整個討論濃縮成一句話：

當你的選擇「沒有 upfront cost 差異」時、就該選未來自由度高的那個。

這個 heuristic 能套到無數技術決定：

這些都不是「過度設計」，是在零成本差異下選擇未來自由度更高的選項。YAGNI 不適用——YAGNI 的成本門檻在這裡根本不存在。

反向校正：什麼時候該堅持 YAGNI？

為了避免本文被讀成「永遠選通用」，補一個反向案例。

YAGNI 在這些情境是對的：

這些都是為了未來付出當下具體成本——抽象層、新概念、額外測試、配置複雜度。YAGNI 在這些情境會帶你做出對的選擇。

判斷的差異是：這個決定是「選哪個免費選項」，還是「要不要付一筆額外開發成本」？ 前者三軸框架；後者 YAGNI。

總結

YAGNI vs 過度設計的爭論，常常因為兩邊在用不同定義而無法收斂。釐清如下：

YAGNI 適用於「為了未來而付出當下的具體成本」 不適用於「在成本相當的選項中選擇更通用的那個」

判斷時跑三軸：

1. 成本對稱性：兩個選項的 upfront cost 是否相當？
2. 可逆性：選錯的話修正昂貴嗎？
3. 領域先驗：這個模式在領域裡發生機率多高？

任一軸顯著偏向「該選通用」，YAGNI 就不適用，這不是過度設計。

回到開頭問題——「最早的設計者沒考慮到多個監聽需求、這算設計瑕疵還是避免過度設計？」答案取決於這三軸的具體狀況、不能一概而論。

但如果像 Stream 這個案例、三軸全部不利於受限預設、那就是設計瑕疵。只是這類瑕疵反映的是工具預設與領域知識內化的系統性問題、不是個別工程師的判斷力不足——修補方向是制度而非個人責備。

一句話帶走

日常情境中、把三軸壓縮成一個問題就夠用：

「我在多付什麼成本？」

• 多付抽象層、新概念、額外測試 → YAGNI 適用、先別付
• 多付幾個字元、一個關鍵字 → 不是 YAGNI、選通用的

需要更精細的時候、再回頭跑完整三軸框架。

核心命題：測試是少數會自我驗證的文件——名稱說的事如果跟實際行為不符，CI 會炸。 設計原則：測試命名應該讓「跳到測試檔讀名字」就能取代讀 doc。

本篇是 函式文件分層設計 的 Layer 4（範例與測試）展開——把「測試命名作為可執行 spec」這個職責拉成獨立主題討論。

起點：被 CI 強制同步的 doc

source code 的 doc comment 有個結構性缺陷：寫得再好，code 改了 doc 沒改，doc 就在說謊。沒有任何工具強制 doc 跟 code 同步。

測試是少數例外。一個命名為 removes_item_when_quantity_reaches_zero 的測試，如果實際上 quantity 到 0 時沒移除，測試會失敗、CI 會擋下 commit。測試名稱跟實際行為的一致性是被 CI 強制的——這讓測試成為會自我驗證的文件。

當你把這個性質有意識地利用起來，測試就不只是 regression 工具，而是可執行的 API 規格。

測試命名的三種主要模式

被測單元的契約大致分三類：「在某狀態下回傳什麼」「某操作會做什麼」「何時 throw / 失敗」——對應到測試命名也分三類 pattern。每類 pattern 的命名格式不同、負責驗證契約的不同切面。

模式 1：state-based（狀態描述）

「在某個狀態下，呼叫 X 會回傳 / 變成什麼」。

1test('returns_null_when_user_not_found', () { ... });
2test('returns_empty_list_when_no_items_match', () { ... });
3test('returns_cached_value_on_second_call', () { ... });

適合：query / read-only 操作。

模式 2：scenario-based（情境描述）

「當某條件成立時，操作會做什麼」。

1test('removes_item_when_quantity_reaches_zero', () { ... });
2test('decreases_quantity_when_item_exists_with_quantity_above_one', () { ... });
3test('updates_lastChangedItem_on_addItem', () { ... });
4test('does_not_update_lastChangedItem_on_removeItem', () { ... });

適合：command / mutation 操作。注意 does_not_X 形式——negative assertion 也該寫進名字，這正是契約的一部分。

模式 3：failure-mode（失敗模式描述）

「在某輸入 / 狀態下，會 throw / error / 失敗」。

1test('throws_NotFoundException_when_id_does_not_exist', () { ... });
2test('throws_StateError_when_called_after_dispose', () { ... });
3test('returns_error_when_network_unavailable', () { ... });

適合：error path、edge case。失敗模式是 doc 最容易漏寫的部分，但對 caller 最關鍵。

Group 結構作為命名空間

巢狀 group 提供了「主題 → 操作 → 情境」的階層命名空間，比扁平命名更易讀：

 1group('CartService', () {
 2  group('addItem', () {
 3    test('appends_when_item_not_in_cart', () { ... });
 4    test('increments_quantity_when_same_item_exists', () { ... });
 5    test('updates_lastChangedItem', () { ... });
 6  });
 7
 8  group('removeItem', () {
 9    test('removes_when_item_exists', () { ... });
10    test('does_nothing_when_item_not_found', () { ... });
11    test('does_not_update_lastChangedItem', () { ... });
12  });
13
14  group('decreaseQuantity', () {
15    test('decreases_when_quantity_above_one', () { ... });
16    test('removes_item_when_quantity_reaches_zero', () { ... });
17  });
18});

讀者掃過 group 結構，立刻知道 CartService 對外提供哪些操作、每個操作有哪些行為承諾——這是這個 service 的 readable spec。

工具支援：好的 IDE / test runner 會把 group 結構顯示為樹狀，跑測試時的輸出也帶階層。把這個視覺結構利用好，測試 console 本身就是 doc 瀏覽器。

把 tests 當 readable spec 的閱讀流程

當你不確定一個 function 的行為時，閱讀順序通常是：

1. 看簽章 → 知道 what / takes / returns
2. 讀 doc → 知道契約、edge case
3. 看實作 → 知道 how
4. 找測試 → 看具體 case

但如果測試命名做得好，順序可以對調：

1. 看簽章
2. 跳到對應 test file，掃 group + test names → 看 API 支援哪些 case、各 case 的承諾
3. 不夠才回去讀 doc / 實作

這個順序的優勢：

• 測試名是被驗證過的事實，doc 是聲明（可能 outdated）
• 測試名涵蓋 edge case，比 doc 完整
• 跳到測試只要一個快捷鍵（多數 IDE 有 “Go to Test” 命令）

當團隊習慣這個閱讀順序，doc 寫多寫少的壓力就會減輕——很多 edge case 直接讓測試說明，doc 留給「測試也表達不了」的部分（業務動機、隱性需求）。

反模式

反模式 1：test_ 前綴 + 模糊主題

正向概念：測試名字的每個 token 都該承載資訊——前綴或主題詞如果讀者一眼推不出「在驗什麼」、就是浪費 token budget。

1// 反：純 noise
2test('test_user', () { ... });
3test('test_user_2', () { ... });
4test('test_user_creation', () { ... });
5
6// 正：說明具體行為
7test('creates_user_with_default_role_when_role_omitted', () { ... });

test_ 前綴是工具年代留下的習慣（早期某些 framework 靠它識別測試 method）；現代 framework 用 annotation / 函式簽章識別、前綴變成純 noise。模糊的主題（test_user、test_creation）等於沒命名——讀者必須跳進 body 才能分辨兩個 test 在驗什麼、命名的 doc 價值消失。

反模式 2：實作洩漏的命名

正向概念：測試驗的是對外可觀察的契約——換實作而契約沒變、測試應該繼續通過、命名也不該需要改。

1// 反：洩漏實作（用 hashmap、用 cache）
2test('uses_hashmap_for_lookup', () { ... });
3test('caches_result_after_first_call', () { ... });
4
5// 正：描述對外可觀察行為
6test('returns_value_in_O_1_for_existing_key', () { ... });
7test('subsequent_calls_return_same_instance', () { ... });

命名洩漏實作後、重構（換 hashmap 為 trie、移除 cache 改用 lazy init）會逼迫測試一起改名——但對外行為其實沒變。一個良好的契約測試、應該在 codebase 大改造後仍能驗證「行為是否還是當初承諾的樣子」、命名洩漏實作會破壞這個性質。

反模式 3：描述「怎麼做」而非「做什麼」

正向概念：測試名描述「被測單元的契約」、test body 描述「測試怎麼寫」——分配給對應的位置、讀者跳到名字看契約、跳到 body 看細節。

1// 反：描述測試怎麼跑（過程）
2test('mocks_db_and_calls_findUser_then_asserts_result', () { ... });
3
4// 正：描述被測 function 的行為
5test('returns_null_when_user_not_found', () { ... });

把「mocks_db_and_calls_X」寫進名字、讀者拿到的是「測試怎麼寫的過程」、不是「被測單元承諾什麼」——但讀 spec 想知道的是後者。「怎麼寫」放 test body、「驗證什麼契約」放名字、兩種讀者都得益。

反模式 4：assertion-style 命名

正向概念：測試名是業務語義的入口、不是 assertion 框架的字面映射——讀者讀名字想推「業務上發生什麼」、不是「assert 用了哪個動詞」。

1// 反：assertion 寫在名字
2test('isFalse_when_disabled', () { ... });
3test('equal_when_same_input', () { ... });
4
5// 正：描述行為
6test('returns_false_when_feature_disabled', () { ... });
7test('returns_same_result_for_equivalent_inputs', () { ... });

isTrue、equal、isNotEmpty 是 assertion 動詞、不是行為描述。讀者讀 isFalse_when_disabled 不知道「false」對應什麼業務語義（feature 關掉？user 不存在？status 失效？）——把業務語義寫進名字、讀者一眼就能 map 到實際情境。

反模式 5：用 numbering 取代命名

正向概念：每個 test case 都有獨特的「驗什麼情境」、命名就是把那個情境寫出來。編號只負責「不重複」、不負責「能識別」——失去命名最關鍵的功能。

1// 反：靠編號區分
2test('addItem_case_1', () { ... });
3test('addItem_case_2', () { ... });
4test('addItem_case_3', () { ... });
5
6// 正：編號變描述
7test('addItem_appends_when_cart_empty', () { ... });
8test('addItem_increments_when_same_item_exists', () { ... });
9test('addItem_handles_null_customization', () { ... });

編號是「我懶得想名字」的訊號。讀者要跳進 test body 才能區分 case 1 跟 case 2 是什麼差別——失去測試命名的全部 doc 價值；CI 報告看到「addItem_case_2 失敗」也無從直接判斷哪個情境壞了。

邊界：什麼時候測試名不適合當 spec

「測試名是 spec 條目」是預設、但有些情境測試命名無法獨自承擔 doc 責任：

• 大量參數化 / property-based test：「對任意輸入 N、結果都 ≥ N」這類 invariant、命名只能寫概念名（preserves_minimum）、具體 input 範圍要靠 doc 或 generator 描述
• 整合 / e2e test：跨多個系統的行為、命名常壓不下完整流程（「user_can_complete_checkout_with_loyalty_points_and_split_payment」）、要靠 setup / scenario doc 補上下文
• 測試本身是業務動機的二次表達：例如 GDPR 合規規則、業務動機的詳細條款仍要寫在介面 doc / spec 文件、命名只負責「驗證點」
• 內部行為對齊 vs 對外契約：私有 helper / internal worker 的測試命名不必當公開 spec、可以直接用實作詞彙（這時候命名價值是「regression 防護」而非「對外文件」）

判斷標準：「讀者只看名字、能不能拿到他要的資訊？」答「能」就讓命名當 spec 用、答「不能」就把詳細上下文寫進 doc / scenario file、命名只當「定位錨點」。

給測試寫作的 checklist

寫一個 test 之前，跑這個 checklist：

• 名字能不能讓讀者不看 body 就知道驗證什麼？ 不能 → 重命名
• 名字描述的是被測 function 的契約嗎？ 不是（描述測試過程）→ 重寫
• 名字有沒有業務面詞彙？ 沒有（只有 assertion 動詞）→ 加業務詞彙
• 同 group 下這個名字跟其他 test 有區辨度嗎？ 沒有（靠編號）→ 加情境描述
• 這個行為契約是 doc 沒寫但這個 test 在驗的嗎？ 是 → 太好了，這個 test 補了 doc 漏洞
• 這個 test 在驗實作細節嗎？ 是 → 改成驗對外可觀察行為，否則重構必折斷

Trade-off：測試名變長的代價

把測試當 doc 寫，名字會變長——addItem_increments_quantity_when_same_item_exists_with_identical_customizations 比 test_add 長 5 倍。

值得嗎？看你怎麼讀測試：

• 只看綠紅燈、不讀名字 → 短名字便利
• 把測試當 spec 讀 → 長名字回收成本

多數團隊低估「把測試當 spec 讀」的價值，因為這個習慣需要團隊一致才有效——一個人寫好命名，其他人不讀，回收不到。這是團隊習慣問題，不是個人偏好問題。要建立這個習慣，最好的切入點是：

1. 新功能 PR 直接讀新 test 的名字判斷契約是否合理——把命名變成 review 的一環
2. 修 bug 時要求新增的 regression test 名字描述 bug 行為（例如 does_not_double_charge_on_retry）——這些名字本身是 incident 紀錄
3. 重構 PR 不允許改 test 名（除非是改名抓 bug 暴露的契約變動）——避免重構順手「整理」掉重要命名

一句話 heuristic

把整個討論濃縮：

測試名是「讀者跳到測試檔、不看 body 就能讀懂的 spec 條目」。

寫測試名時想像一個讀者只會看到名字，他要能從名字推得：

• 在驗哪個操作？
• 在哪個情境下？
• 期待什麼結果？

三件事缺一不可。寫到名字過長覺得難寫——通常是被測 function 同時在做多件事，測試名長是設計訊號，先別急著縮名字，先想能不能拆 function。

收束：測試命名是文件設計的一環

回到開頭——測試是少數會自我驗證的文件。但這個性質只在你有意識利用時才有價值。把測試名寫成 test_1、test_2，你寫的是 regression 網，不是 doc。

把測試名寫成可讀 spec 條目，你寫的是同時包辦兩件事的東西：驗證 + 文件。這兩件事用同一份成本同時做完，是測試這個工具的最高槓桿用法。

把「這份 test file 是這個模組唯一的 doc、讀者夠不夠用？」當成命名的品質門檻——通過這個門檻的命名、自然就具備可讀 spec 的特性。