可驗證性設計三支柱
Vibe Coding 法則四「建立可驗證檢查點」的具體落地方式：設計階段就要問自己——
Reviewer 不讀實作能判斷正確嗎？
如果答案是「不能」，這段 code 不該由 AI 大量生成（要嘛是 Core Code 該由人寫，要嘛是該重新設計到能 verify）。
三支柱
1. 介面優先 (Interface-First)
- 函式 / API 必須有明確的輸入輸出型別與文件
- 副作用（DB 寫入、外部 call）需在介面層說明，不能藏在實作裡
- 介面層說明 = reviewer 讀 type signature + docstring 就能 99% 知道這個東西做什麼
2. 測試覆蓋（依程式類型分層）
| 程式類型 | 必備測試 |
|---|---|
| Pure function / utility | Unit test（含邊界條件） |
| Endpoint / API | Integration test（happy path + 錯誤路徑） |
| 非同步 / 排程 / 長時運行 | Stress test 或長時間 soak test |
| UI 元件 | Snapshot / interaction test |
關鍵：reviewer 不讀實作，光看 test cases 列舉的場景就能判斷「需求 vs 行為」對齊。
3. 可觀測性 (Observability)
- 重要流程須有 log、metric、trace
- 失敗能被監控察覺，而非只丟出 stack trace
光丟 stack trace 對 production 沒用——使用者會體感異常但你不知道原因。設計時就要思考「這段 code 出問題時，從監控面板看得出來嗎？」。
一個對照例子
功能：批次處理使用者匯出請求
✅ 良好設計（reviewer 不讀實作可信任）
| 維度 | 設計 |
|---|---|
| 輸入 | JSON list of user_ids（schema 明確） |
| 輸出 | 每筆寫入 S3，結果回傳 manifest.json 含每筆狀態 |
| 驗證 | 跑 10,000 筆 stress test，比對 manifest 數量 vs S3 物件數量 |
| 結論 | Reviewer 不需讀實作即可信任結果 |
❌ 不良設計
| 維度 | 設計 |
|---|---|
| 輸入 | 散落在多個全域變數 |
| 輸出 | 直接改寫 production DB，無紀錄 |
| 驗證 | 只能祈禱 |
第二個設計不只是「壞的 code」，是從根本上違反可驗證性——三支柱全倒：
- ❌ 介面：輸入散落、輸出無界面
- ❌ 測試：無法測（global state 難 mock）
- ❌ 可觀測性：寫入無紀錄
→ 不該由 AI 生成，連人寫都不該這樣寫。
在 Vibe Coding 流程中的位置
Plan-then-Execute SOP
↓
Step 3 計畫產出 ← 三支柱在這時就要 spec 清楚
↓
Step 4 AI 執行
↓
Step 5 自我驗證 ← 三支柱讓 reviewer 不讀實作也能驗
跟其他工具的對應
| 支柱 | 工具 / 規範 |
|---|---|
| 介面優先 | TypeScript / Pydantic / Protocol Buffer |
| 測試覆蓋 | Vibe Coding TDD 三條 e2e 測試 / pytest / Vitest |
| 可觀測性 | OpenTelemetry / Sentry / 結構化 log |
相關
- Vibe Coding / 四大黃金法則 (Vibe Coding)
- 建立可驗證檢查點 法則 — 法則四
- Vibe Coding TDD 三條 e2e 測試 — 簡化版 TDD 落地
- AI 編程 PR 模板 — PR 內必須證明三支柱都在
- Vibe Coding 團隊規範