"Documentation"
- Pattern：明示語意縮小（不承諾全集）
Pattern 卡片：當 filter 必然只能在 subset 上做、明確告訴使用者「這只在已載入範圍內找」、不假裝是全集 filter。對應 #59 策略 E 的具體實作。重點是「明示」、silent 縮小是反模式。
- 寫註解的動機是怕被改壞時，要處理的是那個約束、不是那行文字
準備為一段程式寫註解、而動機是怕有人改壞它時使用。註解不參與執行、改壞的當下不產生訊號；防護需求要先問這個約束能不能被消除，不能消除才交給會發聲的機制，而判定靠當場破壞。
- 註解防不了改壞——防護需求要交給會發聲的機制
想給欄位或函式寫一行 doc、或審查一則宣稱約束的註解時使用。判斷這個資訊該由測試、型別、命名還是結構承接，以及約束本身能不能先被消除。
- 文件裡的扁平 Product、程式碼裡的雙層聚合 — 宣稱型文件的半衰期
refactor 總結文件記的是決策時刻的快照：扁平 Product（一商品一價一庫存）在真實 POS 業務下演化成 Product + ProductSpecification 雙層、價格三種下沉到規格。欄位放聚合根還是子層的判準是「兩個規格會不會不同」；文件預言的需求全中、預言的結構全錯——這正是先蓋結構會蓋錯的實證。
- Commit message vs source code doc：兩份不同職責的文件
Source code doc 寫給未來讀者、commit message 寫給回顧歷史的考古者。時序敏感的資訊（為什麼這次改、考慮過什麼方案）放 commit、持續適用的契約放 source。配合 git blame 工作流讓考古路徑清楚、source 不必背所有歷史。
- 函式文件分層設計：型別、介面、實作各自該寫什麼
函式文件分層設計：把資訊放在能表達它的最低層次（名稱 / 型別簽章 / 介面 doc / 實作 doc / 範例與測試）、上層留給「下層表達不了的剩餘」。整理各層該寫什麼、容易誤入的內容、配合反模式列表跟寫 doc 前 checklist 收斂出短而精準的文件。
- 型別取代 doc 的收益曲線：強型別語言的 doc 該有多短
型別系統強化等於 doc 表達力轉移——很多 doc 內容應該下移到型別。整理 null safety / enum / wrapper / Result / typestate 各能消除哪類 doc、型別表達不了的剩餘部分（業務動機、性能、副作用、時序）以及收益曲線的邊際遞減點。
- 測試命名作為文件：可執行的規格說明
測試是少數會自我驗證的文件——名稱跟實際行為不符、CI 會炸。把測試命名寫成 state-based / scenario-based / failure-mode 三種模式的 spec 條目、配合 group 結構作為命名空間、讀者跳到測試檔掃名字就能取代讀 doc。