領域建模
在設計過程中主動建構並強化專案的領域模型。這是一項 主動 的紀律:挑戰術語、發想邊界案例,並在概念明確的當下立即記錄詞彙表和決策。(僅僅閱讀 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 中的現有語言衝突時,立即指出。「您的詞彙表將『取消』定義為 X,但您似乎指的是 Y。請問是哪一個?」
精煉模糊的語言
當使用者使用模糊或過載的術語時,建議一個精確的規範術語。「您說『帳戶』:您指的是客戶還是用戶?這是不同的東西。」
討論具體情境
當討論領域關係時,用具體的情境來進行壓力測試。發想能探測邊界案例的情境,並迫使使用者精確定義概念之間的界限。
與程式碼交叉驗證
當使用者說明某個功能如何運作時,檢查程式碼是否一致。如果發現矛盾,提出來:「您的程式碼取消了整個訂單,但您剛才說可以部分取消。哪個才是對的?」
即時更新 GLOSSARY.md
當一個術語被解析完成時,立即更新 GLOSSARY.md。不要將它們分批處理:在發生時就捕捉下來。使用 GLOSSARY-FORMAT.md 中的格式。
GLOSSARY.md 應完全不含實作細節。請勿將 GLOSSARY.md 視為規格、便條紙或存放實作決策的地方。它只是一個詞彙表,沒有其他用途。
審慎提供 ADR
僅在以下三個條件都成立時,才提議建立 ADR:
- 難以逆轉:事後改變決策的成本很高
- 缺乏脈絡會令人訝異:未來的讀者會疑惑「他們為什麼這樣做?」
- 是真正取捨的結果:有真正的替代方案,而你基於特定原因選擇了一個
如果缺少任何一項,就跳過 ADR。使用 ADR-FORMAT.md 中的格式。