Docs Governance Superseded Pattern¶
概念概覽
漂浮設計草稿的識別與處置¶
核心知識¶
漂浮設計草稿的識別與處置¶
32_CI_Pipeline_Design.md 案例展示了典型的文件治理違規模式：
- 設計草稿完成任務後未標記狀態，持續以「現行文件」身份存在
- 內容與 Infra
25_、Architecture25_產生**矛盾和重複** - 跨 repo 職責混入單一 server repo 文件，scope 不清
處置流程¶
1. 識別：文件內容已被其他 owner 文件覆蓋 → 判定為漂浮設計稿
2. 內容歸位：Preview Env 設計 → Infra 25_；tag 策略 → Architecture 25_
3. 標記：32_ 改為 Superseded，metadata 指向接替文件
4. 不刪除：保留歷史決策脈絡，但明確標示不再維護
Owner Scope 原則¶
每份文件必須有明確 owner scope。設計草稿在完成設計後若未及時歸位，隨時間推移會： 1. 與上游文件產生矛盾 2. 增加新人的閱讀混亂（不確定哪份是最新的） 3. 讓 review 和 update 流程碎片化
經驗教訓¶
-
設計草稿完成後必須主動標記 Superseded 並指向接替文件，這是防止文件腐化的關鍵一步
-
文件 scope 邊界（owner scope）比文件內容的完整性更重要——錯放位置比內容不完整更難維護
常見陷阱¶
-
設計草稿長期存活且未標記狀態，會被新成員誤認為現行規範
-
跨 repo 職責寫入單一 repo 文件，造成 scope 不清且難以維護
最佳實踐¶
-
Superseded 文件保留但在 metadata 中明確指向接替文件（用 superseded_by 欄位）
-
設計草稿完成決策後立即執行內容歸位，不留給「之後再整理」
相關概念¶
- Bug Fix vs Capability Expansion Phase Splitting
- 設計文件四塊同步原則
- Document Governance Phase Classification
- PD Spec Rebase vs Patch Strategy
- Preview Environment PR-Level Isolation
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-03-24 | 770400fc-5a4e-4290-92e5-08106a48b63e | 定義設計草稿文件完成後應標記 Superseded 並歸位到正確 owner 文件的治理規範 |