15 KiB

Raw Blame History

Claude 工作指南 (Claude Working Guidelines)

🤖 Claude 協作標準操作程序

本文件為 Claude AI 助手在 Drama Ling 專案中的標準操作程序和協作指南。

🛠️ 系統工具使用

專案執行管理 (新增 2025-09-08)

# ✅ 正確做法：使用專案管理工具
./dl project list        # 列出所有專案
./dl phase status         # 查看階段狀態
./dl status              # 查看執行狀態

問題管理

# ✅ 正確做法：使用問題管理工具  
./dl issue               # 互動式問題管理

# ❌ 禁止行為：直接編輯 ISSUES.md
# 除非是修正現有問題的格式錯誤

報告建立

# ✅ 正確做法：使用系統工具
./dl report analysis "分析主題"
./dl report decision "決策主題" 

# ❌ 禁止行為：手動創建報告檔案

檢查作業

# ✅ 正確做法：使用檢查工具
./dl check

# 其他維護腳本
./check_consistency.sh

🎯 核心工作原則

1. 三層架構任務管理原則 (更新 2025-09-09)

🏗️ 架構設計

TASK_MANAGEMENT.md: 簡潔任務列表，80%日常工作在此進行
projects/[專案名].md: 詳細專案規格和技術文檔
projects/templates/: 純模板參考，不追蹤狀態

📋 任務記錄標準格式

- [ ] 🎯 **任務名稱** - 簡短描述 (預估時間)
  - 📄 參考: [專案詳細文檔](projects/project-name.md)

🔄 工作流程

討論階段: 與Claude自由討論需求
記錄階段: Claude記錄簡潔任務到TASK_MANAGEMENT.md + 創建詳細專案文檔
執行階段: 查看TASK_MANAGEMENT.md選擇批量執行
完成階段: 只在TASK_MANAGEMENT.md標記完成✅

📊 管理原則

優先級驅動: 🔥緊急→⚠️重要→📝一般→💡想法
類型化管理: FE/BE/AI/MB/DOC/ENV/TEST標記
單一更新點: 狀態只在TASK_MANAGEMENT.md更新
參考連結: 任務連結到對應專案詳細文檔

2. 文件版本管理SOP (新增 2025-09-09)

🗃️ 強制性歸檔原則

重要: Claude 在更新重要文件時，必須先歸檔舊版本，避免資料污染

📋 適用情況

重構現有系統文件時 (如TASK_MANAGEMENT.md)
替換重要配置文件時
大幅修改核心文檔時
產生備份版本的文件時 (如*_OLD.md, *_NEW.md)

🔧 SOP執行步驟

# 1. 發現需要歸檔的舊文件時，立即執行歸檔命令
./scripts/archive_file.sh 文件路徑 "歸檔原因"

# 範例
./scripts/archive_file.sh TASK_MANAGEMENT_OLD.md "任務管理系統重構為三層架構"

📊 歸檔機制

目標目錄: archive/YYYY-MM-DD/
文件命名: HHMMSS_原文件名
日誌記錄: archive/logs/file_migration.log
自動化: 時間戳記、操作者記錄、原因說明

🚫 禁止行為

絕對禁止將舊版本文件留在根目錄或主要工作目錄
不可手動移動文件 (必須使用腳本確保日誌記錄)
不可跳過歸檔步驟直接刪除文件

📋 檢查指令

# 查看歸檔狀態 (推薦)
./scripts/view_archives.sh

# 或手動查看
cat archive/logs/file_migration.log        # 查看日誌
ls -la archive/$(date '+%Y-%m-%d')/       # 列出今日歸檔

3. 專案管理整合原則 (新增 2025-09-08)

階段化執行: 大型項目拆分為可管理的階段
任務分類: 使用類型標記（FE/BE/AI/MB/DOC/ENV/TEST）
進度追蹤: 即時更新任務狀態 (⏳ → 🔄 → ✅)
依賴管理: 自動檢查前置條件

3. 協作提醒原則 (整合 2025-09-08)

用戶可以使用以下提醒語句確保問題被記錄：

標準提醒語句： (更新 2025-09-09)

"如果你在過程中發現任何規格不確定、衝突、技術問題或需要決策的地方，請記錄到任務管理系統。"

簡短版本：

"遇到問題就記錄到任務系統"
"發現問題就用統一任務管理記錄"
"討論的內容請記錄到 TASK_MANAGEMENT.md"

新增批量執行提醒：

"這些任務我已經記錄到系統中，你可以選定時間批量執行"
"任務已整理完成，建議按優先級批量處理"

具體場景提醒：

"實作 [功能名稱]，發現問題就用 ./dl issue 記錄"
"檢查 [文檔]，找到不一致或不清楚的地方就記錄問題"  
"重構 [模組]，遇到架構問題或技術債務就記錄"

4. 日期準確性原則

系統工具會自動處理日期
當前日期：2025-09-08
任何手動設定日期都必須使用正確的當前日期

5. 文檔整合原則

所有問題必須記錄到 ISSUES.md
所有分析必須產生正式報告
報告必須與問題系統整合

📋 Claude 應該記錄的問題類型

🔥 緊急問題

架構設計衝突
無法實作的需求
安全性問題
資料不一致

⚠️ 重要問題

規格定義模糊
API 設計不確定
UI/UX 流程不清楚
技術選型疑慮

📝 一般問題

文檔格式不統一
命名規範不一致
小的技術改進建議
程式碼品質提升

📋 標準工作流程

專案任務執行流程 (新增 2025-09-08)

任務執行步驟

用戶提供任務名稱（如："Android Studio 安裝和配置"）
Claude 識別任務類型、階段、專案歸屬
執行相關工作
自動更新 PROJECTS.md 狀態 (⏳ → 🔄 → ✅)
記錄執行結果和發現的問題

