ADR-0010: 文檔類資源統一架構¶

日期： 2026-03-02
提案人： Wei
狀態： 已採納

背景¶

Time Compass 的文檔資源散落在多個位置，缺乏統一的組織邏輯。開發者難以快速定位「我要查 X 功能怎麼做」的文檔。

現狀困境¶

docs/ 下有 ~125 個 Markdown 文檔，按目錄分散但層級混雜
docs/reference/ 內有 21 個檔案，缺乏主題歸類
Prompts 系統雙源：time_compass/domain/*/prompts/ (舊 Gradio) 和 src/time_compass/mcp/prompts/content/ (新 MCP)
根底目錄有過期檔案（README_OLD.md、測試輸出混在根目錄）
文檔索引（reference/README.md）存在但未充分發揮導航作用

決議¶

採用 主題式 (Topic-Based) + 多層級並行 的文檔架構，核心特質：

1. 文檔架構三層¶

Level 1: 獲取入門  (Getting Started)
│  ├─ docs/index.md (主首頁：「妳想做什麼」)
│  ├─ GUIDE.md (快速入門)
│  ├─ docs/explanation/* (概念與決策背景)
│  └─ docs/how-to/* (操作步驟)
│
Level 2: 按主題深入 (Topic-Based Reference)
│  └─ docs/reference/* (按功能域聚焦的技術深度)
│     ├─ README.md (主題選單)
│     ├─ DDD-ARCHITECTURE/ (領域驅動設計)
│     ├─ ERROR-HANDLING/ (錯誤處理框架)
│     ├─ MCP-TOOLS/ (MCP 工具實作)
│     ├─ FRONTEND/ (前端零框架設計)
│     └─ [其他主題...]
│
Level 3: 系統設計記錄 (Architectural Decisions)
│  ├─ docs/adr/* (架構決策紀錄)
│  ├─ docs/architecture/* (系統全景圖和資料流)
│  └─ docs/poster/* (願景與團隊故事)

2. 各層的責任¶

層級	目的	讀者	內容特性
Level 1	新手通道	新開發者、架構師	「怎麼開始」、「為什麼」
Level 2	主題深度	實作開發者	「我要做 X，相關檔案在哪」
Level 3	決策鏈	決策者、架構師	「為什麼做了這個選擇」

3. Reference 的主題劃分¶

每個主題內部遵循 Diátaxis 四層（可選），但內容在同一主題目錄內：

reference/DDD-ARCHITECTURE/
├─ README.md (主題導航：EXPLANATION | HOW-TO | REFERENCE)
├─ EXPLANATION.md (C2-3: 為什麼四層？架構理念)
├─ HOW-TO-EXTEND.md (C3: 怎麼新增資料來源？step-by-step)
└─ MODEL-SPECS.md (C3: 詳細欄位、轉換規則、代碼映射)

關鍵：三份文件內都可導向代碼，避免跳出主題目錄。

4. Prompts 雙源並行系統¶

非 SOT (Single Source of Truth)，而是雙源設計：

來源	架構版本	用途	維護者
`time_compass/domain//prompts/.md`	Gradio / DSPy	舊架構提示詞、簽章定義	領域模組
`src/time_compass/mcp/prompts/content/*.md`	MCP	新 MCP 工具的系統提示詞	MCP 模組

同步規則： - 如果是核心概念（如「emotion」的定義），兩邊應一致 - 如果是實現細節（如 MCP-only 邏輯），兩邊可獨立 - 文檔化於 docs/reference/PROMPTS-SYNC-GUIDE.md

5. 檔案位置清單¶

文檔 (docs/)¶

docs/index.md - 主首頁（待更新）
docs/GUIDE.md - 快速入門指南（保留）
docs/adr/ - 架構決策紀錄（9 份 + 本 ADR）
docs/architecture/ - 系統全景圖、資料流、DEV_MODE 決策
docs/explanation/ - 概念、架構隱喻、開發歷程、agent 能力
docs/how-to/ - 操作指南（Google OAuth、測試、雲端設置）
docs/reference/ - 主題式技術深度（主軸）
README.md - 主題選單（待改造）
DDD-ARCHITECTURE/ - 四層轉換模型
ERROR-HANDLING/ - Railway Oriented Programming
MCP-TOOLS/ - MCP 工具手冊
FRONTEND/ - 前端零框架設計
[待新增主題...]
docs/protocols/ - 協議文檔
docs/poster/ - 團隊故事、策略
docs/archive/ - 歷史紀錄、過期文檔

根目錄¶

README.md - 專案總述（保留，链接到 docs/）
GUIDE.md - 開發入門（與 docs/GUIDE.md 保持同步或重定向）

設計系統 (design-system/)¶

design-system/MASTER.md 及其他 - UI 設計系統（保留）

代碼內嵌文檔¶

src/time_compass/domain/*/ - 領域模組，包含 prompts、design 文檔
src/time_compass/mcp/prompts/content/ - MCP 工具的 Prompt 系統提示詞

測試與生成產物 (tests/, site/)¶

tests/output_result/ - 測試輸出暫存（保留，自動清理）
tests/snapshots/ - API 快照 fixtures（保留）
site/ - MkDocs 生成的靜態網站（保留，git 版本控制）
根目錄暫存檔案 (test_*.py, test_*.txt) - 刪除

Assets¶

assets/ - TOON 統計報告、API 樣本（保留，dev mode用）

改動計劃¶

Phase 1: 決策記錄 ✅¶

[x] 寫 ADR-0010（本文）

Phase 2: 快速清理（30 分鐘）¶

[ ] 刪除 test_versioning_logic.py、test_output.txt
[ ] .gitignore 確認：site/ 應保留；output_result 應是暫存（不版本控制）

Phase 3: README 與導航更新（1.5 小時）¶

[ ] 改造 docs/reference/README.md - 主題選單形式
[ ] 新建 docs/architecture/OVERVIEW.md - C1-C2 快速導航
[ ] 更新 docs/index.md - 主首頁導航

Phase 4: Reference 主題分類（1 小時，只搬移）¶

[ ] 建立各主題目錄（如 DDD-ARCHITECTURE/, MCP-TOOLS/ 等）
[ ] 搬移現有檔案（不改內容）
[ ] 新建各主題的 README.md（導航頁）

Phase 5: Prompts 系統記錄（可選，1 小時）¶

[ ] 檔案 docs/reference/PROMPTS-SYNC-GUIDE.md
[ ] 記錄雙源配置

優勢¶

優勢	說明
新手友善	docs/index → explanation → reference 清晰路徑
實作導向	reference 是主軸，按「我要做 X」的真實需求分類
避免過度分層	不用 C1-C2-C3-C4 精確分層，而是按實際查詢模式
易於維護	主題內自洽，新增功能時清楚該放哪
靈活擴展	Diátaxis 層 (EXPLANATION/HOW-TO/REFERENCE) 按需採用，非強制
Prompts 實況	記錄「不是 SOT」的現實，避免同步誤會

風險與注意事項¶

風險	緩解方案
搬移檔案時舊連結破裂	提交 PR 時檢查 mkdocs.yml 自動對應；文件內部連結用相對路徑
Prompts 雙源造成不一致	文檔化同步規則，考慮 CI check
新手不知道進 reference 後該看哪個檔案	每個主題的 README.md 必須有清晰的「選擇路徑」

後續追蹤¶

Phase 2-4 預計 3-4 小時完成
完成後進行用戶測試：新開發者能否快速找到所需文檔
每季度檢查 reference/* 是否有新主題需要加入