Doc-Flow SKILL
五重文件管理系統 - 專案文件運作的核心控制中心
核心理念
每個文件有單一職責，工程師只需讀對應文件就能理解全部
重要規範：禁用 Emoji
所有五重文件系統中的文件禁止使用 emoji
原因：
- 交接文件需要專業、正式
- emoji 在某些環境可能顯示不正確
- 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 前查詢
- 發現新模式時新增
- 修復後補充預防措施
可用指令
狀態查詢
/doc-flow status # 查看五重文件系統整體狀態
/doc-flow check # 檢查文件一致性
Worklog 管理
/doc-flow worklog init <version> # 初始化新版本 worklog
/doc-flow worklog read <version> # 讀取指定版本 worklog 摘要
/doc-flow worklog update # 更新當前版本 worklog 狀態
Todo 管理
/doc-flow todo list # 列出所有待處理問題
/doc-flow todo add <description> # 新增待處理問題
/doc-flow todo resolve <id> # 標記問題已解決（移除）
/doc-flow todo defer <id> <version> # 延遲到指定版本
Changelog 管理
/doc-flow changelog preview # 預覽即將發布的變更
/doc-flow changelog update # 版本發布時更新
Error Pattern 整合
/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 <ticket-id>
- 開始執行任務
完成版本
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