專案管理互動範例

用戶: "執行 Android Studio 安裝和配置"
Claude: 識別為 ENV 類型任務，屬於階段1環境配置
        [執行安裝配置工作]
        [更新 PROJECTS.md 狀態]
        [報告完成情況]

分析任務流程

建立分析報告: ./dl report analysis "主題"
執行分析工作: 使用適當工具進行分析
更新報告內容: 編輯生成的報告檔案
整合問題系統: 確認相關問題已正確連結

問題處理流程

記錄問題: ./dl issue
分配優先級: 🔥緊急 / ⚠️重要 / 📝一般
建立相關報告: 如有需要，建立分析或決策報告
追蹤解決進展: 定期更新問題狀態

檢查作業流程

執行系統檢查: ./dl check
運行一致性檢查: ./check_consistency.sh
記錄發現問題: 使用問題管理系統
產生檢查報告: 必要時建立分析報告

⚠️ 常見錯誤和避免方法

錯誤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)

功能性檢查: 是否有明確功能分類？
時效性檢查: 是否為臨時性檔案？ → temp/
歷史性檢查: 是否為歷史檔案？ → archive/[日期]/
最終歸類: 完全無法歸類 → misc/

詳細策略請參考：docs/04_technical/file-organization-strategy.md

🔍 品質檢查清單

🛡️ 每次操作前必檢（強制性SOP合規檢查）

⚠️ 重要：任何操作前都必須執行此檢查清單

問題管理操作前檢查

是否需要記錄新問題？如是，必須使用 ./dl issue
完成的問題是否要標記？如是，絕對不可在待處理區標記
完成的問題必須移動到「📚 已完成歷史」對應日期區域
移動時必須保留所有解決詳情和連結

報告建立操作前檢查

是否需要建立報告？如是，必須使用 ./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：統一任務管理 (更新 2025-09-09)

用戶: "我想加入社交功能讓用戶互相挑戰，遇到問題就記錄"
Claude: 這個功能需要以下幾個部分...
        [討論功能細節]
        我已經將以下任務記錄到統一任務管理系統：
        - 🎨 FE 社交挑戰UI設計 (預估4-6小時)
        - ⚙️ BE 挑戰系統API開發 (預估8-12小時) 
        - 📚 DOC 社交功能規格文檔 (預估2-3小時)
        你可以在 TASK_MANAGEMENT.md 查看詳細內容並安排執行時間

範例3：問題發現和記錄 (更新 2025-09-09)

用戶: "檢查API文檔一致性"
Claude: 我發現用戶管理API和認證API的錯誤碼定義衝突...
        已將此問題記錄到任務管理系統：
        - ⚠️ BE API錯誤碼定義衝突 - 需要統一標準 ⏳
        這是重要任務，建議本週內處理

🚨 緊急情況處理

工具故障時

記錄工具故障情況到 ISSUES.md
使用手動方式完成緊急任務
修正工具後重新使用標準流程
檢查並修正手動操作造成的不一致

系統不一致時

立即停止當前工作
運行 ./check_consistency.sh
記錄發現的不一致問題
修正問題後繼續工作

💡 讓協作更順暢的技巧 (整合 2025-09-08)

🏷️ 在任務開始時就說明：

"我希望你把發現的所有問題都記錄下來，這樣我們就不會遺漏任何需要解決的事項。"

🔄 定期檢查：

每週問 Claude："最近有沒有發現什麼新的問題需要記錄？"

📊 任務總結：

"總結一下這次任務中發現的問題，並確保都記錄了。"

📚 相關文檔

🔄 持續改善

發現新問題時

立即記錄到 ISSUES.md
評估是否需要新工具或流程
更新本指南文檔
通知相關團隊成員

工具優化時

測試新工具的正確性
更新操作流程
修訂本指南文檔
確保向下相容性

🤝 標準化指令格式

範例指令

請分析UI設計問題，遵循SOP，記得使用./dl report analysis建立報告
請處理緊急問題，遵循SOP，完成後問題要移到歷史區域不可標記[x]
請建立新的API文檔，遵循SOP，使用正確日期和UTF-8編碼
執行 Android Studio 安裝和配置，遇到問題就記錄

🎉 效益

✅ 不會遺漏問題 - 所有發現的問題都被記錄
✅ 追蹤更完整 - 包含 AI 協助時發現的問題
✅ 決策有依據 - 問題記錄成為決策參考
✅ 開發更順暢 - 提前發現潛在問題 ✅ 專案管理清晰 - 階段化執行，進度透明 (新增 2025-09-08)

重要提醒: 本指南是 Claude AI 助手的強制性操作標準。任何偏離此流程的行為都可能造成系統不一致和品質問題。

💫 記住：Claude 是您的協作夥伴，讓他幫您記錄問題和管理專案，讓開發更完善！

🔔 協作通知規範 (新增 2025-09-09)

📢 任務完成通知

完成任務後: 必須使用 say "I'm done" 通知用戶
適用情境: 任何任務、分析、實作、整合工作完成後
重要性: 讓用戶知道可以查看結果或繼續下一步

🆘 求助通知

需要用戶協助時: 必須使用 say "help" 通知用戶
適用情境: 遇到無法自動決定的問題、需要確認方向時
時機: 在實際需要用戶回應前立即通知

重要: 這些通知習慣對協作體驗很重要，每次對話都必須遵循

最後更新: 2025-09-09
版本: 3.1 - 整合統一任務管理和通知規範 (2025-09-09)
維護者: Drama Ling 開發團隊

15 KiB Raw Blame History Unescape Escape