# Doc-Flow SKILL 五重文件管理系統 - 專案文件運作的核心控制中心 ## 核心理念 **每個文件有單一職責，工程師只需讀對應文件就能理解全部** --- ## 重要規範：禁用 Emoji **所有五重文件系統中的文件禁止使用 emoji** 原因： 1. 交接文件需要專業、正式 2. emoji 在某些環境可能顯示不正確 3. Claude Code CLI 處理 markdown 表格中的 emoji 可能導致 Rust panic 適用範圍： - CHANGELOG.md - todolist.md - worklog (docs/work-logs/) - ticket (docs/work-logs/v*/tickets/) - error-patterns (docs/error-patterns/) --- ## 五重文件系統 ### 職責定義 | 文件 | 核心問題 | 職責定位 | 更新時機 | |------|---------|---------|---------| | **CHANGELOG** | "這個版本做了什麼改變？" | 版本推進變化（給工程師看） | 版本發布時 | | **todo.md** | "還有哪些問題需要處理？" | 已知待處理問題（尚未排程） | 持續更新 | | **worklog** | "這個版本要達成什麼目標？" | 版本企劃（大方向 + 策略） | 版本開始/結束 | | **ticket** | "這個任務的執行細節是什麼？" | 任務執行歷程（細節記錄） | 執行過程中 | | **error-patterns** | "之前遇過類似問題嗎？" | 經驗學習（查詢/更新） | 執行前後 | ### 關係圖 ``` ┌─────────────────┐ │ CHANGELOG │ ← 版本發布時自動更新 │ (版本間差異) │ └────────┬────────┘ │ 提取 ┌────────┴────────┐ │ worklog │ ← 版本企劃 + 目標 │ (大方向) │ └────────┬────────┘ │ 索引 ┌────────────────┼────────────────┐ │ │ │ ┌──────┴──────┐ ┌──────┴──────┐ ┌──────┴──────┐ │ ticket │ │ todo.md │ │error-patterns│ │ (執行細節) │ │ (待處理問題) │ │ (經驗學習) │ └─────────────┘ └─────────────┘ └─────────────┘ ``` --- ## 職責詳解 ### 1. CHANGELOG.md **核心問題**：這個版本做了什麼改變？ **內容範圍**： - 新增功能 - 架構變更 - Bug 修復 - 重大決策 **寫作風格**： - 給其他工程師閱讀 - 簡潔、技術導向 - 按版本倒序排列 **更新時機**：版本發布時（由 `/version-release` 觸發） **禁止內容**： - 過度詳細的實作細節 - 開發過程中的嘗試錯誤 - 用戶不關心的內部變更 ### 2. todo.md **核心問題**：還有哪些問題需要處理？ **內容範圍**： - 已知但尚未排程的問題 - 技術債務清單 - 未來版本的規劃項目 **寫作風格**： - 清單形式 - 簡短描述 - 標記優先級或目標版本 **更新時機**： - 發現新問題時新增 - 問題解決時**移除**（不是標記完成） - 排入版本計畫時移至 worklog **關鍵規則**： - 已解決的問題必須移除 - 已排入執行的任務應在 worklog 中追蹤 ### 3. worklog（版本企劃） **核心問題**：這個版本要達成什麼目標？怎麼規劃？ **內容範圍**： - 版本目標（一句話描述） - 前情提要（為什麼需要這個版本） - 執行策略（Step-by-Step） - Ticket 總覽（連結到細節） - Context 還原指引 **寫作風格**： - 大方向、高層次 - 任何工程師不需其他 context 就能理解 - 執行細節**下沉到 ticket** **更新時機**： - 版本開始時建立 - 版本完成時更新狀態 **禁止內容**： - 具體的程式碼變更 - 詳細的執行日誌 - 問題的完整分析過程（這些屬於 ticket） ### 4. ticket（任務執行細節） **核心問題**：這個任務的完整執行歷程是什麼？ **內容範圍**： - 任務來源和目標 - 5W1H 設計 - 問題分析 - 解決方案 - 測試結果 - 執行進度 **寫作風格**： - 詳細、完整 - 記錄所有決策和變更 - 直到任務完成 **更新時機**： - 任務建立時（/ticket-create） - 執行過程中持續更新 - 完成時標記狀態 **格式**：Markdown + YAML Frontmatter ### 5. error-patterns（經驗學習） **核心問題**：之前遇過類似問題嗎？ **內容範圍**： - 錯誤症狀 - 根因分析 - 解決方案 - 預防措施 - 相關 Ticket **寫作風格**： - 模式化、可查詢 - 按類型分類 - 提供具體範例 **更新時機**： - 執行 ticket 前查詢 - 發現新模式時新增 - 修復後補充預防措施 --- ## 可用指令 ### 狀態查詢 ```bash /doc-flow status # 查看五重文件系統整體狀態 /doc-flow check # 檢查文件一致性 ``` ### Worklog 管理 ```bash /doc-flow worklog init # 初始化新版本 worklog /doc-flow worklog read # 讀取指定版本 worklog 摘要 /doc-flow worklog update # 更新當前版本 worklog 狀態 ``` ### Todo 管理 ```bash /doc-flow todo list # 列出所有待處理問題 /doc-flow todo add # 新增待處理問題 /doc-flow todo resolve # 標記問題已解決（移除） /doc-flow todo defer # 延遲到指定版本 ``` ### Changelog 管理 ```bash /doc-flow changelog preview # 預覽即將發布的變更 /doc-flow changelog update # 版本發布時更新 ``` ### Error Pattern 整合 ```bash /doc-flow learn # 觸發錯誤模式學習流程 ``` --- ## 工作流程整合 ### 開始新版本 ``` 1. /doc-flow worklog init v0.26.0 - 建立版本企劃 - 定義目標和策略 2. /ticket-create - 建立具體任務 tickets - worklog 自動索引 tickets 3. 執行開發 - 更新 ticket 進度 - 查詢/新增 error-patterns ``` ### 執行任務前 ``` 1. /doc-flow check - 確認文件同步狀態 2. /error-pattern query <關鍵字> - 查詢既有經驗 3. /ticket-track claim - 開始執行任務 ``` ### 完成版本 ``` 1. /doc-flow worklog update - 更新版本狀態為完成 2. /doc-flow changelog preview - 預覽 CHANGELOG 更新 3. /version-release - 發布版本 - 自動更新 CHANGELOG ``` --- ## 與現有 SKILL 整合 | 現有 SKILL | 整合方式 | |-----------|---------| | `/ticket-create` | worklog 自動索引新建的 tickets | | `/ticket-track` | 追蹤 ticket 狀態同步到 worklog | | `/tech-debt-capture` | 捕獲的 TD 同步到 todo.md | | `/version-release` | 發布時更新 CHANGELOG 和 worklog | | `/error-pattern` | 經驗學習系統整合 | --- ## 檔案位置 ``` docs/ ├── CHANGELOG.md # 版本變更記錄 ├── todolist.md # 待處理問題清單 ├── error-patterns/ # 錯誤模式知識庫 │ ├── README.md │ └── categories/ └── work-logs/ └── v{VERSION}/ ├── v{VERSION}-main.md # 版本企劃（大方向） └── tickets/ # 執行細節 ├── {version}-W1-001.md └── ... ``` --- ## 設計原則 ### 1. 職責單一化 每個文件回答一個核心問題，不重疊、不混淆。 ### 2. 自給自足原則 讀 worklog 就能理解版本全貌，不需要額外 context。 ### 3. 細節下沉原則 執行細節 → Ticket 大方向 → Worklog ### 4. 經驗累積原則 每次修復都查詢/更新 error-patterns，持續改善工作模式。 --- ## 相關文件 - 方法論：`.claude/methodologies/five-document-system-methodology.md` - 原有規範：`.claude/document-responsibilities.md` - Worklog 模板：`.claude/skills/doc-flow/templates/worklog.md.template`