Document Governance Phase Classification¶
概念概覽
三層分類框架¶
核心知識¶
三層分類框架¶
文檔治理審查發現的問題，必須明確歸類到以下三層，每層的修正時機不同：
| 分類 | 定義 | 修正時機 |
|---|---|---|
| Branch-local code bug | 目前分支的程式碼或文檔有明確錯誤，影響當前 PR 正確性 | 合併前必須修正 |
| Phase-N 入口 blocker | 進入下一 Phase 前必須解決的架構/契約 gap | Phase 開始前的 review gate |
| Production go-live gate | 上線前必須驗證的容量/安全/合規事項 | Go-live checklist |
分類錯誤的風險¶
- 分類太嚴（全列為現在要修）：阻塞 PR，開發摩擦過高
- 分類太寬鬆（全推後）：技術債帶進下一 Phase，到時修正成本倍增
- 最危險：把 branch-local bug 推後（「下次再修」）→ 帶著已知 bug 合併
文檔 Split-Brain 的特殊危險性¶
多份規格互相矛盾（如同一 RPC 在 usecase_flows.md 和 test_plan.md 有不同冪等性定義）比純 code bug 更危險： - Code bug 有 compiler/test 攔截 - Doc split-brain 讓後續開發者各自取用不同版本的「正確」定義，導致實作發散 - 原則：doc split-brain 發現當下即解決，不帶進下一 Phase
審查 Series 命名慣例（本次案例）¶
- F-series：文檔與程式碼不一致
- A-series：架構正確性 bug
- B-series：整合安全邊界
- C-series：容量決策
- D-series：驗證 gate
經驗教訓¶
-
問題分類決定修正時機，分類本身就是架構決策，需要顯式記錄理由
-
文檔 split-brain 必須在當下消除，不能帶進下一 Phase
-
容量基準（CCU/DAU）若各文件引用不同數字，sizing/benchmark/runbook 會各自發散
常見陷阱¶
-
所有問題都推進 backlog，導致 branch-local bug 帶著合併
-
依賴口頭共識而非寫入追蹤文件，Phase 3 入口 review gate 形同虛設
-
多份設計文件共存但未指定哪份是 single source of truth
最佳實踐¶
-
審查報告每條問題標記分類（branch-local/phase-blocker/go-live）和責任人
-
Phase-N 入口 blocker 寫入明確的 review gate 文件，Phase 開始前 sign-off
-
任何規格互相矛盾立即在 PR 評論標記，不等 merge
相關概念¶
- Bug Fix vs Capability Expansion Phase Splitting
- 設計文件四塊同步原則
- Docs Governance Superseded Pattern
- PD Spec Rebase vs Patch Strategy
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-01 | 8a1ca078-1c39-4b3a-aec8-0a4b6acb84e9 | 建立三層問題分類框架（branch-local bug / Phase-N 入口 blocker / go-live gate），防止審查結果被錯誤排程 |