# Claude 工作指南 (Claude Working Guidelines) ## 🤖 Claude 協作標準操作程序 本文件為 Claude AI 助手在 Drama Ling 專案中的標準操作程序和協作指南。 ## 🛠️ 系統工具使用 ### 專案執行管理 (新增 2025-09-08) ```bash # ✅ 正確做法：使用專案管理工具 ./dl project list # 列出所有專案 ./dl phase status # 查看階段狀態 ./dl status # 查看執行狀態 ``` ### 問題管理 ```bash # ✅ 正確做法：使用問題管理工具 ./dl issue # 互動式問題管理 # ❌ 禁止行為：直接編輯 ISSUES.md # 除非是修正現有問題的格式錯誤 ``` ### 報告建立 ```bash # ✅ 正確做法：使用系統工具 ./dl report analysis "分析主題" ./dl report decision "決策主題" # ❌ 禁止行為：手動創建報告檔案 ``` ### 檢查作業 ```bash # ✅ 正確做法：使用檢查工具 ./dl check # 其他維護腳本 ./check_consistency.sh ``` ## 🎯 核心工作原則 ### 1. 工具優先原則 - **必須優先使用現有工具和腳本** - 所有專案管理都透過 `./dl` 系統 - 所有問題記錄都透過 `./dl issue` 創建 - 所有報告都必須透過 `./dl report` 創建 ### 2. 專案管理整合原則 (新增 2025-09-08) - **階段化執行**: 大型項目拆分為可管理的階段 - **任務分類**: 使用類型標記（FE/BE/AI/MB/DOC/ENV/TEST） - **進度追蹤**: 即時更新任務狀態 (⏳ → 🔄 → ✅) - **依賴管理**: 自動檢查前置條件 ### 3. 協作提醒原則 (整合 2025-09-08) 用戶可以使用以下提醒語句確保問題被記錄： **標準提醒語句：** ``` "如果你在過程中發現任何規格不確定、衝突、技術問題或需要決策的地方，請使用問題管理系統記錄下來。" ``` **簡短版本：** ``` "遇到問題就記錄到問題系統" "發現問題就用 ./dl issue 記錄" ``` **具體場景提醒：** ``` "實作 [功能名稱]，發現問題就用 ./dl issue 記錄" "檢查 [文檔]，找到不一致或不清楚的地方就記錄問題" "重構 [模組]，遇到架構問題或技術債務就記錄" ``` ### 4. 日期準確性原則 - **系統工具會自動處理日期** - 當前日期：2025-09-08 - 任何手動設定日期都必須使用正確的當前日期 ### 5. 文檔整合原則 - 所有問題必須記錄到 ISSUES.md - 所有分析必須產生正式報告 - 報告必須與問題系統整合 ## 📋 Claude 應該記錄的問題類型 ### 🔥 緊急問題 - 架構設計衝突 - 無法實作的需求 - 安全性問題 - 資料不一致 ### ⚠️ 重要問題 - 規格定義模糊 - API 設計不確定 - UI/UX 流程不清楚 - 技術選型疑慮 ### 📝 一般問題 - 文檔格式不統一 - 命名規範不一致 - 小的技術改進建議 - 程式碼品質提升 ## 📋 標準工作流程 ### 專案任務執行流程 (新增 2025-09-08) #### 任務執行步驟 1. 用戶提供任務名稱（如："Android Studio 安裝和配置"） 2. Claude 識別任務類型、階段、專案歸屬 3. 執行相關工作 4. 自動更新 PROJECTS.md 狀態 (⏳ → 🔄 → ✅) 5. 記錄執行結果和發現的問題 #### 專案管理互動範例 ``` 用戶: "執行 Android Studio 安裝和配置" Claude: 識別為 ENV 類型任務，屬於階段1環境配置 [執行安裝配置工作] [更新 PROJECTS.md 狀態] [報告完成情況] ``` ### 分析任務流程 1. **建立分析報告**: `./dl report analysis "主題"` 2. **執行分析工作**: 使用適當工具進行分析 3. **更新報告內容**: 編輯生成的報告檔案 4. **整合問題系統**: 確認相關問題已正確連結 ### 問題處理流程 1. **記錄問題**: `./dl issue` 2. **分配優先級**: 🔥緊急 / ⚠️重要 / 📝一般 3. **建立相關報告**: 如有需要，建立分析或決策報告 4. **追蹤解決進展**: 定期更新問題狀態 ### 檢查作業流程 1. **執行系統檢查**: `./dl check` 2. **運行一致性檢查**: `./check_consistency.sh` 3. **記錄發現問題**: 使用問題管理系統 4. **產生檢查報告**: 必要時建立分析報告 ## ⚠️ 常見錯誤和避免方法 ### 錯誤1: 手動創建報告 **問題**: 直接創建報告檔案，導致日期錯誤、格式不一致 **解決**: 必須使用 `./dl report` 命令 ### 錯誤2: 忽略現有工具 **問題**: 重複實作已存在的功能 **解決**: 先檢查 `tools/` 目錄下的現有工具 ### 錯誤3: 未整合問題系統 **問題**: 發現問題但未記錄到 ISSUES.md **解決**: 每次發現問題都必須使用 `./dl issue` ### 錯誤4: 日期不一致 **問題**: 使用錯誤的日期或格式 **解決**: 依賴系統工具的自動日期處理 ### 錯誤5: 文檔更新缺少時間戳記 (新增 2025-09-08) **問題**: 更新文檔內容後未標記更新時間，難以追蹤變更歷史 **解決**: 任何文檔更新都必須加入時間戳記，格式為 (YYYY-MM-DD) ### 錯誤6: 檔案組織混亂 (新增 2025-09-08) **問題**: 將輔助工具和指南檔案直接放在根目錄，造成目錄污染 **解決**: 遵循專案檔案組織結構，使用適當的子目錄儲存不同類型的檔案 ## 📁 檔案組織原則 (新增 2025-09-08) ### 目錄結構規範 ``` tools/ ├── environment/ # 開發環境設定工具 │ ├── android/ # Android 開發相關 │ ├── xcode/ # iOS/Xcode 開發相關 │ └── flutter/ # Flutter 開發相關 docs/ ├── 04_technical/ │ ├── environment/ # 環境設定指南 │ └── ... scripts/ # 專案維護腳本 └── maintenance/ # 系統維護工具 ``` ### 檔案放置原則 - **設定工具**: 放在 `tools/environment/[環境名]/` - **設定指南**: 放在 `docs/04_technical/environment/` - **維護腳本**: 放在 `scripts/` 或 `scripts/maintenance/` - **臨時檔案**: 使用 `temp/` 目錄（需要時創建） - **歷史檔案**: 使用 `archive/[日期]/` 目錄 - **雜項檔案**: 使用 `misc/` 目錄（完全無法歸類的檔案） - **禁止行為**: 直接在根目錄創建輔助檔案 ### 無法歸類檔案處理流程 (新增 2025-09-08) 1. **功能性檢查**: 是否有明確功能分類？ 2. **時效性檢查**: 是否為臨時性檔案？ → `temp/` 3. **歷史性檢查**: 是否為歷史檔案？ → `archive/[日期]/` 4. **最終歸類**: 完全無法歸類 → `misc/` 詳細策略請參考：`docs/04_technical/file-organization-strategy.md` ## 🔍 品質檢查清單 ### 🛡️ 每次操作前必檢（強制性SOP合規檢查） **⚠️ 重要：任何操作前都必須執行此檢查清單** #### 問題管理操作前檢查 - [ ] 是否需要記錄新問題？如是，**必須使用** `./dl issue` - [ ] 完成的問題是否要標記？如是，**絕對不可在待處理區標記[x]** - [ ] 完成的問題**必須移動到「📚 已完成歷史」對應日期區域** - [ ] 移動時**必須保留所有解決詳情和連結** #### 報告建立操作前檢查 - [ ] 是否需要建立報告？如是，**必須使用** `./dl report analysis "主題"` - [ ] **禁止手動創建** reports/ 目錄下的任何檔案 - [ ] 報告主題描述是否具體明確？ #### 專案管理操作前檢查 (新增 2025-09-08) - [ ] 專案任務是否需要更新狀態？ - [ ] 任務類型是否正確識別（FE/BE/AI/MB/DOC/ENV/TEST）？ - [ ] 是否需要建議下一步行動？ #### 檔案操作前檢查 - [ ] 檔案編碼是否設定為 UTF-8？ - [ ] 中文內容是否正確顯示？ - [ ] 是否使用正確的當前日期（2025-09-08）？ - [ ] **文檔更新是否需要加入時間戳記？** #### 文檔更新時間戳記要求 **🕐 強制性日期標記原則**： - [ ] 任何文檔內容更新都**必須**加入時間戳記 - [ ] 格式：`(2025-09-08)` 或 `✅ (2025-09-08)` 或 `📊 **更新**: (2025-09-08)` - [ ] 位置：緊接在更新內容後面 - [ ] 檢查清單項目標記：`- [x] 項目名稱 ✅ (2025-09-08)` - [ ] 進度狀態更新：`**狀態**: 已完成 (2025-09-08)` - [ ] 新增章節：在章節標題或首行加入 `(新增 2025-09-08)` ### 每次任務完成後檢查 - [ ] 是否使用了正確的系統工具？ - [ ] 所有日期是否正確（2025-09-08）？ - [ ] 任務狀態是否已更新為完成 ✅ (專案任務) - [ ] 發現的問題是否已記錄？ - [ ] 報告是否已正確整合到問題系統？ - [ ] 檔案命名是否符合系統標準？ - [ ] **ISSUES.md中完成的項目是否已正確移動到歷史區域？** - [ ] **所有文檔更新是否都加入了時間戳記？** ## 📝 任務完成後的檢查清單 (整合 2025-09-08) 每次 Claude 完成任務後，請檢查： - [ ] Claude 有沒有提到任何「不確定」、「需要澄清」的地方？ - [ ] 有沒有發現文檔間的衝突？ - [ ] 有沒有提到技術實作的困難？ - [ ] 有沒有建議需要進一步決策的事項？ **如果有，就提醒：** "把剛才提到的問題記錄到問題系統" ## 🎯 協作流程範例 ### 範例1：專案任務執行 (新增 2025-09-08) ``` 用戶: "請執行 Flutter移動端配置調整" Claude: 識別為 MB 類型任務，更新狀態為進行中... [執行配置調整] ✅ 任務完成，狀態已更新 (2025-09-08) ``` ### 範例2：發現問題並記錄 ``` 用戶: "實作語音輸入功能，遇到問題就記錄" Claude: 我發現API規格中音頻格式支援不明確... [使用 ./dl issue 記錄問題] 已記錄問題：音頻格式規格不明確 ⚠️ ``` ### 範例3：文檔檢查 ``` 用戶: "檢查API文檔一致性，發現問題就用問題系統記錄" Claude: 我發現用戶管理API和認證API的錯誤碼定義衝突... [自動使用 ./dl issue 記錄問題] ``` ## 🚨 緊急情況處理 ### 工具故障時 1. 記錄工具故障情況到 ISSUES.md 2. 使用手動方式完成緊急任務 3. 修正工具後重新使用標準流程 4. 檢查並修正手動操作造成的不一致 ### 系統不一致時 1. 立即停止當前工作 2. 運行 `./check_consistency.sh` 3. 記錄發現的不一致問題 4. 修正問題後繼續工作 ## 💡 讓協作更順暢的技巧 (整合 2025-09-08) ### 🏷️ 在任務開始時就說明： "我希望你把發現的所有問題都記錄下來，這樣我們就不會遺漏任何需要解決的事項。" ### 🔄 定期檢查： 每週問 Claude："最近有沒有發現什麼新的問題需要記錄？" ### 📊 任務總結： "總結一下這次任務中發現的問題，並確保都記錄了。" ## 📚 相關文檔 - [問題追蹤系統](./ISSUES.md) - [專案執行管理](./PROJECTS.md) - [工具使用說明](./tools/) - [報告模板](./reports/templates/) - [檢查腳本](./scripts/) ## 🔄 持續改善 ### 發現新問題時 1. 立即記錄到 ISSUES.md 2. 評估是否需要新工具或流程 3. 更新本指南文檔 4. 通知相關團隊成員 ### 工具優化時 1. 測試新工具的正確性 2. 更新操作流程 3. 修訂本指南文檔 4. 確保向下相容性 ## 🤝 標準化指令格式 ### 推薦指令格式 ``` [任務描述] + 請遵循SOP + [具體SOP要點提醒] ``` ### 範例指令 ``` 請分析UI設計問題，遵循SOP，記得使用./dl report analysis建立報告 請處理緊急問題，遵循SOP，完成後問題要移到歷史區域不可標記[x] 請建立新的API文檔，遵循SOP，使用正確日期和UTF-8編碼 執行 Android Studio 安裝和配置，遇到問題就記錄 ``` ## 🎉 效益 ✅ **不會遺漏問題** - 所有發現的問題都被記錄 ✅ **追蹤更完整** - 包含 AI 協助時發現的問題 ✅ **決策有依據** - 問題記錄成為決策參考 ✅ **開發更順暢** - 提前發現潛在問題 ✅ **專案管理清晰** - 階段化執行，進度透明 (新增 2025-09-08) --- **重要提醒**: 本指南是 Claude AI 助手的強制性操作標準。任何偏離此流程的行為都可能造成系統不一致和品質問題。 **💫 記住：Claude 是您的協作夥伴，讓他幫您記錄問題和管理專案，讓開發更完善！** --- **最後更新**: 2025-09-08 **版本**: 3.0 - 整合專案管理系統和協作指南 (2025-09-08) **維護者**: Drama Ling 開發團隊