🎯 什麼情境該想到我
當多人協作、系統各處風格/慣例開始發散、「每個模組像不同人寫的」時。
⚙️ 怎麼用
「概念完整性是系統設計中最重要的考量。」 一個一致、可預期的系統，勝過功能多但零散的系統。
- 由少數架構師守護統一的設計理念：整體概念集中決策，避免委員會式的拼湊。
- 架構與實作分離：架構師定「做什麼、對外長怎樣」，實作者決「怎麼做」。
- 寧可少做幾個功能，也要維持一致性：不一致的多功能，認知成本比少功能更高。
- 用共同的慣例、通用語言（工具-通用語言）讓一致性可延續。
★ Brooks 的原始主張與它的證據
“Conceptual integrity is the most important consideration in system design.”
“It is better to have a system omit certain anomalous features and improvements, but to reflect one set of design ideas, than to have one that contains many good but independent and uncoordinated ideas.”
—— Fred Brooks, The Mythical Man-Month
為什麼一致性勝過功能數量：
一致的系統：學會一個模式 → ★ 能推論出其他部分怎麼用
不一致的系統：每個功能都要單獨學 → ★ 認知負荷是「功能數」的線性累加
★ 這是一個關於「使用者的學習成本」的主張，不是關於「程式碼的美感」。
★ 具體長什麼樣：一致 vs 不一致
❌ 不一致的 API（每個端點都是獨立發明的）
GET /users/list?page=1&size=20
GET /orders?offset=0&limit=20
GET /products/all?p=1&n=20 ← ★ 三種分頁、三種命名
POST /user/create { "userName": ... }
POST /orders/new { "order_id": ... } ← ★ 兩種命名風格、兩種路徑慣例
✅ 一致
GET /users?page=1&per_page=20
GET /orders?page=1&per_page=20
GET /products?page=1&per_page=20
POST /users { "user_name": ... }
POST /orders { "order_id": ... }
★ 學會一個，其餘全部會用
同樣的原則適用於：錯誤格式、分頁、認證、時間格式、命名、設定檔結構、CLI 參數、日誌欄位。
★ 「少數架構師」在現代怎麼落地
Brooks 的時代是「架構師做決定，實作者執行」。現在的團隊多半扁平，但一致性的需求不變。
實務上的替代做法：
| 機制 | 做什麼 |
|---|---|
| ★ 明文的慣例文件 | 「我們的 API 長這樣」「錯誤一律這個格式」——寫下來，而不是靠口耳相傳 |
| ★ ADR（架構決策紀錄） | 記錄「我們選了什麼、為什麼、考慮過什麼」。★ 讓後來的人知道理由，而不只是規則 |
| ★ 自動化強制 | linter、schema 驗證、架構測試、API lint（spectral、buf lint）★ 能自動檢查的就不要靠人記得 |
| 範本與腳手架 | 新服務從一個對的模板開始 |
| 設計 review | 但要有明確的判準，不是憑感覺 |
| 少數人守門 | 對「跨越邊界的決定」保留少數人拍板 |
★ 最重要的是第三項：
靠紀律維持的一致性會隨人員流動而衰減；靠工具強制的不會。
★ 「寧可少做功能」在實務上怎麼判斷
這是最違反直覺、也最難執行的一條。 可用的判準：
新功能的價值 vs 它帶來的「不一致成本」
不一致成本 = 使用者要額外學的東西
+ 文件要額外解釋的東西
+ ★ 未來每個相關功能都要處理的特例
+ ★ 它會成為下一個「既然有這個例外，那我也可以」的先例
★ 最後一項最貴：第一個例外會產生第二個例外。
一旦「我們的 API 大致一致，除了這兩個」，一致性就已經失去了它的價值（可推論性）。
★ 和「概念完整性」相關的兩個現代概念
🧪 我實際套用的紀錄
- 2026-07-15：（待填）
⚠️ 注意 / 什麼時候不適用
- ★ 一致性不等於「全部一樣」。不同的問題本來就該有不同的解法——
★ 要一致的是「同類事物的處理方式」，不是「所有事物」。
硬把不同的東西套進同一個模板，是另一種形式的傷害（見 工具-DRY原則 對錯誤抽象的討論）。 - ★ 過度守護一致性會扼殺演進。「我們一直都這樣做」不是理由。
→ 改變要整批改（全部遷移到新慣例），而不是「新的用新的、舊的留著」——
那會產生兩套慣例，比一套不好的慣例更糟。 - 架構師脫離實作會失準。Brooks 自己也強調架構師要懂實作的成本。
★ 不寫程式的架構師會定出實作不了的規範（Anthropic 的面試題之一就是「架構師必須寫程式」，見 架構師必須寫代碼）。 - 一致性有邊界。跨團隊、跨產品線強推同一套慣例的成本可能超過收益。
先確定「這個邊界內」一致，再談跨邊界。 - 新專案容易一致，既有系統很難。務實的做法是**「新程式碼一律照新慣例，舊的隨著改動逐步遷移」**（童子軍規則）。