15 KiB

Raw Blame History

Claude 工作指南 (Claude Working Guidelines)

🤖 Claude 協作標準操作程序

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

🛠️ 系統工具使用

專案執行管理

./dl project list        # 列出所有專案
./dl phase status         # 查看階段狀態
./dl status              # 查看執行狀態

問題管理

./dl issue               # 互動式問題管理

# ❌ 禁止行為：直接編輯問題管理檔案
# 除非是修正現有問題的格式錯誤

報告建立

./dl report analysis "分析主題"
./dl report decision "決策主題" 

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

檢查作業

./dl check
./sop/scripts/maintenance_manager.sh
./sop/scripts/sop_consistency_check.sh    # SOP一致性檢查 (自動生成報告)

🎯 核心工作原則

1. 三層架構任務管理

架構設計

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

任務記錄標準格式

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

工作流程

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

管理原則

優先級驅動: 🔥緊急→⚠️重要→📝一般→💡想法
類型化管理: FE/BE/AI/MB/DOC/ENV/TEST標記
單一更新點: 狀態只在TASKS.md更新
參考連結: 任務連結到對應專案詳細文檔
階段化執行: 大型項目拆分為可管理的階段
進度追蹤: 即時更新任務狀態 (⏳ → 🔄 → ✅)
依賴管理: 自動檢查前置條件

2. 文件版本管理 SOP

強制性歸檔原則

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

適用情況

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

執行步驟

./sop/scripts/archive_file.sh 文件路徑 "歸檔原因"

# 範例
./sop/scripts/archive_file.sh TASK_MANAGEMENT_OLD.md "任務管理系統重構"

歸檔機制

目標目錄: sop/archive/ (扁平化結構)
文件命名: YYYYMMDDHHMMSS_原文件名
日誌記錄: sop/archive/logs/file_migration.log
自動化: 完整時間戳記、操作者記錄、原因說明

禁止行為

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

檢查指令

./sop/scripts/view_archives.sh     # 查看歸檔狀態
cat sop/archive/logs/file_migration.log  # 查看日誌

3. 任務完成清理 SOP

強制性完成後清理原則

重要: Claude 完成任務後，必須執行完整清理流程，保持任務列表整潔

執行步驟

# 1. 標記任務完成
- [x] 📚 **任務名稱** - 任務描述 ✅ (完成日期)

# 2. 移動到已完成區域 - 從當前任務區塊完全移除
# 3. 更新專案文檔狀態為"✅ 已完成 (完成日期)"
# 4. 歸檔專案文檔
./sop/scripts/archive_file.sh projects/專案文檔.md "專案完成，文檔歸檔"
# 5. 更新任務文檔中的連結為歸檔路徑

清理機制

移除規則: 已完成任務從待辦區域完全移除
記錄位置: 移至對應日期的已完成任務區域
詳細保留: 移動時必須保留專案文檔連結和解決細節
狀態同步: 專案文檔狀態必須同步更新為已完成
文檔歸檔: 完成的專案文檔必須歸檔到archive目錄
連結更新: 任務中的專案文檔連結必須更新為歸檔路徑

禁止行為

絕對禁止只標記而不移動到已完成區域
不可在待辦任務區域留下已完成的項目
不可忘記更新對應的專案文檔狀態
不可省略完成總結的撰寫

4. 協作提醒原則

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

標準提醒語句:

"如果你在過程中發現任何規格不確定、衝突、技術問題或需要決策的地方，請記錄到任務管理系統。"
"遇到問題就記錄到任務系統"
"這些任務我已經記錄到系統中，你可以選定時間批量執行"

5. 日期和文檔管理原則

系統工具會自動處理日期 - 當前日期以系統時間為準
任何手動設定日期都必須使用正確的當前日期
主要記錄: 所有任務和問題記錄到 TASKS.md
分析報告: 所有分析必須產生正式報告 (使用 ./dl report)
歷史參考: 歸檔的問題記錄作為歷史參考和流程說明
系統整合: 報告必須與統一任務管理系統整合
文檔更新時間戳記: 任何文檔更新都必須加入時間戳記格式 (YYYY-MM-DD)

📋 Claude 應該記錄的問題類型

🔥 緊急問題

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

⚠️ 重要問題

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

📝 一般問題

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

📋 標準工作流程

專案任務執行流程

