Bug Fix vs Capability Expansion Phase Splitting¶
概念概覽
核心問題¶
核心知識¶
核心問題¶
設計稿把 bug fix 和 capability expansion 混在同一個 Phase，導致： - Bug fix 必須等新功能設計定案才能合入 - PR review 範圍擴大，審查混沌 - 回滾時新舊改動難以切分
正確拆解策略¶
Phase 2A（hardening-only）：修現有 bug，不加新功能
→ 可獨立交付、可獨立回滾
Phase 2B（policy engine）：在 2A 穩定後再加 capability
Phase 2C（surface expansion）：new endpoints/commands
Phase 2D（rollout & observability）：gradual rollout
驗收三方對齊原則¶
每個 Phase 完成後需對照三個維度同時驗收：
1. Code：server-side logic 正確
2. Infra manifest：K8s ConfigMap / Deployment / RBAC 已更新
3. Live cluster：kubectl exec / kubectl get 確認實際狀態
任何一方「宣稱完成」而另一方未跟上，都不算真正交付。
文件與 Code 同步的重要性¶
文件宣稱某 feature done，但 repo 現況不符，是最常見的交付風險。每次 Phase 結束時，文件必須對照 repo 重新 review，不能只靠 PR merge 當作同步。
經驗教訓¶
-
Bug fix 和 capability expansion 混在一起會讓兩者都變慢，必須先切分
-
文件、code、live cluster 三者缺一不可，只有 code 正確不算交付
-
infra wiring 是最容易被低估的交付部分，往往需要 server + infra 雙邊明確 own
常見陷阱¶
-
設計文件說「T13 已完成」但 SPA 仍只有 IP whitelist，無 API key auth
-
把 Phase 完成等同於 PR merge，沒有 live cluster 驗收
最佳實踐¶
-
先切 hardening-only Phase，讓 bug fix 不被新功能依賴卡住
-
每個 Phase 結束後必須三方對齊：code + manifest + live cluster
-
infra handoff checklist 的每個未勾選項都需要明確 owner 和排期
相關概念¶
- Architecture Audit Methodology
- 設計文件四塊同步原則
- Document Governance Phase Classification
- Docs Governance Superseded Pattern
- Go Nil vs Empty Map in Validator Placeholder
- Phase Readiness Blocker Classification
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-03-30 | de4cc14f-f3ed-4243-b84e-6062bb47c079 | 從 Admin Hardening 案例歸納出「先切 hardening-only Phase 再做 capability expansion」的拆解原則，避免 bug fix 被新功能卡住 |