領域建模
在設計過程中主動建立並精煉專案的領域模型。這是主動的紀律:挑戰術語、發明邊界案例,並在術語或決策結晶化時立即撰寫詞彙表和記錄。(僅僅為了詞彙而閱讀 GLOSSARY.md 並非此技能:那是任何技能都能做到的單行習慣。此技能適用於你正在改變模型,而不只是消費它。)
檔案結構
大多數儲存庫只有單一情境:
/
├── GLOSSARY.md
├── docs/
│ └── adr/
│ ├── 0001-event-sourced-orders.md
│ └── 0002-postgres-for-write-model.md
└── src/
如果根目錄存在 GLOSSARY-MAP.md,則表示儲存庫有多個情境。該地圖指向每個情境的位置:
/
├── GLOSSARY-MAP.md
├── docs/
│ └── adr/ ← 系統層級決策
├── src/
│ ├── ordering/
│ │ ├── GLOSSARY.md
│ │ └── docs/adr/ ← 情境特定決策
│ └── billing/
│ ├── GLOSSARY.md
│ └── docs/adr/
懶惰地建立檔案:僅在你需要撰寫內容時才建立。如果不存在 GLOSSARY.md,則在首個術語確定時建立。如果不存在 docs/adr/,則在需要第一個 ADR 時建立。
工作階段期間
對照詞彙表提出挑戰
當使用者使用的術語與 GLOSSARY.md 中的既有語言衝突時,立即指出。「你的詞彙表將 'cancellation' 定義為 X,但你似乎指的是 Y。到底是哪一個?」
銳化模糊語言
當使用者使用模糊或負載過重的術語時,提出精確的規範術語。「你說 'account':你是指 Customer 還是 User?這是不同的東西。」
討論具體情境
當討論領域關係時,用特定情境進行壓力測試。發明能探究邊界情況的情境,迫使使用者對概念之間的界線精確描述。
與程式碼交叉參考
當使用者說明某件事如何運作時,檢查程式碼是否一致。如果發現矛盾,提出來:「你的程式碼會取消整個訂單,但你剛剛說可以部分取消。哪個是對的?」
即時更新 GLOSSARY.md
當一個術語確定後,立即更新 GLOSSARY.md。不要累積起來:在它們發生時就捕捉下來。使用 GLOSSARY-FORMAT.md 中的格式。
GLOSSARY.md 應完全不含實作細節。不要將 GLOSSARY.md 視為規格、草稿或實作決策的存放庫。它只是一個詞彙表,別無其他用途。
謹慎提供 ADR
唯有當以下三個條件皆成立時,才提議建立 ADR:
- 難以逆轉:日後改變主意的成本顯著
- 缺乏脈絡會令人困惑:未來的讀者會納悶「為什麼他們要這樣做?」
- 是真實取捨的結果:存在真正的替代方案,且你因特定原因選擇了其中一個
若缺少任何一項,則跳過 ADR。使用 ADR-FORMAT.md 中的格式。