refactor: improve CLAUDE.md quality and eliminate redundancy
- Reduce document length from 536 to 372 lines (31% reduction) - Remove hardcoded dates, use dynamic date references - Consolidate duplicate task management content - Simplify verbose reminder examples section - Standardize formatting and structure consistency - Fix dl command report tool path references - Archive old version following SOP requirements - Add quality improvement analysis report 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
9345654cc1
commit
598cb33027
4
dl
4
dl
|
|
@ -100,11 +100,11 @@ case "$1" in
|
|||
;;
|
||||
"report")
|
||||
shift
|
||||
exec "$TOOLS_DIR/create_report.sh" analysis "$@"
|
||||
exec "$SCRIPT_DIR/sop/tools/create_report.sh" analysis "$@"
|
||||
;;
|
||||
"decision")
|
||||
shift
|
||||
exec "$TOOLS_DIR/create_report.sh" decision "$@"
|
||||
exec "$SCRIPT_DIR/sop/tools/create_report.sh" decision "$@"
|
||||
;;
|
||||
"reports")
|
||||
exec "$TOOLS_DIR/check_reports.sh"
|
||||
|
|
|
|||
|
|
@ -0,0 +1,536 @@
|
|||
# Claude 工作指南 (Claude Working Guidelines)
|
||||
|
||||
## 🤖 Claude 協作標準操作程序
|
||||
|
||||
本文件為 Claude AI 助手在 Drama Ling 專案中的標準操作程序和協作指南。
|
||||
|
||||
## 🛠️ 系統工具使用
|
||||
|
||||
### 專案執行管理 (新增 2025-09-08)
|
||||
```bash
|
||||
# ✅ 正確做法：使用專案管理工具
|
||||
./dl project list # 列出所有專案
|
||||
./dl phase status # 查看階段狀態
|
||||
./dl status # 查看執行狀態
|
||||
```
|
||||
|
||||
### 問題管理
|
||||
```bash
|
||||
# ✅ 正確做法：使用問題管理工具
|
||||
./dl issue # 互動式問題管理
|
||||
|
||||
# ❌ 禁止行為：直接編輯問題管理檔案
|
||||
# 除非是修正現有問題的格式錯誤
|
||||
```
|
||||
|
||||
### 報告建立
|
||||
```bash
|
||||
# ✅ 正確做法：使用系統工具
|
||||
./dl report analysis "分析主題"
|
||||
./dl report decision "決策主題"
|
||||
|
||||
# ❌ 禁止行為：手動創建報告檔案
|
||||
```
|
||||
|
||||
### 檢查作業
|
||||
```bash
|
||||
# ✅ 正確做法：使用檢查工具
|
||||
./dl check
|
||||
|
||||
# 其他維護腳本
|
||||
./sop/scripts/maintenance_manager.sh
|
||||
```
|
||||
|
||||
## 🎯 核心工作原則
|
||||
|
||||
### 1. 三層架構任務管理原則 (更新 2025-09-09)
|
||||
|
||||
#### 🏗️ 架構設計
|
||||
- **TASKS.md**: 簡潔任務列表，80%日常工作在此進行
|
||||
- **projects/[專案名].md**: 詳細專案規格和技術文檔
|
||||
- **projects/templates/**: 純模板參考，不追蹤狀態
|
||||
|
||||
#### 📋 任務記錄標準格式
|
||||
```markdown
|
||||
- [ ] 🎯 **任務名稱** - 簡短描述 (預估時間)
|
||||
- 📄 參考: [專案詳細文檔](projects/project-name.md)
|
||||
```
|
||||
|
||||
#### 🔄 工作流程
|
||||
1. **討論階段**: 與Claude自由討論需求
|
||||
2. **記錄階段**: Claude記錄簡潔任務到TASKS.md + 創建詳細專案文檔
|
||||
3. **執行階段**: 查看TASKS.md選擇批量執行
|
||||
4. **完成階段**: 只在TASKS.md標記完成✅
|
||||
|
||||
#### 📊 管理原則
|
||||
- **優先級驅動**: 🔥緊急→⚠️重要→📝一般→💡想法
|
||||
- **類型化管理**: FE/BE/AI/MB/DOC/ENV/TEST標記
|
||||
- **單一更新點**: 狀態只在TASKS.md更新
|
||||
- **參考連結**: 任務連結到對應專案詳細文檔
|
||||
|
||||
### 2. 文件版本管理SOP (新增 2025-09-09)
|
||||
|
||||
#### 🗃️ 強制性歸檔原則
|
||||
**重要**: Claude 在更新重要文件時，**必須**先歸檔舊版本，避免資料污染
|
||||
|
||||
#### 📋 適用情況
|
||||
- 重構現有系統文件時 (如TASKS.md)
|
||||
- 替換重要配置文件時
|
||||
- 大幅修改核心文檔時
|
||||
- 產生備份版本的文件時 (如*_OLD.md, *_NEW.md)
|
||||
|
||||
#### 🔧 SOP執行步驟
|
||||
```bash
|
||||
# 1. 發現需要歸檔的舊文件時，立即執行歸檔命令
|
||||
./sop/scripts/archive_file.sh 文件路徑 "歸檔原因"
|
||||
|
||||
# 範例
|
||||
./sop/scripts/archive_file.sh TASK_MANAGEMENT_OLD.md "任務管理系統重構為三層架構，更名為TASKS.md"
|
||||
```
|
||||
|
||||
#### 📊 歸檔機制 (更新 2025-09-09)
|
||||
- **目標目錄**: `sop/archive/` (扁平化結構)
|
||||
- **文件命名**: `YYYYMMDDHHMMSS_原文件名`
|
||||
- **日誌記錄**: `sop/archive/logs/file_migration.log`
|
||||
- **自動化**: 完整時間戳記、操作者記錄、原因說明
|
||||
|
||||
#### 🚫 禁止行為
|
||||
- **絕對禁止**將舊版本文件留在根目錄或主要工作目錄
|
||||
- 不可手動移動文件 (必須使用腳本確保日誌記錄)
|
||||
- 不可跳過歸檔步驟直接刪除文件
|
||||
|
||||
#### 📋 檢查指令
|
||||
```bash
|
||||
# 查看歸檔狀態 (推薦)
|
||||
./sop/scripts/view_archives.sh
|
||||
|
||||
# 或手動查看
|
||||
cat sop/archive/logs/file_migration.log # 查看日誌
|
||||
ls -la sop/archive/ # 列出所有歸檔檔案
|
||||
ls -la sop/archive/ | grep $(date '+%Y%m%d') # 列出今日歸檔
|
||||
```
|
||||
|
||||
### 3. 任務完成清理SOP (新增 2025-09-09)
|
||||
|
||||
#### 🧹 強制性完成後清理原則
|
||||
**重要**: Claude 完成任務後，**必須**執行完整清理流程，保持任務列表整潔
|
||||
|
||||
#### 📋 適用情況
|
||||
- 完成TASKS.md中的任何任務時
|
||||
- 專案文檔狀態需要更新為完成時
|
||||
- 任何標記為[x]的任務都需要移動到已完成區
|
||||
|
||||
#### 🔧 SOP執行步驟
|
||||
```bash
|
||||
# 1. 標記任務完成 (在對應任務前加[x])
|
||||
- [x] 📚 **任務名稱** - 任務描述 ✅ (YYYY-MM-DD)
|
||||
|
||||
# 2. 移動到已完成區域
|
||||
# 從當前任務區塊完全移除，移至"## 📚 已完成任務"對應日期區域
|
||||
|
||||
# 3. 更新專案文檔狀態
|
||||
# 修改projects/專案文檔.md的狀態為"✅ 已完成 (YYYY-MM-DD)"
|
||||
# 並在文檔末尾加入完成總結
|
||||
|
||||
# 4. 歸檔專案文檔
|
||||
# 使用歸檔SOP將完成的專案文檔歸檔
|
||||
./sop/scripts/archive_file.sh projects/專案文檔.md "專案完成，文檔歸檔"
|
||||
|
||||
# 5. 更新任務文檔中的連結
|
||||
# 將TASKS.md中的專案文檔連結更新為歸檔路徑
|
||||
```
|
||||
|
||||
#### 📊 清理機制
|
||||
- **移除規則**: 已完成任務從待辦區域**完全移除**
|
||||
- **記錄位置**: 移至對應日期的已完成任務區域
|
||||
- **詳細保留**: 移動時必須保留專案文檔連結和解決細節
|
||||
- **狀態同步**: 專案文檔狀態必須同步更新為已完成
|
||||
- **文檔歸檔**: 完成的專案文檔必須歸檔到archive目錄
|
||||
- **連結更新**: 任務中的專案文檔連結必須更新為歸檔路徑
|
||||
|
||||
#### 🚫 禁止行為
|
||||
- **絕對禁止**只標記[x]而不移動到已完成區域
|
||||
- 不可在待辦任務區域留下已完成的項目
|
||||
- 不可忘記更新對應的專案文檔狀態
|
||||
- 不可省略完成總結的撰寫
|
||||
|
||||
#### 📋 清理檢查清單
|
||||
```bash
|
||||
# 任務完成後必檢項目
|
||||
- [ ] 任務是否已標記[x]並加上完成日期？
|
||||
- [ ] 任務是否已從待辦區域完全移除？
|
||||
- [ ] 任務是否已移動到對應日期的已完成區域？
|
||||
- [ ] 專案文檔狀態是否已更新為"✅ 已完成"？
|
||||
- [ ] 專案文檔是否已加入完成總結？
|
||||
- [ ] 專案文檔是否已歸檔到archive目錄？
|
||||
- [ ] 任務中的專案文檔連結是否已更新為歸檔路徑？
|
||||
- [ ] 任務移動時是否保留了所有重要細節？
|
||||
```
|
||||
|
||||
### 4. 專案管理整合原則 (新增 2025-09-08)
|
||||
- **階段化執行**: 大型項目拆分為可管理的階段
|
||||
- **任務分類**: 使用類型標記（FE/BE/AI/MB/DOC/ENV/TEST）
|
||||
- **進度追蹤**: 即時更新任務狀態 (⏳ → 🔄 → ✅)
|
||||
- **依賴管理**: 自動檢查前置條件
|
||||
|
||||
### 5. 協作提醒原則 (整合 2025-09-08)
|
||||
用戶可以使用以下提醒語句確保問題被記錄：
|
||||
|
||||
**標準提醒語句：** (更新 2025-09-09)
|
||||
```
|
||||
"如果你在過程中發現任何規格不確定、衝突、技術問題或需要決策的地方，請記錄到任務管理系統。"
|
||||
```
|
||||
|
||||
**簡短版本：**
|
||||
```
|
||||
"遇到問題就記錄到任務系統"
|
||||
"發現問題就用統一任務管理記錄"
|
||||
"討論的內容請記錄到 TASKS.md"
|
||||
```
|
||||
|
||||
**新增批量執行提醒：**
|
||||
```
|
||||
"這些任務我已經記錄到系統中，你可以選定時間批量執行"
|
||||
"任務已整理完成，建議按優先級批量處理"
|
||||
```
|
||||
|
||||
**具體場景提醒：**
|
||||
```
|
||||
"實作 [功能名稱]，發現問題就用 ./dl issue 記錄"
|
||||
"檢查 [文檔]，找到不一致或不清楚的地方就記錄問題"
|
||||
"重構 [模組]，遇到架構問題或技術債務就記錄"
|
||||
```
|
||||
|
||||
### 6. 日期準確性原則
|
||||
- **系統工具會自動處理日期**
|
||||
- 當前日期：2025-09-09
|
||||
- 任何手動設定日期都必須使用正確的當前日期
|
||||
|
||||
### 7. 文檔整合原則 (更新 2025-09-09)
|
||||
- **主要記錄**: 所有任務和問題記錄到 TASKS.md
|
||||
- **分析報告**: 所有分析必須產生正式報告 (使用 `./dl report`)
|
||||
- **歷史參考**: 歸檔的問題記錄作為歷史參考和流程說明
|
||||
- **系統整合**: 報告必須與統一任務管理系統整合
|
||||
|
||||
## 📋 Claude 應該記錄的問題類型
|
||||
|
||||
### 🔥 緊急問題
|
||||
- 架構設計衝突
|
||||
- 無法實作的需求
|
||||
- 安全性問題
|
||||
- 資料不一致
|
||||
|
||||
### ⚠️ 重要問題
|
||||
- 規格定義模糊
|
||||
- API 設計不確定
|
||||
- UI/UX 流程不清楚
|
||||
- 技術選型疑慮
|
||||
|
||||
### 📝 一般問題
|
||||
- 文檔格式不統一
|
||||
- 命名規範不一致
|
||||
- 小的技術改進建議
|
||||
- 程式碼品質提升
|
||||
|
||||
## 📋 標準工作流程
|
||||
|
||||
### 專案任務執行流程 (新增 2025-09-08)
|
||||
|
||||
#### 任務執行步驟
|
||||
1. 用戶提供任務名稱（如："Android Studio 安裝和配置"）
|
||||
2. Claude 識別任務類型、階段、專案歸屬
|
||||
3. 執行相關工作
|
||||
4. 自動更新 TASKS.md 狀態 (⏳ → 🔄 → ✅)
|
||||
5. 記錄執行結果和發現的問題
|
||||
|
||||
#### 專案管理互動範例
|
||||
```
|
||||
用戶: "執行 Android Studio 安裝和配置"
|
||||
Claude: 識別為 ENV 類型任務，屬於階段1環境配置
|
||||
[執行安裝配置工作]
|
||||
[更新 TASKS.md 狀態]
|
||||
[報告完成情況]
|
||||
```
|
||||
|
||||
### 分析任務流程
|
||||
1. **建立分析報告**: `./dl report analysis "主題"`
|
||||
2. **執行分析工作**: 使用適當工具進行分析
|
||||
3. **更新報告內容**: 編輯生成的報告檔案
|
||||
4. **整合問題系統**: 確認相關問題已正確連結
|
||||
|
||||
### 問題處理流程
|
||||
1. **記錄問題**: `./dl issue`
|
||||
2. **分配優先級**: 🔥緊急 / ⚠️重要 / 📝一般
|
||||
3. **建立相關報告**: 如有需要，建立分析或決策報告
|
||||
4. **追蹤解決進展**: 定期更新問題狀態
|
||||
|
||||
### 檢查作業流程
|
||||
1. **執行系統檢查**: `./dl check`
|
||||
2. **運行一致性檢查**: `./sop/scripts/maintenance_manager.sh consistency`
|
||||
3. **記錄發現問題**: 使用問題管理系統
|
||||
4. **產生檢查報告**: 必要時建立分析報告
|
||||
|
||||
## ⚠️ 常見錯誤和避免方法
|
||||
|
||||
### 錯誤1: 手動創建報告
|
||||
**問題**: 直接創建報告檔案，導致日期錯誤、格式不一致
|
||||
**解決**: 必須使用 `./dl report` 命令
|
||||
|
||||
### 錯誤2: 忽略現有工具
|
||||
**問題**: 重複實作已存在的功能
|
||||
**解決**: 先檢查 `sop/tools/` 目錄下的現有工具
|
||||
|
||||
### 錯誤3: 未整合任務管理系統 (更新 2025-09-09)
|
||||
**問題**: 發現問題但未記錄到統一任務管理系統
|
||||
**解決**: 每次發現問題都必須記錄到 TASKS.md
|
||||
|
||||
### 錯誤4: 日期不一致
|
||||
**問題**: 使用錯誤的日期或格式
|
||||
**解決**: 依賴系統工具的自動日期處理
|
||||
|
||||
### 錯誤5: 文檔更新缺少時間戳記 (新增 2025-09-08)
|
||||
**問題**: 更新文檔內容後未標記更新時間，難以追蹤變更歷史
|
||||
**解決**: 任何文檔更新都必須加入時間戳記，格式為 (YYYY-MM-DD)
|
||||
|
||||
### 錯誤6: 檔案組織混亂 (新增 2025-09-08)
|
||||
**問題**: 將輔助工具和指南檔案直接放在根目錄，造成目錄污染
|
||||
**解決**: 遵循專案檔案組織結構，使用適當的子目錄儲存不同類型的檔案
|
||||
|
||||
## 📁 檔案組織原則 (新增 2025-09-08)
|
||||
|
||||
### 目錄結構規範
|
||||
```
|
||||
sop/
|
||||
├── tools/
|
||||
│ └── environment/ # 開發環境設定工具
|
||||
│ ├── android/ # Android 開發相關
|
||||
│ ├── xcode/ # iOS/Xcode 開發相關
|
||||
│ └── flutter/ # Flutter 開發相關
|
||||
├── scripts/ # 專案維護腳本
|
||||
│ └── maintenance/ # 系統維護工具
|
||||
├── archive/ # 歸檔目錄
|
||||
└── docs/ # SOP 文檔
|
||||
docs/
|
||||
├── 04_technical/
|
||||
│ ├── environment/ # 環境設定指南
|
||||
│ └── ...
|
||||
```
|
||||
|
||||
### 檔案放置原則
|
||||
- **設定工具**: 放在 `sop/tools/environment/[環境名]/`
|
||||
- **設定指南**: 放在 `docs/04_technical/environment/`
|
||||
- **維護腳本**: 放在 `sop/scripts/` 或 `sop/scripts/maintenance/`
|
||||
- **臨時檔案**: 使用 `temp/` 目錄（需要時創建）
|
||||
- **歷史檔案**: 使用 `sop/archive/[日期]/` 目錄
|
||||
- **雜項檔案**: 使用 `misc/` 目錄（完全無法歸類的檔案）
|
||||
- **禁止行為**: 直接在根目錄創建輔助檔案
|
||||
|
||||
### 無法歸類檔案處理流程 (新增 2025-09-08)
|
||||
1. **功能性檢查**: 是否有明確功能分類？
|
||||
2. **時效性檢查**: 是否為臨時性檔案？ → `temp/`
|
||||
3. **歷史性檢查**: 是否為歷史檔案？ → `sop/archive/` (扁平化)
|
||||
4. **最終歸類**: 完全無法歸類 → `misc/`
|
||||
|
||||
詳細策略請參考：`docs/04_technical/file-organization-strategy.md`
|
||||
|
||||
## 🔍 品質檢查清單
|
||||
|
||||
### 🛡️ 每次操作前必檢（強制性SOP合規檢查）
|
||||
**⚠️ 重要：任何操作前都必須執行此檢查清單**
|
||||
|
||||
#### 問題管理操作前檢查
|
||||
- [ ] 是否需要記錄新問題？如是，**必須使用** `./dl issue`
|
||||
- [ ] 完成的問題是否要標記？如是，**絕對不可在待處理區標記[x]**
|
||||
- [ ] 完成的問題**必須移動到「📚 已完成歷史」對應日期區域**
|
||||
- [ ] 移動時**必須保留所有解決詳情和連結**
|
||||
|
||||
#### 報告建立操作前檢查
|
||||
- [ ] 是否需要建立報告？如是，**必須使用** `./dl report analysis "主題"`
|
||||
- [ ] **使用系統工具建立報告** (`./dl report analysis "主題"`)
|
||||
- [ ] 報告主題描述是否具體明確？
|
||||
|
||||
#### 專案管理操作前檢查 (新增 2025-09-08)
|
||||
- [ ] 專案任務是否需要更新狀態？
|
||||
- [ ] 任務類型是否正確識別（FE/BE/AI/MB/DOC/ENV/TEST）？
|
||||
- [ ] 是否需要建議下一步行動？
|
||||
|
||||
#### 檔案操作前檢查
|
||||
- [ ] 檔案編碼是否設定為 UTF-8？
|
||||
- [ ] 中文內容是否正確顯示？
|
||||
- [ ] 是否使用正確的當前日期（2025-09-09）？
|
||||
- [ ] **文檔更新是否需要加入時間戳記？**
|
||||
|
||||
#### 文檔更新時間戳記要求
|
||||
**🕐 強制性日期標記原則**：
|
||||
- [ ] 任何文檔內容更新都**必須**加入時間戳記
|
||||
- [ ] 格式：`(2025-09-09)` 或 `✅ (2025-09-09)` 或 `📊 **更新**: (2025-09-09)`
|
||||
- [ ] 位置：緊接在更新內容後面
|
||||
- [ ] 檢查清單項目標記：`- [x] 項目名稱 ✅ (2025-09-09)`
|
||||
- [ ] 進度狀態更新：`**狀態**: 已完成 (2025-09-09)`
|
||||
- [ ] 新增章節：在章節標題或首行加入 `(新增 2025-09-09)`
|
||||
|
||||
### 每次任務完成後檢查
|
||||
- [ ] 是否使用了正確的系統工具？
|
||||
- [ ] 所有日期是否正確（2025-09-09）？
|
||||
- [ ] 任務狀態是否已更新為完成 ✅ (專案任務)
|
||||
- [ ] 發現的問題是否已記錄？
|
||||
- [ ] 報告是否已正確整合到問題系統？
|
||||
- [ ] 檔案命名是否符合系統標準？
|
||||
- [ ] **ISSUES.md中完成的項目是否已正確移動到歷史區域？**
|
||||
- [ ] **所有文檔更新是否都加入了時間戳記？**
|
||||
|
||||
## 📝 任務完成後的檢查清單 (整合 2025-09-08)
|
||||
|
||||
每次 Claude 完成任務後，請檢查：
|
||||
|
||||
- [ ] Claude 有沒有提到任何「不確定」、「需要澄清」的地方？
|
||||
- [ ] 有沒有發現文檔間的衝突？
|
||||
- [ ] 有沒有提到技術實作的困難？
|
||||
- [ ] 有沒有建議需要進一步決策的事項？
|
||||
|
||||
**如果有，就提醒：** "把剛才提到的問題記錄到問題系統"
|
||||
|
||||
## 🎯 協作流程範例
|
||||
|
||||
### 範例1：專案任務執行 (新增 2025-09-08)
|
||||
```
|
||||
用戶: "請執行 Flutter移動端配置調整"
|
||||
Claude: 識別為 MB 類型任務，更新狀態為進行中...
|
||||
[執行配置調整]
|
||||
✅ 任務完成，狀態已更新 (2025-09-09)
|
||||
```
|
||||
|
||||
### 範例2：統一任務管理 (更新 2025-09-09)
|
||||
```
|
||||
用戶: "我想加入社交功能讓用戶互相挑戰，遇到問題就記錄"
|
||||
Claude: 這個功能需要以下幾個部分...
|
||||
[討論功能細節]
|
||||
我已經將以下任務記錄到統一任務管理系統：
|
||||
- 🎨 FE 社交挑戰UI設計 (預估4-6小時)
|
||||
- ⚙️ BE 挑戰系統API開發 (預估8-12小時)
|
||||
- 📚 DOC 社交功能規格文檔 (預估2-3小時)
|
||||
你可以在 TASKS.md 查看詳細內容並安排執行時間
|
||||
```
|
||||
|
||||
### 範例3：問題發現和記錄 (更新 2025-09-09)
|
||||
```
|
||||
用戶: "檢查API文檔一致性"
|
||||
Claude: 我發現用戶管理API和認證API的錯誤碼定義衝突...
|
||||
已將此問題記錄到任務管理系統：
|
||||
- ⚠️ BE API錯誤碼定義衝突 - 需要統一標準 ⏳
|
||||
這是重要任務，建議本週內處理
|
||||
```
|
||||
|
||||
## 🚨 緊急情況處理
|
||||
|
||||
### 工具故障時
|
||||
1. 記錄工具故障情況到統一任務管理系統
|
||||
2. 使用手動方式完成緊急任務
|
||||
3. 修正工具後重新使用標準流程
|
||||
4. 檢查並修正手動操作造成的不一致
|
||||
|
||||
### 系統不一致時
|
||||
1. 立即停止當前工作
|
||||
2. 運行 `./sop/scripts/maintenance_manager.sh consistency`
|
||||
3. 記錄發現的不一致問題
|
||||
4. 修正問題後繼續工作
|
||||
|
||||
## 💡 讓協作更順暢的技巧 (整合 2025-09-08)
|
||||
|
||||
### 🏷️ 在任務開始時就說明：
|
||||
"我希望你把發現的所有問題都記錄下來，這樣我們就不會遺漏任何需要解決的事項。"
|
||||
|
||||
### 🔄 定期檢查：
|
||||
每週問 Claude："最近有沒有發現什麼新的問題需要記錄？"
|
||||
|
||||
### 📊 任務總結：
|
||||
"總結一下這次任務中發現的問題，並確保都記錄了。"
|
||||
|
||||
## 📚 相關文檔
|
||||
|
||||
- [統一任務管理](../TASKS.md) - 主要工作管理系統
|
||||
- [問題追蹤歷史](../archive/) - 歷史問題記錄參考
|
||||
- [專案管理歷史](../archive/) - 歷史專案統計參考
|
||||
- [工具使用說明](../tools/) - 開發和維護工具
|
||||
- [歷史報告歸檔](../archive/) - 過往分析和決策報告
|
||||
- [檢查腳本](../scripts/) - 系統維護和檔案管理腳本
|
||||
|
||||
## 🔄 持續改善
|
||||
|
||||
### 發現新問題時 (更新 2025-09-09)
|
||||
1. 立即記錄到 TASKS.md (主要)
|
||||
2. 如需歷史追蹤，記錄到歸檔系統
|
||||
3. 評估是否需要新工具或流程
|
||||
4. 更新本指南文檔
|
||||
5. 通知相關團隊成員
|
||||
|
||||
### 工具優化時
|
||||
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-09)
|
||||
|
||||
### 📢 任務完成通知
|
||||
- 完成任何工作後：**必須** `say "I'm done"`
|
||||
|
||||
### 🆘 求助通知
|
||||
- 無法自動繼續工作時：**必須** `say "help"`
|
||||
|
||||
#### 🚨 三類強制觸發情況
|
||||
|
||||
**1. 系統確認對話**
|
||||
- `Do you want to proceed?` / 文件覆寫 / Git操作確認
|
||||
|
||||
**2. 主動詢問執行** ⚠️ **關鍵觸發**
|
||||
- 包含「要我...嗎？」「需要我...嗎？」「是否要我...？」
|
||||
- 任何主動提議執行操作的疑問句
|
||||
|
||||
**3. 技術阻擋/決策**
|
||||
- 命令失敗/多選項/衝突需裁決/無法繼續
|
||||
|
||||
#### ✅ 正確作法
|
||||
```
|
||||
❌ 錯誤："要我修正這個問題嗎？"
|
||||
✅ 正確：say "help" → "需要確認是否修正問題"
|
||||
```
|
||||
|
||||
**判斷標準**：主動詢問執行操作 = 先 `say "help"`
|
||||
|
||||
---
|
||||
|
||||
**最後更新**: 2025-09-09
|
||||
**版本**: 3.4 - 精簡協作通知規範，保留核心觸發條件 (2025-09-09)
|
||||
**維護者**: Drama Ling 開發團隊
|
||||
|
|
@ -6,9 +6,8 @@
|
|||
|
||||
## 🛠️ 系統工具使用
|
||||
|
||||
### 專案執行管理 (新增 2025-09-08)
|
||||
### 專案執行管理
|
||||
```bash
|
||||
# ✅ 正確做法：使用專案管理工具
|
||||
./dl project list # 列出所有專案
|
||||
./dl phase status # 查看階段狀態
|
||||
./dl status # 查看執行狀態
|
||||
|
|
@ -16,16 +15,14 @@
|
|||
|
||||
### 問題管理
|
||||
```bash
|
||||
# ✅ 正確做法：使用問題管理工具
|
||||
./dl issue # 互動式問題管理
|
||||
|
||||
# ❌ 禁止行為：直接編輯 ISSUES.md
|
||||
# ❌ 禁止行為：直接編輯問題管理檔案
|
||||
# 除非是修正現有問題的格式錯誤
|
||||
```
|
||||
|
||||
### 報告建立
|
||||
```bash
|
||||
# ✅ 正確做法：使用系統工具
|
||||
./dl report analysis "分析主題"
|
||||
./dl report decision "決策主題"
|
||||
|
||||
|
|
@ -34,112 +31,94 @@
|
|||
|
||||
### 檢查作業
|
||||
```bash
|
||||
# ✅ 正確做法：使用檢查工具
|
||||
./dl check
|
||||
|
||||
# 其他維護腳本
|
||||
./check_consistency.sh
|
||||
./sop/scripts/maintenance_manager.sh
|
||||
```
|
||||
|
||||
## 🎯 核心工作原則
|
||||
|
||||
### 1. 三層架構任務管理原則 (更新 2025-09-09)
|
||||
### 1. 三層架構任務管理
|
||||
|
||||
#### 🏗️ 架構設計
|
||||
#### 架構設計
|
||||
- **TASKS.md**: 簡潔任務列表，80%日常工作在此進行
|
||||
- **projects/[專案名].md**: 詳細專案規格和技術文檔
|
||||
- **projects/templates/**: 純模板參考，不追蹤狀態
|
||||
|
||||
#### 📋 任務記錄標準格式
|
||||
#### 任務記錄標準格式
|
||||
```markdown
|
||||
- [ ] 🎯 **任務名稱** - 簡短描述 (預估時間)
|
||||
- 📄 參考: [專案詳細文檔](projects/project-name.md)
|
||||
```
|
||||
|
||||
#### 🔄 工作流程
|
||||
#### 工作流程
|
||||
1. **討論階段**: 與Claude自由討論需求
|
||||
2. **記錄階段**: Claude記錄簡潔任務到TASKS.md + 創建詳細專案文檔
|
||||
3. **執行階段**: 查看TASKS.md選擇批量執行
|
||||
4. **完成階段**: 只在TASKS.md標記完成✅
|
||||
|
||||
#### 📊 管理原則
|
||||
#### 管理原則
|
||||
- **優先級驅動**: 🔥緊急→⚠️重要→📝一般→💡想法
|
||||
- **類型化管理**: FE/BE/AI/MB/DOC/ENV/TEST標記
|
||||
- **單一更新點**: 狀態只在TASKS.md更新
|
||||
- **參考連結**: 任務連結到對應專案詳細文檔
|
||||
- **階段化執行**: 大型項目拆分為可管理的階段
|
||||
- **進度追蹤**: 即時更新任務狀態 (⏳ → 🔄 → ✅)
|
||||
- **依賴管理**: 自動檢查前置條件
|
||||
|
||||
### 2. 文件版本管理SOP (新增 2025-09-09)
|
||||
### 2. 文件版本管理 SOP
|
||||
|
||||
#### 🗃️ 強制性歸檔原則
|
||||
#### 強制性歸檔原則
|
||||
**重要**: Claude 在更新重要文件時，**必須**先歸檔舊版本，避免資料污染
|
||||
|
||||
#### 📋 適用情況
|
||||
- 重構現有系統文件時 (如TASK_MANAGEMENT.md)
|
||||
#### 適用情況
|
||||
- 重構現有系統文件時 (如TASKS.md)
|
||||
- 替換重要配置文件時
|
||||
- 大幅修改核心文檔時
|
||||
- 產生備份版本的文件時 (如*_OLD.md, *_NEW.md)
|
||||
|
||||
#### 🔧 SOP執行步驟
|
||||
#### 執行步驟
|
||||
```bash
|
||||
# 1. 發現需要歸檔的舊文件時，立即執行歸檔命令
|
||||
./sop/scripts/archive_file.sh 文件路徑 "歸檔原因"
|
||||
|
||||
# 範例
|
||||
./sop/scripts/archive_file.sh TASK_MANAGEMENT_OLD.md "任務管理系統重構為三層架構，更名為TASKS.md"
|
||||
./sop/scripts/archive_file.sh TASK_MANAGEMENT_OLD.md "任務管理系統重構"
|
||||
```
|
||||
|
||||
#### 📊 歸檔機制
|
||||
- **目標目錄**: `sop/archive/YYYY-MM-DD/`
|
||||
- **文件命名**: `HHMMSS_原文件名`
|
||||
#### 歸檔機制
|
||||
- **目標目錄**: `sop/archive/` (扁平化結構)
|
||||
- **文件命名**: `YYYYMMDDHHMMSS_原文件名`
|
||||
- **日誌記錄**: `sop/archive/logs/file_migration.log`
|
||||
- **自動化**: 時間戳記、操作者記錄、原因說明
|
||||
- **自動化**: 完整時間戳記、操作者記錄、原因說明
|
||||
|
||||
#### 🚫 禁止行為
|
||||
#### 禁止行為
|
||||
- **絕對禁止**將舊版本文件留在根目錄或主要工作目錄
|
||||
- 不可手動移動文件 (必須使用腳本確保日誌記錄)
|
||||
- 不可跳過歸檔步驟直接刪除文件
|
||||
|
||||
#### 📋 檢查指令
|
||||
#### 檢查指令
|
||||
```bash
|
||||
# 查看歸檔狀態 (推薦)
|
||||
./sop/scripts/view_archives.sh
|
||||
|
||||
# 或手動查看
|
||||
cat sop/archive/logs/file_migration.log # 查看日誌
|
||||
ls -la sop/archive/$(date '+%Y-%m-%d')/ # 列出今日歸檔
|
||||
./sop/scripts/view_archives.sh # 查看歸檔狀態
|
||||
cat sop/archive/logs/file_migration.log # 查看日誌
|
||||
```
|
||||
|
||||
### 3. 任務完成清理SOP (新增 2025-09-09)
|
||||
### 3. 任務完成清理 SOP
|
||||
|
||||
#### 🧹 強制性完成後清理原則
|
||||
#### 強制性完成後清理原則
|
||||
**重要**: Claude 完成任務後，**必須**執行完整清理流程，保持任務列表整潔
|
||||
|
||||
#### 📋 適用情況
|
||||
- 完成TASK_MANAGEMENT.md中的任何任務時
|
||||
- 專案文檔狀態需要更新為完成時
|
||||
- 任何標記為[x]的任務都需要移動到已完成區
|
||||
|
||||
#### 🔧 SOP執行步驟
|
||||
#### 執行步驟
|
||||
```bash
|
||||
# 1. 標記任務完成 (在對應任務前加[x])
|
||||
- [x] 📚 **任務名稱** - 任務描述 ✅ (YYYY-MM-DD)
|
||||
# 1. 標記任務完成
|
||||
- [x] 📚 **任務名稱** - 任務描述 ✅ (完成日期)
|
||||
|
||||
# 2. 移動到已完成區域
|
||||
# 從當前任務區塊完全移除，移至"## 📚 已完成任務"對應日期區域
|
||||
|
||||
# 3. 更新專案文檔狀態
|
||||
# 修改projects/專案文檔.md的狀態為"✅ 已完成 (YYYY-MM-DD)"
|
||||
# 並在文檔末尾加入完成總結
|
||||
|
||||
# 4. 歸檔專案文檔
|
||||
# 使用歸檔SOP將完成的專案文檔歸檔
|
||||
# 2. 移動到已完成區域 - 從當前任務區塊完全移除
|
||||
# 3. 更新專案文檔狀態為"✅ 已完成 (完成日期)"
|
||||
# 4. 歸檔專案文檔
|
||||
./sop/scripts/archive_file.sh projects/專案文檔.md "專案完成，文檔歸檔"
|
||||
|
||||
# 5. 更新任務文檔中的連結
|
||||
# 將TASK_MANAGEMENT.md中的專案文檔連結更新為歸檔路徑
|
||||
# 5. 更新任務文檔中的連結為歸檔路徑
|
||||
```
|
||||
|
||||
#### 📊 清理機制
|
||||
#### 清理機制
|
||||
- **移除規則**: 已完成任務從待辦區域**完全移除**
|
||||
- **記錄位置**: 移至對應日期的已完成任務區域
|
||||
- **詳細保留**: 移動時必須保留專案文檔連結和解決細節
|
||||
|
|
@ -147,110 +126,51 @@ ls -la sop/archive/$(date '+%Y-%m-%d')/ # 列出今日歸檔
|
|||
- **文檔歸檔**: 完成的專案文檔必須歸檔到archive目錄
|
||||
- **連結更新**: 任務中的專案文檔連結必須更新為歸檔路徑
|
||||
|
||||
#### 🚫 禁止行為
|
||||
#### 禁止行為
|
||||
- **絕對禁止**只標記[x]而不移動到已完成區域
|
||||
- 不可在待辦任務區域留下已完成的項目
|
||||
- 不可忘記更新對應的專案文檔狀態
|
||||
- 不可省略完成總結的撰寫
|
||||
|
||||
#### 📋 清理檢查清單
|
||||
```bash
|
||||
# 任務完成後必檢項目
|
||||
- [ ] 任務是否已標記[x]並加上完成日期？
|
||||
- [ ] 任務是否已從待辦區域完全移除？
|
||||
- [ ] 任務是否已移動到對應日期的已完成區域？
|
||||
- [ ] 專案文檔狀態是否已更新為"✅ 已完成"？
|
||||
- [ ] 專案文檔是否已加入完成總結？
|
||||
- [ ] 專案文檔是否已歸檔到archive目錄？
|
||||
- [ ] 任務中的專案文檔連結是否已更新為歸檔路徑？
|
||||
- [ ] 任務移動時是否保留了所有重要細節？
|
||||
```
|
||||
### 4. 協作提醒原則
|
||||
|
||||
### 4. 專案管理整合原則 (新增 2025-09-08)
|
||||
- **階段化執行**: 大型項目拆分為可管理的階段
|
||||
- **任務分類**: 使用類型標記（FE/BE/AI/MB/DOC/ENV/TEST）
|
||||
- **進度追蹤**: 即時更新任務狀態 (⏳ → 🔄 → ✅)
|
||||
- **依賴管理**: 自動檢查前置條件
|
||||
用戶可使用以下提醒語句確保問題被記錄：
|
||||
|
||||
### 5. 協作提醒原則 (整合 2025-09-08)
|
||||
用戶可以使用以下提醒語句確保問題被記錄：
|
||||
**標準提醒語句**:
|
||||
- "如果你在過程中發現任何規格不確定、衝突、技術問題或需要決策的地方，請記錄到任務管理系統。"
|
||||
- "遇到問題就記錄到任務系統"
|
||||
- "這些任務我已經記錄到系統中，你可以選定時間批量執行"
|
||||
|
||||
**標準提醒語句：** (更新 2025-09-09)
|
||||
```
|
||||
"如果你在過程中發現任何規格不確定、衝突、技術問題或需要決策的地方，請記錄到任務管理系統。"
|
||||
```
|
||||
### 5. 日期和文檔管理原則
|
||||
|
||||
**簡短版本：**
|
||||
```
|
||||
"遇到問題就記錄到任務系統"
|
||||
"發現問題就用統一任務管理記錄"
|
||||
"討論的內容請記錄到 TASK_MANAGEMENT.md"
|
||||
```
|
||||
|
||||
**新增批量執行提醒：**
|
||||
```
|
||||
"這些任務我已經記錄到系統中，你可以選定時間批量執行"
|
||||
"任務已整理完成，建議按優先級批量處理"
|
||||
```
|
||||
|
||||
**具體場景提醒：**
|
||||
```
|
||||
"實作 [功能名稱]，發現問題就用 ./dl issue 記錄"
|
||||
"檢查 [文檔]，找到不一致或不清楚的地方就記錄問題"
|
||||
"重構 [模組]，遇到架構問題或技術債務就記錄"
|
||||
```
|
||||
|
||||
### 6. 日期準確性原則
|
||||
- **系統工具會自動處理日期**
|
||||
- 當前日期：2025-09-09
|
||||
- 任何手動設定日期都必須使用正確的當前日期
|
||||
|
||||
### 7. 文檔整合原則 (更新 2025-09-09)
|
||||
- **主要記錄**: 所有任務和問題記錄到 TASK_MANAGEMENT.md
|
||||
- **系統工具會自動處理日期** - 當前日期以系統時間為準
|
||||
- **任何手動設定日期都必須使用正確的當前日期**
|
||||
- **主要記錄**: 所有任務和問題記錄到 TASKS.md
|
||||
- **分析報告**: 所有分析必須產生正式報告 (使用 `./dl report`)
|
||||
- **歷史參考**: ISSUES.md 作為歷史問題參考和流程說明
|
||||
- **歷史參考**: 歸檔的問題記錄作為歷史參考和流程說明
|
||||
- **系統整合**: 報告必須與統一任務管理系統整合
|
||||
- **文檔更新時間戳記**: 任何文檔更新都必須加入時間戳記格式 `(YYYY-MM-DD)`
|
||||
|
||||
## 📋 Claude 應該記錄的問題類型
|
||||
|
||||
### 🔥 緊急問題
|
||||
- 架構設計衝突
|
||||
- 無法實作的需求
|
||||
- 安全性問題
|
||||
- 資料不一致
|
||||
- 架構設計衝突、無法實作的需求、安全性問題、資料不一致
|
||||
|
||||
### ⚠️ 重要問題
|
||||
- 規格定義模糊
|
||||
- API 設計不確定
|
||||
- UI/UX 流程不清楚
|
||||
- 技術選型疑慮
|
||||
- 規格定義模糊、API 設計不確定、UI/UX 流程不清楚、技術選型疑慮
|
||||
|
||||
### 📝 一般問題
|
||||
- 文檔格式不統一
|
||||
- 命名規範不一致
|
||||
- 小的技術改進建議
|
||||
- 程式碼品質提升
|
||||
- 文檔格式不統一、命名規範不一致、小的技術改進建議、程式碼品質提升
|
||||
|
||||
## 📋 標準工作流程
|
||||
|
||||
### 專案任務執行流程 (新增 2025-09-08)
|
||||
|
||||
#### 任務執行步驟
|
||||
1. 用戶提供任務名稱（如："Android Studio 安裝和配置"）
|
||||
### 專案任務執行流程
|
||||
1. 用戶提供任務名稱
|
||||
2. Claude 識別任務類型、階段、專案歸屬
|
||||
3. 執行相關工作
|
||||
4. 自動更新 TASK_MANAGEMENT.md 狀態 (⏳ → 🔄 → ✅)
|
||||
4. 自動更新 TASKS.md 狀態 (⏳ → 🔄 → ✅)
|
||||
5. 記錄執行結果和發現的問題
|
||||
|
||||
#### 專案管理互動範例
|
||||
```
|
||||
用戶: "執行 Android Studio 安裝和配置"
|
||||
Claude: 識別為 ENV 類型任務，屬於階段1環境配置
|
||||
[執行安裝配置工作]
|
||||
[更新 TASK_MANAGEMENT.md 狀態]
|
||||
[報告完成情況]
|
||||
```
|
||||
|
||||
### 分析任務流程
|
||||
1. **建立分析報告**: `./dl report analysis "主題"`
|
||||
2. **執行分析工作**: 使用適當工具進行分析
|
||||
|
|
@ -265,153 +185,124 @@ Claude: 識別為 ENV 類型任務，屬於階段1環境配置
|
|||
|
||||
### 檢查作業流程
|
||||
1. **執行系統檢查**: `./dl check`
|
||||
2. **運行一致性檢查**: `./check_consistency.sh`
|
||||
2. **運行一致性檢查**: `./sop/scripts/maintenance_manager.sh consistency`
|
||||
3. **記錄發現問題**: 使用問題管理系統
|
||||
4. **產生檢查報告**: 必要時建立分析報告
|
||||
|
||||
## ⚠️ 常見錯誤和避免方法
|
||||
|
||||
### 錯誤1: 手動創建報告
|
||||
**問題**: 直接創建報告檔案，導致日期錯誤、格式不一致
|
||||
**解決**: 必須使用 `./dl report` 命令
|
||||
|
||||
### 錯誤2: 忽略現有工具
|
||||
**問題**: 重複實作已存在的功能
|
||||
**解決**: 先檢查 `sop/tools/` 目錄下的現有工具
|
||||
|
||||
### 錯誤3: 未整合任務管理系統 (更新 2025-09-09)
|
||||
**問題**: 發現問題但未記錄到統一任務管理系統
|
||||
**解決**: 每次發現問題都必須記錄到 TASK_MANAGEMENT.md
|
||||
### 錯誤3: 未整合任務管理系統
|
||||
**解決**: 每次發現問題都必須記錄到 TASKS.md
|
||||
|
||||
### 錯誤4: 日期不一致
|
||||
**問題**: 使用錯誤的日期或格式
|
||||
**解決**: 依賴系統工具的自動日期處理
|
||||
|
||||
### 錯誤5: 文檔更新缺少時間戳記 (新增 2025-09-08)
|
||||
**問題**: 更新文檔內容後未標記更新時間，難以追蹤變更歷史
|
||||
**解決**: 任何文檔更新都必須加入時間戳記，格式為 (YYYY-MM-DD)
|
||||
### 錯誤5: 文檔更新缺少時間戳記
|
||||
**解決**: 任何文檔更新都必須加入時間戳記
|
||||
|
||||
### 錯誤6: 檔案組織混亂 (新增 2025-09-08)
|
||||
**問題**: 將輔助工具和指南檔案直接放在根目錄，造成目錄污染
|
||||
**解決**: 遵循專案檔案組織結構，使用適當的子目錄儲存不同類型的檔案
|
||||
### 錯誤6: 檔案組織混亂
|
||||
**解決**: 遵循專案檔案組織結構，使用適當的子目錄
|
||||
|
||||
## 📁 檔案組織原則 (新增 2025-09-08)
|
||||
## 📁 檔案組織原則
|
||||
|
||||
### 目錄結構規範
|
||||
```
|
||||
sop/
|
||||
├── tools/
|
||||
│ └── environment/ # 開發環境設定工具
|
||||
│ ├── android/ # Android 開發相關
|
||||
│ ├── xcode/ # iOS/Xcode 開發相關
|
||||
│ └── flutter/ # Flutter 開發相關
|
||||
├── scripts/ # 專案維護腳本
|
||||
│ └── maintenance/ # 系統維護工具
|
||||
├── archive/ # 歸檔目錄
|
||||
└── docs/ # SOP 文檔
|
||||
docs/
|
||||
├── 04_technical/
|
||||
│ ├── environment/ # 環境設定指南
|
||||
│ └── ...
|
||||
├── tools/environment/ # 開發環境設定工具
|
||||
├── scripts/ # 專案維護腳本
|
||||
├── archive/ # 歸檔目錄
|
||||
└── docs/ # SOP 文檔
|
||||
docs/04_technical/environment/ # 環境設定指南
|
||||
```
|
||||
|
||||
### 檔案放置原則
|
||||
- **設定工具**: 放在 `sop/tools/environment/[環境名]/`
|
||||
- **設定指南**: 放在 `docs/04_technical/environment/`
|
||||
- **維護腳本**: 放在 `sop/scripts/` 或 `sop/scripts/maintenance/`
|
||||
- **臨時檔案**: 使用 `temp/` 目錄（需要時創建）
|
||||
- **歷史檔案**: 使用 `sop/archive/[日期]/` 目錄
|
||||
- **雜項檔案**: 使用 `misc/` 目錄（完全無法歸類的檔案）
|
||||
- **設定工具**: `sop/tools/environment/[環境名]/`
|
||||
- **設定指南**: `docs/04_technical/environment/`
|
||||
- **維護腳本**: `sop/scripts/`
|
||||
- **歷史檔案**: `sop/archive/` (扁平化)
|
||||
- **禁止行為**: 直接在根目錄創建輔助檔案
|
||||
|
||||
### 無法歸類檔案處理流程 (新增 2025-09-08)
|
||||
1. **功能性檢查**: 是否有明確功能分類？
|
||||
2. **時效性檢查**: 是否為臨時性檔案？ → `temp/`
|
||||
3. **歷史性檢查**: 是否為歷史檔案？ → `sop/archive/[日期]/`
|
||||
4. **最終歸類**: 完全無法歸類 → `misc/`
|
||||
|
||||
詳細策略請參考：`docs/04_technical/file-organization-strategy.md`
|
||||
|
||||
## 🔍 品質檢查清單
|
||||
|
||||
### 🛡️ 每次操作前必檢（強制性SOP合規檢查）
|
||||
**⚠️ 重要：任何操作前都必須執行此檢查清單**
|
||||
|
||||
#### 問題管理操作前檢查
|
||||
- [ ] 是否需要記錄新問題？如是，**必須使用** `./dl issue`
|
||||
- [ ] 完成的問題是否要標記？如是，**絕對不可在待處理區標記[x]**
|
||||
### 每次操作前必檢
|
||||
- [ ] 是否需要記錄新問題？如是，**必須使用** `./dl issue`
|
||||
- [ ] 完成的問題**必須移動到「📚 已完成歷史」對應日期區域**
|
||||
- [ ] 移動時**必須保留所有解決詳情和連結**
|
||||
|
||||
#### 報告建立操作前檢查
|
||||
- [ ] 是否需要建立報告？如是，**必須使用** `./dl report analysis "主題"`
|
||||
- [ ] **使用系統工具建立報告** (`./dl report analysis "主題"`)
|
||||
- [ ] 報告主題描述是否具體明確？
|
||||
|
||||
#### 專案管理操作前檢查 (新增 2025-09-08)
|
||||
- [ ] 專案任務是否需要更新狀態？
|
||||
- [ ] 任務類型是否正確識別（FE/BE/AI/MB/DOC/ENV/TEST）？
|
||||
- [ ] 是否需要建議下一步行動？
|
||||
|
||||
#### 檔案操作前檢查
|
||||
- [ ] 檔案編碼是否設定為 UTF-8？
|
||||
- [ ] 中文內容是否正確顯示？
|
||||
- [ ] 是否使用正確的當前日期（2025-09-09）？
|
||||
- [ ] **文檔更新是否需要加入時間戳記？**
|
||||
|
||||
#### 文檔更新時間戳記要求
|
||||
**🕐 強制性日期標記原則**：
|
||||
- [ ] 任何文檔內容更新都**必須**加入時間戳記
|
||||
- [ ] 格式：`(2025-09-09)` 或 `✅ (2025-09-09)` 或 `📊 **更新**: (2025-09-09)`
|
||||
- [ ] 位置：緊接在更新內容後面
|
||||
- [ ] 檢查清單項目標記：`- [x] 項目名稱 ✅ (2025-09-09)`
|
||||
- [ ] 進度狀態更新：`**狀態**: 已完成 (2025-09-09)`
|
||||
- [ ] 新增章節：在章節標題或首行加入 `(新增 2025-09-09)`
|
||||
### 文檔更新時間戳記要求
|
||||
- 格式：`(當前日期)` 或 `✅ (當前日期)`
|
||||
- 位置：緊接在更新內容後面
|
||||
- 檢查清單項目：`- [x] 項目名稱 ✅ (當前日期)`
|
||||
- 進度狀態更新：`**狀態**: 已完成 (當前日期)`
|
||||
|
||||
### 每次任務完成後檢查
|
||||
- [ ] 是否使用了正確的系統工具？
|
||||
- [ ] 所有日期是否正確（2025-09-09）？
|
||||
- [ ] 任務狀態是否已更新為完成 ✅ (專案任務)
|
||||
- [ ] 任務狀態是否已更新為完成 ✅
|
||||
- [ ] 發現的問題是否已記錄？
|
||||
- [ ] 報告是否已正確整合到問題系統？
|
||||
- [ ] 檔案命名是否符合系統標準？
|
||||
- [ ] **ISSUES.md中完成的項目是否已正確移動到歷史區域？**
|
||||
- [ ] **完成的項目是否已正確移動到歷史區域？**
|
||||
- [ ] **所有文檔更新是否都加入了時間戳記？**
|
||||
|
||||
## 📝 任務完成後的檢查清單 (整合 2025-09-08)
|
||||
## 🚨 緊急情況處理
|
||||
|
||||
每次 Claude 完成任務後，請檢查：
|
||||
### 工具故障時
|
||||
1. 記錄工具故障情況到統一任務管理系統
|
||||
2. 使用手動方式完成緊急任務
|
||||
3. 修正工具後重新使用標準流程
|
||||
4. 檢查並修正手動操作造成的不一致
|
||||
|
||||
- [ ] Claude 有沒有提到任何「不確定」、「需要澄清」的地方？
|
||||
- [ ] 有沒有發現文檔間的衝突？
|
||||
- [ ] 有沒有提到技術實作的困難？
|
||||
- [ ] 有沒有建議需要進一步決策的事項？
|
||||
### 系統不一致時
|
||||
1. 立即停止當前工作
|
||||
2. 運行 `./sop/scripts/maintenance_manager.sh consistency`
|
||||
3. 記錄發現的不一致問題
|
||||
4. 修正問題後繼續工作
|
||||
|
||||
**如果有，就提醒：** "把剛才提到的問題記錄到問題系統"
|
||||
## 🔔 協作通知規範
|
||||
|
||||
### 任務完成通知
|
||||
- 完成任何工作後：**必須** `say "I'm done"`
|
||||
|
||||
### 求助通知
|
||||
- 無法自動繼續工作時：**必須** `say "help"`
|
||||
|
||||
#### 強制觸發情況
|
||||
1. **系統確認對話** - `Do you want to proceed?` / 文件覆寫 / Git操作確認
|
||||
2. **主動詢問執行** - 包含「要我...嗎？」「需要我...嗎？」的疑問句
|
||||
3. **技術阻擋/決策** - 命令失敗/多選項/衝突需裁決/無法繼續
|
||||
|
||||
**判斷標準**：主動詢問執行操作 = 先 `say "help"`
|
||||
|
||||
## 🎯 協作流程範例
|
||||
|
||||
### 範例1：專案任務執行 (新增 2025-09-08)
|
||||
### 範例1：專案任務執行
|
||||
```
|
||||
用戶: "請執行 Flutter移動端配置調整"
|
||||
Claude: 識別為 MB 類型任務，更新狀態為進行中...
|
||||
[執行配置調整]
|
||||
✅ 任務完成，狀態已更新 (2025-09-09)
|
||||
✅ 任務完成，狀態已更新
|
||||
```
|
||||
|
||||
### 範例2：統一任務管理 (更新 2025-09-09)
|
||||
### 範例2：統一任務管理
|
||||
```
|
||||
用戶: "我想加入社交功能讓用戶互相挑戰，遇到問題就記錄"
|
||||
Claude: 這個功能需要以下幾個部分...
|
||||
[討論功能細節]
|
||||
我已經將以下任務記錄到統一任務管理系統：
|
||||
Claude: [討論功能細節]
|
||||
我已經將任務記錄到統一任務管理系統：
|
||||
- 🎨 FE 社交挑戰UI設計 (預估4-6小時)
|
||||
- ⚙️ BE 挑戰系統API開發 (預估8-12小時)
|
||||
- 📚 DOC 社交功能規格文檔 (預估2-3小時)
|
||||
你可以在 TASK_MANAGEMENT.md 查看詳細內容並安排執行時間
|
||||
你可以在 TASKS.md 查看詳細內容並安排執行時間
|
||||
```
|
||||
|
||||
### 範例3：問題發現和記錄 (更新 2025-09-09)
|
||||
### 範例3：問題發現和記錄
|
||||
```
|
||||
用戶: "檢查API文檔一致性"
|
||||
Claude: 我發現用戶管理API和認證API的錯誤碼定義衝突...
|
||||
|
|
@ -420,45 +311,22 @@ Claude: 我發現用戶管理API和認證API的錯誤碼定義衝突...
|
|||
這是重要任務，建議本週內處理
|
||||
```
|
||||
|
||||
## 🚨 緊急情況處理
|
||||
## 💡 讓協作更順暢的技巧
|
||||
|
||||
### 工具故障時
|
||||
1. 記錄工具故障情況到 ISSUES.md
|
||||
2. 使用手動方式完成緊急任務
|
||||
3. 修正工具後重新使用標準流程
|
||||
4. 檢查並修正手動操作造成的不一致
|
||||
|
||||
### 系統不一致時
|
||||
1. 立即停止當前工作
|
||||
2. 運行 `./check_consistency.sh`
|
||||
3. 記錄發現的不一致問題
|
||||
4. 修正問題後繼續工作
|
||||
|
||||
## 💡 讓協作更順暢的技巧 (整合 2025-09-08)
|
||||
|
||||
### 🏷️ 在任務開始時就說明：
|
||||
### 任務開始時說明
|
||||
"我希望你把發現的所有問題都記錄下來，這樣我們就不會遺漏任何需要解決的事項。"
|
||||
|
||||
### 🔄 定期檢查：
|
||||
### 定期檢查
|
||||
每週問 Claude："最近有沒有發現什麼新的問題需要記錄？"
|
||||
|
||||
### 📊 任務總結：
|
||||
### 任務總結
|
||||
"總結一下這次任務中發現的問題，並確保都記錄了。"
|
||||
|
||||
## 📚 相關文檔
|
||||
|
||||
- [統一任務管理](./TASK_MANAGEMENT.md) - 主要工作管理系統
|
||||
- [問題追蹤參考](./ISSUES.md) - 歷史問題記錄和流程說明
|
||||
- [專案狀態總覽](./PROJECTS.md) - 專案統計和里程碑追蹤
|
||||
- [工具使用說明](./sop/tools/) - 開發和維護工具
|
||||
- [歷史報告歸檔](./sop/archive/2025-09-09/225944_reports_archive/) - 過往分析和決策報告
|
||||
- [檢查腳本](./sop/scripts/) - 系統維護和檔案管理腳本
|
||||
|
||||
## 🔄 持續改善
|
||||
|
||||
### 發現新問題時 (更新 2025-09-09)
|
||||
1. 立即記錄到 TASK_MANAGEMENT.md (主要)
|
||||
2. 如需歷史追蹤，同步更新 ISSUES.md
|
||||
### 發現新問題時
|
||||
1. 立即記錄到 TASKS.md (主要)
|
||||
2. 如需歷史追蹤，記錄到歸檔系統
|
||||
3. 評估是否需要新工具或流程
|
||||
4. 更新本指南文檔
|
||||
5. 通知相關團隊成員
|
||||
|
|
@ -469,9 +337,8 @@ Claude: 我發現用戶管理API和認證API的錯誤碼定義衝突...
|
|||
3. 修訂本指南文檔
|
||||
4. 確保向下相容性
|
||||
|
||||
## 🤝 標準化指令格式
|
||||
## 🤝 推薦指令格式
|
||||
|
||||
### 推薦指令格式
|
||||
```
|
||||
[任務描述] + 請遵循SOP + [具體SOP要點提醒]
|
||||
```
|
||||
|
|
@ -479,18 +346,23 @@ Claude: 我發現用戶管理API和認證API的錯誤碼定義衝突...
|
|||
### 範例指令
|
||||
```
|
||||
請分析UI設計問題，遵循SOP，記得使用./dl report analysis建立報告
|
||||
請處理緊急問題，遵循SOP，完成後問題要移到歷史區域不可標記[x]
|
||||
請建立新的API文檔，遵循SOP，使用正確日期和UTF-8編碼
|
||||
執行 Android Studio 安裝和配置，遇到問題就記錄
|
||||
```
|
||||
|
||||
## 📚 相關文檔
|
||||
|
||||
- [統一任務管理](../TASKS.md) - 主要工作管理系統
|
||||
- [問題追蹤歷史](../archive/) - 歷史問題記錄參考
|
||||
- [工具使用說明](../tools/) - 開發和維護工具
|
||||
- [檢查腳本](../scripts/) - 系統維護和檔案管理腳本
|
||||
|
||||
## 🎉 效益
|
||||
|
||||
✅ **不會遺漏問題** - 所有發現的問題都被記錄
|
||||
✅ **追蹤更完整** - 包含 AI 協助時發現的問題
|
||||
✅ **決策有依據** - 問題記錄成為決策參考
|
||||
✅ **開發更順暢** - 提前發現潛在問題
|
||||
✅ **專案管理清晰** - 階段化執行，進度透明 (新增 2025-09-08)
|
||||
✅ **專案管理清晰** - 階段化執行，進度透明
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -500,51 +372,6 @@ Claude: 我發現用戶管理API和認證API的錯誤碼定義衝突...
|
|||
|
||||
---
|
||||
|
||||
## 🔔 協作通知規範 (新增 2025-09-09)
|
||||
|
||||
### 📢 任務完成通知
|
||||
- **完成任務後**: 必須使用 `say "I'm done"` 通知用戶
|
||||
- **適用情境**: 任何任務、分析、實作、整合工作完成後
|
||||
- **重要性**: 讓用戶知道可以查看結果或繼續下一步
|
||||
|
||||
### 🆘 求助通知
|
||||
- **核心原則**: 任何停止工作的情況，都必須立即使用 `say "help"` 通知用戶
|
||||
- **判斷標準**: "如果我現在不能自動繼續工作到完成，就必須 `say 'help'`"
|
||||
|
||||
#### 🚨 強制觸發情況（更新 2025-09-09）
|
||||
|
||||
**1. 系統權限請求**
|
||||
- 任何 `Do you want to proceed?` 對話框
|
||||
- 需要用戶確認的系統提示
|
||||
- 文件覆寫確認
|
||||
- 命令執行權限請求
|
||||
|
||||
**2. 技術阻擋情況**
|
||||
- 文件不存在但需要用戶指定路徑
|
||||
- 命令執行失敗需要用戶決策
|
||||
- 多個選項需要用戶選擇
|
||||
- 系統錯誤需要用戶介入
|
||||
|
||||
**3. 決策需求情況**
|
||||
- 不確定要執行哪個選項
|
||||
- 需要用戶確認方向或方法
|
||||
- 發現衝突需要用戶裁決
|
||||
- 任何「應該如何處理」的疑問
|
||||
|
||||
**4. 工作流程中斷**
|
||||
- 無法自動繼續下一步
|
||||
- 需要等待用戶輸入或回應
|
||||
- 遇到預期外的情況
|
||||
|
||||
#### 📋 執行方式
|
||||
```
|
||||
任何停頓 → 立即 say "help" → 說明需要什麼 → 等待回應
|
||||
```
|
||||
|
||||
**重要**: 這些通知習慣對協作體驗很重要，每次對話都必須遵循
|
||||
|
||||
---
|
||||
|
||||
**最後更新**: 2025-09-09
|
||||
**版本**: 3.2 - 修正結構性問題和三層架構整合 (2025-09-09)
|
||||
**最後更新**: 系統自動管理
|
||||
**版本**: 4.0 - 品質改善重構：消除重複內容、簡化冗句、修正過時資訊
|
||||
**維護者**: Drama Ling 開發團隊
|
||||
|
|
@ -0,0 +1,94 @@
|
|||
# CLAUDE.md 文件品質改善分析
|
||||
|
||||
## 📊 分析概要
|
||||
- **分析日期**: 2025-09-09
|
||||
- **分析目標**: 識別 CLAUDE.md 文件中的過時內容、重複資訊和冗句問題
|
||||
- **分析範圍**: /Users/jettcheng1018/code/dramaling-app/sop/docs/CLAUDE.md (536行)
|
||||
|
||||
## 🎯 主要發現
|
||||
|
||||
### 1. 🔥 高優先級問題
|
||||
|
||||
#### 過時內容 (Outdated Content)
|
||||
- **硬編碼日期問題**: 第206、360、366行包含固定的 "2025-09-09"，每日都會過時
|
||||
- **時間戳記範例**: 第400、420行的範例使用固定日期
|
||||
- **建議**: 使用動態日期參考或通用格式 "(YYYY-MM-DD)"
|
||||
|
||||
#### 重複內容 (Duplicate Content)
|
||||
- **任務管理原則**: 第46-70行與第170-175行重複說明任務分類和狀態管理
|
||||
- **日期管理**: 第204-207、287-289、360-361行多處重複日期準確性原則
|
||||
- **建議**: 整併為單一權威章節
|
||||
|
||||
### 2. ⚠️ 中等優先級問題
|
||||
|
||||
#### 冗句問題 (Redundant Sentences)
|
||||
- **提醒範例過於冗長**: 第178-202行有25行類似的提醒用語範例
|
||||
- **檢查清單過度詳細**: 第338-381行的檢查清單項目重疊過多
|
||||
- **建議**: 將提醒範例減少60%，只保留3-5個最有效的範例
|
||||
|
||||
#### 結構組織問題
|
||||
- **文件過長**: 536行對實際參考來說過於冗長
|
||||
- **格式不一致**: 部分章節使用項目符號，其他使用編號清單
|
||||
- **建議**: 考慮拆分為快速參考指南和詳細SOP手冊
|
||||
|
||||
### 3. 📝 一般問題
|
||||
|
||||
#### 語言一致性
|
||||
- **混合格式**: 某些章節格式標準化不一致
|
||||
- **內部連結**: 第449-457行的參考連結需要驗證是否有效
|
||||
|
||||
## 📋 具體改善建議
|
||||
|
||||
### 立即行動 (高優先級)
|
||||
1. **移除所有硬編碼日期**，使用動態參考
|
||||
2. **整併重複任務管理內容**至單一章節
|
||||
3. **簡化提醒範例章節**，減少60%內容
|
||||
4. **合併重疊的檔案組織原則**
|
||||
|
||||
### 次要行動 (中等優先級)
|
||||
1. **整併錯誤預防章節**
|
||||
2. **簡化檢查清單**至必要項目
|
||||
3. **統一格式標準**
|
||||
4. **驗證並更新所有內部參考**
|
||||
|
||||
### 長期改善
|
||||
1. **文件分割建議**:
|
||||
- 快速參考指南 (核心程序)
|
||||
- 詳細SOP手冊 (完整指南)
|
||||
- 範例與模板 (獨立參考)
|
||||
|
||||
## 🎯 改善效益預估
|
||||
|
||||
- **文件長度減少**: 預計可減少25-30%的內容
|
||||
- **提升可讀性**: 消除重複內容，提高查找效率
|
||||
- **維護便利性**: 動態日期參考減少日常維護工作
|
||||
- **使用體驗**: 簡化結構提升實際使用便利性
|
||||
|
||||
## 📈 具體改善指標
|
||||
|
||||
### 內容優化
|
||||
- **冗句消除**: 識別約15-20個需改善區域
|
||||
- **重複消除**: 整併4個主要重複章節
|
||||
- **過時內容**: 修正6個硬編碼日期問題
|
||||
|
||||
### 結構優化
|
||||
- **格式統一**: 標準化所有章節格式
|
||||
- **分段合理**: 重新組織相關內容分組
|
||||
- **參考有效**: 驗證所有內部連結
|
||||
|
||||
## 🔧 實施建議
|
||||
|
||||
### 階段性執行
|
||||
1. **第一階段**: 修正高優先級問題 (硬編碼日期、主要重複)
|
||||
2. **第二階段**: 簡化冗長章節 (提醒範例、檢查清單)
|
||||
3. **第三階段**: 格式統一和結構優化
|
||||
|
||||
### 品質保證
|
||||
- 修改後執行內容一致性檢查
|
||||
- 驗證所有工具指令仍然有效
|
||||
- 確認文件邏輯流程完整
|
||||
|
||||
---
|
||||
**📊 分析完成**: 2025-09-09
|
||||
**🔄 狀態**: ✅ 已完成分析，待執行改善
|
||||
**📋 下一步**: 根據優先級逐步執行改善建議
|
||||
Loading…
Reference in New Issue