199 lines
6.3 KiB
Markdown
199 lines
6.3 KiB
Markdown
# Claude 工作指南 (Claude Working Guidelines)
|
||
|
||
## 🤖 Claude 協作標準操作程序
|
||
|
||
本文件為 Claude AI 助手在 Drama Ling 專案中的標準操作程序，確保工作流程的一致性和品質。
|
||
|
||
## 🛠️ 必須使用的系統工具
|
||
|
||
### 報告建立
|
||
```bash
|
||
# ✅ 正確做法：使用系統工具
|
||
./drama report analysis "分析主題"
|
||
./drama report decision "決策主題"
|
||
|
||
# ❌ 禁止行為：手動創建報告檔案
|
||
# 直接 Write 或 Edit reports/ 目錄下的檔案
|
||
```
|
||
|
||
### 問題管理
|
||
```bash
|
||
# ✅ 正確做法：使用問題管理工具
|
||
./drama issue
|
||
|
||
# ❌ 禁止行為：直接編輯 ISSUES.md
|
||
# 除非是修正現有問題的格式錯誤
|
||
```
|
||
|
||
### 檢查作業
|
||
```bash
|
||
# ✅ 正確做法：使用檢查工具
|
||
./drama check
|
||
|
||
# 其他維護腳本
|
||
./check_consistency.sh
|
||
```
|
||
|
||
## 🎯 核心工作原則
|
||
|
||
### 1. 工具優先原則
|
||
- **必須優先使用現有工具和腳本**
|
||
- 手動操作只能用於緊急修正
|
||
- 所有報告都必須透過 `./drama report` 創建
|
||
|
||
### 2. 日期準確性原則
|
||
- **系統工具會自動處理日期**
|
||
- 當前日期：2025-09-08
|
||
- 任何手動設定日期都必須使用正確的當前日期
|
||
|
||
### 3. 文檔整合原則
|
||
- 所有問題必須記錄到 ISSUES.md
|
||
- 所有分析必須產生正式報告
|
||
- 報告必須與問題系統整合
|
||
|
||
## 📋 標準工作流程
|
||
|
||
### 分析任務流程
|
||
1. **建立分析報告**: `./drama report analysis "主題"`
|
||
2. **執行分析工作**: 使用適當工具進行分析
|
||
3. **更新報告內容**: 編輯生成的報告檔案
|
||
4. **整合問題系統**: 確認相關問題已正確連結
|
||
|
||
### 問題處理流程
|
||
1. **記錄問題**: `./drama issue`
|
||
2. **分配優先級**: 🔥緊急 / ⚠️重要 / 📝一般
|
||
3. **建立相關報告**: 如有需要，建立分析或決策報告
|
||
4. **追蹤解決進展**: 定期更新問題狀態
|
||
|
||
### 檢查作業流程
|
||
1. **執行系統檢查**: `./drama check`
|
||
2. **運行一致性檢查**: `./check_consistency.sh`
|
||
3. **記錄發現問題**: 使用問題管理系統
|
||
4. **產生檢查報告**: 必要時建立分析報告
|
||
|
||
## ⚠️ 常見錯誤和避免方法
|
||
|
||
### 錯誤1: 手動創建報告
|
||
**問題**: 直接創建報告檔案，導致日期錯誤、格式不一致
|
||
**解決**: 必須使用 `./drama report` 命令
|
||
|
||
### 錯誤2: 忽略現有工具
|
||
**問題**: 重複實作已存在的功能
|
||
**解決**: 先檢查 `tools/` 目錄下的現有工具
|
||
|
||
### 錯誤3: 未整合問題系統
|
||
**問題**: 發現問題但未記錄到 ISSUES.md
|
||
**解決**: 每次發現問題都必須使用 `./drama issue`
|
||
|
||
### 錯誤4: 日期不一致
|
||
**問題**: 使用錯誤的日期或格式
|
||
**解決**: 依賴系統工具的自動日期處理
|
||
|
||
### 錯誤5: 文檔更新缺少時間戳記 (新增 2025-09-08)
|
||
**問題**: 更新文檔內容後未標記更新時間，難以追蹤變更歷史
|
||
**解決**: 任何文檔更新都必須加入時間戳記，格式為 (YYYY-MM-DD)
|
||
**範例**:
|
||
```
|
||
- [x] 任務完成 ✅ (2025-09-08)
|
||
📊 **進度更新**: 已完成19個UI (2025-09-08)
|
||
### 新增功能 (新增 2025-09-08)
|
||
```
|
||
|
||
## 🔍 品質檢查清單
|
||
|
||
### 🛡️ 每次操作前必檢（強制性SOP合規檢查）
|
||
**⚠️ 重要：任何操作前都必須執行此檢查清單**
|
||
|
||
#### 問題管理操作前檢查
|
||
- [ ] 是否需要記錄新問題？如是，**必須使用** `./drama issue`
|
||
- [ ] 完成的問題是否要標記？如是，**絕對不可在待處理區標記[x]**
|
||
- [ ] 完成的問題**必須移動到「📚 已完成歷史」對應日期區域**
|
||
- [ ] 移動時**必須保留所有解決詳情和連結**
|
||
|
||
#### 報告建立操作前檢查
|
||
- [ ] 是否需要建立報告？如是，**必須使用** `./drama report analysis "主題"`
|
||
- [ ] **禁止手動創建** reports/ 目錄下的任何檔案
|
||
- [ ] 報告主題描述是否具體明確？
|
||
|
||
#### 檔案操作前檢查
|
||
- [ ] 檔案編碼是否設定為 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中完成的項目是否已正確移動到歷史區域？**
|
||
- [ ] **所有文檔更新是否都加入了時間戳記？**
|
||
|
||
## 🚨 緊急情況處理
|
||
|
||
### 工具故障時
|
||
1. 記錄工具故障情況到 ISSUES.md
|
||
2. 使用手動方式完成緊急任務
|
||
3. 修正工具後重新使用標準流程
|
||
4. 檢查並修正手動操作造成的不一致
|
||
|
||
### 系統不一致時
|
||
1. 立即停止當前工作
|
||
2. 運行 `./check_consistency.sh`
|
||
3. 記錄發現的不一致問題
|
||
4. 修正問題後繼續工作
|
||
|
||
## 📚 相關文檔
|
||
|
||
- [問題追蹤系統](./ISSUES.md)
|
||
- [工具使用說明](./tools/)
|
||
- [報告模板](./reports/templates/)
|
||
- [檢查腳本](./scripts/)
|
||
|
||
## 🔄 持續改善
|
||
|
||
### 發現新問題時
|
||
1. 立即記錄到 ISSUES.md
|
||
2. 評估是否需要新工具或流程
|
||
3. 更新本指南文檔
|
||
4. 通知相關團隊成員
|
||
|
||
### 工具優化時
|
||
1. 測試新工具的正確性
|
||
2. 更新操作流程
|
||
3. 修訂本指南文檔
|
||
4. 確保向下相容性
|
||
|
||
---
|
||
|
||
**重要提醒**: 本指南是 Claude AI 助手的強制性操作標準。任何偏離此流程的行為都可能造成系統不一致和品質問題。
|
||
|
||
## 🤝 標準化指令格式（方案A）
|
||
|
||
### 推薦指令格式
|
||
```
|
||
[任務描述] + 請遵循SOP + [具體SOP要點提醒]
|
||
```
|
||
|
||
### 範例指令
|
||
```
|
||
請分析UI設計問題，遵循SOP，記得使用./drama report analysis建立報告
|
||
請處理緊急問題，遵循SOP，完成後問題要移到歷史區域不可標記[x]
|
||
請建立新的API文檔，遵循SOP，使用正確日期和UTF-8編碼
|
||
```
|
||
|
||
---
|
||
|
||
**最後更新**: 2025-09-08
|
||
**版本**: 2.1 - 加入文檔更新時間戳記強制性要求 (2025-09-08)
|
||
**維護者**: Drama Ling 開發團隊 |