用戶提供任務名稱
Claude 識別任務類型、階段、專案歸屬
執行相關工作
自動更新 TASKS.md 狀態 (⏳ → 🔄 → ✅)
記錄執行結果和發現的問題

分析任務流程

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

問題處理流程

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

檢查作業流程

執行系統檢查: ./dl check
運行一致性檢查: ./sop/scripts/maintenance_manager.sh consistency
SOP工具一致性檢查: ./sop/scripts/sop_consistency_check.sh (自動生成檢查log到 sop/reports/logs/)
記錄發現問題: 使用問題管理系統
產生檢查報告: 必要時建立分析報告

⚠️ 常見錯誤和避免方法

錯誤1: 手動創建報告

解決: 必須使用 ./dl report 命令

錯誤2: 忽略現有工具

解決: 先檢查 sop/tools/ 目錄下的現有工具

錯誤3: 未整合任務管理系統

解決: 每次發現問題都必須記錄到 TASKS.md

錯誤4: 日期不一致

解決: 依賴系統工具的自動日期處理

錯誤5: 文檔更新缺少時間戳記

解決: 任何文檔更新都必須加入時間戳記

錯誤6: 檔案組織混亂

解決: 遵循專案檔案組織結構，使用適當的子目錄

📁 檔案組織原則

目錄結構規範

sop/
├── tools/environment/  # 開發環境設定工具
├── scripts/            # 專案維護腳本
├── archive/            # 歸檔目錄
└── docs/              # SOP 文檔
docs/04_technical/environment/  # 環境設定指南

檔案放置原則

設定工具: sop/tools/environment/[環境名]/
設定指南: docs/04_technical/environment/
維護腳本: sop/scripts/
歷史檔案: sop/archive/ (扁平化)
禁止行為: 直接在根目錄創建輔助檔案

🔍 品質檢查清單

每次操作前必檢

是否需要記錄新問題？如是，必須使用 ./dl issue
完成的問題必須移動到「📚 已完成歷史」對應日期區域
是否需要建立報告？如是，必須使用 ./dl report analysis "主題"
檔案編碼是否設定為 UTF-8？
中文內容是否正確顯示？
文檔更新是否需要加入時間戳記？

文檔更新時間戳記要求

格式：(當前日期) 或 ✅ (當前日期)
位置：緊接在更新內容後面
檢查清單項目：- [x] 項目名稱 ✅ (當前日期)
進度狀態更新：**狀態**: 已完成 (當前日期)

每次任務完成後檢查

是否使用了正確的系統工具？
任務狀態是否已更新為完成 ✅
發現的問題是否已記錄？
報告是否已正確整合到問題系統？
完成的項目是否已正確移動到歷史區域？
所有文檔更新是否都加入了時間戳記？

🚨 緊急情況處理

工具故障時

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

系統不一致時

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

🔔 協作通知規範

任務完成通知

完成任何工作後：必須語音提醒 say "I'm done"

求助通知

無法自動繼續工作時：必須語音提醒 say "help"

強制觸發情況

系統確認對話 - Do you want to proceed? / 文件覆寫 / Git操作確認
主動詢問執行 - 包含「要我...嗎？」「需要我...嗎？」的疑問句
技術阻擋/決策 - 命令失敗/多選項/衝突需裁決/無法繼續

判斷標準：主動詢問執行操作 = 先 say "help"

🎯 協作流程範例

範例1：專案任務執行

用戶: "請執行 Flutter移動端配置調整"
Claude: 識別為 MB 類型任務，更新狀態為進行中...
        [執行配置調整]  
        ✅ 任務完成，狀態已更新

範例2：統一任務管理

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

範例3：問題發現和記錄

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

💡 讓協作更順暢的技巧

任務開始時說明

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

定期檢查

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

任務總結

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

🔄 持續改善

發現新問題時

立即記錄到 TASKS.md (主要)
如需歷史追蹤，記錄到歸檔系統
評估是否需要新工具或流程
更新本指南文檔
通知相關團隊成員

工具優化時

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

📋 開發計劃生成標準流程

強制約束指令格式

重要: AI生成任何開發計劃時，必須使用以下標準指令格式，確保完全遵循既有docs規範：

請生成[功能名稱]開發計劃，**必須嚴格遵循以下約束**：

