設計文件四塊同步原則¶
概念概覽
四塊必須保持 consistency¶
核心知識¶
四塊必須保持 consistency¶
複雜重構計畫的設計文件必須在以下四個區塊之間保持一致性，任何一塊的修改都必須同步更新其他三塊：
- 步驟說明（Implementation Steps）：每個 step 的具體操作
- 影響範圍表（Affected Files/Components）：受影響的檔案與模組清單
- 測試矩陣（Test Matrix）：對應的測試 scenario 與 blocker/non-blocker 分類
- 設計決策（Design Decisions / Resolved Questions）：Open Questions 的決議結果
Rollout Gates 升格原則¶
Open Questions 中涉及「rollout 前必須驗證」的項目，應升格為正式的 Pre-rollout Validation Gates 小節，而非留在 Open Questions： - Gate 1：Static config scan（確認無非正數 quantity） - Gate 2：Legacy data audit（blocked set 涵蓋所有非 canonical type，不只是 drop_group）
Legacy Escrow Blocked Set 完整性¶
reward_escrow 稽核的 blocked set 必須包含**所有**非 canonical type：
- drop_group
- hero_exp
- player_exp
不能只防 drop_group，否則稽核結果給出錯誤的安全保證。
經驗教訓¶
-
設計文件最常見的品質問題是「四塊不同步」：步驟改了但影響範圍表沒更新，或測試矩陣沒有覆蓋新增的 code path
-
Open Questions 留著不決議是技術債：reviewer 無法判斷風險，應明確轉換為 Resolved Decisions 或升格為 Rollout Gate
常見陷阱¶
-
Legacy data audit 只防已知的 non-canonical type 而非全集，給出錯誤的安全保證
-
Bot smoke tests 被標記為 non-blocker，但 regression gate 意義的測試不應是 optional
最佳實踐¶
-
設計文件起草時即建立四塊同步 checklist，不要等最後 review 才做 consistency pass
-
任何涉及「rollout 前必須確認」的 Open Question 應立即升格為 Gate，並指定執行者與時間點
-
Bot smoke tests（end-to-end regression）應列為 blocker，不應作為 non-blocker 選項
相關概念¶
- Architecture Audit Methodology
- Bug Fix vs Capability Expansion Phase Splitting
- ClaimMarker Pattern (PostgreSQL Idempotency)
- Document Governance Phase Classification
- Docs Governance Superseded Pattern
- Dungeon Reward Dual-Path Contract
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-03-22 | 4d2cd4bd-d412-452e-8787-2ed0d493c165 | 提出複雜重構設計文件的「四塊同步 checklist」框架，識別 reviewer 最常找到漏洞的結構性原因 |