codebase-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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 是否讓相同規則集中在可追蹤的位置。

From CloudyWing/ai-dotfiles, MIT.

More from CloudyWing/ai-dotfiles