1. **視覺設計基準**: /docs/02_design/html-prototypes/[相關頁面]
2. **技術架構遵循**: /docs/04_technical/03_frontend/vue-frontend-architecture.md
3. **功能規格對應**: /docs/02_design/function-specs/web/[功能規格].md  
4. **開發標準執行**: /docs/04_technical/03_frontend/vue-development-standards.md

**要求**:
- 每章節開始前明確引用對應docs文件
- 不得添加docs規格外的功能
- 技術選型必須與既定規範一致
- 在結論說明如何確保不偏離規格

三階段驗證流程

階段1：規範掃描

讀取所有相關 docs/ 文件
列出必須遵循的約束清單
識別可能的衝突點

階段2：計劃生成

基於約束清單生成計劃
每個決策點引用docs依據
標註與原型的對應關係

階段3：符合性檢查

檢查每個章節是否符合docs規範
驗證技術選型一致性
確認視覺設計對齊度

開發計劃生成檢查清單

生成前檢查

已讀取所有相關 docs/ 文件
已識別對應的 html-prototypes
已確認 function-specs 範圍
已檢查 technical docs 約束

生成後驗證

視覺設計完全基於html-prototypes
技術選型符合vue-frontend-architecture
功能範圍限於function-specs定義
開發標準遵循vue-development-standards
每章節都有明確的docs引用

禁止行為

絕對禁止生成未基於docs規範的開發計劃
不可忽略現有的html-prototypes視覺設計
不可添加function-specs範圍外的功能
不可使用與技術架構文檔衝突的選型

🤝 推薦指令格式

[任務描述] + 請遵循SOP + [具體SOP要點提醒]

範例指令

請分析UI設計問題，遵循SOP，記得使用./dl report analysis建立報告
執行 Android Studio 安裝和配置，遇到問題就記錄
請生成詞彙學習開發計劃，必須嚴格遵循docs約束，基於html-prototypes視覺設計

📚 相關文檔

統一任務管理 - 主要工作管理系統
問題追蹤歷史 - 歷史問題記錄參考
工具使用說明 - 開發和維護工具
檢查腳本 - 系統維護和檔案管理腳本

🎉 效益

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

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

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

最後更新: 2025-09-10 - 新增開發計劃生成標準流程
版本: 4.1 - 系統性改善：新增AI開發計劃生成規範約束機制
維護者: Drama Ling 開發團隊

15 KiB Raw Blame History Unescape Escape

Claude 工作指南 (Claude Working Guidelines)

🤖 Claude 協作標準操作程序

🛠️ 系統工具使用

專案執行管理

問題管理

報告建立

檢查作業

🎯 核心工作原則

1. 三層架構任務管理

架構設計

任務記錄標準格式

工作流程

管理原則

2. 文件版本管理 SOP

強制性歸檔原則

適用情況

執行步驟

歸檔機制

禁止行為

檢查指令

3. 任務完成清理 SOP

強制性完成後清理原則

執行步驟

清理機制

禁止行為

4. 協作提醒原則

5. 日期和文檔管理原則

📋 Claude 應該記錄的問題類型

🔥 緊急問題

⚠️ 重要問題

📝 一般問題

📋 標準工作流程

專案任務執行流程

分析任務流程

問題處理流程

檢查作業流程

⚠️ 常見錯誤和避免方法

錯誤1: 手動創建報告

錯誤2: 忽略現有工具

錯誤3: 未整合任務管理系統

錯誤4: 日期不一致

錯誤5: 文檔更新缺少時間戳記

錯誤6: 檔案組織混亂

📁 檔案組織原則

目錄結構規範

檔案放置原則

🔍 品質檢查清單

每次操作前必檢

文檔更新時間戳記要求

每次任務完成後檢查

🚨 緊急情況處理

工具故障時

系統不一致時

🔔 協作通知規範

任務完成通知

求助通知

強制觸發情況

🎯 協作流程範例

範例1：專案任務執行

範例2：統一任務管理

範例3：問題發現和記錄

💡 讓協作更順暢的技巧

任務開始時說明

定期檢查

任務總結

🔄 持續改善

發現新問題時

工具優化時

📋 開發計劃生成標準流程

強制約束指令格式

三階段驗證流程

階段1：規範掃描

階段2：計劃生成

階段3：符合性檢查

開發計劃生成檢查清單

生成前檢查

生成後驗證

禁止行為

🤝 推薦指令格式

15 KiB

Raw Blame History