codebase-designlisted

# Codebase Design 詞彙與判斷規則 本 Skill 統一描述模組邊界、抽象層與變更影響，讓設計文件、實作與審查使用相同詞彙。 ## 共用詞彙 | 詞彙 | 定義 | 判斷問題 | | --- | --- | --- | | Module | 擁有明確責任、輸入、輸出與相依性的邊界單位 | 這段邏輯能否以單一責任描述？ | | Interface | 呼叫端依賴的行為契約與測試替身邊界 | 呼叫端需要承諾哪些行為？ | | Depth | 請求或資料穿越的層數，以及每層新增的語意 | 每一層是否轉換了責任或只轉發？ | | Seam | 可以替換、觀察或隔離行為的連接點 | 測試或變更能在哪裡切開？ | | Adapter | 將一個既有契約轉成另一個契約的實作 | 轉換是否有明確的來源與目標？ | | Leverage | 一個變更能影響的使用者、流程或模組範圍 | 這個抽象能減少多少重複變更？ | | Locality | 相關規則與實作在程式碼中的鄰近程度 | 修改一項行為需要跨越多少檔案？ | Interface 就是測試面。若 Interface 沒有提供可觀察的行為契約，測試只是在驗證具體實作細節。 ## Seam 判斷 一個 adapter 是假接縫，兩個才是真的。單一 Adapter 只有在相同實作上增加轉發層，沒有帶來替換或隔離能力。當至少存在兩個可互換的實作、或一個正式實作加上一個測試替身時，才形成可驗證的 Seam。 判斷 Seam 時確認： - 呼叫端依賴的是 Interface，而非具體類別。 - 每個實作都能遵守同一組輸入、輸出與錯誤契約。 - 替換實作不需要修改呼叫端的業務判斷。 - 測試能在 Seam 上隔離外部 I/O 或非決定性來源。 ## Deletion Test 評估模組、抽象或流程是否必要時，先執行 deletion test。暫時移除目標元素，檢查是否仍有編譯錯誤、契約缺口、行為回歸或無法驗證的外部相依。 - 沒有可觀察影響的元素屬候選刪除項目。 - 只有文件、命名或空殼 Interface 的元素不能以存在本身證明必要性。 - 刪除會破壞契約、替換能力或責任邊界時，保留元素並寫明承擔的責任。 Deletion test 是篩選候選的方法，不直接決定業務範圍。涉及公開契約、資料遷移或不可逆變更時，先列出影響範圍與驗收條件。 ## 變更判斷 設計或審查跨模組變更時，依序確認： 1. Module 是否有單一且可觀察的責任。 2. Interface 是否描述呼叫端真正需要的行為。 3. Depth 是否由必要的責任轉換構成。 4. Seam 是否提供替換、隔離或觀察價值。 5. Leverage 是否足以抵銷新增抽象的維護成本。 6. Locality 是否讓相同規則集中在可追蹤的位置。