Initial commit
This commit is contained in:
Zhongwei Li
158
commands/analyze-dependencies.md
Normal file
158
commands/analyze-dependencies.md
Normal file
@@ -0,0 +1,158 @@
|
||||
## 依賴關系分析
|
||||
|
||||
分析項目的依賴關系，評估架構的健康狀况。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/dependency-analysis [選項]
|
||||
```
|
||||
|
||||
### 選項
|
||||
|
||||
- `--visual` : 可視化顯示依賴關系
|
||||
- `--circular` : 仅檢測循環依賴
|
||||
- `--depth <數值>` : 指定分析深度 (默認: 3)
|
||||
- `--focus <路徑>` : 聚焦于特定模塊/目錄
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 整個項目的依賴關系分析
|
||||
/dependency-analysis
|
||||
|
||||
# 檢測循環依賴
|
||||
/dependency-analysis --circular
|
||||
|
||||
# 特定模塊的詳细分析
|
||||
/dependency-analysis --focus src/core --depth 5
|
||||
```
|
||||
|
||||
### 分析項目
|
||||
|
||||
#### 1. 依賴關系矩阵
|
||||
|
||||
數值化顯示模塊間的依賴關系：
|
||||
|
||||
- 直接依賴
|
||||
- 間接依賴
|
||||
- 依賴深度
|
||||
- 扇入/扇出
|
||||
|
||||
#### 2. 架構违規檢測
|
||||
|
||||
- 層級违規 (下層依賴上層)
|
||||
- 循環依賴
|
||||
- 過度耦合 (高依賴度)
|
||||
- 孤立模塊
|
||||
|
||||
#### 3. Clean Architecture 合規性檢查
|
||||
|
||||
- 領域層的独立性
|
||||
- 基礎設施層的適当分離
|
||||
- 用例層的依賴方向
|
||||
- 接口的應用情况
|
||||
|
||||
### 輸出示例
|
||||
|
||||
```text
|
||||
依賴關系分析報告
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📊 指標概覽
|
||||
├─ 模塊總數: 42
|
||||
├─ 平均依賴數: 3.2
|
||||
├─ 最大依賴深度: 5
|
||||
└─ 循環依賴: 檢測到 2 個
|
||||
|
||||
⚠️ 架構违規
|
||||
├─ [HIGH] src/domain/user.js → src/infra/database.js
|
||||
│ └─ 領域層直接依賴基礎設施層
|
||||
├─ [MED] src/api/auth.js ⟲ src/services/user.js
|
||||
│ └─ 檢測到循環依賴
|
||||
└─ [LOW] src/utils/helper.js → 12 modules
|
||||
└─ 扇出過度
|
||||
|
||||
✅ 建議操作
|
||||
1. 引入 UserRepository 接口
|
||||
2. 重新設計認證服務的职責
|
||||
3. 按功能拆分辅助函數
|
||||
|
||||
📈 依賴關系圖
|
||||
[用 ASCII 艺術顯示可視化依賴關系圖]
|
||||
```
|
||||
|
||||
### 高級用法
|
||||
|
||||
```bash
|
||||
# CI/CD 管道中的自動檢查
|
||||
/dependency-analysis --circular --fail-on-violation
|
||||
|
||||
# 定義和驗證架構規則
|
||||
/dependency-analysis --rules .architecture-rules.yml
|
||||
|
||||
# 追蹤依賴關系的時間變化
|
||||
/dependency-analysis --compare HEAD~10
|
||||
```
|
||||
|
||||
### 配置文件示例 (.dependency-analysis.yml)
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: "Domain Independence"
|
||||
source: "src/domain/**"
|
||||
forbidden: ["src/infra/**", "src/api/**"]
|
||||
|
||||
- name: "API Layer Dependencies"
|
||||
source: "src/api/**"
|
||||
allowed: ["src/domain/**", "src/application/**"]
|
||||
forbidden: ["src/infra/**"]
|
||||
|
||||
thresholds:
|
||||
max_dependencies: 8
|
||||
max_depth: 4
|
||||
coupling_threshold: 0.7
|
||||
|
||||
ignore:
|
||||
- "**/test/**"
|
||||
- "**/mocks/**"
|
||||
```
|
||||
|
||||
### 集成工具
|
||||
|
||||
- `madge` : JavaScript/TypeScript 依賴關系可視化
|
||||
- `dep-cruiser` : 依賴關系規則驗證
|
||||
- `nx` : 單體倉庫依賴關系管理
|
||||
- `plato` : 復杂度與依賴關系综合分析
|
||||
|
||||
### 與 Claude 的協作
|
||||
|
||||
```bash
|
||||
# 包含 package.json 的分析
|
||||
cat package.json
|
||||
/analyze-dependencies
|
||||
"分析這個項目的依賴關系問題"
|
||||
|
||||
# 結合特定模塊的源代碼
|
||||
ls -la src/core/
|
||||
/analyze-dependencies --focus src/core
|
||||
"詳细評估核心模塊的依賴關系"
|
||||
|
||||
# 與架構文檔對比
|
||||
cat docs/architecture.md
|
||||
/analyze-dependencies --visual
|
||||
"確認設計文檔與實現的差異"
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
- **前提條件**: 需要在項目根目錄執行
|
||||
- **限制事項**: 大型項目的分析可能需要较长時間
|
||||
- **建議事項**: 發現循環依賴時應立即考虑處理
|
||||
|
||||
### 最佳實践
|
||||
|
||||
1. **定期分析**: 每週檢查依賴關系的健康狀况
|
||||
2. **規則明文化**: 通過配置文件管理架構規則
|
||||
3. **渐進式改進**: 避免大規模重構，逐步改進
|
||||
4. **指標追蹤**: 監控依賴關系復杂度的時間序列
|
||||
168
commands/analyze-performance.md
Normal file
168
commands/analyze-performance.md
Normal file
@@ -0,0 +1,168 @@
|
||||
## Analyze Performance
|
||||
|
||||
從使用者體驗的角度分析應用程式效能，並量化透過最佳化實現的感知速度提升。基於 Core Web Vitals 計算 UX 分數，並提出有優先序的最佳化策略。
|
||||
|
||||
### UX 效能分數
|
||||
|
||||
```text
|
||||
使用者體驗分數：B+ (78/100)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
⏱️ Core Web Vitals
|
||||
├─ LCP (載入)：2.3 秒 [良好] 目標<2.5 秒 ✅
|
||||
├─ FID (回應)：95ms [良好] 目標<100ms ✅
|
||||
├─ CLS (視覺穩定)：0.08 [良好] 目標<0.1 ✅
|
||||
├─ FCP (首次繪製)：1.8 秒 [良好] 目標<1.8 秒 ✅
|
||||
├─ TTFB (伺服器)：450ms [需要改善] 目標<200ms ⚠️
|
||||
└─ TTI (可互動)：3.5 秒 [需要改善] 目標<3.8 秒 ⚠️
|
||||
|
||||
📊 使用者感知速度
|
||||
├─ 初始顯示：2.3 秒 [業界平均：3.0 秒]
|
||||
├─ 頁面切換：1.1 秒 [業界平均：1.5 秒]
|
||||
├─ 搜尋結果顯示：0.8 秒 [業界平均：1.2 秒]
|
||||
├─ 表單提交：1.5 秒 [業界平均：2.0 秒]
|
||||
└─ 圖片載入：已實作延遲載入 ✅
|
||||
|
||||
😊 使用者滿意度預測
|
||||
├─ 跳出率預測：12%(業界平均：20%)
|
||||
├─ 完成率預測：78%(目標：85%)
|
||||
├─ 推薦 NPS：+24(業界平均：+15)
|
||||
└─ 回訪率：65%(目標：70%)
|
||||
|
||||
📊 對使用者體驗的影響
|
||||
├─ 縮短顯示時間 0.5 秒 → 跳出率 -7%
|
||||
├─ 降低跳出率 5% → 工作階段長度 +15%
|
||||
├─ 改善搜尋 → 停留時間 +15%
|
||||
└─ 整體 UX 改善度：+25%
|
||||
|
||||
🎯 預期改善效果 (優先序排序)
|
||||
├─ [P0] TTFB 改善 (導入 CDN)→ LCP -0.3 秒 = 感知速度 +15%
|
||||
├─ [P1] JS 套件最佳化 → TTI -0.8 秒 = 互動時間 -20%
|
||||
├─ [P2] 圖片最佳化 (WebP)→ 傳輸量 -40% = 載入時間 -25%
|
||||
└─ [P3] 快取策略 → 重複訪問時快 50%
|
||||
```
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# UX 分數的綜合分析
|
||||
find . -name "*.js" -o -name "*.ts" | xargs wc -l | sort -rn | head -10
|
||||
「計算 UX 效能分數並評估 Core Web Vitals」
|
||||
|
||||
# 效能瓶頸檢測
|
||||
grep -r "for.*await\|forEach.*await" . --include="*.js"
|
||||
「檢測非同步處理的瓶頸並分析對使用者感受的影響」
|
||||
|
||||
# 對使用者體驗的影響分析
|
||||
grep -r "addEventListener\|setInterval" . --include="*.js" | grep -v "removeEventListener\|clearInterval"
|
||||
「分析效能問題對使用者體驗的影響」
|
||||
```
|
||||
|
||||
### 基本範例
|
||||
|
||||
```bash
|
||||
# 套件大小與載入時間
|
||||
npm ls --depth=0 && find ./public -name "*.js" -o -name "*.css" | xargs ls -lh
|
||||
"識別套件大小與資源最佳化的改善點"
|
||||
|
||||
# 資料庫效能
|
||||
grep -r "SELECT\|findAll\|query" . --include="*.js" | head -20
|
||||
"分析資料庫查詢的最佳化點"
|
||||
|
||||
# 相依性的效能影響
|
||||
npm outdated && npm audit
|
||||
"評估舊版相依性對效能的影響"
|
||||
```
|
||||
|
||||
### 分析觀點
|
||||
|
||||
#### 1. 程式碼層級問題
|
||||
|
||||
- **O(n²) 演算法**：檢測低效的陣列操作
|
||||
- **同步 I/O**：識別阻塞處理
|
||||
- **重複處理**：刪除不必要的計算和請求
|
||||
- **記憶體洩漏**：管理事件監聽器和計時器
|
||||
|
||||
#### 2. 架構層級問題
|
||||
|
||||
- **N+1 查詢**：資料庫存取模式
|
||||
- **缺乏快取**：重複計算和 API 呼叫
|
||||
- **套件大小**：不必要的程式庫和程式碼分割
|
||||
- **資源管理**：連線池和執行緒使用量
|
||||
|
||||
#### 3. 技術債務的影響
|
||||
|
||||
- **遺留程式碼**：舊實作導致的效能劣化
|
||||
- **設計問題**：責任分散不足導致的高耦合度
|
||||
- **測試不足**：效能回歸檢測的遺漏
|
||||
- **監控不足**：問題早期發現體制
|
||||
|
||||
### 效能改善 ROI 矩陣
|
||||
|
||||
```text
|
||||
改善 ROI = (時間縮短效果 + 品質提升)÷ 實作工時
|
||||
```
|
||||
|
||||
| 優先度 | 使用者體驗提升 | 實作難度 | 時間縮短效果 | 具體例子 | 工時 | 效果 |
|
||||
| --------------------- | -------------- | -------- | ------------ | ---------- | ---- | --------- |
|
||||
| **[P0] 立即實作** | 高 | 低 | > 50% | 導入 CDN | 8h | 回應 -60% |
|
||||
| **[P1] 早期實作建議** | 高 | 中 | 20-50% | 圖片最佳化 | 16h | 載入 -30% |
|
||||
| **[P2] 計劃性實作** | 低 | 高 | 10-20% | 程式碼分割 | 40h | 初始 -15% |
|
||||
| **[P3] 保留/觀察** | 低 | 低 | < 10% | 微調最佳化 | 20h | 部分 -5% |
|
||||
|
||||
#### 優先度判定標準
|
||||
|
||||
- **P0(立即實作)**：UX 提升「高」× 難度「低」= ROI 最大
|
||||
- **P1(早期實作)**：UX 提升「高」× 難度「中」= ROI 高
|
||||
- **P2(計劃性)**：UX 提升「低」× 難度「高」= ROI 中
|
||||
- **P3(保留)**：UX 提升「低」× 難度「低」= ROI 低
|
||||
|
||||
### 效能指標與 UX 改善相關性
|
||||
|
||||
| 指標 | 改善幅度 | 感知速度提升 | 使用者滿意度 | 實作工時 |
|
||||
| ----------------- | -------- | ------------ | ------------- | -------- |
|
||||
| **LCP(載入)** | -0.5 秒 | +30% | 跳出率 -7% | 16h |
|
||||
| **FID(回應)** | -50ms | +15% | 壓力 -20% | 8h |
|
||||
| **CLS(視覺穩定)** | -0.05 | +10% | 誤操作 -50% | 4h |
|
||||
| **TTFB(伺服器)** | -200ms | +25% | 感知速度 +40% | 24h |
|
||||
| **TTI(可互動)** | -1.0 秒 | +35% | 完成率 +15% | 32h |
|
||||
| **套件大小** | -30% | +20% | 首次訪問 +25% | 16h |
|
||||
|
||||
### 測量與工具
|
||||
|
||||
#### Node.js / JavaScript
|
||||
|
||||
```bash
|
||||
# 效能分析
|
||||
node --prof app.js
|
||||
clinic doctor -- node app.js
|
||||
|
||||
# 套件分析
|
||||
npx webpack-bundle-analyzer
|
||||
lighthouse --chrome-flags="--headless"
|
||||
```
|
||||
|
||||
#### 資料庫
|
||||
|
||||
```sql
|
||||
-- 查詢分析
|
||||
EXPLAIN ANALYZE SELECT ...
|
||||
SHOW SLOW LOG;
|
||||
```
|
||||
|
||||
#### 前端
|
||||
|
||||
```bash
|
||||
# React 效能
|
||||
grep -r "useMemo\|useCallback" . --include="*.jsx"
|
||||
|
||||
# 資源分析
|
||||
find ./src -name "*.png" -o -name "*.jpg" | xargs ls -lh
|
||||
```
|
||||
|
||||
### 持續改善
|
||||
|
||||
- **定期稽核**：執行週期性效能測試
|
||||
- **指標收集**：追蹤回應時間、記憶體使用量
|
||||
- **警報設定**：超過閾值時自動通知
|
||||
- **團隊共享**：記錄改善案例和反模式
|
||||
104
commands/check-fact.md
Normal file
104
commands/check-fact.md
Normal file
@@ -0,0 +1,104 @@
|
||||
## 事實檢查
|
||||
|
||||
參考項目內的代碼庫、文檔 (docs/、README.md 等)，確認所給資訊的正確性。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 基本用法
|
||||
/check-fact "Flutter 應用使用了 Riverpod"
|
||||
|
||||
# 一次性確認多個資訊
|
||||
/check-fact "這個項目使用 GraphQL，並通過 auto_route 管理路由"
|
||||
|
||||
# 確認特定技術規範
|
||||
/check-fact "使用 JWT 進行身份驗證，未使用 Firebase Auth"
|
||||
```
|
||||
|
||||
### 確認流程
|
||||
|
||||
1. **資訊源優先級**
|
||||
- 代碼庫 (最可靠)
|
||||
- README.md、docs/ 內文檔
|
||||
- package.json、pubspec.yaml 等配置文件
|
||||
- Issue、Pull Request 的讨論歷史
|
||||
|
||||
2. **判定結果分類**
|
||||
- `✅ 正確` - 資訊與代碼庫完全一致
|
||||
- `❌ 錯誤` - 資訊明顯錯誤
|
||||
- `⚠️ 部分正確` - 部分準確但不完整
|
||||
- `❓ 無法判斷` - 缺少必要的確認資訊
|
||||
|
||||
3. **依據明示**
|
||||
- 相關文件名和行号
|
||||
- 相關代碼片段
|
||||
- 文檔相關部分
|
||||
|
||||
### 報告格式
|
||||
|
||||
```text
|
||||
## 事實檢查結果
|
||||
|
||||
### 檢驗對象
|
||||
「[用戶提供的資訊]」
|
||||
|
||||
### 結論
|
||||
[✅/❌/⚠️/❓] [判定結果]
|
||||
|
||||
### 依據
|
||||
- **文件**: `path/to/file.dart:123`
|
||||
- **內容**: [相關代碼/文本]
|
||||
- **補充**: [额外說明]
|
||||
|
||||
### 詳细說明
|
||||
[如果錯誤，提供正確資訊]
|
||||
[如果部分正確，指出不準確的部分]
|
||||
[如果無法判斷，說明缺少的資訊]
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 項目技術棧確認
|
||||
/check-fact "這個應用是 Flutter + Riverpod + GraphQL 的架構"
|
||||
|
||||
# 實現狀况確認
|
||||
/check-fact "已實現暗黑模式功能，可從用戶設置切換"
|
||||
|
||||
# 架構確認
|
||||
/check-fact "狀態管理全部使用 Riverpod，未使用 BLoC"
|
||||
|
||||
# 安全實現確認
|
||||
/check-fact "認證令牌已加密存儲在 secure storage 中"
|
||||
```
|
||||
|
||||
### 與 Claude 的協作
|
||||
|
||||
```bash
|
||||
# 分析整個代碼庫後進行確認
|
||||
ls -la && find . -name "pubspec.yaml" -exec cat {} \;
|
||||
/check-fact "這個項目使用的主要依賴有..."
|
||||
|
||||
# 確認特定功能的實現狀况
|
||||
grep -r "authentication" . --include="*.dart"
|
||||
/check-fact "認證功能為自定義實現，未使用第三方認證"
|
||||
|
||||
# 確認與文檔的一致性
|
||||
cat README.md
|
||||
/check-fact "README 中記載的功能都已實現"
|
||||
```
|
||||
|
||||
### 應用場景
|
||||
|
||||
- 技術規格書編寫時: 確認內容準確性
|
||||
- 項目交接時: 確認對現有實現的理解
|
||||
- 客戶報告前: 確認實現狀况
|
||||
- 技術博客撰寫時: 驗證文章內容準確性
|
||||
- 面試·說明資料制作時: 確認項目概要準確性
|
||||
|
||||
### 注意事項
|
||||
|
||||
- 代碼庫是最可靠的資訊源
|
||||
- 如果文檔過時，以實現為準
|
||||
- 缺少判斷所需資訊時，坦诚回答"無法判斷"
|
||||
- 對涉及安全的資訊要特別谨慎驗證
|
||||
53
commands/check-github-ci.md
Normal file
53
commands/check-github-ci.md
Normal file
@@ -0,0 +1,53 @@
|
||||
## GitHub CI 監控
|
||||
|
||||
監控 GitHub Actions CI 狀態，並跟蹤到完成。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 檢查 CI 狀態
|
||||
gh pr checks
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# PR 創建後的 CI 確認
|
||||
gh pr create --title "新功能添加" --body "說明"
|
||||
gh pr checks
|
||||
```
|
||||
|
||||
### 與 Claude 的協作
|
||||
|
||||
```bash
|
||||
# CI 確認到修復的流程
|
||||
gh pr checks
|
||||
"分析 CI 檢查結果，如有失败項目請提出修復方案"
|
||||
|
||||
# 修復後的再確認
|
||||
git push origin feature-branch
|
||||
gh pr checks
|
||||
"確認修復後的 CI 結果，確保没有問題"
|
||||
```
|
||||
|
||||
### 執行結果示例
|
||||
|
||||
```text
|
||||
All checks were successful
|
||||
0 cancelled, 0 failing, 8 successful, 3 skipped, and 0 pending checks
|
||||
|
||||
NAME DESCRIPTION ELAPSED URL
|
||||
○ Build/test (pull_request) 5m20s https://github.com/user/repo/actions/runs/123456789
|
||||
○ Build/lint (pull_request) 2m15s https://github.com/user/repo/actions/runs/123456789
|
||||
○ Security/scan (pull_request) 1m30s https://github.com/user/repo/actions/runs/123456789
|
||||
○ Type Check (pull_request) 45s https://github.com/user/repo/actions/runs/123456789
|
||||
○ Commit Messages (pull_request) 12s https://github.com/user/repo/actions/runs/123456789
|
||||
- Deploy Preview (pull_request) https://github.com/user/repo/actions/runs/123456789
|
||||
- Visual Test (pull_request) https://github.com/user/repo/actions/runs/123456789
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
- 失败時需要詳细確認
|
||||
- 等待所有檢查完成後再合並
|
||||
- 必要時重新執行 `gh pr checks`
|
||||
461
commands/check-prompt.md
Normal file
461
commands/check-prompt.md
Normal file
@@ -0,0 +1,461 @@
|
||||
## 提示詞檢查
|
||||
|
||||
AI Agent 提示詞質量評估與改進的全面最佳實践集。基于實際提示詞改進過程中积累的經驗，系統化地涵蓋了消除歧義、資訊整合、強制力強化、追蹤系統、持續改進等所有重要方面。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 檢查提示詞文件的質量
|
||||
cat your-prompt.md
|
||||
/check-prompt
|
||||
"檢查這個提示詞的質量並提出改進建議"
|
||||
```
|
||||
|
||||
### 選項
|
||||
|
||||
- 無 : 分析當前文件或選中的文本
|
||||
- `--category <name>` : 仅檢查特定類別 (structure/execution/restrictions/quality/roles/improvement)
|
||||
- `--score` : 仅計算質量分數
|
||||
- `--fix` : 自動更正建議
|
||||
- `--deep` : 深度分析模式 (重點檢查歧義性、資訊分散、強制力)
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 提示詞整體質量評估
|
||||
cat devin/playbooks/code-review.md
|
||||
/check-prompt
|
||||
"從 6 個類別評估這個提示詞的質量，指出問題並提出改進方案"
|
||||
|
||||
# 深度分析模式
|
||||
/check-prompt --deep
|
||||
"重點檢查歧義性、資訊分散、強制力不足，提出根本性改進方案"
|
||||
|
||||
# 特定類別檢查
|
||||
/check-prompt --category structure
|
||||
"從結構和清晰度角度檢查這個提示詞"
|
||||
|
||||
# 模糊表達檢測與更正
|
||||
/check-prompt --fix
|
||||
"檢測模糊表達並提出明確的更正建議"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 核心設計原則
|
||||
|
||||
### 原則 1: 完全消除解釋空間
|
||||
|
||||
- **绝對禁止**: "原則上"、"推薦"、"如果可能"、"根據情况"、"酌情判斷"
|
||||
- **必须使用**: "必须"、"绝對"、"严格遵守"、"無例外"、"強制"
|
||||
- **例外條件**: 用數值严格限定 ("仅以下 3 個條件"、"除這 2 种情况外")
|
||||
|
||||
### 原則 2: 資訊的战略性整合
|
||||
|
||||
- 相關重要資訊完全整合到一個部分
|
||||
- 在執行清單中總結全貌
|
||||
- 彻底消除循環引用或分散
|
||||
|
||||
### 原則 3: 構建分級強制力
|
||||
|
||||
- 🔴 (執行停止級) → 🟡 (質量重要) → 🟢 (建議事項) 的明確層級
|
||||
- 從推薦級逐步升級到必须級
|
||||
- 明示违反時的影響程度和處理方法
|
||||
|
||||
### 原則 4: 確保可追蹤性
|
||||
|
||||
- 所有執行結果可記錄、驗證
|
||||
- 技術上防止虛假報告
|
||||
- 成功/失败的客觀判斷標準
|
||||
|
||||
### 原則 5: 反饋驅動改進
|
||||
|
||||
- 從實際失败案例中學習
|
||||
- 持續驗證有效性
|
||||
- 自動檢測新模式
|
||||
|
||||
---
|
||||
|
||||
## 📋 全面檢查項目
|
||||
|
||||
### 1. 📐 結構與清晰度 (配分: 25 分)
|
||||
|
||||
#### 1.1 指示優先級顯示 (8 分)
|
||||
|
||||
- [ ] 🔴🟡🟢 優先級標記在所有重要指示上
|
||||
- [ ] 執行停止級條件具體且明確定義
|
||||
- [ ] 各優先級判斷標準客觀且可驗證
|
||||
- [ ] 優先級層級一致應用
|
||||
|
||||
#### 1.2 完全消除模糊表達 (9 分)
|
||||
|
||||
- [ ] **致命模糊表達**: "原則上"、"推薦"、"如果可能"為 0 個
|
||||
- [ ] **強制表達使用**: 適当使用"必须"、"绝對"、"严格遵守"、"無例外"
|
||||
- [ ] **例外條件數值限定**: "仅 3 個條件"等明確邊界
|
||||
- [ ] **消除判斷余地**: 仅使用不可能多重解釋的表達
|
||||
- [ ] **消灭灰色地带**: 所有情况都有明確判斷標準
|
||||
|
||||
#### 1.3 資訊的战略性整合 (8 分)
|
||||
|
||||
- [ ] 完全解決重要資訊在多處分散的問題
|
||||
- [ ] 相關指示邏輯地整合到一個部分
|
||||
- [ ] 執行清單完整總結全貌
|
||||
- [ ] 不存在循環引用或無限循環
|
||||
|
||||
### 2. 🎯 可執行性 (配分: 20 分)
|
||||
|
||||
#### 2.1 具體步骤的完整性 (7 分)
|
||||
|
||||
- [ ] 所有命令示例實際可執行且已驗證
|
||||
- [ ] 環境變量、前提條件、依賴關系完整記錄
|
||||
- [ ] 錯誤處理方法具體且可執行
|
||||
- [ ] 步骤顺序邏輯且必然
|
||||
|
||||
#### 2.2 確保可驗證性 (7 分)
|
||||
|
||||
- [ ] 執行結果的成功/失败可客觀判斷
|
||||
- [ ] 輸出示例、日誌格式、期望值具體展示
|
||||
- [ ] 測試方法、驗證步骤可實施
|
||||
- [ ] 中間結果確認點適当配置
|
||||
|
||||
#### 2.3 自動化適應性 (6 分)
|
||||
|
||||
- [ ] 易于腳本化、CI/CD 集成的格式
|
||||
- [ ] 人工判斷與 AI 執行部分明確分離
|
||||
- [ ] 支持批處理、並行執行
|
||||
|
||||
### 3. 🚫 明確禁止事項 (配分: 15 分)
|
||||
|
||||
#### 3.1 绝對禁止事項的系統化 (8 分)
|
||||
|
||||
- [ ] 完整列出不可執行的操作
|
||||
- [ ] 明示各禁止事項的违反影響度 (轻微/重大/致命)
|
||||
- [ ] 具體提示替代手段、規避方法
|
||||
- [ ] 說明禁止事項的技術依據
|
||||
|
||||
#### 3.2 严格限定例外條件 (7 分)
|
||||
|
||||
- [ ] 允许例外的條件具體且限定 (數值指定)
|
||||
- [ ] "完全重復"、"明確記載"等客觀判斷標準
|
||||
- [ ] 不留灰色地带的明確邊界
|
||||
- [ ] 明示例外適用時的新增條件、限制
|
||||
|
||||
### 4. 📊 質量保證機制 (配分: 20 分)
|
||||
|
||||
#### 4.1 追蹤系統的完整性 (8 分)
|
||||
|
||||
- [ ] 全執行結果自動記錄、統計獲取功能
|
||||
- [ ] 技術上防止虛假報告的驗證功能
|
||||
- [ ] 實時監控、告警功能
|
||||
- [ ] 審計日誌防篡改功能
|
||||
|
||||
#### 4.2 模板遵守的強制 (7 分)
|
||||
|
||||
- [ ] 必要元素的明確定義和檢查功能
|
||||
- [ ] 禁止自定義部分的技術限制
|
||||
- [ ] 自動化的遵守確認檢查點
|
||||
- [ ] 违反時的自動更正、警告功能
|
||||
|
||||
#### 4.3 錯誤處理的全面性 (5 分)
|
||||
|
||||
- [ ] 預期錯誤模式的完整目錄化
|
||||
- [ ] 錯誤時的分級處理流程
|
||||
- [ ] 技術上防止將失败報告為成功
|
||||
|
||||
### 5. 🎭 角色與責任的明確化 (配分: 10 分)
|
||||
|
||||
#### 5.1 AI Agent 的權限範圍 (5 分)
|
||||
|
||||
- [ ] 可執行操作與禁止操作的明確邊界
|
||||
- [ ] 判斷權限的具體範圍和限制
|
||||
- [ ] 需要人工確認的操作明確分離
|
||||
|
||||
#### 5.2 分類系統的統一 (5 分)
|
||||
|
||||
- [ ] 分類定義的明確性、唯一性、排他性
|
||||
- [ ] 防止分類間重要度誤解的明確說明
|
||||
- [ ] 各分類的具體使用示例和判斷流程圖
|
||||
|
||||
### 6. 🔄 持續改進 (配分: 10 分)
|
||||
|
||||
#### 6.1 反饋收集的自動化 (5 分)
|
||||
|
||||
- [ ] 從執行日誌自動提取改進點
|
||||
- [ ] 基于機器學習的失败模式分析
|
||||
- [ ] 最佳實践的自動更新機制
|
||||
|
||||
#### 6.2 學習功能的實現 (5 分)
|
||||
|
||||
- [ ] 新模式的自動檢測、分類
|
||||
- [ ] 現有規則有效性的持續監控
|
||||
- [ ] 渐進式改進的自動建議
|
||||
|
||||
---
|
||||
|
||||
## 🚨 致命問題模式 (需立即更正)
|
||||
|
||||
### ❌ 級別 1: 致命歧義 (執行停止級)
|
||||
|
||||
- **多重解釋可能的指示**: "酌情判斷"、"根據情况"、"原則上"
|
||||
- **模糊的例外條件**: "特殊情况下"、"必要時"
|
||||
- **主觀判斷標準**: "適当地"、"充分地"、"尽可能"
|
||||
- **未定義的重要概念**: "標準的"、"一般的"、"基本的"
|
||||
|
||||
### ❌ 級別 2: 結構缺陷 (質量重要級)
|
||||
|
||||
- **資訊分散**: 相關重要資訊散布在 3 處以上
|
||||
- **循環引用**: 部分 A→B→C→A 的無限循環
|
||||
- **矛盾指示**: 不同部分有相反的指示
|
||||
- **執行顺序不明**: 依賴關系不明確的步骤
|
||||
|
||||
### ❌ 級別 3: 質量下降 (建議改進級)
|
||||
|
||||
- **不可驗證性**: 成功/失败判斷標準不明
|
||||
- **自動化困難**: 依賴人工主觀判斷的設計
|
||||
- **維護困難**: 更新時影響範圍不可預測的結構
|
||||
- **學習困難**: 新人理解需要時間的復杂度
|
||||
|
||||
---
|
||||
|
||||
## 🎯 經過驗證的改進方法
|
||||
|
||||
### ✅ 分阶段強化方法
|
||||
|
||||
1. **現狀分析**: 問題分類、優先級排序、影響度評估
|
||||
2. **致命問題優先**: 最優先完全解決級別 1 問題
|
||||
3. **分阶段實施**: 不一次性全部更改，以可驗證單位實施
|
||||
4. **效果測量**: 改進前後的定量比较
|
||||
5. **持續監控**: 確認改進效果的持續性
|
||||
|
||||
### ✅ 消除歧義的實践方法
|
||||
|
||||
```markdown
|
||||
# ❌ 改進前 (模糊)
|
||||
|
||||
"原則上，請將指摘事項作為內聯評論記錄在 GitHub 上相應的更改位置"
|
||||
|
||||
# ✅ 改進後 (明確)
|
||||
|
||||
"必须將指摘事項作為內聯評論記錄在 GitHub 上相應的更改位置。例外仅限于第 3.3 节定義的 3 個條件"
|
||||
```
|
||||
|
||||
### ✅ 資訊整合的實践方法
|
||||
|
||||
```markdown
|
||||
# ❌ 改進前 (分散)
|
||||
|
||||
第 2.1 节: "使用必需的 6 個部分"
|
||||
第 3.5 节: "📊 综合評價、📋 指摘事項..."
|
||||
第 4.2 节: "禁止刪除部分"
|
||||
|
||||
# ✅ 改進後 (整合)
|
||||
|
||||
執行清單:
|
||||
□ 10. 發布總結評論 (必须使用 6 個部分)
|
||||
🔴 必需的 6 個部分： 1) 📊 综合評價 2) 📋 分類別指摘事項匯總 3) ⚠️ 主要關注點 4) ✅ 值得肯定的點 5) 🎯 結論 6) 🤖 AI 審查質量自我評價
|
||||
❌ 绝對禁止：刪除、添加、重命名部分
|
||||
```
|
||||
|
||||
### ✅ 追蹤系統的實施模式
|
||||
|
||||
```bash
|
||||
# 严格追蹤執行結果
|
||||
POSTED_COMMENTS=0
|
||||
FAILED_COMMENTS=0
|
||||
TOTAL_COMMENTS=0
|
||||
|
||||
# 記錄各操作結果
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✅ 成功: $OPERATION" >> /tmp/execution_log.txt
|
||||
POSTED_COMMENTS=$((POSTED_COMMENTS + 1))
|
||||
else
|
||||
echo "❌ 失败: $OPERATION" >> /tmp/execution_log.txt
|
||||
FAILED_COMMENTS=$((FAILED_COMMENTS + 1))
|
||||
fi
|
||||
|
||||
# 防止虛假報告
|
||||
if [ $POSTED_COMMENTS -ne $REPORTED_COMMENTS ]; then
|
||||
echo "🚨 警告: 報告數與實際發布數不一致"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📈 質量分數計算 (改進版)
|
||||
|
||||
### 综合分數計算
|
||||
|
||||
```text
|
||||
基礎分數 = Σ(各類別分數 × 配分) / 100
|
||||
|
||||
致命問題惩罚:
|
||||
- 級別 1 問題: -20 分/個
|
||||
- 級別 2 問題: -10 分/個
|
||||
- 級別 3 問題: -5 分/個
|
||||
|
||||
奖励要素:
|
||||
- 自動化支持: +5 分
|
||||
- 學習功能實施: +5 分
|
||||
- 經驗證的改進案例: +5 分
|
||||
|
||||
最終分數 = 基礎分數 + 奖励 - 惩罚
|
||||
```
|
||||
|
||||
### 質量級別判定
|
||||
|
||||
```text
|
||||
95-100 分: 世界最高水平 (可作為行業標準推薦)
|
||||
90-94 分: 優秀 (可用于生產環境)
|
||||
80-89 分: 良好 (轻微改進後可運行)
|
||||
70-79 分: 普通 (需要改進)
|
||||
60-69 分: 需改進 (需要大幅更正)
|
||||
50-59 分: 需大幅更正 (需要根本性重新審視)
|
||||
49 分以下: 禁止使用 (需要完全重新設計)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 實践改進流程
|
||||
|
||||
### 阶段 1: 診斷·分析 (1-2 天)
|
||||
|
||||
1. **整體結構把握**: 可視化部分構成、資訊流、依賴關系
|
||||
2. **歧義檢測**: 全面提取有解釋空間的表達
|
||||
3. **資訊分散分析**: 映射相關資訊分散模式
|
||||
4. **強制力評估**: 評估推薦/必须分類和實效性
|
||||
5. **可追蹤性確認**: 評估執行結果記錄、驗證功能
|
||||
|
||||
### 阶段 2: 優先級排序·計劃 (半天)
|
||||
|
||||
1. **致命度分類**: 級別 1-3 問題分類和影響度評估
|
||||
2. **改進顺序決定**: 考虑相互依賴的最優顺序
|
||||
3. **資源分配**: 優化改進效果與成本的平衡
|
||||
4. **風險評估**: 預測改進時的副作用、兼容性問題
|
||||
|
||||
### 阶段 3: 分阶段實施 (2-5 天)
|
||||
|
||||
1. **級別 1 問題解決**: 完全消除致命歧義
|
||||
2. **資訊整合實施**: 战略性聚合分散資訊
|
||||
3. **強制力強化**: 從推薦逐步升級到必须
|
||||
4. **追蹤系統實施**: 自動記錄、驗證執行結果
|
||||
5. **模板強化**: 明確必要元素並強制遵守
|
||||
|
||||
### 阶段 4: 驗證·調整 (1-2 天)
|
||||
|
||||
1. **功能測試**: 確認所有更改點的操作
|
||||
2. **集成測試**: 確認系統整體一致性
|
||||
3. **性能測試**: 確認執行效率、響應
|
||||
4. **可用性測試**: 在實際使用場景中驗證
|
||||
|
||||
### 阶段 5: 運行·監控 (持續)
|
||||
|
||||
1. **效果測量**: 改進前後的定量比较
|
||||
2. **持續監控**: 早期檢測質量下降
|
||||
3. **反饋收集**: 提取實際運行中的問題
|
||||
4. **持續優化**: 持續改進循環
|
||||
|
||||
---
|
||||
|
||||
## 📊 實際改進案例 (詳细版)
|
||||
|
||||
### 案例研究: 大規模提示詞的質量改進
|
||||
|
||||
#### 改進前狀况
|
||||
|
||||
```bash
|
||||
質量分數: 70 分/100 分
|
||||
- 模糊表達: 發現 15 處
|
||||
- 資訊分散: 重要資訊散布在 6 處
|
||||
- 強制力不足: 推薦級表達佔 80%
|
||||
- 追蹤功能: 無執行結果記錄
|
||||
- 錯誤處理: 失败時處理方法不明確
|
||||
```
|
||||
|
||||
#### 實施的改進內容
|
||||
|
||||
```bash
|
||||
# 1. 消除歧義 (2 天)
|
||||
- "原則上"→"例外仅限第 3.3 节的 3 個條件"
|
||||
- "推薦"→"必须"(重要度級別 2 以上)
|
||||
- "酌情"→明示具體判斷標準
|
||||
|
||||
# 2. 資訊整合 (1 天)
|
||||
- 分散的必需 6 部分資訊→整合到執行清單
|
||||
- 相關禁止事項→聚合到一個部分
|
||||
- 解決循環引用→線性資訊流
|
||||
|
||||
# 3. 追蹤系統實施 (1 天)
|
||||
- 執行結果自動日誌記錄
|
||||
- 防止虛假報告的驗證功能
|
||||
- 實時統計顯示
|
||||
|
||||
# 4. 錯誤處理強化 (半天)
|
||||
- 預期錯誤模式的完整目錄化
|
||||
- 分級處理流程的明文化
|
||||
- 自動恢復功能的實施
|
||||
```
|
||||
|
||||
#### 改進後結果
|
||||
|
||||
```bash
|
||||
質量分數: 90 分/100 分 (提升 20 分)
|
||||
- 模糊表達: 0 處 (完全消除)
|
||||
- 資訊整合: 重要資訊聚合到 3 處
|
||||
- 強制力: 必须級表達 95%
|
||||
- 追蹤功能: 完全自動化
|
||||
- 錯誤處理: 90% 問題自動解決
|
||||
|
||||
實際改進效果:
|
||||
- 判斷錯誤: 减少 85%
|
||||
- 執行時間: 縮短 40%
|
||||
- 錯誤發生率: 减少 70%
|
||||
- 用戶满意度: 提升 95%
|
||||
```
|
||||
|
||||
### 經驗教訓·最佳實践
|
||||
|
||||
#### 成功因素
|
||||
|
||||
1. **分阶段方法**: 不一次性全部更改，以可驗證單位實施
|
||||
2. **數據驅動**: 基于實測數據而非主觀判斷的改進
|
||||
3. **持續監控**: 定期確認改進效果的持續性
|
||||
4. **重視反饋**: 积极收集實際用戶的意見
|
||||
|
||||
#### 避免失败策略
|
||||
|
||||
1. **過度完美主義**: 達到 90 分後先開始運行，通過持續改進追求 100 分
|
||||
2. **一次性更改的危險**: 大規模更改必须分阶段實施
|
||||
3. **向後兼容性**: 最小化對現有工作流的影響
|
||||
4. **文檔不足**: 詳细記錄、共享所有更改
|
||||
|
||||
---
|
||||
|
||||
### 與 Claude 的協作
|
||||
|
||||
```bash
|
||||
# 結合提示詞文件的質量檢查
|
||||
cat your-prompt.md
|
||||
/check-prompt
|
||||
"評估這個提示詞的質量，提出改進點"
|
||||
|
||||
# 比较多個提示詞文件
|
||||
cat prompt-v1.md && echo "---" && cat prompt-v2.md
|
||||
/check-prompt
|
||||
"比较两個版本，分析改進的點和剩余的問題"
|
||||
|
||||
# 結合實際錯誤日誌的分析
|
||||
cat execution-errors.log
|
||||
/check-prompt --deep
|
||||
"識別可能導致這個錯誤的提示詞問題"
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
- **前提條件**: 建議提示詞文件以 Markdown 格式編寫
|
||||
- **限制事項**: 大規模提示詞 (超過 1 万行) 建議分割後分析
|
||||
- **建議事項**: 定期進行提示詞質量檢查，持續改進
|
||||
|
||||
---
|
||||
|
||||
_這個檢查清單是在實際提示詞改進項目中驗證的完整版知識，並將持續進化。_
|
||||
354
commands/commit-message.md
Normal file
354
commands/commit-message.md
Normal file
@@ -0,0 +1,354 @@
|
||||
## 提交消息
|
||||
|
||||
從暂存的更改 (git diff --staged) 生成合適的提交消息。仅生成消息並復制到剪贴板，不執行 git 命令。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/commit-message [選項]
|
||||
```
|
||||
|
||||
### 選項
|
||||
|
||||
- `--format <格式>` : 指定消息格式 (conventional, gitmoji, angular)
|
||||
- `--lang <語言>` : 強制指定消息語言 (en, zh-tw)
|
||||
- `--breaking` : 檢測並記錄 Breaking Change
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 從暂存的更改生成消息 (自動判定語言)
|
||||
# 主要候選會自動復制到剪贴板
|
||||
/commit-message
|
||||
|
||||
# 強制指定語言
|
||||
/commit-message --lang zh-tw
|
||||
/commit-message --lang en
|
||||
|
||||
# 檢測 Breaking Change
|
||||
/commit-message --breaking
|
||||
```
|
||||
|
||||
### 前提條件
|
||||
|
||||
**重要**: 此命令仅分析暂存的更改。需要先使用 `git add` 暂存更改。
|
||||
|
||||
```bash
|
||||
# 如果没有暂存更改，會顯示警告
|
||||
$ /commit-message
|
||||
没有暂存的更改。請先執行 git add。
|
||||
```
|
||||
|
||||
### 自動剪贴板功能
|
||||
|
||||
生成的主要候選會以 `git commit -m "消息"` 的完整格式自動復制到剪贴板。可以直接在終端粘贴執行。
|
||||
|
||||
**實現注意事項**:
|
||||
|
||||
- 將提交命令傳遞給 `pbcopy` 時，應與消息輸出分開執行
|
||||
- 使用 `printf` 而不是 `echo` 以避免末尾換行
|
||||
|
||||
### 項目規範自動檢測
|
||||
|
||||
**重要**: 如果存在項目特有的規範，將優先使用。
|
||||
|
||||
#### 1. CommitLint 配置檢查
|
||||
|
||||
從以下文件自動檢測配置：
|
||||
|
||||
- `commitlint.config.js`
|
||||
- `commitlint.config.mjs`
|
||||
- `commitlint.config.cjs`
|
||||
- `commitlint.config.ts`
|
||||
- `.commitlintrc.js`
|
||||
- `.commitlintrc.json`
|
||||
- `.commitlintrc.yml`
|
||||
- `.commitlintrc.yaml`
|
||||
- `package.json` 的 `commitlint` 部分
|
||||
|
||||
```bash
|
||||
# 搜索配置文件
|
||||
find . -name "commitlint.config.*" -o -name ".commitlintrc.*" | head -1
|
||||
```
|
||||
|
||||
#### 2. 自定義類型檢測
|
||||
|
||||
項目特有類型示例：
|
||||
|
||||
```javascript
|
||||
// commitlint.config.mjs
|
||||
export default {
|
||||
extends: ["@commitlint/config-conventional"],
|
||||
rules: {
|
||||
"type-enum": [
|
||||
2,
|
||||
"always",
|
||||
[
|
||||
"feat",
|
||||
"fix",
|
||||
"docs",
|
||||
"style",
|
||||
"refactor",
|
||||
"test",
|
||||
"chore",
|
||||
"wip", // 進行中
|
||||
"hotfix", // 紧急修復
|
||||
"release", // 發布
|
||||
"deps", // 依賴更新
|
||||
"config", // 配置更改
|
||||
],
|
||||
],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### 3. 語言設置檢測
|
||||
|
||||
```javascript
|
||||
// 項目使用繁体字中文消息時
|
||||
export default {
|
||||
rules: {
|
||||
"subject-case": [0], // 為支持繁体字中文而禁用
|
||||
"subject-max-length": [2, "always", 72], // 為繁体字中文調整字符數限制
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### 4. 現有提交歷史分析
|
||||
|
||||
```bash
|
||||
# 從最近的提交學習使用模式
|
||||
git log --oneline -50 --pretty=format:"%s"
|
||||
|
||||
# 使用類型統計
|
||||
git log --oneline -100 --pretty=format:"%s" | \
|
||||
grep -oE '^[a-z]+(\([^)]+\))?' | \
|
||||
sort | uniq -c | sort -nr
|
||||
```
|
||||
|
||||
### 語言自動判定
|
||||
|
||||
根據以下條件自動切換繁体字中文/英文：
|
||||
|
||||
1. **CommitLint 配置**中的語言設置
|
||||
2. **git log 分析**的自動判定
|
||||
3. **項目文件**的語言設置
|
||||
4. **更改文件**中的注釋和字符串分析
|
||||
|
||||
默認為英文。判定為繁体字中文項目時生成繁体字中文消息。
|
||||
|
||||
### 消息格式
|
||||
|
||||
#### Conventional Commits (默認)
|
||||
|
||||
```text
|
||||
<type>: <description>
|
||||
```
|
||||
|
||||
**重要**: 必须生成單行提交消息。不生成多行消息。
|
||||
|
||||
**注意**: 如果項目有特有規範，將優先使用。
|
||||
|
||||
### 標準類型
|
||||
|
||||
**必须類型**:
|
||||
|
||||
- `feat`: 新功能 (用戶可見的功能添加)
|
||||
- `fix`: 缺陷修復
|
||||
|
||||
**可選類型**:
|
||||
|
||||
- `build`: 構建系統或外部依賴的更改
|
||||
- `chore`: 其他更改 (不影響發布)
|
||||
- `ci`: CI 配置文件或腳本的更改
|
||||
- `docs`: 仅文檔更改
|
||||
- `style`: 不影響代碼含義的更改 (空格、格式、分号等)
|
||||
- `refactor`: 既不修復缺陷也不添加功能的代碼更改
|
||||
- `perf`: 性能改進
|
||||
- `test`: 添加或更正測試
|
||||
|
||||
### 輸出示例 (英文項目)
|
||||
|
||||
```bash
|
||||
$ /commit-message
|
||||
|
||||
📝 提交消息建議
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
✨ 主要候選:
|
||||
feat: implement JWT-based authentication system
|
||||
|
||||
📋 備選方案:
|
||||
1. feat: add user authentication with JWT tokens
|
||||
2. fix: resolve token validation error in auth middleware
|
||||
3. refactor: extract auth logic into separate module
|
||||
|
||||
✅ `git commit -m "feat: implement JWT-based authentication system"` 已復制到剪贴板
|
||||
```
|
||||
|
||||
**實現示例 (更正版)**:
|
||||
|
||||
```bash
|
||||
# 先將提交命令復制到剪贴板 (無換行)
|
||||
printf 'git commit -m "%s"' "$COMMIT_MESSAGE" | pbcopy
|
||||
|
||||
# 然後顯示消息
|
||||
cat << EOF
|
||||
📝 提交消息建議
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
✨ 主要候選:
|
||||
$COMMIT_MESSAGE
|
||||
|
||||
📋 備選方案:
|
||||
1. ...
|
||||
2. ...
|
||||
3. ...
|
||||
|
||||
✅ `git commit -m "$COMMIT_MESSAGE"` 已復制到剪贴板
|
||||
EOF
|
||||
```
|
||||
|
||||
### 輸出示例 (繁体字中文項目)
|
||||
|
||||
```bash
|
||||
$ /commit-message
|
||||
|
||||
📝 提交消息建議
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
✨ 主要候選:
|
||||
feat: 實作 JWT 認證系統
|
||||
|
||||
📋 備選方案:
|
||||
1. feat: 新增基於 JWT 令牌的使用者認證
|
||||
2. fix: 解決認證中介軟體的令牌驗證錯誤
|
||||
3. docs: 將認證邏輯分離到獨立模組
|
||||
|
||||
✅ `git commit -m "feat: 實作 JWT 認證系統"` 已復制到剪贴板
|
||||
```
|
||||
|
||||
### 工作概要
|
||||
|
||||
1. **分析**: 分析 `git diff --staged` 的內容
|
||||
2. **生成**: 生成合適的提交消息
|
||||
3. **復制**: 自動將主要候選復制到剪贴板
|
||||
|
||||
**注意**: 此命令不執行 git add 或 git commit。仅生成提交消息並復制到剪贴板。
|
||||
|
||||
### 智能功能
|
||||
|
||||
#### 1. 更改內容自動分類 (仅暂存文件)
|
||||
|
||||
- 新文件添加 → `feat`
|
||||
- 錯誤修復模式 → `fix`
|
||||
- 仅測試文件 → `test`
|
||||
- 配置文件更改 → `chore`
|
||||
- README/docs 更新 → `docs`
|
||||
|
||||
#### 2. 項目規範自動檢測
|
||||
|
||||
- `.gitmessage` 文件
|
||||
- `CONTRIBUTING.md` 中的規範
|
||||
- 過去提交歷史模式
|
||||
|
||||
#### 3. 語言判定詳情 (仅暂存更改)
|
||||
|
||||
```bash
|
||||
# 判定基準 (優先級)
|
||||
1. 從 git diff --staged 的內容判定語言
|
||||
2. 暂存文件的注釋分析
|
||||
3. git log --oneline -20 的語言分析
|
||||
4. 項目主要語言設置
|
||||
```
|
||||
|
||||
#### 4. 暂存分析詳情
|
||||
|
||||
分析使用的資訊 (仅讀取):
|
||||
|
||||
- `git diff --staged --name-only` - 更改文件列表
|
||||
- `git diff --staged` - 實際更改內容
|
||||
- `git status --porcelain` - 文件狀態
|
||||
|
||||
### Breaking Change 檢測時
|
||||
|
||||
当有 API 破坏性更改時：
|
||||
|
||||
**英文**:
|
||||
|
||||
```bash
|
||||
feat!: change user API response format
|
||||
|
||||
BREAKING CHANGE: user response now includes additional metadata
|
||||
```
|
||||
|
||||
或
|
||||
|
||||
```bash
|
||||
feat(api)!: change authentication flow
|
||||
```
|
||||
|
||||
**繁体字中文**:
|
||||
|
||||
```bash
|
||||
feat!: 更改用戶 API 響應格式
|
||||
|
||||
BREAKING CHANGE: 響應現在包含额外的元數據
|
||||
```
|
||||
|
||||
或
|
||||
|
||||
```bash
|
||||
feat(api)!: 更改認證流程
|
||||
```
|
||||
|
||||
### 最佳實践
|
||||
|
||||
1. **適應項目**: 遵循現有的提交語言
|
||||
2. **簡洁性**: 50 字符內要清楚
|
||||
3. **一致性**: 不要混合使用 (英文就統一英文)
|
||||
4. **OSS**: 開源軟件推薦英文
|
||||
5. **坚持單行**: 必须單行提交消息 (需要詳细說明時在 PR 中補充)
|
||||
|
||||
### 常見模式
|
||||
|
||||
**英文**:
|
||||
|
||||
```text
|
||||
feat: add user registration endpoint
|
||||
fix: resolve memory leak in cache manager
|
||||
docs: update API documentation
|
||||
```
|
||||
|
||||
**繁体字中文**:
|
||||
|
||||
```text
|
||||
feat: 添加用戶注冊端點
|
||||
fix: 解決緩存管理器內存洩漏
|
||||
docs: 更新 API 文檔
|
||||
```
|
||||
|
||||
### 與 Claude 的協作
|
||||
|
||||
```bash
|
||||
# 與暂存更改結合使用
|
||||
git add -p # 交互式暂存
|
||||
/commit-message
|
||||
"生成最優的提交消息"
|
||||
|
||||
# 仅暂存特定文件後分析
|
||||
git add src/auth/*.js
|
||||
/commit-message --lang zh-tw
|
||||
"為認證相關更改生成合適的消息"
|
||||
|
||||
# Breaking Change 檢測和應對
|
||||
git add -A
|
||||
/commit-message --breaking
|
||||
"如有破坏性更改請適当標記"
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
- **前提條件**: 更改需要先通過 `git add` 暂存
|
||||
- **限制事項**: 未暂存的更改不在分析範圍內
|
||||
- **推薦事項**: 請事先確認項目現有的提交規範
|
||||
50
commands/context7.md
Normal file
50
commands/context7.md
Normal file
@@ -0,0 +1,50 @@
|
||||
## Context7
|
||||
|
||||
使用 MCP 的 Context7 搜索技術文檔。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 以請求 Claude 的形式
|
||||
"用 context7 搜索 [搜索關鍵詞]"
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# React hooks 調研
|
||||
"用 context7 搜索 React hooks"
|
||||
|
||||
# 錯誤解決方法搜索
|
||||
"用 context7 查找 TypeScript 的類型錯誤"
|
||||
```
|
||||
|
||||
### 與 Claude 的協作
|
||||
|
||||
```bash
|
||||
# 技術調研請求
|
||||
"用 context7 查找 Rust 的所有權系統，並以初學者友好的方式解釋"
|
||||
|
||||
# 錯誤解決請求
|
||||
"用 context7 搜索 Python 的 ImportError 常見原因和解決方法"
|
||||
|
||||
# 最佳實践確認
|
||||
"用 context7 查找 React 性能優化的最佳實践"
|
||||
```
|
||||
|
||||
### 詳细示例
|
||||
|
||||
```bash
|
||||
# 從多個角度調研
|
||||
"用 context7 從以下角度調研 GraphQL：
|
||||
1. 基本概念和與 REST API 的區別
|
||||
2. 實現方法和最佳實践
|
||||
3. 常見問題和解決方法"
|
||||
|
||||
# 特定版本或環境的調研
|
||||
"用 context7 搜索 Next.js 14 的新功能，重點說明 App Router 的使用方法"
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
如果 Context7 找不到資訊，Claude 會自動建議其他方法，如 Web 搜索等。
|
||||
186
commands/design-patterns.md
Normal file
186
commands/design-patterns.md
Normal file
@@ -0,0 +1,186 @@
|
||||
## 設計模式
|
||||
|
||||
提出可應用于代碼庫的設計模式，評估 SOLID 原則的遵守情况。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/design-patterns [分析對象] [選項]
|
||||
```
|
||||
|
||||
### 選項
|
||||
|
||||
- `--suggest` : 提出可應用的模式 (默認)
|
||||
- `--analyze` : 分析現有模式的使用情况
|
||||
- `--refactor` : 生成重構方案
|
||||
- `--solid` : 檢查 SOLID 原則的遵守情况
|
||||
- `--anti-patterns` : 檢測反模式
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 整個項目的模式分析
|
||||
/design-patterns
|
||||
|
||||
# 對特定文件提出模式建議
|
||||
/design-patterns src/services/user.js --suggest
|
||||
|
||||
# SOLID 原則檢查
|
||||
/design-patterns --solid
|
||||
|
||||
# 反模式檢測
|
||||
/design-patterns --anti-patterns
|
||||
```
|
||||
|
||||
### 分析類別
|
||||
|
||||
#### 1. 創建型模式
|
||||
|
||||
- **Factory Pattern**: 對象創建的抽象化
|
||||
- **Builder Pattern**: 復杂對象的分步構建
|
||||
- **Singleton Pattern**: 保證實例的唯一性
|
||||
- **Prototype Pattern**: 對象的克隆生成
|
||||
|
||||
#### 2. 結構型模式
|
||||
|
||||
- **Adapter Pattern**: 接口轉換
|
||||
- **Decorator Pattern**: 動態添加功能
|
||||
- **Facade Pattern**: 簡化復杂子系統
|
||||
- **Proxy Pattern**: 對象訪問控制
|
||||
|
||||
#### 3. 行為型模式
|
||||
|
||||
- **Observer Pattern**: 事件通知的實現
|
||||
- **Strategy Pattern**: 算法切換
|
||||
- **Command Pattern**: 操作封裝
|
||||
- **Iterator Pattern**: 集合遍歷
|
||||
|
||||
### SOLID 原則檢查項
|
||||
|
||||
```text
|
||||
S - Single Responsibility Principle (單一职責原則)
|
||||
O - Open/Closed Principle (開闭原則)
|
||||
L - Liskov Substitution Principle (里氏替換原則)
|
||||
I - Interface Segregation Principle (接口隔離原則)
|
||||
D - Dependency Inversion Principle (依賴倒置原則)
|
||||
```
|
||||
|
||||
### 輸出示例
|
||||
|
||||
```text
|
||||
設計模式分析報告
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
當前使用的模式
|
||||
├─ Observer Pattern: EventEmitter (12 處)
|
||||
├─ Factory Pattern: UserFactory (3 處)
|
||||
├─ Singleton Pattern: DatabaseConnection (1 處)
|
||||
└─ Strategy Pattern: PaymentProcessor (5 處)
|
||||
|
||||
推薦模式
|
||||
├─ [HIGH] Repository Pattern
|
||||
│ └─ 對象: src/models/*.js
|
||||
│ └─ 原因: 分離數據訪問邏輯
|
||||
│ └─ 示例:
|
||||
│ class UserRepository {
|
||||
│ async findById(id) { ... }
|
||||
│ async save(user) { ... }
|
||||
│ }
|
||||
│
|
||||
├─ [MED] Command Pattern
|
||||
│ └─ 對象: src/api/handlers/*.js
|
||||
│ └─ 原因: 統一請求處理
|
||||
│
|
||||
└─ [LOW] Decorator Pattern
|
||||
└─ 對象: src/middleware/*.js
|
||||
└─ 原因: 改進功能組合
|
||||
|
||||
SOLID 原則违反
|
||||
├─ [S] UserService: 同時負責認證和權限管理
|
||||
├─ [O] PaymentGateway: 添加新支付方式需要修改
|
||||
├─ [D] EmailService: 直接依賴具體類
|
||||
└─ [I] IDataStore: 包含未使用的方法
|
||||
|
||||
重構建議
|
||||
1. 將 UserService 拆分為認證和權限管理
|
||||
2. 引入 PaymentStrategy 接口
|
||||
3. 定義 EmailService 接口
|
||||
4. 按用途拆分 IDataStore
|
||||
```
|
||||
|
||||
### 高級用法
|
||||
|
||||
```bash
|
||||
# 模式應用的影響分析
|
||||
/design-patterns --impact-analysis Repository
|
||||
|
||||
# 生成特定模式的實現示例
|
||||
/design-patterns --generate Factory --for src/models/Product.js
|
||||
|
||||
# 模式組合建議
|
||||
/design-patterns --combine --context "带緩存的 API"
|
||||
|
||||
# 架構模式評估
|
||||
/design-patterns --architecture MVC
|
||||
```
|
||||
|
||||
### 模式應用示例
|
||||
|
||||
#### Before (有問題的代碼)
|
||||
|
||||
```javascript
|
||||
class OrderService {
|
||||
processOrder(order, paymentType) {
|
||||
if (paymentType === "credit") {
|
||||
// 信用卡處理
|
||||
} else if (paymentType === "paypal") {
|
||||
// PayPal 處理
|
||||
}
|
||||
// 其他支付方式...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### After (應用 Strategy Pattern)
|
||||
|
||||
```javascript
|
||||
// 策略接口
|
||||
class PaymentStrategy {
|
||||
process(amount) {
|
||||
throw new Error("必须實現 process 方法");
|
||||
}
|
||||
}
|
||||
|
||||
// 具體策略
|
||||
class CreditCardPayment extends PaymentStrategy {
|
||||
process(amount) {
|
||||
/* 實現 */
|
||||
}
|
||||
}
|
||||
|
||||
// 上下文
|
||||
class OrderService {
|
||||
constructor(paymentStrategy) {
|
||||
this.paymentStrategy = paymentStrategy;
|
||||
}
|
||||
|
||||
processOrder(order) {
|
||||
this.paymentStrategy.process(order.total);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 反模式檢測
|
||||
|
||||
- **God Object**: 承担過多职責的類
|
||||
- **Spaghetti Code**: 控制流復杂纠缠的代碼
|
||||
- **Copy-Paste Programming**: 過度使用重復代碼
|
||||
- **Magic Numbers**: 硬編碼的常量
|
||||
- **Callback Hell**: 深度嵌套的回調
|
||||
|
||||
### 最佳實践
|
||||
|
||||
1. **渐進式應用**: 不要一次應用太多模式
|
||||
2. **必要性驗證**: 模式是解決問題的手段而非目的
|
||||
3. **團隊共識**: 應用模式前團隊讨論
|
||||
4. **文檔化**: 記錄應用模式的意圖
|
||||
75
commands/explain-code.md
Normal file
75
commands/explain-code.md
Normal file
@@ -0,0 +1,75 @@
|
||||
## 代碼解釋
|
||||
|
||||
詳细解釋代碼的運行機制。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 顯示文件內容並請求 Claude
|
||||
cat <file>
|
||||
"解釋這段代碼的運行機制"
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 理解 Rust 的所有權
|
||||
cat main.rs
|
||||
"從 Rust 的所有權和生命週期角度解釋"
|
||||
|
||||
# 算法解釋
|
||||
grep -A 50 "quicksort" sort.rs
|
||||
"解釋這個排序算法的機制和時間復杂度"
|
||||
|
||||
# 設計模式說明
|
||||
cat factory.rs
|
||||
"說明使用的設計模式及其優點"
|
||||
```
|
||||
|
||||
### 與 Claude 的協作
|
||||
|
||||
```bash
|
||||
# 初學者友好的解釋
|
||||
cat complex_function.py
|
||||
"用初學者也能理解的方式逐行解釋這段代碼"
|
||||
|
||||
# 性能分析
|
||||
cat algorithm.rs
|
||||
"指出這段代碼的性能問題並提出改進方案"
|
||||
|
||||
# 带圖解的說明
|
||||
cat state_machine.js
|
||||
"用 ASCII 艺術圖解說明這段代碼的處理流程"
|
||||
|
||||
# 安全審查
|
||||
cat auth_handler.go
|
||||
"指出這段代碼的安全隱患"
|
||||
```
|
||||
|
||||
### 詳细示例
|
||||
|
||||
```bash
|
||||
# 復杂邏輯的解釋
|
||||
cat recursive_parser.rs
|
||||
"從以下角度解釋這個遞歸解析器的運行機制：
|
||||
1. 整體處理流程
|
||||
2. 各函數的角色和职責
|
||||
3. 邊界情况處理
|
||||
4. 可改進的地方"
|
||||
|
||||
# 異步處理的解釋
|
||||
cat async_handler.ts
|
||||
"解釋這個異步處理的以下方面：
|
||||
1. Promise 鏈的流程
|
||||
2. 錯誤處理機制
|
||||
3. 是否有並發處理
|
||||
4. 死鎖的可能性"
|
||||
|
||||
# 架構說明
|
||||
ls -la src/ && cat src/main.rs src/lib.rs
|
||||
"解釋這個項目的架構和模塊結構"
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
代碼解釋不仅說明運行機制，還會解釋為什么這樣實現、有什么優點、潜在問題是什么等深層洞察。
|
||||
311
commands/fix-error.md
Normal file
311
commands/fix-error.md
Normal file
@@ -0,0 +1,311 @@
|
||||
## Error Fix
|
||||
|
||||
從錯誤訊息中識別根本原因，預測解決時間並提出經過驗證的解決方案。學習類似錯誤的模式，立即提供適當的處理方法。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/fix-error [選項]
|
||||
```
|
||||
|
||||
### 選項
|
||||
|
||||
- 無 : 標準錯誤分析
|
||||
- `--deep` : 深度分析模式 (包括依賴關係・環境因素)
|
||||
- `--preventive` : 重視預防措施的分析
|
||||
- `--quick` : 僅提供立即可用的修復方案
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 標準錯誤分析
|
||||
npm run build 2>&1
|
||||
/fix-error
|
||||
"分析建置錯誤並提出修復方法"
|
||||
|
||||
# 深度分析模式
|
||||
python app.py 2>&1
|
||||
/fix-error --deep
|
||||
"包括環境因素在內分析錯誤的根本原因"
|
||||
|
||||
# 即時修復重視
|
||||
cargo test 2>&1
|
||||
/fix-error --quick
|
||||
"提供可立即應用的修復方法"
|
||||
|
||||
# 預防措施重視
|
||||
./app 2>&1 | tail -50
|
||||
/fix-error --preventive
|
||||
"提出錯誤修復和未來的預防措施"
|
||||
```
|
||||
|
||||
### 與 Claude 的協作
|
||||
|
||||
```bash
|
||||
# 錯誤日誌分析
|
||||
cat error.log
|
||||
/fix-error
|
||||
"識別錯誤的根本原因，提出修復方法"
|
||||
|
||||
# 測試失敗的解決
|
||||
npm test 2>&1
|
||||
/fix-error --quick
|
||||
"分析失敗的測試，提出可立即應用的修復方案"
|
||||
|
||||
# 堆疊追蹤的解析
|
||||
python script.py 2>&1
|
||||
/fix-error --deep
|
||||
"從這個堆疊追蹤中定位問題，包括環境因素一起分析"
|
||||
|
||||
# 批次解決多個錯誤
|
||||
grep -E "ERROR|WARN" app.log | tail -20
|
||||
/fix-error
|
||||
"按優先順序分類這些錯誤和警告，分別提出解決方法"
|
||||
```
|
||||
|
||||
### 錯誤解決時間預測
|
||||
|
||||
```text
|
||||
🚀 即時修復 (5 分鐘以內)
|
||||
├─ 拼字錯誤、import 遺漏
|
||||
├─ 環境變數未設定
|
||||
├─ 未定義變數的參照
|
||||
└─ 預測時間: 2-5 分鐘
|
||||
|
||||
⚡ 快速修復 (30 分鐘以內)
|
||||
├─ 依賴關係不一致
|
||||
├─ 設定檔錯誤
|
||||
├─ 型別不匹配
|
||||
└─ 預測時間: 10-30 分鐘
|
||||
|
||||
🔧 需要調查 (2 小時以內)
|
||||
├─ 複雜的邏輯錯誤
|
||||
├─ 非同步處理競爭
|
||||
├─ API 整合問題
|
||||
└─ 預測時間: 30 分鐘-2 小時
|
||||
|
||||
🔬 深度分析 (半天以上)
|
||||
├─ 架構起因
|
||||
├─ 多系統連接
|
||||
├─ 效能劣化
|
||||
└─ 預測時間: 4 小時-數天
|
||||
```
|
||||
|
||||
### 類似錯誤模式資料庫
|
||||
|
||||
```text
|
||||
頻發錯誤與即時解決方案
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📊 "Cannot read property 'X' of undefined/null" (頻度: 極高)
|
||||
├─ 主要原因: 物件的 null 檢查不足
|
||||
├─ 解決時間: 5-10 分鐘
|
||||
└─ 處理方法: 添加 Optional chaining (?.) 或 null 檢查
|
||||
|
||||
📊 "ECONNREFUSED" / "ENOTFOUND" (頻度: 高)
|
||||
├─ 主要原因: 服務未啟動或 URL 設定錯誤
|
||||
├─ 解決時間: 5-15 分鐘
|
||||
└─ 處理方法: 確認服務啟動，檢查環境變數
|
||||
|
||||
📊 "Module not found" / "Cannot resolve" (頻度: 高)
|
||||
├─ 主要原因: 套件未安裝，路徑指定錯誤
|
||||
├─ 解決時間: 2-5 分鐘
|
||||
└─ 處理方法: 執行 npm install，確認相對路徑
|
||||
|
||||
📊 "Unexpected token" / "SyntaxError" (頻度: 中)
|
||||
├─ 主要原因: 括號・引號不一致，使用保留字
|
||||
├─ 解決時間: 2-10 分鐘
|
||||
└─ 處理方法: 確認語法高亮，執行 Linter
|
||||
|
||||
📊 "CORS policy" / "Access-Control-Allow-Origin" (頻度: 中)
|
||||
├─ 主要原因: 伺服器端 CORS 設定不足
|
||||
├─ 解決時間: 15-30 分鐘
|
||||
└─ 處理方法: 伺服器 CORS 設定，代理設定
|
||||
|
||||
📊 "Maximum call stack size exceeded" (頻度: 低)
|
||||
├─ 主要原因: 無限迴圈・遞迴，循環參照
|
||||
├─ 解決時間: 30 分鐘-2 小時
|
||||
└─ 處理方法: 確認遞迴結束條件，解除循環參照
|
||||
```
|
||||
|
||||
### 錯誤分析的優先順序矩陣
|
||||
|
||||
| 優先順序 | 圖示 | 影響範圍 | 解決難度 | 回應期限 | 說明 |
|
||||
| ----------------- | ----------- | -------- | -------- | ------------- | ---------------------------- |
|
||||
| **Critical** | 🔴 緊急回應 | 廣 | 低 | 15 分鐘內著手 | 系統全面停止，資料遺失風險 |
|
||||
| **High Priority** | 🟠 早期回應 | 廣 | 高 | 1 小時內著手 | 主要功能停止，多數使用者影響 |
|
||||
| **Medium** | 🟡 計畫回應 | 窄 | 高 | 當日回應 | 部分功能限制，有迴避方案 |
|
||||
| **Low** | 🟢 過程觀察 | 窄 | 低 | 下次修改時 | 輕微不良，對 UX 影響小 |
|
||||
|
||||
### 分析流程
|
||||
|
||||
#### 階段 1: 錯誤資訊收集
|
||||
|
||||
```bash
|
||||
🔴 必須執行:
|
||||
- 完整取得錯誤訊息
|
||||
- 確認堆疊追蹤
|
||||
- 確定發生條件 (可重現性)
|
||||
|
||||
🟡 早期執行:
|
||||
- 收集環境資訊 (OS，版本，依賴關係)
|
||||
- 直接變更歷程 (git log，最近提交)
|
||||
- 確認相關日誌
|
||||
|
||||
🟢 額外執行:
|
||||
- 系統資源狀況
|
||||
- 網路狀態
|
||||
- 外部服務狀態
|
||||
```
|
||||
|
||||
#### 階段 2: 根本原因分析
|
||||
|
||||
1. **整理表面症狀**
|
||||
- 錯誤訊息的正確內容
|
||||
- 發生時間和模式
|
||||
- 確定影響範圍
|
||||
|
||||
2. **確定深層原因**
|
||||
- 應用 5 Whys 分析
|
||||
- 追蹤依賴關係
|
||||
- 確認環境差異
|
||||
|
||||
3. **驗證假設**
|
||||
- 建立最小重現程式碼
|
||||
- 執行隔離測試
|
||||
- 縮小原因範圍
|
||||
|
||||
#### 階段 3: 解決方案實作
|
||||
|
||||
```bash
|
||||
🔴 即時處理 (熱修復):
|
||||
- 抑制症狀的最小修復
|
||||
- 應用暫時迴避方案
|
||||
- 準備緊急部署
|
||||
|
||||
🟡 根本解決:
|
||||
- 針對原因的本質修復
|
||||
- 新增測試案例
|
||||
- 更新文件
|
||||
|
||||
🟢 預防措施實作:
|
||||
- 強化錯誤處理
|
||||
- 設定監控・警報
|
||||
- 改善 CI/CD 管線
|
||||
```
|
||||
|
||||
### 輸出範例
|
||||
|
||||
```text
|
||||
🚨 錯誤分析報告
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📍 錯誤概要
|
||||
├─ 類型: [編譯/執行時/邏輯/環境]
|
||||
├─ 緊急度: 🔴 高 / 🟡 中 / 🟢 低
|
||||
├─ 影響範圍: [功能名/元件]
|
||||
└─ 重現性: [100% / 間歇性 / 特定條件]
|
||||
|
||||
🔍 根本原因
|
||||
├─ 直接原因: [具體原因]
|
||||
├─ 背景因素: [環境/設定/依賴關係]
|
||||
└─ 觸發器: [發生條件]
|
||||
|
||||
💡 解決方案
|
||||
🔴 即時處理:
|
||||
1. [具體修復指令/程式碼]
|
||||
2. [暫時迴避方案]
|
||||
|
||||
🟡 根本解決:
|
||||
1. [本質修復方法]
|
||||
2. [必要的重構]
|
||||
|
||||
🟢 預防措施:
|
||||
1. [錯誤處理改善]
|
||||
2. [測試新增]
|
||||
3. [監控設定]
|
||||
|
||||
📝 驗證程序
|
||||
1. [修復套用後確認方法]
|
||||
2. [測試執行指令]
|
||||
3. [動作確認項目]
|
||||
```
|
||||
|
||||
### 錯誤類型別分析技法
|
||||
|
||||
#### 編譯/建置錯誤
|
||||
|
||||
```bash
|
||||
# TypeScript 型別錯誤
|
||||
必須確認 (高):
|
||||
- tsconfig.json 設定
|
||||
- 型別定義檔 (.d.ts) 的存在
|
||||
- import 陳述句的正確性
|
||||
|
||||
# Rust 生命週期錯誤
|
||||
必須確認 (高):
|
||||
- 所有權移動
|
||||
- 參照的有效期間
|
||||
- 可變性衝突
|
||||
```
|
||||
|
||||
#### 執行時錯誤
|
||||
|
||||
```bash
|
||||
# Null/Undefined 參照
|
||||
必須確認 (高):
|
||||
- 可選鏈結不足
|
||||
- 初始化時機
|
||||
- 非同步處理的完成等待
|
||||
|
||||
# 記憶體相關錯誤
|
||||
必須確認 (高):
|
||||
- 取得堆積傾印
|
||||
- 分析 GC 日誌
|
||||
- 偵測循環參照
|
||||
```
|
||||
|
||||
#### 依賴關係錯誤
|
||||
|
||||
```bash
|
||||
# 版本衝突
|
||||
必須確認 (高):
|
||||
- lock 檔案的一致性
|
||||
- peer dependencies 要求
|
||||
- 傳遞性依賴關係
|
||||
|
||||
# 模組解析錯誤
|
||||
必須確認 (高):
|
||||
- NODE_PATH 設定
|
||||
- 路徑別名設定
|
||||
- 符號連結
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
- **絕對禁止**: 僅憑錯誤訊息的一部分判斷，未驗證就套用 Stack Overflow 解決方案
|
||||
- **例外條件**: 暫時迴避方案僅在以下 3 個條件下允許
|
||||
1. 生產環境緊急回應 (24 小時內根本解決必須)
|
||||
2. 外部服務故障 (復原等待中的替代手段)
|
||||
3. 已知框架錯誤 (等待修正版本發布)
|
||||
- **建議事項**: 以根本原因確定為最優先，避免表面修復
|
||||
|
||||
### 最佳實務
|
||||
|
||||
1. **完整資訊收集**: 從頭到尾確認錯誤訊息
|
||||
2. **確認重現性**: 最優先建立最小重現程式碼
|
||||
3. **階段性方法**: 從小修復開始驗證
|
||||
4. **文件化**: 記錄解決過程進行知識分享
|
||||
|
||||
#### 常犯錯誤
|
||||
|
||||
- **處理症狀**: 遺漏根本原因的表面修復
|
||||
- **過度一般化**: 廣泛套用特定案例的解決方案
|
||||
- **省略驗證**: 不確認修復後的副作用
|
||||
- **知識個人化**: 不將解決方法文件化
|
||||
|
||||
### 相關指令
|
||||
|
||||
- `/design-patterns` : 分析程式碼結構問題並提出模式建議
|
||||
- `/tech-debt` : 從技術債務觀點分析錯誤的根本原因
|
||||
- `/analyzer` : 需要更深入根本原因分析的情況
|
||||
314
commands/multi-role.md
Normal file
314
commands/multi-role.md
Normal file
@@ -0,0 +1,314 @@
|
||||
## 多角色分析
|
||||
|
||||
使用多個角色並行分析同一對象，生成综合報告的命令。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/multi-role <角色 1>,<角色 2> [--agent|-a] [分析對象]
|
||||
/multi-role <角色 1>,<角色 2>,<角色 3> [--agent|-a] [分析對象]
|
||||
```
|
||||
|
||||
### 可用角色
|
||||
|
||||
#### 專業分析角色
|
||||
|
||||
- `security` : 安全審計專家
|
||||
- `performance` : 性能優化專家
|
||||
- `analyzer` : 根本原因分析專家
|
||||
- `frontend` : 前端·UI/UX 專家
|
||||
- `mobile` : 移動開發專家
|
||||
- `backend` : 後端與伺服器端專家
|
||||
|
||||
#### 開發支援角色
|
||||
|
||||
- `reviewer` : 程式碼審查專家
|
||||
- `architect` : 系統架構師
|
||||
- `qa` : 測試工程師
|
||||
|
||||
**重要**:
|
||||
|
||||
- `--agent` 選項需要放在角色指定之後
|
||||
- 消息要寫在 `--agent` 之後
|
||||
- 正確示例: `/multi-role qa,architect --agent 評估計劃`
|
||||
- 錯誤示例: `/multi-role qa,architect 評估計劃 --agent`
|
||||
|
||||
### 選項
|
||||
|
||||
- `--agent` 或 `-a` : 將各角色作為子代理並行執行 (推薦用于大規模分析)
|
||||
- 使用此選項時，如果角色的 description 中包含自動委托促進短語 (如 "use PROACTIVELY" 等)，將啟用更积极的自動委托
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 安全和性能的雙重分析 (常規)
|
||||
/multi-role security,performance
|
||||
"評估這個 API 端點"
|
||||
|
||||
# 大規模系統的並行分析 (子代理)
|
||||
/multi-role security,performance --agent
|
||||
"全面分析系統的安全性和性能"
|
||||
|
||||
# 前端·移動·性能的综合分析
|
||||
/multi-role frontend,mobile,performance
|
||||
"考虑這個界面的優化方案"
|
||||
|
||||
# 架構設計的多角度評估 (子代理)
|
||||
/multi-role architect,security,performance --agent
|
||||
"評估微服務化的設計"
|
||||
```
|
||||
|
||||
### 分析流程
|
||||
|
||||
### 阶段 1: 並行分析
|
||||
|
||||
各角色独立分析同一對象
|
||||
|
||||
- 從專業視角進行評估
|
||||
- 按角色特有標準判定
|
||||
- 生成独立的建議
|
||||
|
||||
### 阶段 2: 综合分析
|
||||
|
||||
結構化整合結果
|
||||
|
||||
- 整理各角色的評估結果
|
||||
- 識別重復·矛盾點
|
||||
- 明確互補關系
|
||||
|
||||
### 阶段 3: 综合報告
|
||||
|
||||
生成最終建議
|
||||
|
||||
- 带優先級的行動計劃
|
||||
- 明示權衡取舍
|
||||
- 提供實施路線圖
|
||||
|
||||
### 輸出格式示例
|
||||
|
||||
### 2 角色分析的情况
|
||||
|
||||
```text
|
||||
多角色分析: Security + Performance
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
分析對象: API 端點 /api/users
|
||||
|
||||
Security 分析結果:
|
||||
認證: JWT 驗證實施得当
|
||||
授權: 基于角色的訪問控制不完整
|
||||
加密: API 密鑰在日誌中以明文輸出
|
||||
|
||||
評估分數: 65/100
|
||||
重要度: High(因為訪問敏感數據)
|
||||
|
||||
Performance 分析結果:
|
||||
響應時間: 平均 180ms(目標 200ms 以內)
|
||||
數據庫查询: 檢測到 N+1 問題
|
||||
緩存: Redis 緩存未實施
|
||||
|
||||
評估分數: 70/100
|
||||
重要度: Medium(目前在可接受範圍內)
|
||||
|
||||
相互關聯分析:
|
||||
協同效應機會:
|
||||
- 實施 Redis 緩存時同時考虑加密
|
||||
- 改進日誌輸出提升安全性和性能
|
||||
|
||||
權衡點:
|
||||
- 加強授權檢查 ↔ 對響應時間的影響
|
||||
- 日誌加密 ↔ 調試效率降低
|
||||
|
||||
综合優先級:
|
||||
Critical: 修復 API 密鑰明文輸出
|
||||
High: 解決 N+1 查询
|
||||
Medium: 實施 Redis 緩存 + 加密
|
||||
Low: 细化授權控制
|
||||
|
||||
實施路線圖:
|
||||
第 1 週: 實施 API 密鑰屏蔽
|
||||
第 2 週: 優化數據庫查询
|
||||
第 3-4 週: 設計·實施緩存層
|
||||
第 2 月: 逐步加強授權控制
|
||||
```
|
||||
|
||||
### 3 角色分析的情况
|
||||
|
||||
```text
|
||||
多角色分析: Frontend + Mobile + Performance
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
分析對象: 用戶資料界面
|
||||
|
||||
Frontend 分析結果:
|
||||
可用性: 直觀的布局
|
||||
可訪問性: WCAG 2.1 符合率 85%
|
||||
響應式: 平板顯示有問題
|
||||
|
||||
Mobile 分析結果:
|
||||
觸摸目標: 確保 44pt 以上
|
||||
單手操作: 重要按钮在上方
|
||||
離線支持: 未實施
|
||||
|
||||
Performance 分析結果:
|
||||
初始顯示: LCP 2.1 秒 (良好)
|
||||
圖像優化: 不支持 WebP
|
||||
延遲加載: 未實施
|
||||
|
||||
综合建議:
|
||||
1. 移動優化 (單手操作 + 離線支持)
|
||||
2. 圖像優化 (WebP + 延遲加載)
|
||||
3. 改進平板 UI
|
||||
|
||||
優先級: Mobile > Performance > Frontend
|
||||
實施期間: 3-4 週
|
||||
```
|
||||
|
||||
### 有效的組合模式
|
||||
|
||||
### 安全重視
|
||||
|
||||
```bash
|
||||
/multi-role security,architect
|
||||
"認證系統的設計"
|
||||
|
||||
/multi-role security,frontend
|
||||
"登錄界面的安全性"
|
||||
|
||||
/multi-role security,mobile
|
||||
"移動應用的數據保護"
|
||||
```
|
||||
|
||||
### 性能重視
|
||||
|
||||
```bash
|
||||
/multi-role performance,architect
|
||||
"可擴展性設計"
|
||||
|
||||
/multi-role performance,frontend
|
||||
"Web 页面高速化"
|
||||
|
||||
/multi-role performance,mobile
|
||||
"應用運行優化"
|
||||
```
|
||||
|
||||
### 用戶體驗重視
|
||||
|
||||
```bash
|
||||
/multi-role frontend,mobile
|
||||
"跨平台 UI"
|
||||
|
||||
/multi-role frontend,performance
|
||||
"UX 與性能的平衡"
|
||||
|
||||
/multi-role mobile,performance
|
||||
"移動 UX 優化"
|
||||
```
|
||||
|
||||
### 全面分析
|
||||
|
||||
```bash
|
||||
/multi-role architect,security,performance
|
||||
"系統整體評估"
|
||||
|
||||
/multi-role frontend,mobile,performance
|
||||
"用戶體驗综合評估"
|
||||
|
||||
/multi-role security,performance,mobile
|
||||
"移動應用综合診斷"
|
||||
```
|
||||
|
||||
### 與 Claude 的協作
|
||||
|
||||
```bash
|
||||
# 結合文件分析
|
||||
cat src/components/UserProfile.tsx
|
||||
/multi-role frontend,mobile
|
||||
"從多個視角評估這個組件"
|
||||
|
||||
# 設計文檔評估
|
||||
cat architecture-design.md
|
||||
/multi-role architect,security,performance
|
||||
"從多個專業領域評估這個設計"
|
||||
|
||||
# 錯誤分析
|
||||
cat performance-issues.log
|
||||
/multi-role performance,analyzer
|
||||
"多角度分析性能問題"
|
||||
```
|
||||
|
||||
### multi-role vs role-debate 的使用區分
|
||||
|
||||
### 使用 multi-role 的場合
|
||||
|
||||
- 需要各專業領域的独立評估
|
||||
- 想制定综合改進計劃
|
||||
- 需要整理矛盾或重復
|
||||
- 要決定實施優先級
|
||||
|
||||
### 使用 role-debate 的場合
|
||||
|
||||
- 專業領域間存在權衡
|
||||
- 技術選型可能有分歧
|
||||
- 想通過讨論決定設計方针
|
||||
- 想听取不同視角的辩論
|
||||
|
||||
### 子代理並行執行 (--agent)
|
||||
|
||||
使用 `--agent` 選項時，各角色作為独立的子代理並行執行。
|
||||
|
||||
#### 自動委托的促進
|
||||
|
||||
当角色文件的 description 字段包含以下短語時，使用 `--agent` 會啟用更积极的自動委托：
|
||||
|
||||
- "use PROACTIVELY"
|
||||
- "MUST BE USED"
|
||||
- 其他強調表達
|
||||
|
||||
#### 執行流程
|
||||
|
||||
```text
|
||||
常規執行:
|
||||
角色 1 → 角色 2 → 角色 3 → 综合
|
||||
(顺序執行，約 3-5 分鐘)
|
||||
|
||||
--agent 執行:
|
||||
角色 1 ─┐
|
||||
角色 2 ─┼→ 综合
|
||||
角色 3 ─┘
|
||||
(並行執行，約 1-2 分鐘)
|
||||
```
|
||||
|
||||
#### 有效使用示例
|
||||
|
||||
```bash
|
||||
# 大規模系統的综合評估
|
||||
/multi-role architect,security,performance,qa --agent
|
||||
"新系統的全面評估"
|
||||
|
||||
# 多視角的詳细分析
|
||||
/multi-role frontend,mobile,performance --agent
|
||||
"所有界面的 UX 優化分析"
|
||||
```
|
||||
|
||||
#### 性能比较
|
||||
|
||||
| 角色數 | 常規執行 | --agent 執行 | 縮短率 |
|
||||
| ------ | -------- | ------------ | ------ |
|
||||
| 2 角色 | 2-3 分鐘 | 1 分鐘 | 50% |
|
||||
| 3 角色 | 3-5 分鐘 | 1-2 分鐘 | 60% |
|
||||
| 4 角色 | 5-8 分鐘 | 2-3 分鐘 | 65% |
|
||||
|
||||
### 注意事項
|
||||
|
||||
- 同時執行 3 個以上角色時輸出會變长
|
||||
- 復杂分析可能需要更长執行時間
|
||||
- 出現相互矛盾的建議時，也可考虑 role-debate
|
||||
- 最終判斷請參考综合結果由用戶決定
|
||||
- **使用 --agent 時**: 會使用更多資源，但對大規模分析更高效
|
||||
|
||||
### 角色設定詳情
|
||||
|
||||
- 各角色的詳細設定、專業知識與討論特性都定義在 `.claude/agents/roles/` 目錄中
|
||||
- 包含 Evidence-First 手法與認知偏差對策
|
||||
- 角色專屬觸發語句會自動啟用特化模式
|
||||
134
commands/plan.md
Normal file
134
commands/plan.md
Normal file
@@ -0,0 +1,134 @@
|
||||
## 計劃模式
|
||||
|
||||
啟動實施前的計劃制定模式，制定詳细的實施策略。通過在代碼實施前制定結構化計劃，支持高效開發。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 請求 Claude 進入 Plan Mode
|
||||
"制定 [實施內容] 的實施計劃"
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 新功能的實施計劃
|
||||
"制定用戶認證功能的實施計劃"
|
||||
|
||||
# 系統設計計劃
|
||||
"制定微服務拆分的實施計劃"
|
||||
|
||||
# 重構計劃
|
||||
"制定遗留代碼的重構計劃"
|
||||
```
|
||||
|
||||
### 與 Claude 的協作
|
||||
|
||||
```bash
|
||||
# 復杂功能實施
|
||||
"制定聊天功能的實施計劃。包括 WebSocket、實時通知、歷史管理"
|
||||
|
||||
# 數據庫設計
|
||||
"制定電商網站的數據庫設計計劃。包括商品、訂單、用戶管理"
|
||||
|
||||
# API 設計
|
||||
"制定 GraphQL API 的實施計劃。包括認證、緩存、速率限制"
|
||||
|
||||
# 基礎設施設計
|
||||
"制定 Docker 化的實施計劃。包括開發環境、生產環境、CI/CD"
|
||||
```
|
||||
|
||||
### Plan Mode 的特點
|
||||
|
||||
**自動啟動**
|
||||
|
||||
- 檢測到實施任務時自動啟動 Plan Mode
|
||||
- 可通過"制定實施計劃"等關鍵詞明確啟動
|
||||
|
||||
**結構化規格書**
|
||||
|
||||
- 需求定義 (用戶故事·驗收標準)
|
||||
- 設計書 (架構·數據設計·UI 設計)
|
||||
- 實施計劃 (任務分解·進度跟蹤·質量保證)
|
||||
- 風險分析與對策
|
||||
|
||||
**審批流程**
|
||||
|
||||
- 通過 `exit_plan_mode` 工具提交計劃
|
||||
- **重要**: 無論工具返回值如何，必须等待用戶的明確批準
|
||||
- 禁止未經批準就開始實施
|
||||
- 可以修改·調整計劃
|
||||
- 仅在批準後才開始使用 TodoWrite 進行任務管理
|
||||
|
||||
### 詳细示例
|
||||
|
||||
```bash
|
||||
# 復杂系統實施
|
||||
"制定在線支付系統的實施計劃。包括 Stripe 集成、安全性、錯誤處理"
|
||||
|
||||
# 前端實施
|
||||
"制定 React 儀表板的實施計劃。包括狀態管理、組件設計、測試"
|
||||
|
||||
# 後端實施
|
||||
"制定 RESTful API 的實施計劃。包括認證、驗證、日誌記錄"
|
||||
|
||||
# DevOps 實施
|
||||
"制定 CI/CD 管道的實施計劃。包括測試自動化、部署、監控"
|
||||
```
|
||||
|
||||
### 3 阶段工作流程
|
||||
|
||||
#### 阶段 1: Requirements(需求定義)
|
||||
|
||||
- **用戶故事**: 明確功能的目的和價值
|
||||
- **驗收標準**: 定義完成條件和質量標準
|
||||
- **約束·前提條件**: 整理技術·時間約束
|
||||
- **優先級排序**: Must-have/Nice-to-have 分類
|
||||
|
||||
#### 阶段 2: Design(設計)
|
||||
|
||||
- **架構設計**: 系統構成和技術選型
|
||||
- **數據設計**: 模式、API 規格、數據流
|
||||
- **UI/UX 設計**: 界面構成和操作流程
|
||||
- **風險分析**: 潜在問題和對策
|
||||
|
||||
#### 阶段 3: Implementation(實施)
|
||||
|
||||
- **任務分解**: 细分為可實施的單位
|
||||
- **進度跟蹤**: 通過 TodoWrite 進行狀態管理
|
||||
- **質量保證**: 測試策略和驗證方法
|
||||
- **審批流程**: 通過 exit_plan_mode 提交計劃並等待明確批準
|
||||
|
||||
### 注意事項
|
||||
|
||||
**適用範圍**
|
||||
|
||||
- Plan Mode 最適合復杂的實施任務
|
||||
- 簡單修改或小規模變更使用常規實施形式
|
||||
- 推薦用于 3 步以上的工作或新功能開發
|
||||
|
||||
**技術約束**
|
||||
|
||||
- 不要信任 `exit_plan_mode` 工具的返回值
|
||||
- 審批流程通過用戶的明確意思表示判斷
|
||||
- 與 CLI 的 plan mode 是不同的功能
|
||||
|
||||
**執行注意事項**
|
||||
|
||||
- 严禁在批準前開始實施
|
||||
- 提交計劃後必须等待用戶響應
|
||||
- 出錯時提供替代方案
|
||||
|
||||
### 執行示例
|
||||
|
||||
```bash
|
||||
# 使用示例
|
||||
"制定用戶管理系統的實施計劃"
|
||||
|
||||
# 預期行為
|
||||
# 1. Plan Mode 自動啟動
|
||||
# 2. 需求分析和技術選型
|
||||
# 3. 實施步骤的結構化
|
||||
# 4. 通過 exit_plan_mode 提交計劃
|
||||
# 5. 批準後開始實施
|
||||
```
|
||||
460
commands/pr-auto-update.md
Normal file
460
commands/pr-auto-update.md
Normal file
@@ -0,0 +1,460 @@
|
||||
## PR 自動更新
|
||||
|
||||
## 概述
|
||||
|
||||
自動更新 Pull Request 描述和標簽的命令。通過分析 Git 更改內容，生成並設置適当的描述文本和標簽。
|
||||
|
||||
## 使用方法
|
||||
|
||||
```bash
|
||||
/pr-auto-update [選項] [PR 編号]
|
||||
```
|
||||
|
||||
### 選項
|
||||
|
||||
- `--pr <編号>` : 指定目標 PR 編号 (省略時從當前分支自動檢測)
|
||||
- `--description-only` : 仅更新描述 (不修改標簽)
|
||||
- `--labels-only` : 仅更新標簽 (不修改描述)
|
||||
- `--dry-run` : 不執行實際更新，仅顯示生成的內容
|
||||
- `--lang <語言>` : 指定語言 (zh-tw, en)
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 自動更新當前分支的 PR
|
||||
/pr-auto-update
|
||||
|
||||
# 更新特定的 PR
|
||||
/pr-auto-update --pr 1234
|
||||
|
||||
# 仅更新描述
|
||||
/pr-auto-update --description-only
|
||||
|
||||
# 預演模式確認
|
||||
/pr-auto-update --dry-run
|
||||
```
|
||||
|
||||
## 功能詳情
|
||||
|
||||
### 1. PR 自動檢測
|
||||
|
||||
從當前分支自動檢測對應的 PR：
|
||||
|
||||
```bash
|
||||
# 從分支搜索 PR
|
||||
gh pr list --head $(git branch --show-current) --json number,title,url
|
||||
```
|
||||
|
||||
### 2. 更改內容分析
|
||||
|
||||
收集和分析以下資訊：
|
||||
|
||||
- **文件更改**: 添加、刪除、修改的文件
|
||||
- **代碼分析**: import 語句、函數定義、類定義的更改
|
||||
- **測試**: 測試文件的存在與內容
|
||||
- **文檔**: README、docs 的更新
|
||||
- **配置**: package.json、pubspec.yaml、配置文件的更改
|
||||
- **CI/CD**: GitHub Actions、workflow 的更改
|
||||
|
||||
### 3. 描述文本自動生成
|
||||
|
||||
#### 模板處理優先級
|
||||
|
||||
1. **現有 PR 描述**: **完全遵循**已存在的內容
|
||||
2. **項目模板**: 從 `.github/PULL_REQUEST_TEMPLATE.md` 獲取結構
|
||||
3. **默認模板**: 上述不存在時的後備方案
|
||||
|
||||
#### 現有內容保留規則
|
||||
|
||||
**重要**: 不修改現有內容
|
||||
|
||||
- 保留已寫的部分
|
||||
- 仅補充空白部分
|
||||
- 保留功能性注釋 (如 Copilot review rule 等)
|
||||
|
||||
#### 項目模板的使用
|
||||
|
||||
```bash
|
||||
# 解析 .github/PULL_REQUEST_TEMPLATE.md 的結構
|
||||
parse_template_structure() {
|
||||
local template_file="$1"
|
||||
|
||||
if [ -f "$template_file" ]; then
|
||||
# 提取部分結構
|
||||
grep -E '^##|^###' "$template_file"
|
||||
|
||||
# 識別注釋佔位符
|
||||
grep -E '<!--.*-->' "$template_file"
|
||||
|
||||
# 完全遵循現有模板結構
|
||||
cat "$template_file"
|
||||
fi
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 標簽自動設置
|
||||
|
||||
#### 標簽獲取機制
|
||||
|
||||
**優先級**:
|
||||
|
||||
1. **`.github/labels.yml`**: 從項目特定的標簽定義獲取
|
||||
2. **GitHub API**: 使用 `gh api repos/{OWNER}/{REPO}/labels --jq '.[].name'` 獲取現有標簽
|
||||
|
||||
#### 自動判定規則
|
||||
|
||||
**基于文件模式**:
|
||||
|
||||
- 文檔: `*.md`, `README`, `docs/` → 包含 `documentation|docs|doc` 的標簽
|
||||
- 測試: `test`, `spec` → 包含 `test|testing` 的標簽
|
||||
- CI/CD: `.github/`, `*.yml`, `Dockerfile` → 包含 `ci|build|infra|ops` 的標簽
|
||||
- 依賴: `package.json`, `pubspec.yaml`, `requirements.txt` → 包含 `dependencies|deps` 的標簽
|
||||
|
||||
**基于更改內容**:
|
||||
|
||||
- Bug 修復: `fix|bug|error|crash|修復` → 包含 `bug|fix` 的標簽
|
||||
- 新功能: `feat|feature|add|implement|新功能|實裝` → 包含 `feature|enhancement|feat` 的標簽
|
||||
- 重構: `refactor|clean|重構` → 包含 `refactor|cleanup|clean` 的標簽
|
||||
- 性能: `performance|perf|optimize|性能` → 包含 `performance|perf` 的標簽
|
||||
- 安全: `security|secure|安全` → 包含 `security` 的標簽
|
||||
|
||||
#### 約束
|
||||
|
||||
- **最多 3 個**: 自動選擇的標簽數量上限
|
||||
- **仅限現有標簽**: 禁止創建新標簽
|
||||
- **部分匹配**: 根據標簽名是否包含關鍵詞判定
|
||||
|
||||
#### 實際使用示例
|
||||
|
||||
**存在 `.github/labels.yml` 時**:
|
||||
|
||||
```bash
|
||||
# 從標簽定義自動獲取
|
||||
grep "^- name:" .github/labels.yml | sed "s/^- name: '\\?\\([^']*\\)'\\?/\\1/"
|
||||
|
||||
# 例：使用項目特定的標簽體系
|
||||
```
|
||||
|
||||
**從 GitHub API 獲取時**:
|
||||
|
||||
```bash
|
||||
# 獲取現有標簽列表
|
||||
gh api repos/{OWNER}/{REPO}/labels --jq '.[].name'
|
||||
|
||||
# 例：使用 bug, enhancement, documentation 等標準標簽
|
||||
```
|
||||
|
||||
### 5. 執行流程
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# 1. PR 檢測與獲取
|
||||
detect_pr() {
|
||||
if [ -n "$PR_NUMBER" ]; then
|
||||
echo $PR_NUMBER
|
||||
else
|
||||
gh pr list --head $(git branch --show-current) --json number --jq '.[0].number'
|
||||
fi
|
||||
}
|
||||
|
||||
# 2. 更改內容分析
|
||||
analyze_changes() {
|
||||
local pr_number=$1
|
||||
|
||||
# 獲取文件更改
|
||||
gh pr diff $pr_number --name-only
|
||||
|
||||
# 內容分析
|
||||
gh pr diff $pr_number | head -1000
|
||||
}
|
||||
|
||||
# 3. 描述生成
|
||||
generate_description() {
|
||||
local pr_number=$1
|
||||
local changes=$2
|
||||
|
||||
# 獲取當前 PR 描述
|
||||
local current_body=$(gh pr view $pr_number --json body --jq -r .body)
|
||||
|
||||
# 如有現有內容則直接使用
|
||||
if [ -n "$current_body" ]; then
|
||||
echo "$current_body"
|
||||
else
|
||||
# 從模板生成新內容
|
||||
local template_file=".github/PULL_REQUEST_TEMPLATE.md"
|
||||
if [ -f "$template_file" ]; then
|
||||
generate_from_template "$(cat "$template_file")" "$changes"
|
||||
else
|
||||
generate_from_template "" "$changes"
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
# 從模板生成
|
||||
generate_from_template() {
|
||||
local template="$1"
|
||||
local changes="$2"
|
||||
|
||||
if [ -n "$template" ]; then
|
||||
# 直接使用模板 (保留 HTML 注釋)
|
||||
echo "$template"
|
||||
else
|
||||
# 使用默認格式生成
|
||||
echo "## What does this change?"
|
||||
echo ""
|
||||
echo "$changes"
|
||||
fi
|
||||
}
|
||||
|
||||
# 4. 標簽確定
|
||||
determine_labels() {
|
||||
local changes=$1
|
||||
local file_list=$2
|
||||
local pr_number=$3
|
||||
|
||||
# 獲取可用標簽
|
||||
local available_labels=()
|
||||
if [ -f ".github/labels.yml" ]; then
|
||||
# 從 labels.yml 提取標簽名
|
||||
available_labels=($(grep "^- name:" .github/labels.yml | sed "s/^- name: '\\?\\([^']*\\)'\\?/\\1/"))
|
||||
else
|
||||
# 從 GitHub API 獲取標簽
|
||||
local repo_info=$(gh repo view --json owner,name)
|
||||
local owner=$(echo "$repo_info" | jq -r .owner.login)
|
||||
local repo=$(echo "$repo_info" | jq -r .name)
|
||||
available_labels=($(gh api "repos/$owner/$repo/labels" --jq '.[].name'))
|
||||
fi
|
||||
|
||||
local suggested_labels=()
|
||||
|
||||
# 通用模式匹配
|
||||
analyze_change_patterns "$file_list" "$changes" available_labels suggested_labels
|
||||
|
||||
# 限制最多 3 個
|
||||
echo "${suggested_labels[@]:0:3}"
|
||||
}
|
||||
|
||||
# 根據更改模式確定標簽
|
||||
analyze_change_patterns() {
|
||||
local file_list="$1"
|
||||
local changes="$2"
|
||||
local -n available_ref=$3
|
||||
local -n suggested_ref=$4
|
||||
|
||||
# 根據文件類型判定
|
||||
if echo "$file_list" | grep -q "\\.md$\\|README\\|docs/"; then
|
||||
add_matching_label "documentation\\|docs\\|doc" available_ref suggested_ref
|
||||
fi
|
||||
|
||||
if echo "$file_list" | grep -q "test\\|spec"; then
|
||||
add_matching_label "test\\|testing" available_ref suggested_ref
|
||||
fi
|
||||
|
||||
# 根據更改內容判定
|
||||
if echo "$changes" | grep -iq "fix\\|bug\\|error\\|crash\\|修復"; then
|
||||
add_matching_label "bug\\|fix" available_ref suggested_ref
|
||||
fi
|
||||
|
||||
if echo "$changes" | grep -iq "feat\\|feature\\|add\\|implement\\|新功能\\|實現"; then
|
||||
add_matching_label "feature\\|enhancement\\|feat" available_ref suggested_ref
|
||||
fi
|
||||
}
|
||||
|
||||
# 添加匹配的標簽
|
||||
add_matching_label() {
|
||||
local pattern="$1"
|
||||
local -n available_ref=$2
|
||||
local -n suggested_ref=$3
|
||||
|
||||
# 如果已有 3 個則跳過
|
||||
if [ ${#suggested_ref[@]} -ge 3 ]; then
|
||||
return
|
||||
fi
|
||||
|
||||
# 添加匹配模式的第一個標簽
|
||||
for available_label in "${available_ref[@]}"; do
|
||||
if echo "$available_label" | grep -iq "$pattern"; then
|
||||
# 重復檢查
|
||||
local already_exists=false
|
||||
for existing in "${suggested_ref[@]}"; do
|
||||
if [ "$existing" = "$available_label" ]; then
|
||||
already_exists=true
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
if [ "$already_exists" = false ]; then
|
||||
suggested_ref+=("$available_label")
|
||||
return
|
||||
fi
|
||||
fi
|
||||
done
|
||||
}
|
||||
|
||||
# 為兼容性保留旧函數
|
||||
find_and_add_label() {
|
||||
add_matching_label "$@"
|
||||
}
|
||||
|
||||
# 5. PR 更新
|
||||
update_pr() {
|
||||
local pr_number=$1
|
||||
local description="$2"
|
||||
local labels="$3"
|
||||
|
||||
if [ "$DRY_RUN" = "true" ]; then
|
||||
echo "=== DRY RUN ==="
|
||||
echo "Description:"
|
||||
echo "$description"
|
||||
echo "Labels: $labels"
|
||||
else
|
||||
# 獲取倉庫資訊
|
||||
local repo_info=$(gh repo view --json owner,name)
|
||||
local owner=$(echo "$repo_info" | jq -r .owner.login)
|
||||
local repo=$(echo "$repo_info" | jq -r .name)
|
||||
|
||||
# 使用 GitHub API 更新正文 (保留 HTML 注釋)
|
||||
# 正確處理 JSON 轉義
|
||||
local escaped_body=$(echo "$description" | jq -R -s .)
|
||||
gh api \
|
||||
--method PATCH \
|
||||
"/repos/$owner/$repo/pulls/$pr_number" \
|
||||
--field body="$description"
|
||||
|
||||
# 標簽使用常規 gh 命令即可
|
||||
if [ -n "$labels" ]; then
|
||||
gh pr edit $pr_number --add-label "$labels"
|
||||
fi
|
||||
fi
|
||||
}
|
||||
```
|
||||
|
||||
## 配置文件 (未來擴展用)
|
||||
|
||||
`~/.claude/pr-auto-update.config`:
|
||||
|
||||
```json
|
||||
{
|
||||
"language": "zh-tw",
|
||||
"max_labels": 3
|
||||
}
|
||||
```
|
||||
|
||||
## 常見模式
|
||||
|
||||
### Flutter 項目
|
||||
|
||||
```markdown
|
||||
## What does this change?
|
||||
|
||||
實現了{功能名}。解決了用戶的{問題}。
|
||||
|
||||
### 主要更改內容
|
||||
|
||||
- **UI 實現**: 新建{画面名}
|
||||
- **狀態管理**: 添加 Riverpod Provider
|
||||
- **API 集成**: 實現 GraphQL 查询與變更
|
||||
- **測試**: 添加 Widget 測試和單元測試
|
||||
|
||||
### 技術規格
|
||||
|
||||
- **架構**: {使用的模式}
|
||||
- **依賴**: {新增的包}
|
||||
- **性能**: {優化內容}
|
||||
```
|
||||
|
||||
### Node.js 項目
|
||||
|
||||
```markdown
|
||||
## What does this change?
|
||||
|
||||
實現了{API 名}端點。支持{用例}。
|
||||
|
||||
### 主要更改內容
|
||||
|
||||
- **API 實現**: 新建{端點}
|
||||
- **驗證**: 添加請求驗證邏輯
|
||||
- **數據庫**: 實現對{表名}的操作
|
||||
- **測試**: 添加集成測試和單元測試
|
||||
|
||||
### 安全性
|
||||
|
||||
- **認證**: JWT 令牌驗證
|
||||
- **授權**: 基于角色的訪問控制
|
||||
- **輸入驗證**: SQL 注入防護
|
||||
```
|
||||
|
||||
### CI/CD 改進
|
||||
|
||||
```markdown
|
||||
## What does this change?
|
||||
|
||||
改進了 GitHub Actions 工作流。實現了{效果}。
|
||||
|
||||
### 改進內容
|
||||
|
||||
- **性能**: 構建時間减少{時間}
|
||||
- **可靠性**: 增強錯誤處理
|
||||
- **安全性**: 改進密鑰管理
|
||||
|
||||
### 技術细节
|
||||
|
||||
- **並行化**: {作業名}並行執行
|
||||
- **緩存**: 優化{緩存對象}的緩存策略
|
||||
- **監控**: 添加{指標}監控
|
||||
```
|
||||
|
||||
## 注意事項
|
||||
|
||||
1. **完全保留現有內容**:
|
||||
- **一字不改**現有描述內容
|
||||
- 仅補充空白注釋和佔位符
|
||||
- 尊重用戶有意編寫的內容
|
||||
|
||||
2. **模板優先級**:
|
||||
- 現有 PR 描述 > `.github/PULL_REQUEST_TEMPLATE.md` > 默認
|
||||
- 完全遵循項目特定的模板結構
|
||||
|
||||
3. **標簽約束**:
|
||||
- 如存在 `.github/labels.yml` 則優先使用
|
||||
- 不存在時從 GitHub API 獲取現有標簽
|
||||
- 禁止創建新標簽
|
||||
- 自動選擇最多 3 個
|
||||
|
||||
4. **安全更新**:
|
||||
- 推薦使用 `--dry-run` 預先確認
|
||||
- 包含敏感資訊的更改時顯示警告
|
||||
- 保存原始描述作為備份
|
||||
|
||||
5. **保持一致性**:
|
||||
- 符合項目現有 PR 風格
|
||||
- 統一語言 (中文/英語)
|
||||
- 繼承標簽規則
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常見問題
|
||||
|
||||
1. **找不到 PR**: 檢查分支名與 PR 的關聯
|
||||
2. **權限錯誤**: 檢查 GitHub CLI 的認證狀態
|
||||
3. **無法設置標簽**: 檢查倉庫權限
|
||||
4. **HTML 注釋被轉義**: GitHub CLI 的規格導致 `<!-- -->` 被轉換為 `<!-- -->`
|
||||
|
||||
### GitHub CLI 的 HTML 注釋轉義問題
|
||||
|
||||
**重要**: GitHub CLI (`gh pr edit`) 會自動轉義 HTML 注釋。此外，Shell 的重定向處理可能混入 `EOF < /dev/null` 等非法字符串。
|
||||
|
||||
#### 根本解決方案
|
||||
|
||||
1. **使用 GitHub API 的 --field 選項**: 使用 `--field` 進行適当的轉義處理
|
||||
2. **簡化 Shell 處理**: 避免復杂的重定向和管道處理
|
||||
3. **簡化模板處理**: 废除 HTML 注釋移除處理，完全保留
|
||||
4. **正確處理 JSON 轉義**: 正確處理特殊字符
|
||||
|
||||
### 調試選項
|
||||
|
||||
```bash
|
||||
# 輸出詳细日誌 (實現時添加)
|
||||
/pr-auto-update --verbose
|
||||
```
|
||||
251
commands/pr-create.md
Normal file
251
commands/pr-create.md
Normal file
@@ -0,0 +1,251 @@
|
||||
## PR 創建 (已不推薦)
|
||||
|
||||
> 不再推薦：請優先使用 `/pr-create-smart` 生成高質量的 PR 描述草稿，然後使用 gh/GUI 創建 PR。本命令属于“端到端自動創建 PR(保留模板、自動打標簽、創建 Draft)”的旧方案，仅為兼容保留。
|
||||
|
||||
基于 Git 變更分析的自動 PR 創建，實現高效的 Pull Request 工作流程。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 基于變更分析的自動 PR 創建
|
||||
git add . && git commit -m "feat: 實現用戶認證功能"
|
||||
"分析變更內容並使用適当的描述和標簽創建 Draft PR"
|
||||
|
||||
# 保留現有模板的更新
|
||||
cp .github/PULL_REQUEST_TEMPLATE.md pr_body.md
|
||||
"完全保留模板結構並補充變更內容"
|
||||
|
||||
# 逐步提升質量
|
||||
gh pr ready
|
||||
"質量確認完成後，更改為 Ready for Review"
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 1. 創建分支並提交
|
||||
git checkout main && git pull
|
||||
git checkout -b feat-user-profile
|
||||
git add . && git commit -m "feat: 實現用戶檔案功能"
|
||||
git push -u origin feat-user-profile
|
||||
|
||||
# 2. PR 創建
|
||||
"請按以下步骤創建 PR：
|
||||
1. 使用 git diff --cached 確認變更內容
|
||||
2. 使用 .github/PULL_REQUEST_TEMPLATE.md 創建描述
|
||||
3. 從變更內容選擇最多 3 個適当的標簽
|
||||
4. 創建 Draft PR(保留 HTML 注釋)"
|
||||
|
||||
# 3. CI 確認後轉為 Ready
|
||||
"CI 通過後將 PR 更改為 Ready for Review"
|
||||
```
|
||||
|
||||
### 執行步骤
|
||||
|
||||
#### 1. 分支創建
|
||||
|
||||
```bash
|
||||
# 遵循準則的命名規則: {type}-{subject}
|
||||
git checkout main
|
||||
git pull
|
||||
git checkout -b feat-user-authentication
|
||||
|
||||
# 確認分支 (顯示當前分支名)
|
||||
git branch --show-current
|
||||
```
|
||||
|
||||
#### 2. 提交
|
||||
|
||||
```bash
|
||||
# 暂存變更
|
||||
git add .
|
||||
|
||||
# 遵循準則的提交消息
|
||||
git commit -m "feat: 實現用戶認證 API"
|
||||
```
|
||||
|
||||
#### 3. 推送到远程
|
||||
|
||||
```bash
|
||||
# 首次推送 (設置 upstream)
|
||||
git push -u origin feat-user-authentication
|
||||
|
||||
# 後續推送
|
||||
git push
|
||||
```
|
||||
|
||||
#### 4. 基于自動分析創建 Draft PR
|
||||
|
||||
**步骤 1: 分析變更內容**
|
||||
|
||||
```bash
|
||||
# 獲取文件變更 (確認已暂存的變更)
|
||||
git diff --cached --name-only
|
||||
|
||||
# 內容分析 (最多 1000 行)
|
||||
git diff --cached | head -1000
|
||||
```
|
||||
|
||||
**步骤 2: 自動生成描述**
|
||||
|
||||
```bash
|
||||
# 模板處理優先級
|
||||
# 1. 現有 PR 描述 (完全保留)
|
||||
# 2. .github/PULL_REQUEST_TEMPLATE.md
|
||||
# 3. 默認模板
|
||||
|
||||
cp .github/PULL_REQUEST_TEMPLATE.md pr_body.md
|
||||
# 保留 HTML 注釋·分隔線，仅補充空白部分
|
||||
```
|
||||
|
||||
**步骤 3: 自動選擇標簽**
|
||||
|
||||
```bash
|
||||
# 獲取可用標簽 (非交互式)
|
||||
"從 .github/labels.yml 或 GitHub 倉庫獲取可用標簽，根據變更內容自動選擇適当的標簽"
|
||||
|
||||
# 通過模式匹配自動選擇 (最多 3 個)
|
||||
# - 文檔: *.md, docs/ → documentation|docs
|
||||
# - 測試: test, spec → test|testing
|
||||
# - Bug 修復: fix|bug → bug|fix
|
||||
# - 新功能: feat|feature → feature|enhancement
|
||||
```
|
||||
|
||||
**步骤 4: 通過 GitHub API 創建 PR(保留 HTML 注釋)**
|
||||
|
||||
```bash
|
||||
# PR 創建
|
||||
"使用以下資訊創建 Draft PR：
|
||||
- 標題: 從提交消息自動生成
|
||||
- 描述: 使用 .github/PULL_REQUEST_TEMPLATE.md 適当填寫
|
||||
- 標簽: 從變更內容自動選擇 (最多 3 個)
|
||||
- 基礎分支: main
|
||||
- 完全保留 HTML 注釋"
|
||||
```
|
||||
|
||||
**方法 B: GitHub MCP(備用)**
|
||||
|
||||
```javascript
|
||||
// 保留 HTML 注釋的 PR 創建
|
||||
mcp_github_create_pull_request({
|
||||
owner: "organization",
|
||||
repo: "repository",
|
||||
base: "main",
|
||||
head: "feat-user-authentication",
|
||||
title: "feat: 實現用戶認證",
|
||||
body: prBodyContent, // 包含 HTML 注釋的完整內容
|
||||
draft: true,
|
||||
maintainer_can_modify: true,
|
||||
});
|
||||
```
|
||||
|
||||
### 自動標簽選擇系統
|
||||
|
||||
#### 基于文件模式的判定
|
||||
|
||||
- **文檔**: `*.md`, `README`, `docs/` → `documentation|docs|doc`
|
||||
- **測試**: `test`, `spec` → `test|testing`
|
||||
- **CI/CD**: `.github/`, `*.yml`, `Dockerfile` → `ci|build|infra|ops`
|
||||
- **依賴**: `package.json`, `pubspec.yaml` → `dependencies|deps`
|
||||
|
||||
#### 基于變更內容的判定
|
||||
|
||||
- **Bug 修復**: `fix|bug|error|crash|修復` → `bug|fix`
|
||||
- **新功能**: `feat|feature|add|implement|新功能|實現` → `feature|enhancement|feat`
|
||||
- **重構**: `refactor|clean|重構` → `refactor|cleanup|clean`
|
||||
- **性能**: `performance|perf|optimize` → `performance|perf`
|
||||
- **安全**: `security|secure` → `security`
|
||||
|
||||
#### 約束條件
|
||||
|
||||
- **最多 3 個**: 自動選擇的上限
|
||||
- **仅現有標簽**: 禁止新建
|
||||
- **部分匹配**: 通過關鍵詞包含進行判定
|
||||
|
||||
### 項目準則
|
||||
|
||||
#### 基本原則
|
||||
|
||||
1. **必须以 Draft 開始**: 所有 PR 都以 Draft 狀態創建
|
||||
2. **逐步提升質量**: 阶段 1(基本實現)→ 阶段 2(添加測試)→ 阶段 3(更新文檔)
|
||||
3. **適当的標簽**: 必须添加最多 3 种標簽
|
||||
4. **使用模板**: 必须使用 `.github/PULL_REQUEST_TEMPLATE.md`
|
||||
5. **中文空格**: 中文與半角英數字之間必须有半角空格
|
||||
|
||||
#### 分支命名規則
|
||||
|
||||
```text
|
||||
{type}-{subject}
|
||||
|
||||
示例:
|
||||
- feat-user-profile
|
||||
- fix-login-error
|
||||
- refactor-api-client
|
||||
```
|
||||
|
||||
#### 提交消息
|
||||
|
||||
```text
|
||||
{type}: {description}
|
||||
|
||||
示例:
|
||||
- feat: 實現用戶認證 API
|
||||
- fix: 修復登錄錯誤
|
||||
- docs: 更新 README
|
||||
```
|
||||
|
||||
### 模板處理系統
|
||||
|
||||
#### 處理優先級
|
||||
|
||||
1. **現有 PR 描述**: **完全沿用**已編寫的內容
|
||||
2. **項目模板**: 保持 `.github/PULL_REQUEST_TEMPLATE.md` 結構
|
||||
3. **默認模板**: 以上不存在時使用
|
||||
|
||||
#### 現有內容保留規則
|
||||
|
||||
- **一字不改**: 已編寫的內容
|
||||
- **仅補充空白部分**: 用變更內容填充佔位符部分
|
||||
- **保留功能性注釋**: 保持 `<!-- Copilot review rule -->` 等
|
||||
- **保留 HTML 注釋**: 完全保留 `<!-- ... -->`
|
||||
- **保留分隔線**: 保持 `---` 等結構
|
||||
|
||||
#### HTML 注釋保留的處理方法
|
||||
|
||||
**重要**: GitHub CLI (`gh pr edit`) 會自動轉義 HTML 注釋，在 Shell 處理中可能混入 `EOF < /dev/null` 等非法字符串。
|
||||
|
||||
**根本解決方案**:
|
||||
|
||||
1. **使用 GitHub API 的 --field 選項**: 通過適当的轉義處理保留 HTML 注釋
|
||||
2. **簡化模板處理**: 避免復杂的管道處理和重定向
|
||||
3. **完全保留方法**: 废除 HTML 注釋刪除處理，完全保留模板
|
||||
|
||||
### 審查評論響應
|
||||
|
||||
```bash
|
||||
# 變更後重新提交
|
||||
git add .
|
||||
git commit -m "fix: 基于審查反饋的更正"
|
||||
git push
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
#### HTML 注釋保留的重要性
|
||||
|
||||
- **GitHub CLI 限制**: `gh pr edit` 會轉義 HTML 注釋，混入非法字符串
|
||||
- **根本規避策略**: 使用 GitHub API 的 `--field` 選項進行適当的轉義處理
|
||||
- **模板完全保留**: 废除 HTML 注釋刪除處理，完全維護結構
|
||||
|
||||
#### 自動化的約束
|
||||
|
||||
- **禁止新建標簽**: 不可創建 `.github/labels.yml` 定義外的標簽
|
||||
- **最多 3 個標簽**: 自動選擇的上限
|
||||
- **現有內容優先**: 不更改手動編寫的內容
|
||||
|
||||
#### 逐步提升質量
|
||||
|
||||
- **Draft 必须**: 所有 PR 以 Draft 開始
|
||||
- **CI 確認**: 使用 `gh pr checks` 確認狀態
|
||||
- **轉為 Ready**: 質量確認完成後使用 `gh pr ready`
|
||||
- **完全遵守模板**: 維護項目特有的結構
|
||||
143
commands/pr-feedback.md
Normal file
143
commands/pr-feedback.md
Normal file
@@ -0,0 +1,143 @@
|
||||
## PR 反饋處理
|
||||
|
||||
高效處理 Pull Request 的審查評論，採用錯誤分析三阶段方法寻求根本解決方案。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 獲取並分析審查評論
|
||||
gh pr view --comments
|
||||
「請按優先級分類審查評論並創建應對計劃」
|
||||
|
||||
# 錯誤相關評論的詳细分析
|
||||
gh pr checks
|
||||
「請用三阶段方法分析 CI 錯誤並找出根本原因」
|
||||
|
||||
# 修復完成後的質量確認
|
||||
npm test && npm run lint
|
||||
「修復已完成，請檢查回歸測試和代碼質量」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 執行評論分類
|
||||
gh pr view 123 --comments | head -20
|
||||
"請將審查評論分類為 must/imo/nits/q 並決定處理顺序"
|
||||
|
||||
# 收集錯誤資訊
|
||||
npm run build 2>&1 | tee error.log
|
||||
"請找出構建錯誤的根本原因並提出適当的修復方法"
|
||||
|
||||
# 確認修復實現
|
||||
git diff HEAD~1
|
||||
"請評估此修復是否恰当解決了審查指出的問題"
|
||||
```
|
||||
|
||||
### 評論分類體系
|
||||
|
||||
```text
|
||||
🔴 must: 必须修復
|
||||
├─ 安全問題
|
||||
├─ 功能缺陷
|
||||
├─ 設計原則违反
|
||||
└─ 規範违反
|
||||
|
||||
🟡 imo: 改進建議
|
||||
├─ 更好的實現方法
|
||||
├─ 性能改進
|
||||
├─ 可讀性提升
|
||||
└─ 重構建議
|
||||
|
||||
🟢 nits: 轻微指摘
|
||||
├─ 拼寫錯誤更正
|
||||
├─ 縮進調整
|
||||
├─ 注釋添加
|
||||
└─ 命名微調
|
||||
|
||||
🔵 q: 問題與確認
|
||||
├─ 實現意圖確認
|
||||
├─ 規格明確化
|
||||
├─ 設計決策背景
|
||||
└─ 替代方案探讨
|
||||
```
|
||||
|
||||
### 錯誤分析三阶段方法
|
||||
|
||||
#### 第一阶段：資訊收集
|
||||
|
||||
**必须執行**
|
||||
|
||||
- 完整獲取錯誤消息
|
||||
- 確認堆棧跟蹤
|
||||
- 確定重現條件
|
||||
|
||||
**推薦執行**
|
||||
|
||||
- 收集環境資訊
|
||||
- 最近的更改歷史
|
||||
- 確認相關日誌
|
||||
|
||||
#### 第二阶段：根本原因分析
|
||||
|
||||
- 應用 5 Whys 分析
|
||||
- 追蹤依賴關系
|
||||
- 確認環境差異
|
||||
- 創建最小重現代碼
|
||||
|
||||
#### 第三阶段：解決方案實施
|
||||
|
||||
- 立即處理 (熱修復)
|
||||
- 根本解決 (本質修復)
|
||||
- 預防措施 (防止復發)
|
||||
|
||||
### 應對流程
|
||||
|
||||
1. **評論分析**: 按優先級分類
|
||||
2. **修復計劃**: 決定處理顺序
|
||||
3. **阶段性修復**: Critical → High → Medium → Low
|
||||
4. **質量確認**: 測試、代碼檢查、構建
|
||||
5. **進度報告**: 具體說明修復內容
|
||||
|
||||
### 修復後的確認
|
||||
|
||||
```bash
|
||||
# 基本檢查
|
||||
npm test
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# 回歸測試
|
||||
npm run test:e2e
|
||||
|
||||
# 代碼質量
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
### 回復模板
|
||||
|
||||
**修復完成報告**
|
||||
|
||||
```markdown
|
||||
@reviewer 感谢您的指正。
|
||||
修復已完成：
|
||||
|
||||
- [具體修復內容]
|
||||
- [測試結果]
|
||||
- [確認方法]
|
||||
```
|
||||
|
||||
**技術判斷說明**
|
||||
|
||||
```markdown
|
||||
實現背景：[原因]
|
||||
考虑的替代方案：[選項與判斷依據]
|
||||
採用方案的優點：[優勢]
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
- **遵守優先級**: 按 Critical → High → Medium → Low 顺序處理
|
||||
- **測試優先**: 修復前確認回歸測試
|
||||
- **明確報告**: 具體描述修復內容和確認方法
|
||||
- **建設性對話**: 基于技術依據的礼貌沟通
|
||||
78
commands/pr-issue.md
Normal file
78
commands/pr-issue.md
Normal file
@@ -0,0 +1,78 @@
|
||||
## Issue 列表
|
||||
|
||||
顯示當前倉庫的開放 Issue 列表，並按優先級排序。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 向 Claude 請求
|
||||
「請按優先級顯示開放的 Issue 列表」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 獲取倉庫資訊
|
||||
gh repo view --json nameWithOwner | jq -r '.nameWithOwner'
|
||||
|
||||
# 獲取開放 Issue 資訊並請求 Claude
|
||||
gh issue list --state open --json number,title,author,createdAt,updatedAt,labels,assignees,comments --limit 30
|
||||
|
||||
「請按優先級整理上述 Issue，並包含每個 Issue 的 2 行概要。使用上面獲取的倉庫名生成 URL」
|
||||
```
|
||||
|
||||
### 顯示格式
|
||||
|
||||
```text
|
||||
開放 Issue 列表 (按優先級排序)
|
||||
|
||||
### 高優先級
|
||||
#編号 標題 [標簽] | 作者 | 開放時长 | 評論數 | 負責人
|
||||
├─ 概要第 1 行
|
||||
└─ 概要第 2 行
|
||||
https://github.com/owner/repo/issues/編号
|
||||
|
||||
### 中優先級
|
||||
(相同格式)
|
||||
|
||||
### 低優先級
|
||||
(相同格式)
|
||||
```
|
||||
|
||||
### 優先級判定標準
|
||||
|
||||
**高優先級**
|
||||
|
||||
- 带有 `bug` 標簽的 Issue
|
||||
- 带有 `critical` 或 `urgent` 標簽的 Issue
|
||||
- 带有 `security` 標簽的 Issue
|
||||
|
||||
**中優先級**
|
||||
|
||||
- 带有 `enhancement` 標簽的 Issue
|
||||
- 带有 `feature` 標簽的 Issue
|
||||
- 已分配負責人的 Issue
|
||||
|
||||
**低優先級**
|
||||
|
||||
- 带有 `documentation` 標簽的 Issue
|
||||
- 带有 `good first issue` 標簽的 Issue
|
||||
- 带有 `wontfix` 或 `duplicate` 標簽的 Issue
|
||||
|
||||
### 按標簽筛選
|
||||
|
||||
```bash
|
||||
# 仅獲取特定標簽的 Issue
|
||||
gh issue list --state open --label "bug" --json number,title,author,createdAt,labels,comments --limit 30
|
||||
|
||||
# 使用多個標簽筛選 (AND 條件)
|
||||
gh issue list --state open --label "bug,high-priority" --json number,title,author,createdAt,labels,comments --limit 30
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
- 需要安裝 GitHub CLI (`gh`)
|
||||
- 仅顯示開放狀態的 Issue
|
||||
- 最多顯示 30 個 Issue
|
||||
- 時长是從 Issue 開放至今的時間
|
||||
- Issue URL 根據實際倉庫名自動生成
|
||||
66
commands/pr-list.md
Normal file
66
commands/pr-list.md
Normal file
@@ -0,0 +1,66 @@
|
||||
## PR 列表
|
||||
|
||||
顯示當前倉庫的開放 PR 列表，並按優先級排序。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 向 Claude 請求
|
||||
「請按優先級顯示開放的 PR 列表」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 獲取倉庫資訊
|
||||
gh repo view --json nameWithOwner | jq -r '.nameWithOwner'
|
||||
|
||||
# 獲取開放 PR 資訊並請求 Claude
|
||||
gh pr list --state open --draft=false --json number,title,author,createdAt,additions,deletions,reviews --limit 30
|
||||
|
||||
「請按優先級整理上述 PR，並包含每個 PR 的 2 行概要。使用上面獲取的倉庫名生成 URL」
|
||||
```
|
||||
|
||||
### 顯示格式
|
||||
|
||||
```text
|
||||
開放 PR 列表 (按優先級排序)
|
||||
|
||||
### 高優先級
|
||||
#編号 標題 [Draft/DNM] | 作者 | 開放時长 | 批準數 | +添加/-刪除
|
||||
├─ 概要第 1 行
|
||||
└─ 概要第 2 行
|
||||
https://github.com/owner/repo/pull/編号
|
||||
|
||||
### 中優先級
|
||||
(相同格式)
|
||||
|
||||
### 低優先級
|
||||
(相同格式)
|
||||
```
|
||||
|
||||
### 優先級判定標準
|
||||
|
||||
**高優先級**
|
||||
|
||||
- `fix:` Bug 修復
|
||||
- `release:` 發布工作
|
||||
|
||||
**中優先級**
|
||||
|
||||
- `feat:` 新功能
|
||||
- `update:` 功能改進
|
||||
- 其他常規 PR
|
||||
|
||||
**低優先級**
|
||||
|
||||
- 包含 DO NOT MERGE 的 PR
|
||||
- Draft 狀態的 `test:`、`build:`、`perf:` PR
|
||||
|
||||
### 注意事項
|
||||
|
||||
- 需要安裝 GitHub CLI (`gh`)
|
||||
- 仅顯示開放狀態的 PR(排除 Draft)
|
||||
- 最多顯示 30 個 PR
|
||||
- 時长是從 PR 開放至今的時間
|
||||
- PR URL 根據實際倉庫名自動生成
|
||||
172
commands/pr-review.md
Normal file
172
commands/pr-review.md
Normal file
@@ -0,0 +1,172 @@
|
||||
## PR 審查
|
||||
|
||||
通過 Pull Request 的系統化審查確保代碼質量和架構健全性。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# PR 的全面審查
|
||||
gh pr view 123 --comments
|
||||
"系統化審查這個 PR，從代碼質量、安全性、架構角度提供反饋"
|
||||
|
||||
# 安全性專注審查
|
||||
gh pr diff 123
|
||||
"專注于安全風險和漏洞進行審查"
|
||||
|
||||
# 架構視角的審查
|
||||
gh pr checkout 123 && find . -name "*.js" | head -10
|
||||
"從層級分離、依賴關系、SOLID 原則的角度評估架構"
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 代碼質量的數值評估
|
||||
find . -name "*.js" -exec wc -l {} + | sort -rn | head -5
|
||||
"評估代碼的復杂度、函數大小、重復度並指出改進點"
|
||||
|
||||
# 安全漏洞檢查
|
||||
grep -r "password\|secret\|token" . --include="*.js" | head -10
|
||||
"檢查敏感資訊洩露、硬編碼、認證绕過的風險"
|
||||
|
||||
# 架構违規檢測
|
||||
grep -r "import.*from.*\\.\\./\\.\\." . --include="*.js"
|
||||
"評估層級违規、循環依賴、耦合度問題"
|
||||
```
|
||||
|
||||
### 評論分類體系
|
||||
|
||||
```text
|
||||
🔴 critical.must: 致命問題
|
||||
├─ 安全漏洞
|
||||
├─ 數據一致性問題
|
||||
└─ 系統故障風險
|
||||
|
||||
🟡 high.imo: 高優先級改進
|
||||
├─ 功能故障風險
|
||||
├─ 性能問題
|
||||
└─ 可維護性大幅降低
|
||||
|
||||
🟢 medium.imo: 中優先級改進
|
||||
├─ 可讀性提升
|
||||
├─ 代碼結構改進
|
||||
└─ 測試質量提升
|
||||
|
||||
🟢 low.nits: 轻微指摘
|
||||
├─ 風格統一
|
||||
├─ 拼寫錯誤更正
|
||||
└─ 注釋添加
|
||||
|
||||
🔵 info.q: 問題·資訊提供
|
||||
├─ 實現意圖確認
|
||||
├─ 設計決策背景
|
||||
└─ 最佳實践分享
|
||||
```
|
||||
|
||||
### 審查觀點
|
||||
|
||||
#### 1. 代碼正確性
|
||||
|
||||
- **邏輯錯誤**: 邊界值、Null 檢查、異常處理
|
||||
- **數據一致性**: 類型安全、驗證
|
||||
- **錯誤處理**: 全面性、適当處理
|
||||
|
||||
#### 2. 安全性
|
||||
|
||||
- **認證·授權**: 適当檢查、權限管理
|
||||
- **輸入驗證**: SQL 注入、XSS 對策
|
||||
- **敏感資訊**: 禁止日誌輸出、加密
|
||||
|
||||
#### 3. 性能
|
||||
|
||||
- **算法**: 時間復杂度、內存效率
|
||||
- **數據庫**: N+1 查询、索引優化
|
||||
- **資源**: 內存洩漏、緩存利用
|
||||
|
||||
#### 4. 架構
|
||||
|
||||
- **層級分離**: 依賴方向、適当分離
|
||||
- **耦合度**: 松耦合、接口使用
|
||||
- **SOLID 原則**: 單一职責、開闭原則、依賴倒置
|
||||
|
||||
### 審查流程
|
||||
|
||||
1. **事前確認**: PR 資訊、變更差異、相關 Issue
|
||||
2. **系統化檢查**: 安全性 → 正確性 → 性能 → 架構
|
||||
3. **建設性反饋**: 具體改進建議和代碼示例
|
||||
4. **後續跟進**: 更正確認、CI 狀態、最終批準
|
||||
|
||||
### 有效的評論示例
|
||||
|
||||
#### 安全問題模板
|
||||
|
||||
**格式：**
|
||||
|
||||
```text
|
||||
**critical.must.** [問題描述]
|
||||
|
||||
[改進建議代碼]
|
||||
|
||||
[説明文字]
|
||||
```
|
||||
|
||||
**示例：**
|
||||
|
||||
```text
|
||||
**critical.must.** 密碼以明文保存
|
||||
|
||||
// 更正建議
|
||||
const bcrypt = require('bcrypt');
|
||||
const hashedPassword = await bcrypt.hash(password, 12);
|
||||
|
||||
為防止安全風險，必须進行哈希處理。
|
||||
```
|
||||
|
||||
#### 性能改進模板
|
||||
|
||||
**格式：**
|
||||
|
||||
```text
|
||||
**high.imo.** [性能問題描述]
|
||||
|
||||
[改進建議代碼]
|
||||
|
||||
[效果說明]
|
||||
```
|
||||
|
||||
**示例：**
|
||||
|
||||
```text
|
||||
**high.imo.** 會發生 N+1 查询問題
|
||||
|
||||
// 改進建議: Eager Loading
|
||||
const users = await User.findAll({ include: [Post] });
|
||||
|
||||
可以大幅减少查询數量。
|
||||
```
|
||||
|
||||
#### 架構违規模板
|
||||
|
||||
**格式：**
|
||||
|
||||
```text
|
||||
**high.must.** [架構問題描述]
|
||||
|
||||
[具體說明和解決方案]
|
||||
```
|
||||
|
||||
**示例：**
|
||||
|
||||
```text
|
||||
**high.must.** 發生了層級违規
|
||||
|
||||
領域層直接依賴基礎設施層。
|
||||
請通過依賴倒置原則引入接口。
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
- **建設性語气**: 協作而非攻擊性的沟通
|
||||
- **具體建議**: 不仅指出問題，還要提供解決方案
|
||||
- **優先級排序**: 按 Critical → High → Medium → Low 顺序處理
|
||||
- **持續改進**: 將審查結果知識庫化
|
||||
305
commands/refactor.md
Normal file
305
commands/refactor.md
Normal file
@@ -0,0 +1,305 @@
|
||||
## Refactor
|
||||
|
||||
實施安全且漸進式的代碼重構，定量評估 SOLID 原則的遵守狀況。可視化技術債務，明確改善優先級。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 複雜代碼的識別和重構計劃
|
||||
find . -name "*.js" -exec wc -l {} + | sort -rn | head -10
|
||||
「請重構大檔案以減少複雜度」
|
||||
|
||||
# 重複代碼的檢測與整合
|
||||
grep -r "function processUser" . --include="*.js"
|
||||
「請用 Extract Method 整合重複的函數」
|
||||
|
||||
# SOLID 原則違反的檢測
|
||||
grep -r "class.*Service" . --include="*.js" | head -10
|
||||
「請評估這些類是否遵循單一責任原則」
|
||||
```
|
||||
|
||||
### 基本範例
|
||||
|
||||
```bash
|
||||
# 長方法的檢測
|
||||
grep -A 50 "function" src/*.js | grep -B 50 -A 50 "return" | wc -l
|
||||
"請用 Extract Method 分割 50 行以上的方法"
|
||||
|
||||
# 條件分支的複雜度
|
||||
grep -r "if.*if.*if" . --include="*.js"
|
||||
"請用 Strategy 模式改善巢狀條件語句"
|
||||
|
||||
# 代碼異味的檢測
|
||||
grep -r "TODO\|FIXME\|HACK" . --exclude-dir=node_modules
|
||||
"請解決成為技術債務的註釋"
|
||||
```
|
||||
|
||||
### 重構技法
|
||||
|
||||
#### Extract Method(方法提取)
|
||||
|
||||
```javascript
|
||||
// Before: 冗長的方法
|
||||
function processOrder(order) {
|
||||
// 50 行的複雜處理
|
||||
}
|
||||
|
||||
// After: 責任分離
|
||||
function processOrder(order) {
|
||||
validateOrder(order);
|
||||
calculateTotal(order);
|
||||
saveOrder(order);
|
||||
}
|
||||
```
|
||||
|
||||
#### Replace Conditional with Polymorphism
|
||||
|
||||
```javascript
|
||||
// Before: switch 語句
|
||||
function getPrice(user) {
|
||||
switch (user.type) {
|
||||
case "premium":
|
||||
return basePrice * 0.8;
|
||||
case "regular":
|
||||
return basePrice;
|
||||
}
|
||||
}
|
||||
|
||||
// After: Strategy 模式
|
||||
class PremiumPricing {
|
||||
calculate(basePrice) {
|
||||
return basePrice * 0.8;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SOLID 原則評分 (0-100 分)
|
||||
|
||||
#### 評估標準與配分
|
||||
|
||||
```text
|
||||
S - Single Responsibility(20 分)
|
||||
├─ 類的責任數: 1 個 (20 分) | 2 個 (15 分) | 3 個 (10 分) | 4 個以上 (5 分)
|
||||
├─ 方法數: <7 個 (+5 分) | 7-15 個 (+3 分) | >15 個 (0 分)
|
||||
├─ 變更理由的明確性: 明確 (+5 分) | 模糊 (0 分)
|
||||
└─ 分數例: UserService(認證+資料處理) = 10 分
|
||||
|
||||
O - Open/Closed(20 分)
|
||||
├─ 擴展點: Strategy/Template Method(20 分) | 僅繼承 (10 分) | 無 (5 分)
|
||||
├─ 新功能添加時的既有代碼變更: 不必要 (+5 分) | 最小化 (+3 分) | 必要 (0 分)
|
||||
├─ 介面利用: 適當 (+5 分) | 部分 (+3 分) | 無 (0 分)
|
||||
└─ 分數例: PaymentProcessor(Strategy) = 20 分
|
||||
|
||||
L - Liskov Substitution(20 分)
|
||||
├─ 衍生類的契約遵守: 完全 (20 分) | 部分 (10 分) | 違反 (0 分)
|
||||
├─ 前置條件的強化: 無 (+5 分) | 有 (-5 分)
|
||||
├─ 後置條件的弱化: 無 (+5 分) | 有 (-5 分)
|
||||
└─ 分數例: Square extends Rectangle = 0 分 (違反)
|
||||
|
||||
I - Interface Segregation(20 分)
|
||||
├─ 介面大小: 1-3 方法 (20 分) | 4-7(15 分) | 8+(5 分)
|
||||
├─ 未使用方法實現: 無 (+5 分) | 1-2 個 (+2 分) | 3 個以上 (0 分)
|
||||
├─ 角色的明確性: 單一角色 (+5 分) | 多重角色 (0 分)
|
||||
└─ 分數例: Readable/Writable 分離 = 20 分
|
||||
|
||||
D - Dependency Inversion(20 分)
|
||||
├─ 依賴方向: 僅抽象 (20 分) | 混合 (10 分) | 僅具象 (5 分)
|
||||
├─ DI 利用: Constructor Injection(+5 分) | Setter(+3 分) | 無 (0 分)
|
||||
├─ 可測試性: Mock 可能 (+5 分) | 困難 (0 分)
|
||||
└─ 分數例: Repository Pattern = 20 分
|
||||
|
||||
總分 = S + O + L + I + D
|
||||
├─ 90-100 分: Excellent(SOLID 完全遵循)
|
||||
├─ 70-89 分: Good(輕微改善空間)
|
||||
├─ 50-69 分: Fair(建議重構)
|
||||
├─ 30-49 分: Poor(大規模改善必要)
|
||||
└─ 0-29 分: Critical(設計重新檢討必須)
|
||||
```
|
||||
|
||||
### 技術債務的定量化
|
||||
|
||||
#### 債務計算公式
|
||||
|
||||
```text
|
||||
技術債務 (時間) = 複雜度分數 × 影響範圍 × 修正難度
|
||||
|
||||
複雜度分數:
|
||||
├─ 循環複雜度: 1-5(低) | 6-10(中) | 11-20(高) | 21+(危險)
|
||||
├─ 認知複雜度: 巢狀深度 × 條件分支數
|
||||
├─ 代碼行數: <50(1 分) | 50-200(2 分) | 200-500(3 分) | 500+(5 分)
|
||||
└─ 重複率: 0-10%(1 分) | 10-30%(2 分) | 30-50%(3 分) | 50%+(5 分)
|
||||
|
||||
影響範圍:
|
||||
├─ 依賴模組數: 直接依賴 + 間接依賴 × 0.5
|
||||
├─ 使用頻率: API 呼叫次數/日
|
||||
├─ 業務重要度: Critical(×3) | High(×2) | Medium(×1) | Low(×0.5)
|
||||
└─ 團隊知識: 理解者 1 名 (×3) | 2-3 名 (×2) | 4 名以上 (×1)
|
||||
|
||||
修正難度:
|
||||
├─ 測試覆蓋率: 0%(×3) | <50%(×2) | 50-80%(×1.5) | >80%(×1)
|
||||
├─ 文件: 無 (×2) | 不充分 (×1.5) | 充分 (×1)
|
||||
├─ 依賴關係: 緊耦合 (×3) | 中度 (×2) | 鬆耦合 (×1)
|
||||
└─ 變更風險: Breaking Change(×3) | 相容性考慮 (×2) | 安全 (×1)
|
||||
|
||||
成本換算:
|
||||
├─ 時間成本: 債務時間 × 開發者時薪
|
||||
├─ 機會損失: 新功能開發延遲日數 × 日營收影響
|
||||
├─ 品質成本: Bug 發生機率 × 修正成本 × 發生頻率
|
||||
└─ 總成本: 時間 + 機會損失 + 品質成本
|
||||
```
|
||||
|
||||
#### 優先級矩陣
|
||||
|
||||
| 優先級 | 影響度 | 修正成本 | 回應期限 | 具體例 | 建議行動 |
|
||||
| ------------------------- | ------ | -------- | -------- | ------------------------ | -------------------- |
|
||||
| **Critical(即刻回應)** | 高 | 低 | 1 週內 | God Object、循環依賴 | 立即開始重構 |
|
||||
| **Important(計劃性回應)** | 高 | 高 | 1 個月內 | 大規模責任分離、架構變更 | 納入 Sprint 計劃 |
|
||||
| **Watch(監視對象)** | 低 | 高 | 3 個月內 | 複雜度高的內部處理 | 指標監視、惡化時回應 |
|
||||
| **Acceptable(容許範圍)** | 低 | 低 | 不必要 | 輕微的代碼異味 | 通常重構處理 |
|
||||
|
||||
### 重構程序
|
||||
|
||||
1. **現況分析與測量**
|
||||
- 複雜度測量 (循環・認知)
|
||||
- SOLID 分數計算 (0-100 分)
|
||||
- 技術債務的定量化 (時間/成本)
|
||||
- 優先級矩陣製作
|
||||
|
||||
2. **階段性執行**
|
||||
- 小步驟 (15-30 分鐘單位)
|
||||
- 各變更後的測試執行
|
||||
- 頻繁的提交
|
||||
- SOLID 分數的持續測量
|
||||
|
||||
3. **品質確認**
|
||||
- 測試覆蓋率維持
|
||||
- 效能測量
|
||||
- 技術債務削減確認
|
||||
- 代碼審查
|
||||
|
||||
### 常見代碼異味與債務分數
|
||||
|
||||
| 代碼異味 | 檢測標準 | 債務分數 | 改善技法 |
|
||||
| ----------------------- | -------------------- | ----------- | ----------------------- |
|
||||
| **God Object** | 責任 >3, 方法 >20 | 高 (15-20h) | Extract Class, SRP 適用 |
|
||||
| **Long Method** | 行數 >50, 複雜度 >10 | 中 (5-10h) | Extract Method |
|
||||
| **Duplicate Code** | 重複率 >30% | 高 (10-15h) | Extract Method/Class |
|
||||
| **Large Class** | 行數 >300, 方法 >15 | 高 (10-20h) | Extract Class |
|
||||
| **Long Parameter List** | 參數 >4 | 低 (2-5h) | Parameter Object |
|
||||
| **Feature Envy** | 其他類參照 >5 | 中 (5-10h) | Move Method |
|
||||
| **Data Clumps** | 相同參數群的重複 | 低 (3-5h) | Extract Class |
|
||||
| **Primitive Obsession** | 基本型別的過度使用 | 中 (5-8h) | Replace with Object |
|
||||
| **Switch Statements** | case >5 | 中 (5-10h) | Strategy Pattern |
|
||||
| **Shotgun Surgery** | 變更時的影響處 >3 | 高 (10-15h) | Move Method/Field |
|
||||
|
||||
### 實踐例：SOLID 分數評估
|
||||
|
||||
```javascript
|
||||
// 評估對象: UserService 類
|
||||
class UserService {
|
||||
constructor(db, cache, logger, emailService) { // 4 個依賴
|
||||
this.db = db;
|
||||
this.cache = cache;
|
||||
this.logger = logger;
|
||||
this.emailService = emailService;
|
||||
}
|
||||
|
||||
// 責任 1: 認證
|
||||
authenticate(username, password) { /* ... */ }
|
||||
refreshToken(token) { /* ... */ }
|
||||
|
||||
// 責任 2: 用戶管理
|
||||
createUser(data) { /* ... */ }
|
||||
updateUser(id, data) { /* ... */ }
|
||||
deleteUser(id) { /* ... */ }
|
||||
|
||||
// 責任 3: 通知
|
||||
sendWelcomeEmail(user) { /* ... */ }
|
||||
sendPasswordReset(email) { /* ... */ }
|
||||
}
|
||||
|
||||
// SOLID 分數評估結果
|
||||
S: 10 分 (責任 3 個: 認證、CRUD、通知)
|
||||
O: 5 分 (無擴展點、直接實現)
|
||||
L: 15 分 (無繼承、不適用)
|
||||
I: 10 分 (介面未分離)
|
||||
D: 10 分 (具象類依賴)
|
||||
總計: 50 分 (Fair - 建議重構)
|
||||
|
||||
// 技術債務
|
||||
複雜度: 15 (方法 7 個、責任 3 個)
|
||||
影響範圍: 8 (認證在全功能中使用)
|
||||
修正難度: 2 (有測試、文件不足)
|
||||
債務時間: 15 × 8 × 2 = 240 小時
|
||||
優先級: Critical (認證系統需即刻回應)
|
||||
```
|
||||
|
||||
### 改善後的實現例
|
||||
|
||||
```javascript
|
||||
// SOLID 原則適用後 (分數: 90 分)
|
||||
|
||||
// S: 單一責任 (20 分)
|
||||
class AuthenticationService {
|
||||
authenticate(credentials) { /* ... */ }
|
||||
refreshToken(token) { /* ... */ }
|
||||
}
|
||||
|
||||
// O: 開放封閉 (20 分)
|
||||
class UserRepository {
|
||||
constructor(storage) { // Strategy Pattern
|
||||
this.storage = storage;
|
||||
}
|
||||
save(user) { return this.storage.save(user); }
|
||||
}
|
||||
|
||||
// I: 介面分離 (20 分)
|
||||
interface Readable {
|
||||
find(id);
|
||||
findAll();
|
||||
}
|
||||
interface Writable {
|
||||
save(entity);
|
||||
delete(id);
|
||||
}
|
||||
|
||||
// D: 依賴反轉 (20 分)
|
||||
class UserService {
|
||||
constructor(
|
||||
private auth: IAuthService,
|
||||
private repo: IUserRepository,
|
||||
private notifier: INotificationService
|
||||
) {}
|
||||
}
|
||||
|
||||
// 債務削減: 240 小時 → 20 小時 (削減 92%)
|
||||
```
|
||||
|
||||
### 自動化支援
|
||||
|
||||
```bash
|
||||
# SOLID 分數測量
|
||||
npx solid-analyzer src/ --output report.json
|
||||
|
||||
# 複雜度分析
|
||||
npx complexity-report src/ --format json
|
||||
sonar-scanner -Dsonar.javascript.lcov.reportPaths=coverage/lcov.info
|
||||
|
||||
# 技術債務的可視化
|
||||
npx code-debt-analyzer --config .debt.yml
|
||||
|
||||
# 代碼格式化
|
||||
npm run lint:fix
|
||||
prettier --write src/
|
||||
|
||||
# 測試執行和覆蓋率
|
||||
npm test -- --coverage
|
||||
npm run test:mutation # 變異測試
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
- **功能變更的禁止**: 不改變外部行為
|
||||
- **測試優先**: 重構前追加測試
|
||||
- **階段性方法**: 不一次做大的變更
|
||||
- **持續驗證**: 各步驟的測試執行
|
||||
571
commands/role-debate.md
Normal file
571
commands/role-debate.md
Normal file
@@ -0,0 +1,571 @@
|
||||
## 角色辩論
|
||||
|
||||
不同專業角色進行辩論，考虑權衡取舍並導出最優解的命令。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/role-debate <角色 1>,<角色 2> [議題]
|
||||
/role-debate <角色 1>,<角色 2>,<角色 3> [議題]
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 安全性 vs 性能的權衡
|
||||
/role-debate security,performance
|
||||
"關于 JWT 令牌的有效期設置"
|
||||
|
||||
# 可用性 vs 安全性的平衡
|
||||
/role-debate frontend,security
|
||||
"關于雙因素認證的 UX 優化"
|
||||
|
||||
# 技術選型的辩論
|
||||
/role-debate architect,mobile
|
||||
"關于 React Native vs Flutter 的選擇"
|
||||
|
||||
# 三方辩論
|
||||
/role-debate architect,security,performance
|
||||
"關于微服務化的必要性"
|
||||
```
|
||||
|
||||
### 辩論的基本原則
|
||||
|
||||
#### 建設性辩論準則
|
||||
|
||||
- **相互尊重**: 尊重其他角色的專業性和視角
|
||||
- **基于事實**: 基于數據·證據的辩論，而非情绪化反驳
|
||||
- **解決導向**: 旨在寻找更好的解決方案，而非為批判而批判
|
||||
- **重視實施**: 考虑可實現性的提案，而非理想論
|
||||
|
||||
#### 論據的質量要求
|
||||
|
||||
- **官方文檔**: 引用標準·指南·官方文檔
|
||||
- **實證案例**: 具體引用成功案例·失败案例
|
||||
- **定量評估**: 尽可能使用數值·指標進行比较
|
||||
- **時間考慮**: 評估短期·中期·長期的影響
|
||||
|
||||
#### 辩論倫理
|
||||
|
||||
- **诚實性**: 承認自身專業領域的局限
|
||||
- **開放性**: 對新資訊·視角保持灵活性
|
||||
- **透明性**: 明示判斷依據·前提條件
|
||||
- **責任性**: 包括提案的實施風險
|
||||
|
||||
### 辩論流程
|
||||
|
||||
### 阶段 1: 初始立場表明
|
||||
|
||||
各角色從專業視角独立表達意見
|
||||
|
||||
- 提出推薦方案
|
||||
- 明示依據的標準·文檔
|
||||
- 說明預期的風險·挑战
|
||||
- 定義成功指標
|
||||
|
||||
### 阶段 2: 相互辩論·反驳
|
||||
|
||||
角色間的交叉辩論
|
||||
|
||||
- 對其他角色提案的建設性反驳
|
||||
- 指出被忽視的視角
|
||||
- 明確權衡取舍
|
||||
- 提出替代方案
|
||||
|
||||
### 阶段 3: 妥協點探索
|
||||
|
||||
寻求可實施的解決方案
|
||||
|
||||
- 評估各視角的重要性
|
||||
- 考虑雙赢解決方案
|
||||
- 分阶段實施方法
|
||||
- 考虑風險緩解策略
|
||||
|
||||
### 阶段 4: 综合結論
|
||||
|
||||
決定最終推薦事項
|
||||
|
||||
- 達成共識的解決方案
|
||||
- 實施路線圖
|
||||
- 成功指標·測量方法
|
||||
- 未來的審查點
|
||||
|
||||
### 輸出格式示例
|
||||
|
||||
### 2 角色辩論的情况
|
||||
|
||||
```text
|
||||
角色辩論: Security vs Performance
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
議題: JWT 令牌的有效期設置
|
||||
|
||||
Security 角色的主张:
|
||||
"推薦 15 分鐘的短期有效期"
|
||||
|
||||
依據:
|
||||
- 符合 OWASP JWT Security Cheat Sheet
|
||||
- 最小化令牌洩露時的损害時間窗口
|
||||
- 限制攻擊者的可用時間
|
||||
|
||||
担忧事項:
|
||||
- 長期有效期使攻擊風險呈指數級增長
|
||||
- 合規要求 (金融系統) 必须使用短期
|
||||
|
||||
成功指標:
|
||||
- 安全事件發生率 < 0.1%
|
||||
- 平均攻擊檢測時間 < 5 分鐘
|
||||
|
||||
Performance 角色的反驳:
|
||||
"推薦 2 小時的有效期"
|
||||
|
||||
依據:
|
||||
- 參考 Google OAuth 2.0 Best Practices
|
||||
- 避免頻繁重新認證導致的服務器負載增加
|
||||
- 最小化用戶體驗 (工作中斷)
|
||||
|
||||
担忧事項:
|
||||
- 15 分鐘間隔的重新認證使 API 負載增加 8 倍
|
||||
- 移動環境下連接中斷頻發
|
||||
|
||||
成功指標:
|
||||
- 保持 API 響應時間 < 200ms
|
||||
- 服務器 CPU 使用率 < 60%
|
||||
|
||||
相互辩論:
|
||||
Security → Performance:
|
||||
"安全漏洞的業務损失远大于服務器負載。
|
||||
例: Equifax 事件造成 7 亿美元损失"
|
||||
|
||||
Performance → Security:
|
||||
"通過刷新令牌機制可以两全其美。
|
||||
後台更新可確保安全而不损害 UX"
|
||||
|
||||
Security → Performance:
|
||||
"刷新令牌也是攻擊目標。需要正確實施"
|
||||
|
||||
Performance → Security:
|
||||
"建議分阶段方法。普通操作 30 分鐘，敏感操作 15 分鐘"
|
||||
|
||||
妥協點探索:
|
||||
共同理解:
|
||||
- 需要兼顾用戶體驗和安全性
|
||||
- 根據風險級別灵活應對
|
||||
- 現實考虑實施·運維成本
|
||||
|
||||
雙赢要素:
|
||||
- 利用刷新令牌機制
|
||||
- 逐步引入基于風險的認證
|
||||
- 通過自動登出功能補充
|
||||
|
||||
综合結論:
|
||||
"30 分鐘有效期 + 刷新令牌 + 基于風險的認證"
|
||||
|
||||
實施詳情:
|
||||
1. 訪問令牌: 30 分鐘有效期
|
||||
2. 刷新令牌: 7 天有效期
|
||||
3. 高風險操作: 15 分鐘強制重新認證
|
||||
4. 無操作 30 分鐘自動登出
|
||||
|
||||
分阶段實施:
|
||||
第 1-2 週: 基本的 30 分鐘令牌實施
|
||||
第 3-4 週: 添加刷新令牌機制
|
||||
第 2 月: 引入基于風險的認證
|
||||
|
||||
成功指標:
|
||||
- 安全: 事件發生率 < 0.1%
|
||||
- 性能: API 負載增加率 < 20%
|
||||
- UX: 用戶满意度 > 85%
|
||||
|
||||
未來審查:
|
||||
- 3 個月後: 評估實際攻擊模式·負載情况
|
||||
- 6 個月後: 考虑遷移到更精细的基于風險的認證
|
||||
```
|
||||
|
||||
### 3 角色辩論的情况
|
||||
|
||||
```text
|
||||
角色辩論: Architect vs Security vs Performance
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
議題: 微服務化的必要性
|
||||
|
||||
Architect 角色的主张:
|
||||
"推薦分阶段微服務化"
|
||||
依據: 明確領域邊界、独立部署、技術選擇自由度
|
||||
|
||||
Security 角色的担忧:
|
||||
"服務間通信的安全性復杂化"
|
||||
依據: API Gateway、mTLS、分布式認證的管理成本
|
||||
|
||||
Performance 角色的担忧:
|
||||
"網絡通信導致延遲增加"
|
||||
依據: 內部 API 調用導致的 N+1 問題、分布式事務
|
||||
|
||||
3 方辩論:
|
||||
Architect → Security: "通過 API Gateway 集中管理可以控制"
|
||||
Security → Architect: "成為單點故障的風險"
|
||||
Performance → Architect: "服務拆分的粒度很重要"
|
||||
...(辩論繼續)
|
||||
|
||||
综合結論:
|
||||
"領域驅動設計的分阶段拆分 + 安全優先設計"
|
||||
```
|
||||
|
||||
### 有效的辩論模式
|
||||
|
||||
### 技術選型
|
||||
|
||||
```bash
|
||||
/role-debate architect,performance
|
||||
"數據庫選擇: PostgreSQL vs MongoDB"
|
||||
|
||||
/role-debate frontend,mobile
|
||||
"UI 框架: React vs Vue"
|
||||
|
||||
/role-debate security,architect
|
||||
"認證方式: JWT vs Session Cookie"
|
||||
```
|
||||
|
||||
### 設計決策
|
||||
|
||||
```bash
|
||||
/role-debate security,frontend
|
||||
"用戶認證的 UX 設計"
|
||||
|
||||
/role-debate performance,mobile
|
||||
"數據同步策略的優化"
|
||||
|
||||
/role-debate architect,qa
|
||||
"測試策略與架構設計"
|
||||
```
|
||||
|
||||
### 權衡問題
|
||||
|
||||
```bash
|
||||
/role-debate security,performance
|
||||
"加密級別 vs 處理速度"
|
||||
|
||||
/role-debate frontend,performance
|
||||
"丰富 UI vs 页面加載速度"
|
||||
|
||||
/role-debate mobile,security
|
||||
"便利性 vs 數據保護級別"
|
||||
```
|
||||
|
||||
### 角色別辩論特性
|
||||
|
||||
#### 🔒 Security 角色
|
||||
|
||||
```yaml
|
||||
辩論立場:
|
||||
- 保守方法 (風險最小化)
|
||||
- 重視規則遵守 (謹慎偏離標準)
|
||||
- 最壞情況假設 (攻擊者視角)
|
||||
- 重視長期影響 (安全作為技術債務)
|
||||
|
||||
典型論點:
|
||||
- "安全 vs 便利性" 的權衡
|
||||
- "合規要求的必達"
|
||||
- "攻擊成本 vs 防御成本的比较"
|
||||
- "隱私保護的彻底性"
|
||||
|
||||
論據來源:
|
||||
- OWASP 指南
|
||||
- NIST 框架
|
||||
- 行業標準 (ISO 27001, SOC 2)
|
||||
- 實際攻擊案例·統計
|
||||
|
||||
辩論優勢:
|
||||
- 風險評估的精度
|
||||
- 監管要求的知識
|
||||
- 對攻擊手法的理解
|
||||
|
||||
需注意的偏見:
|
||||
- 過度保守 (阻礙創新)
|
||||
- 對 UX 的考虑不足
|
||||
- 忽視實施成本
|
||||
```
|
||||
|
||||
#### ⚡ Performance 角色
|
||||
|
||||
```yaml
|
||||
辩論立場:
|
||||
- 數據驅動決策 (基于測量)
|
||||
- 重視效率 (成本效益優化)
|
||||
- 用戶體驗優先 (重視體感速度)
|
||||
- 持續改進 (分阶段優化)
|
||||
|
||||
典型論點:
|
||||
- "性能 vs 安全"
|
||||
- "優化成本 vs 效果的投資回報"
|
||||
- "現在 vs 未來的可擴展性"
|
||||
- "用戶體驗 vs 系統效率"
|
||||
|
||||
論據來源:
|
||||
- Core Web Vitals 指標
|
||||
- 基準測試結果·統計
|
||||
- 對用戶行為的影響數據
|
||||
- 行業性能標準
|
||||
|
||||
辩論優勢:
|
||||
- 定量評估能力
|
||||
- 瓶頸識別
|
||||
- 優化手法的知識
|
||||
|
||||
需注意的偏見:
|
||||
- 忽視安全性
|
||||
- 對可維護性考虑不足
|
||||
- 過早優化
|
||||
```
|
||||
|
||||
#### 🏗️ Architect 角色
|
||||
|
||||
```yaml
|
||||
辩論立場:
|
||||
- 重視長期視角 (考慮系統演進)
|
||||
- 追求平衡 (全局優化)
|
||||
- 分阶段變更 (風險管理)
|
||||
- 標準遵守 (優先經過驗證的模式)
|
||||
|
||||
典型論點:
|
||||
- "短期效率 vs 長期可維護性"
|
||||
- "技術债務 vs 開發速度"
|
||||
- "微服務 vs 單體"
|
||||
- "新技術採用 vs 稳定性"
|
||||
|
||||
論據來源:
|
||||
- 架構模式集
|
||||
- 設計原則 (SOLID, DDD)
|
||||
- 大規模系統案例
|
||||
- 技術演進趨勢
|
||||
|
||||
辩論優勢:
|
||||
- 全局俯瞰能力
|
||||
- 設計模式的知識
|
||||
- 長期影響的預測
|
||||
|
||||
需注意的偏見:
|
||||
- 過度泛化
|
||||
- 對新技術的保守性
|
||||
- 對實施细节的理解不足
|
||||
```
|
||||
|
||||
#### 🎨 Frontend 角色
|
||||
|
||||
```yaml
|
||||
辩論立場:
|
||||
- 用戶中心設計 (UX 最優先)
|
||||
- 包容性方法 (考虑多樣性)
|
||||
- 重視直觀性 (最小化學習成本)
|
||||
- 可訪問性標準 (WCAG 準拠)
|
||||
|
||||
典型論點:
|
||||
- "可用性 vs 安全性"
|
||||
- "設計統一 vs 平台優化"
|
||||
- "功能性 vs 簡洁性"
|
||||
- "性能 vs 丰富體驗"
|
||||
|
||||
論據來源:
|
||||
- UX 研究·可用性測試結果
|
||||
- 可訪問性指南
|
||||
- 設計系統標準
|
||||
- 用戶行為數據
|
||||
|
||||
辩論優勢:
|
||||
- 代表用戶視角
|
||||
- 設計原則的知識
|
||||
- 可訪問性要求
|
||||
|
||||
需注意的偏見:
|
||||
- 對技術約束的理解不足
|
||||
- 忽視安全要求
|
||||
- 低估性能影響
|
||||
```
|
||||
|
||||
#### 📱 Mobile 角色
|
||||
|
||||
```yaml
|
||||
辩論立場:
|
||||
- 平台特化 (考虑 iOS/Android 差異)
|
||||
- 場景適應 (移動中·單手操作)
|
||||
- 資源約束 (電池·內存·通信)
|
||||
- 商店準拠 (審核指南)
|
||||
|
||||
典型論點:
|
||||
- "原生 vs 跨平台"
|
||||
- "離線支持 vs 實時同步"
|
||||
- "電池效率 vs 功能性"
|
||||
- "平台統一 vs 優化"
|
||||
|
||||
論據來源:
|
||||
- iOS HIG / Android Material Design
|
||||
- App Store / Google Play 指南
|
||||
- 移動 UX 研究
|
||||
- 設備性能統計
|
||||
|
||||
辩論優勢:
|
||||
- 理解移動特有約束
|
||||
- 平台差異的知識
|
||||
- 觸摸界面設計
|
||||
|
||||
需注意的偏見:
|
||||
- 對 Web 平台的理解不足
|
||||
- 忽視服務器端約束
|
||||
- 對桌面環境的考虑不足
|
||||
```
|
||||
|
||||
#### 🔍 Analyzer 角色
|
||||
|
||||
```yaml
|
||||
辩論立場:
|
||||
- 重視證據 (數據優先)
|
||||
- 假設驗證 (科學方法)
|
||||
- 結構思維 (系統思維)
|
||||
- 偏差排除 (追求客觀性)
|
||||
|
||||
典型論點:
|
||||
- "相關性 vs 因果關系"
|
||||
- "對症疗法 vs 根本解決"
|
||||
- "假設 vs 事實的區別"
|
||||
- "短期症狀 vs 結構問題"
|
||||
|
||||
論據來源:
|
||||
- 實測數據·日誌分析
|
||||
- 統計方法·分析結果
|
||||
- 系統思維理論
|
||||
- 認知偏差研究
|
||||
|
||||
辩論優勢:
|
||||
- 邏輯分析能力
|
||||
- 證據評估的客觀性
|
||||
- 結構問題的發現
|
||||
|
||||
需注意的偏見:
|
||||
- 分析瘫痪 (行動力不足)
|
||||
- 完美主義 (忽視實用性)
|
||||
- 數據万能主義
|
||||
```
|
||||
|
||||
### 辩論進行模板
|
||||
|
||||
#### 阶段 1: 立場表明模板
|
||||
|
||||
```text
|
||||
【角色名】的推薦方案:
|
||||
"[具體提案]"
|
||||
|
||||
依據:
|
||||
- [官方文檔·標準的引用]
|
||||
- [實證案例·數據]
|
||||
- [專業領域的原則]
|
||||
|
||||
預期效果:
|
||||
- [短期效果]
|
||||
- [中長期效果]
|
||||
|
||||
担忧·風險:
|
||||
- [實施風險]
|
||||
- [運維風險]
|
||||
- [對其他領域的影響]
|
||||
|
||||
成功指標:
|
||||
- [可測量指標 1]
|
||||
- [可測量指標 2]
|
||||
```
|
||||
|
||||
#### 阶段 2: 反驳模板
|
||||
|
||||
```text
|
||||
對 [目標角色] 的反驳:
|
||||
"[對目標提案的具體反驳]"
|
||||
|
||||
反驳依據:
|
||||
- [被忽視的視角]
|
||||
- [對立的證據·案例]
|
||||
- [專業領域的担忧]
|
||||
|
||||
替代方案:
|
||||
"[改進的提案]"
|
||||
|
||||
可妥協點:
|
||||
- [可接受的條件]
|
||||
- [分阶段實施的可能性]
|
||||
```
|
||||
|
||||
#### 阶段 3: 综合解決模板
|
||||
|
||||
```text
|
||||
综合解決方案:
|
||||
"[考虑各角色担忧的最終提案]"
|
||||
|
||||
對各角色的考虑:
|
||||
- [Security]: [如何满足安全要求]
|
||||
- [Performance]: [如何满足性能要求]
|
||||
- [其他]: [如何满足其他要求]
|
||||
|
||||
實施路線圖:
|
||||
- 阶段 1 (立即): [紧急應對事項]
|
||||
- 阶段 2 (短期): [基本實施]
|
||||
- 阶段 3 (中期): [完整實施]
|
||||
|
||||
成功指標·測量方法:
|
||||
- [综合成功指標]
|
||||
- [測量方法·頻率]
|
||||
- [審查時機]
|
||||
```
|
||||
|
||||
### 辩論質量檢查清單
|
||||
|
||||
#### 論據質量
|
||||
|
||||
- [ ] 引用了官方文檔·標準
|
||||
- [ ] 提供了具體案例·數據
|
||||
- [ ] 明確區分了推測和事實
|
||||
- [ ] 明示了資訊來源
|
||||
|
||||
#### 辩論的建設性
|
||||
|
||||
- [ ] 準確理解了對方的提案
|
||||
- [ ] 邏輯而非情绪化的反驳
|
||||
- [ ] 也提出了替代方案
|
||||
- [ ] 探索了雙赢的可能性
|
||||
|
||||
#### 可實施性
|
||||
|
||||
- [ ] 考虑了技術可實現性
|
||||
- [ ] 估算了實施成本·期間
|
||||
- [ ] 檢讨了分阶段實施的可能性
|
||||
- [ ] 提出了風險緩解策略
|
||||
|
||||
#### 综合性
|
||||
|
||||
- [ ] 考虑了對其他領域的影響
|
||||
- [ ] 追求全局優化
|
||||
- [ ] 包含長期視角
|
||||
- [ ] 設置了可測量的成功指標
|
||||
|
||||
### 與 Claude 的協作
|
||||
|
||||
```bash
|
||||
# 基于設計文檔的辩論
|
||||
cat system-design.md
|
||||
/role-debate architect,security
|
||||
"辩論這個設計在安全方面的挑战"
|
||||
|
||||
# 基于問題的解決方案辩論
|
||||
cat performance-issues.md
|
||||
/role-debate performance,architect
|
||||
"辩論性能問題的根本解決方案"
|
||||
|
||||
# 基于需求的技術選型辩論
|
||||
/role-debate mobile,frontend
|
||||
"辩論 iOS·Android·Web 的統一 UI 策略"
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
- 辩論可能需要時間 (復杂議題需要更长時間)
|
||||
- 3 個以上角色可能導致辩論發散
|
||||
- 最終決策請用戶參考辩論結果做出
|
||||
- 紧急性高的問題請先考虑 single role 或 multi-role
|
||||
276
commands/role-help.md
Normal file
276
commands/role-help.md
Normal file
@@ -0,0 +1,276 @@
|
||||
## 角色帮助
|
||||
|
||||
迷茫時的角色選擇指南和帮助系統。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/role-help # 全面的角色選擇指南
|
||||
/role-help <情况/問題> # 特定情况的推薦角色
|
||||
/role-help compare <角色 1>,<角色 2> # 角色比较
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 一般指導
|
||||
/role-help
|
||||
→ 顯示可用角色及特點列表
|
||||
|
||||
# 情况別推薦
|
||||
/role-help "担心 API 的安全性"
|
||||
→ 推薦 security 角色及使用方法
|
||||
|
||||
# 角色比较
|
||||
/role-help compare frontend,mobile
|
||||
→ frontend 和 mobile 的區別與使用場景
|
||||
```
|
||||
|
||||
### 情况別角色選擇指南
|
||||
|
||||
### 安全相關
|
||||
|
||||
```text
|
||||
這种情况使用 security 角色:
|
||||
✅ 登錄·認證功能的實現
|
||||
✅ API 的安全漏洞檢查
|
||||
✅ 數據加密·隱私保護
|
||||
✅ 安全合規性確認
|
||||
✅ 滲透測試·滲透測試
|
||||
|
||||
使用方法: /role security
|
||||
```
|
||||
|
||||
### 🏗️ 架構·設計
|
||||
|
||||
```text
|
||||
這种情况使用 architect 角色:
|
||||
✅ 系統整體設計評估
|
||||
✅ 微服務 vs 單體判斷
|
||||
✅ 數據庫設計·技術選型
|
||||
✅ 可擴展性·擴展性考虑
|
||||
✅ 技術债務評估·改進計劃
|
||||
|
||||
使用方法: /role architect
|
||||
```
|
||||
|
||||
### ⚡ 性能問題
|
||||
|
||||
```text
|
||||
這种情况使用 performance 角色:
|
||||
✅ 應用程序運行緩慢
|
||||
✅ 數據庫查询優化
|
||||
✅ Web 页面加載速度改進
|
||||
✅ 內存·CPU 使用量優化
|
||||
✅ 擴展·負載對策
|
||||
|
||||
使用方法: /role performance
|
||||
```
|
||||
|
||||
### 🔍 問題原因調查
|
||||
|
||||
```text
|
||||
這种情况使用 analyzer 角色:
|
||||
✅ Bug·錯誤的根本原因分析
|
||||
✅ 系統故障原因究明
|
||||
✅ 復杂問題的結構分析
|
||||
✅ 數據分析·統計調查
|
||||
✅ 為什么會發生這個問題的解明
|
||||
|
||||
使用方法: /role analyzer
|
||||
```
|
||||
|
||||
### 🎨 前端·UI/UX
|
||||
|
||||
```text
|
||||
這种情况使用 frontend 角色:
|
||||
✅ 用戶界面改進
|
||||
✅ 可訪問性支持
|
||||
✅ 響應式設計
|
||||
✅ 可用性·易用性提升
|
||||
✅ Web 前端技術全般
|
||||
|
||||
使用方法: /role frontend
|
||||
```
|
||||
|
||||
### 📱 移動應用開發
|
||||
|
||||
```text
|
||||
這种情况使用 mobile 角色:
|
||||
✅ iOS·Android 應用優化
|
||||
✅ 移動特有的 UX 設計
|
||||
✅ 觸摸界面優化
|
||||
✅ 離線支持·同步功能
|
||||
✅ App Store·Google Play 支持
|
||||
|
||||
使用方法: /role mobile
|
||||
```
|
||||
|
||||
### 👀 代碼審查·質量
|
||||
|
||||
```text
|
||||
這种情况使用 reviewer 角色:
|
||||
✅ 代碼質量檢查
|
||||
✅ 可讀性·可維護性評估
|
||||
✅ 編碼規範確認
|
||||
✅ 重構建議
|
||||
✅ PR·提交審查
|
||||
|
||||
使用方法: /role reviewer
|
||||
```
|
||||
|
||||
### 🧪 測試·質量保證
|
||||
|
||||
```text
|
||||
這种情况使用 qa 角色:
|
||||
✅ 測試策略制定
|
||||
✅ 測試覆蓋率評估
|
||||
✅ 自動測試實施方针
|
||||
✅ Bug 預防·質量提升策略
|
||||
✅ CI/CD 中的測試自動化
|
||||
|
||||
使用方法: /role qa
|
||||
```
|
||||
|
||||
### 需要多個角色的情况
|
||||
|
||||
### 🔄 multi-role (並行分析)
|
||||
|
||||
```text
|
||||
這种情况使用 multi-role:
|
||||
✅ 需要多個專業視角的評估
|
||||
✅ 想制定综合改進計劃
|
||||
✅ 想比较各領域的評估
|
||||
✅ 想整理矛盾·重復
|
||||
|
||||
例: /multi-role security,performance
|
||||
```
|
||||
|
||||
### 🗣️ role-debate (辩論)
|
||||
|
||||
```text
|
||||
這种情况使用 role-debate:
|
||||
✅ 專業領域間存在權衡
|
||||
✅ 技術選型有分歧
|
||||
✅ 想通過辩論決定設計方针
|
||||
✅ 想听取不同視角的辩論
|
||||
|
||||
例: /role-debate security,performance
|
||||
```
|
||||
|
||||
### 🤖 smart-review (自動建議)
|
||||
|
||||
```text
|
||||
這种情况使用 smart-review:
|
||||
✅ 不知道该使用哪個角色
|
||||
✅ 想了解當前情况的最佳方法
|
||||
✅ 想從多個選項中選擇
|
||||
✅ 初學者不知如何判斷
|
||||
|
||||
例: /smart-review
|
||||
```
|
||||
|
||||
### 角色比较表
|
||||
|
||||
### 安全系
|
||||
|
||||
| 角色 | 主要用途 | 擅长領域 | 不擅长領域 |
|
||||
| -------- | ------------- | ------------------ | ---------------- |
|
||||
| security | 漏洞·攻擊對策 | 威胁分析、認證設計 | UX、性能 |
|
||||
| analyzer | 根本原因分析 | 邏輯分析、證據收集 | 預防策、未來規劃 |
|
||||
|
||||
### 設計系
|
||||
|
||||
| 角色 | 主要用途 | 擅长領域 | 不擅长領域 |
|
||||
| --------- | -------- | ------------------ | ------------------ |
|
||||
| architect | 系統設計 | 长期視角、全局優化 | 詳细實現、短期解決 |
|
||||
| reviewer | 代碼質量 | 實現級別、可維護性 | 業務需求、UX |
|
||||
|
||||
### 性能系
|
||||
|
||||
| 角色 | 主要用途 | 擅长領域 | 不擅长領域 |
|
||||
| ----------- | ----------- | ------------ | ---------- |
|
||||
| performance | 高速化·優化 | 測量、瓶頸 | 安全性、UX |
|
||||
| qa | 質量保證 | 測試、自動化 | 設計、架構 |
|
||||
|
||||
### 用戶體驗系
|
||||
|
||||
| 角色 | 主要用途 | 擅长領域 | 不擅长領域 |
|
||||
| -------- | --------- | ---------------- | ------------- |
|
||||
| frontend | Web UI/UX | 瀏覽器、可訪問性 | 服務器端、DB |
|
||||
| mobile | 移動 UX | 觸摸、離線支持 | 服務器端、Web |
|
||||
|
||||
### 迷茫時的流程圖
|
||||
|
||||
```text
|
||||
問題的性質是？
|
||||
├─ 安全相關 → security
|
||||
├─ 性能問題 → performance
|
||||
├─ Bug·故障調查 → analyzer
|
||||
├─ UI/UX 改進 → frontend or mobile
|
||||
├─ 設計·架構 → architect
|
||||
├─ 代碼質量 → reviewer
|
||||
├─ 測試相關 → qa
|
||||
└─ 復合·復杂 → smart-review 建議
|
||||
|
||||
跨越多個領域？
|
||||
├─ 想要综合分析 → multi-role
|
||||
├─ 辩論·權衡 → role-debate
|
||||
└─ 不知如何判斷 → smart-review
|
||||
```
|
||||
|
||||
### 常見問題
|
||||
|
||||
### Q: frontend 和 mobile 的區別是？
|
||||
|
||||
```text
|
||||
A:
|
||||
frontend: 以 Web 瀏覽器為中心、HTML/CSS/JavaScript
|
||||
mobile: 以移動應用為中心、iOS/Android 原生·React Native 等
|
||||
|
||||
两者都相關時推薦 multi-role frontend,mobile
|
||||
```
|
||||
|
||||
### Q: security 和 analyzer 的使用場景？
|
||||
|
||||
```text
|
||||
A:
|
||||
security: 攻擊·威胁預防、安全設計
|
||||
analyzer: 已發生問題的原因分析、調查
|
||||
|
||||
安全事件調查使用 multi-role security,analyzer
|
||||
```
|
||||
|
||||
### Q: architect 和 performance 的區別是？
|
||||
|
||||
```text
|
||||
A:
|
||||
architect: 系統整體的长期設計、擴展性
|
||||
performance: 具體的速度·效率改進
|
||||
|
||||
大規模系統的性能設計使用 multi-role architect,performance
|
||||
```
|
||||
|
||||
### 與 Claude 的協作
|
||||
|
||||
```bash
|
||||
# 結合情况說明
|
||||
/role-help
|
||||
"React 應用页面加載慢，用戶投诉很多"
|
||||
|
||||
# 結合文件內容
|
||||
cat problem-description.md
|
||||
/role-help
|
||||
"推薦適合這個問題的角色"
|
||||
|
||||
# 特定選項的迷茫
|
||||
/role-help compare security,performance
|
||||
"JWT 令牌有效期問題该用哪個角色？"
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
- 復杂問題多角色組合更有效
|
||||
- 紧急性高時使用 single role 快速應對
|
||||
- 迷茫時推薦使用 smart-review 獲得自動建議
|
||||
- 最終判斷請用戶根據問題性質決定
|
||||
367
commands/role.md
Normal file
367
commands/role.md
Normal file
@@ -0,0 +1,367 @@
|
||||
## 角色
|
||||
|
||||
切換到特定角色 (role)，執行專業分析或工作。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/role <角色名> [--agent|-a]
|
||||
```
|
||||
|
||||
### 選項
|
||||
|
||||
- `--agent` 或 `-a` : 作為子代理独立執行 (推薦用于大規模分析)
|
||||
- 使用此選項時，如果角色的 description 包含自動委托促進短語 (如 "use PROACTIVELY" 等)，將啟用更积极的自動委托
|
||||
|
||||
### 可用角色
|
||||
|
||||
#### 專業分析角色 (Evidence-First 集成)
|
||||
|
||||
- `security` : 安全審計專家 (OWASP Top 10·威脅建模·Zero Trust 原則·CVE 對照)
|
||||
- `performance` : 性能優化專家 (Core Web Vitals·RAIL 模型·漸進式優化·ROI 分析)
|
||||
- `analyzer` : 根本原因分析專家 (5 Whys·系統思維·假設驅動·認知偏差對策)
|
||||
- `frontend` : 前端·UI/UX 專家 (WCAG 2.1·設計系統·使用者中心設計)
|
||||
- `mobile` : 移動開發專家 (iOS HIG·Android Material Design·跨平台策略)
|
||||
- `backend` : 後端與伺服器端專家 (RESTful 設計·可擴展性·資料庫最佳化)
|
||||
|
||||
#### 開發支援角色
|
||||
|
||||
- `reviewer` : 程式碼審查專家 (可讀性·可維護性·性能·重構建議)
|
||||
- `architect` : 系統架構師 (Evidence-First 設計·MECE 分析·演進式架構)
|
||||
- `qa` : 測試工程師 (測試覆蓋率·E2E/整合/單元策略·自動化建議)
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 切換到安全審計模式 (常規)
|
||||
/role security
|
||||
"檢查這個項目的安全漏洞"
|
||||
|
||||
# 使用子代理執行安全審計 (大規模分析)
|
||||
/role security --agent
|
||||
"執行整個項目的安全審計"
|
||||
|
||||
# 切換到代碼審查模式
|
||||
/role reviewer
|
||||
"審查最近的變更並指出改進點"
|
||||
|
||||
# 切換到性能優化模式
|
||||
/role performance
|
||||
"分析應用程序的瓶頸"
|
||||
|
||||
# 切換到根本原因分析模式
|
||||
/role analyzer
|
||||
"調查這個故障的根本原因"
|
||||
|
||||
# 切換到前端專業模式
|
||||
/role frontend
|
||||
"評估 UI/UX 的改進點"
|
||||
|
||||
# 切換到移動開發專業模式
|
||||
/role mobile
|
||||
"評估這個應用的移動優化"
|
||||
|
||||
# 返回常規模式
|
||||
/role default
|
||||
"返回常規 Claude"
|
||||
```
|
||||
|
||||
### 與 Claude 的協作
|
||||
|
||||
```bash
|
||||
# 安全專注分析
|
||||
/role security
|
||||
cat app.js
|
||||
"詳细分析這段代碼的潜在安全風險"
|
||||
|
||||
# 架構視角評估
|
||||
/role architect
|
||||
ls -la src/
|
||||
"提出當前結構的問題和改進方案"
|
||||
|
||||
# 測試策略制定
|
||||
/role qa
|
||||
"為這個項目提出最佳測試策略"
|
||||
```
|
||||
|
||||
### 詳细示例
|
||||
|
||||
```bash
|
||||
# 多角色分析
|
||||
/role security
|
||||
"首先從安全角度檢查"
|
||||
git diff HEAD~1
|
||||
|
||||
/role reviewer
|
||||
"接下來審查一般代碼質量"
|
||||
|
||||
/role architect
|
||||
"最後從架構角度評估"
|
||||
|
||||
# 角色特定的輸出格式
|
||||
/role security
|
||||
安全分析結果
|
||||
━━━━━━━━━━━━━━━━━━━━━
|
||||
漏洞: SQL 注入
|
||||
严重度: High
|
||||
位置: db.js:42
|
||||
修復建議: 使用參數化查询
|
||||
```
|
||||
|
||||
### Evidence-First 集成功能
|
||||
|
||||
#### 核心理念
|
||||
|
||||
各角色採用 **Evidence-First(基于證據)** 方法，基于 **經過驗證的方法·官方指南·客觀數據** 而非推測進行分析·建議。
|
||||
|
||||
#### 共同特徵
|
||||
|
||||
- **官方文檔準拠**: 優先參考各領域權威官方指南
|
||||
- **MECE 分析**: 無遗漏無重復的系統化問題分解
|
||||
- **多角度評估**: 技術·業務·運維·用戶的多視角
|
||||
- **認知偏差對策**: 排除確認偏差等的機制
|
||||
- **辩論特性**: 角色特有的專業辩論立場
|
||||
|
||||
### 專業分析角色詳情
|
||||
|
||||
#### security(安全審計專家)
|
||||
|
||||
**Evidence-Based 安全審計**
|
||||
|
||||
- 通過 OWASP Top 10·Testing Guide·SAMM 進行系統評估
|
||||
- 通過 CVE·NVD 數據庫對照檢查已知漏洞
|
||||
- 通過 STRIDE·Attack Tree·PASTA 進行威胁建模
|
||||
- 通過 Zero Trust 原則·最小權限進行設計評估
|
||||
|
||||
**專業報告格式**
|
||||
|
||||
```text
|
||||
Evidence-Based 安全審計結果
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
OWASP Top 10 合規度: XX% / CVE 對照: 完成
|
||||
威胁建模: STRIDE 分析完成
|
||||
```
|
||||
|
||||
#### performance(性能優化專家)
|
||||
|
||||
**Evidence-First 性能優化**
|
||||
|
||||
- Core Web Vitals(LCP·FID·CLS)·RAIL 模型準拠
|
||||
- Google PageSpeed Insights 建議實施
|
||||
- 渐進式優化流程 (測量→分析→優先級→實施)
|
||||
- 通過 ROI 分析進行投資回報的定量評估
|
||||
|
||||
**專業報告格式**
|
||||
|
||||
```text
|
||||
Evidence-First 性能分析
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Core Web Vitals: LCP[XXXms] FID[XXXms] CLS[X.XX]
|
||||
Performance Budget: XX% / ROI 分析: XX% 改進預測
|
||||
```
|
||||
|
||||
#### analyzer(根本原因分析專家)
|
||||
|
||||
**Evidence-First 根本原因分析**
|
||||
|
||||
- 5 Whys + α方法 (包含反證檢讨)
|
||||
- 基于系統思維的結構分析 (Peter Senge 原則)
|
||||
- 認知偏差對策 (排除確認偏差·锚定效應等)
|
||||
- 彻底的假設驅動分析 (並行驗證多個假設)
|
||||
|
||||
**專業報告格式**
|
||||
|
||||
```text
|
||||
Evidence-First 根本原因分析
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
分析可信度: 高 / 偏差對策: 已實施
|
||||
假設驗證矩阵: XX% 確信度
|
||||
```
|
||||
|
||||
#### frontend(前端·UI/UX 專家)
|
||||
|
||||
**Evidence-First 前端開發**
|
||||
|
||||
- WCAG 2.1 可訪問性準拠
|
||||
- Material Design·iOS HIG 官方指南準拠
|
||||
- 用戶中心設計·設計系統標準應用
|
||||
- 通過 A/B 測試·用戶行為分析進行驗證
|
||||
|
||||
### 開發支持角色詳情
|
||||
|
||||
#### reviewer(代碼審查專家)
|
||||
|
||||
- 可讀性·可維護性·性能的多角度評估
|
||||
- 編碼規範遵守檢查·重構建議
|
||||
- 安全性·可訪問性的横向確認
|
||||
|
||||
#### architect(系統架構师)
|
||||
|
||||
- Evidence-First 設計原則·MECE 分析的分阶段思考
|
||||
- 演進式架構·多視角評估 (技術·業務·運維·用戶)
|
||||
- 官方架構模式·最佳實践參考
|
||||
|
||||
#### qa(測試工程师)
|
||||
|
||||
- 測試覆蓋率分析·E2E/集成/單元測試策略
|
||||
- 測試自動化建議·質量指標設計
|
||||
|
||||
#### mobile(移動開發專家)
|
||||
|
||||
- iOS HIG·Android Material Design 官方指南準拠
|
||||
- 跨平台策略·Touch-First 設計
|
||||
- 應用商店審核指南·移動特化 UX 優化
|
||||
|
||||
#### backend (後端與伺服器端專家)
|
||||
|
||||
- RESTful/GraphQL API 設計、領域驅動設計、Clean Architecture
|
||||
- 可擴展性、容錯能力、效能最佳化
|
||||
- 資料庫最佳化、快取策略、可靠性提升
|
||||
|
||||
### 角色特有的辩論特性
|
||||
|
||||
各角色根據專業領域具有独特的辩論立場·論據來源·優勢。
|
||||
|
||||
#### security 角色的辩論特性
|
||||
|
||||
- **立場**: 保守方法·風險最小化優先·最坏情况假設
|
||||
- **論據**: OWASP 指南·NIST 框架·實際攻擊案例
|
||||
- **優勢**: 風險評估精度·深厚的監管要求知識·全面的攻擊手法理解
|
||||
- **注意**: 過度保守·對 UX 的考虑不足·忽視實施成本
|
||||
|
||||
#### performance 角色的辩論特性
|
||||
|
||||
- **立場**: 數據驅動決策·效率重視·用戶體驗優先·持續改進
|
||||
- **論據**: Core Web Vitals·基準測試結果·用戶行為數據·行業標準
|
||||
- **優勢**: 定量評估能力·瓶頸識別精度·ROI 分析
|
||||
- **注意**: 忽視安全性·對可維護性考虑不足·過度重視測量
|
||||
|
||||
#### analyzer 角色的辩論特性
|
||||
|
||||
- **立場**: 證據重視·假設驗證·結構思維·偏差排除
|
||||
- **論據**: 實測數據·統計方法·系統思維理論·認知偏差研究
|
||||
- **優勢**: 邏輯分析能力·證據評估的客觀性·結構問題的發現力
|
||||
- **注意**: 分析瘫痪·完美主義·數據万能主義·過度怀疑
|
||||
|
||||
#### frontend 角色的辩論特性
|
||||
|
||||
- **立場**: 用戶中心·可訪問性重視·設計原則準拠·體驗價值優先
|
||||
- **論據**: UX 調研·可訪問性標準·設計系統·可用性測試
|
||||
- **優勢**: 用戶視角·設計原則·可訪問性·體驗設計
|
||||
- **注意**: 忽視技術約束·對性能考虑不足·實施復杂性
|
||||
|
||||
### 多角色協作的效果
|
||||
|
||||
通過組合具有不同辩論特性的角色，可以實現平衡的分析：
|
||||
|
||||
#### 典型的協作模式
|
||||
|
||||
- **security + frontend**: 安全性與可用性的平衡
|
||||
- **performance + security**: 速度與安全的两立
|
||||
- **analyzer + architect**: 問題分析與結構設計的整合
|
||||
- **reviewer + qa**: 代碼質量與測試策略的協作
|
||||
|
||||
## 高級角色功能
|
||||
|
||||
### 智能角色選擇
|
||||
|
||||
- `/smart-review` : 通過項目分析自動建議角色
|
||||
- `/role-help` : 根據情况的最佳角色選擇指南
|
||||
|
||||
### 多角色協作
|
||||
|
||||
- `/multi-role <角色 1>,<角色 2>` : 多角色同時分析
|
||||
- `/role-debate <角色 1>,<角色 2>` : 角色間辩論
|
||||
|
||||
### 使用示例
|
||||
|
||||
#### 自動角色建議
|
||||
|
||||
```bash
|
||||
/smart-review
|
||||
→ 分析當前情况並建議最佳角色
|
||||
|
||||
/smart-review src/auth/
|
||||
→ 從認證相關文件推薦 security 角色
|
||||
```
|
||||
|
||||
#### 多角色分析
|
||||
|
||||
```bash
|
||||
/multi-role security,performance
|
||||
"從多個視角評估這個 API"
|
||||
→ 從安全和性能两方面進行综合分析
|
||||
|
||||
/role-debate frontend,security
|
||||
"讨論雙因素認證的 UX"
|
||||
→ 從可用性和安全性角度進行辩論
|
||||
```
|
||||
|
||||
#### 角色選擇困惑時
|
||||
|
||||
```bash
|
||||
/role-help "API 慢且担心安全"
|
||||
→ 建議適当的方法 (multi-role 或 debate)
|
||||
|
||||
/role-help compare frontend,mobile
|
||||
→ 前端和移動角色的區別與使用分場
|
||||
```
|
||||
|
||||
## 注意事項
|
||||
|
||||
### 關于角色行為
|
||||
|
||||
- 切換角色時，Claude 的 **行為·優先事項·分析方法·報告格式** 會專門化
|
||||
- 各角色通過 **Evidence-First 方法** 優先應用官方指南·經過驗證的方法
|
||||
- 使用 `default` 返回常規模式 (解除角色特化)
|
||||
- 角色仅在當前會話內有效
|
||||
|
||||
### 有效使用方法
|
||||
|
||||
- **簡單問題**: 單一角色的專業分析足够
|
||||
- **復杂問題**: multi-role 或 role-debate 的多角度分析有效
|
||||
- **困惑時**: 請使用 smart-review 或 role-help
|
||||
- **持續改進**: 同一角色也會通過新證據·方法提高分析精度
|
||||
|
||||
### 子代理功能 (--agent 選項)
|
||||
|
||||
需要大規模分析或独立專業處理時，可使用 `--agent` 選項將角色作為子代理執行。
|
||||
|
||||
#### 優點
|
||||
|
||||
- **独立上下文**: 不幹扰主對話
|
||||
- **並行執行**: 可同時執行多個分析
|
||||
- **專業特化**: 更深入的分析和詳细報告
|
||||
- **促進自動委托**: 角色的 description 包含 "use PROACTIVELY" 或 "MUST BE USED" 時，啟用更积极的自動委托
|
||||
|
||||
#### 推薦使用場景
|
||||
|
||||
```bash
|
||||
# 安全: OWASP 全項目檢查、CVE 對照
|
||||
/role security --agent
|
||||
"全代碼庫的安全審計"
|
||||
|
||||
# 分析器: 大量日誌的根本原因分析
|
||||
/role analyzer --agent
|
||||
"分析過去一週的錯誤日誌"
|
||||
|
||||
# 審查员: 大規模 PR 的詳细審查
|
||||
/role reviewer --agent
|
||||
"審查 PR #500 的 1000 行變更"
|
||||
```
|
||||
|
||||
#### 常規角色 vs 子代理
|
||||
|
||||
| 場景 | 推薦 | 命令 |
|
||||
| ---------- | -------- | ------------------------ |
|
||||
| 簡單確認 | 常規角色 | `/role security` |
|
||||
| 大規模分析 | 子代理 | `/role security --agent` |
|
||||
| 交互式工作 | 常規角色 | `/role frontend` |
|
||||
| 独立審計 | 子代理 | `/role qa --agent` |
|
||||
|
||||
### 角色設置詳情
|
||||
|
||||
- 各角色的詳细設置·專業知識·辩論特性在 `.claude/agents/roles/` 目錄內定義
|
||||
- 包含 Evidence-First 方法·認知偏差對策
|
||||
- 通過角色特有的觸發短語自動啟用特化模式
|
||||
- 實際角色文件由 200 行以上的專業內容構成
|
||||
103
commands/screenshot.md
Normal file
103
commands/screenshot.md
Normal file
@@ -0,0 +1,103 @@
|
||||
## 截圖
|
||||
|
||||
在 macOS 上截取屏幕並分析圖像。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/screenshot [選項]
|
||||
```
|
||||
|
||||
### 選項
|
||||
|
||||
- 無 : 選擇窗口 (Claude 會確認選項)
|
||||
- `--window` : 指定窗口截圖
|
||||
- `--full` : 截取整個屏幕
|
||||
- `--crop` : 選擇範圍截圖
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 截取窗口並分析
|
||||
/screenshot --window
|
||||
"分析截取的画面"
|
||||
|
||||
# 選擇範圍並分析
|
||||
/screenshot --crop
|
||||
"說明選中範圍的內容"
|
||||
|
||||
# 全屏截圖並分析
|
||||
/screenshot --full
|
||||
"分析整個屏幕的構成"
|
||||
```
|
||||
|
||||
### 與 Claude 的協作
|
||||
|
||||
```bash
|
||||
# 無特定問題 - 情况分析
|
||||
/screenshot --crop
|
||||
(Claude 會自動分析屏幕內容，說明元素和構成)
|
||||
|
||||
# UI/UX 問題分析
|
||||
/screenshot --window
|
||||
"提出這個 UI 的問題點和改進方案"
|
||||
|
||||
# 錯誤分析
|
||||
/screenshot --window
|
||||
"告诉我這個錯誤消息的原因和解決方法"
|
||||
|
||||
# 設計審查
|
||||
/screenshot --full
|
||||
"從 UX 角度評估這個設計"
|
||||
|
||||
# 代碼分析
|
||||
/screenshot --crop
|
||||
"指出這段代碼的問題"
|
||||
|
||||
# 數據可視化分析
|
||||
/screenshot --crop
|
||||
"分析從這個圖表中可以讀取的趨勢"
|
||||
```
|
||||
|
||||
### 詳细示例
|
||||
|
||||
```bash
|
||||
# 從多個角度分析
|
||||
/screenshot --window
|
||||
"分析這個画面的以下方面：
|
||||
1. UI 的一致性
|
||||
2. 可訪問性問題
|
||||
3. 改進建議"
|
||||
|
||||
# 為比较分析多次截圖
|
||||
/screenshot --window
|
||||
# (保存 before 圖像)
|
||||
# 進行更改
|
||||
/screenshot --window
|
||||
# (保存 after 圖像)
|
||||
"比较 before 和 after 圖像，分析變更點和改進效果"
|
||||
|
||||
# 聚焦特定元素
|
||||
/screenshot --crop
|
||||
"評估選中按钮的設計是否與其他元素協調"
|
||||
```
|
||||
|
||||
### 禁止事項
|
||||
|
||||
- **禁止在未截圖的情况下說"已截圖"**
|
||||
- **禁止尝試分析不存在的圖像文件**
|
||||
- **`/screenshot` 命令不會實際執行截圖**
|
||||
|
||||
### 注意事項
|
||||
|
||||
- 未指定選項時，請提示以下選擇：
|
||||
|
||||
```
|
||||
"請選擇截圖方式？
|
||||
1. 選擇窗口 (--window) → screencapture -W
|
||||
2. 整個屏幕 (--full) → screencapture -x
|
||||
3. 選擇範圍 (--crop) → screencapture -i"
|
||||
```
|
||||
|
||||
- 請在用戶執行 screencapture 命令後開始圖像分析
|
||||
- 指定具體問題或觀點可以進行更有针對性的分析
|
||||
66
commands/search-gemini.md
Normal file
66
commands/search-gemini.md
Normal file
@@ -0,0 +1,66 @@
|
||||
## Gemini 網絡搜索
|
||||
|
||||
使用 Gemini CLI 執行網絡搜索以獲取最新資訊。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 通過 Gemini CLI 進行網絡搜索 (必须)
|
||||
gemini --prompt "WebSearch: <搜索查询>"
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 使用 Gemini CLI
|
||||
gemini --prompt "WebSearch: React 19 新功能"
|
||||
gemini --prompt "WebSearch: TypeError Cannot read property of undefined 解決方法"
|
||||
```
|
||||
|
||||
### 與 Claude 配合
|
||||
|
||||
```bash
|
||||
# 文檔搜索和摘要
|
||||
gemini --prompt "WebSearch: Next.js 14 App Router 官方文檔"
|
||||
「請總結搜索結果並說明主要功能」
|
||||
|
||||
# 錯誤調查
|
||||
cat error.log
|
||||
gemini --prompt "WebSearch: [錯誤消息] 解決方法"
|
||||
「請從搜索結果中提出最合適的解決方法」
|
||||
|
||||
# 技術比较
|
||||
gemini --prompt "WebSearch: Rust vs Go performance benchmark 2024"
|
||||
「請從搜索結果總結性能差異」
|
||||
```
|
||||
|
||||
### 詳细示例
|
||||
|
||||
```bash
|
||||
# 從多個來源收集資訊
|
||||
gemini --prompt "WebSearch: GraphQL best practices 2024 multiple sources"
|
||||
「請從搜索結果整理多個可靠來源的資訊」
|
||||
|
||||
# 調查時間序列變化
|
||||
gemini --prompt "WebSearch: JavaScript ES2015 ES2016 ES2017 ES2018 ES2019 ES2020 ES2021 ES2022 ES2023 ES2024 features"
|
||||
「請按時間顺序整理各版本的主要變更」
|
||||
|
||||
# 限定特定域名搜索
|
||||
gemini --prompt "WebSearch: site:github.com Rust WebAssembly projects stars:>1000"
|
||||
「請按星標數量從高到低列出 10 個項目」
|
||||
|
||||
# 最新的安全資訊
|
||||
gemini --prompt "WebSearch: CVE-2024 Node.js vulnerabilities"
|
||||
「請總結發現的漏洞影響和對策」
|
||||
```
|
||||
|
||||
### 禁止事項
|
||||
|
||||
- **禁止使用 Claude 的內置 WebSearch 工具**
|
||||
- 需要網絡搜索時，必须使用 `gemini --prompt "WebSearch: ..."`
|
||||
|
||||
### 注意事項
|
||||
|
||||
- **如果 Gemini CLI 可用，必须使用 `gemini --prompt "WebSearch: ..."`**
|
||||
- 網絡搜索結果不一定總是最新的
|
||||
- 重要資訊建議通過官方文檔或可靠來源確認
|
||||
1137
commands/semantic-commit.md
Normal file
1137
commands/semantic-commit.md
Normal file
File diff suppressed because it is too large
Load Diff
90
commands/sequential-thinking.md
Normal file
90
commands/sequential-thinking.md
Normal file
@@ -0,0 +1,90 @@
|
||||
## 顺序思考
|
||||
|
||||
通過動態且迭代的思考過程，逐步解決復杂問題。這是一种在思考過程中可以調整方向和重新審視的灵活方法。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 請求 Claude 進行分阶段思考
|
||||
「請用 sequential-thinking 考虑[课題]」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 算法設計
|
||||
「請用 sequential-thinking 設計高效的緩存策略」
|
||||
|
||||
# 問題解決
|
||||
「請用 sequential-thinking 解決數據庫性能問題」
|
||||
|
||||
# 設計探讨
|
||||
「請用 sequential-thinking 探讨實時通知系統的設計」
|
||||
```
|
||||
|
||||
### 與 Claude 配合
|
||||
|
||||
```bash
|
||||
# 復杂的實現方针
|
||||
「請用 sequential-thinking 探讨認證系統的實現方针。考虑 OAuth2、JWT、會話管理」
|
||||
|
||||
# Bug 原因分析
|
||||
「請用 sequential-thinking 分析內存洩漏的原因。包含代碼審查和性能分析結果」
|
||||
|
||||
# 重構策略
|
||||
cat src/complex_module.js
|
||||
「請用 sequential-thinking 制定此模塊的重構策略」
|
||||
|
||||
# 技術選型
|
||||
「請用 sequential-thinking 分析前端框架的選擇。考虑項目需求和約束」
|
||||
```
|
||||
|
||||
### 思考過程
|
||||
|
||||
1. **初始分析** - 基本理解和分解問題
|
||||
2. **假設生成** - 建立解決方案的假設
|
||||
3. **驗證與更正** - 驗證假設，必要時更正
|
||||
4. **分支與探索** - 探索多個解決路徑
|
||||
5. **整合與結論** - 得出最優解
|
||||
|
||||
### 特點
|
||||
|
||||
- **動態調整** - 可在思考過程中轉換方向
|
||||
- **假設驗證** - 建立假設並驗證的循環
|
||||
- **分支思考** - 同時探索多個思考路徑
|
||||
- **逐步细化** - 逐步優化解決方案
|
||||
- **灵活性** - 基于新資訊調整方针
|
||||
|
||||
### 詳细示例
|
||||
|
||||
```bash
|
||||
# 復杂系統設計
|
||||
「請用 sequential-thinking 探讨電商網站的微服務設計。包括訂單處理、庫存管理、支付的協作」
|
||||
|
||||
# 安全設計
|
||||
「請用 sequential-thinking 探讨 API 安全設計。包括認證、授權、速率限制、審計日誌」
|
||||
|
||||
# 性能優化
|
||||
「請用 sequential-thinking 探讨大規模數據處理的優化。考虑內存使用、處理速度、可擴展性」
|
||||
|
||||
# 依賴管理
|
||||
「請用 sequential-thinking 探讨 monorepo 的依賴管理策略。包括構建時間、部署、測試執行」
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
sequential-thinking 最適合需要逐步深化思考的復杂問題。對于簡單問題或有明確答案的情况，請使用常規的提問形式。
|
||||
|
||||
### 執行示例
|
||||
|
||||
```bash
|
||||
# 使用示例
|
||||
「請用 sequential-thinking 探讨 GraphQL Schema 的設計」
|
||||
|
||||
# 預期行為
|
||||
# 1. 初始分析：分析 GraphQL Schema 的基本需求
|
||||
# 2. 假設生成：探讨多种設計模式
|
||||
# 3. 驗證：驗證各模式的優缺點
|
||||
# 4. 分支：必要時探索新方法
|
||||
# 5. 整合：提出最優的 Schema 設計
|
||||
```
|
||||
59
commands/show-plan.md
Normal file
59
commands/show-plan.md
Normal file
@@ -0,0 +1,59 @@
|
||||
## 顯示計劃
|
||||
|
||||
顯示當前會話中正在執行或已執行的計劃。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/show-plan
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 確認當前計劃
|
||||
/show-plan
|
||||
「顯示正在執行的計劃」
|
||||
|
||||
# 没有計劃時
|
||||
/show-plan
|
||||
「當前會話没有計劃」
|
||||
```
|
||||
|
||||
### 功能
|
||||
|
||||
- 檢測由 exit_plan_mode 創建的計劃
|
||||
- 搜索包含實施計劃、實施內容、計劃等關鍵詞的標題
|
||||
- 格式化並顯示計劃內容
|
||||
- 没有計劃時明確通知
|
||||
|
||||
### 與 Claude 配合
|
||||
|
||||
```bash
|
||||
# 實施過程中確認計劃
|
||||
「我在實施什么來着？」
|
||||
/show-plan
|
||||
|
||||
# 執行多個任務時
|
||||
「让我再確認一下當前計劃」
|
||||
/show-plan
|
||||
|
||||
# 計劃執行後回顾
|
||||
「請顯示刚才執行的計劃內容」
|
||||
/show-plan
|
||||
```
|
||||
|
||||
### 檢測模式
|
||||
|
||||
基于 exit_plan_mode 生成的計劃格式，檢測以下模式：
|
||||
|
||||
- 以 `##` 開头的標題 (包含計劃、Plan)
|
||||
- `### 變更內容`
|
||||
- `### 實施內容`
|
||||
- `### 實施計劃`
|
||||
- `### 1.` 等带編号的標題
|
||||
|
||||
### 注意事項
|
||||
|
||||
- 仅顯示當前會話內的計劃 (不包括過去的會話)
|
||||
- 優先顯示最新的計劃
|
||||
174
commands/smart-review.md
Normal file
174
commands/smart-review.md
Normal file
@@ -0,0 +1,174 @@
|
||||
## 智能審查
|
||||
|
||||
分析當前情况，自動建議最佳角色和方法的命令。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/smart-review # 分析當前目錄
|
||||
/smart-review <文件/目錄> # 分析特定對象
|
||||
```
|
||||
|
||||
### 自動判定邏輯
|
||||
|
||||
### 基于文件擴展名的判定
|
||||
|
||||
- `package.json`, `*.tsx`, `*.jsx`, `*.css`, `*.scss` → **frontend**
|
||||
- `Dockerfile`, `docker-compose.yml`, `*.yaml` → **architect**
|
||||
- `*.test.js`, `*.spec.ts`, `test/`, `__tests__/` → **qa**
|
||||
- `*.rs`, `Cargo.toml`, `performance/` → **performance**
|
||||
|
||||
### 安全相關文件檢測
|
||||
|
||||
- `auth.js`, `security.yml`, `.env`, `config/auth/` → **security**
|
||||
- `login.tsx`, `signup.js`, `jwt.js` → **security + frontend**
|
||||
- `api/auth/`, `middleware/auth/` → **security + architect**
|
||||
|
||||
### 復合判定模式
|
||||
|
||||
- `mobile/` + `*.swift`, `*.kt`, `react-native/` → **mobile**
|
||||
- `webpack.config.js`, `vite.config.js`, `large-dataset/` → **performance**
|
||||
- `components/` + `responsive.css` → **frontend + mobile**
|
||||
- `api/` + `auth/` → **security + architect**
|
||||
|
||||
### 錯誤與問題分析
|
||||
|
||||
- 堆棧跟蹤、`error.log`, `crash.log` → **analyzer**
|
||||
- `memory leak`, `high CPU`, `slow query` → **performance + analyzer**
|
||||
- `SQL injection`, `XSS`, `CSRF` → **security + analyzer**
|
||||
|
||||
### 建議模式
|
||||
|
||||
### 單一角色建議
|
||||
|
||||
```bash
|
||||
$ /smart-review src/auth/login.js
|
||||
→ 「檢測到認證文件」
|
||||
→ 「推薦使用 security 角色分析」
|
||||
→ 「是否執行？ [y]es / [n]o / [m]ore options」
|
||||
```
|
||||
|
||||
### 多角色建議
|
||||
|
||||
```bash
|
||||
$ /smart-review src/mobile/components/
|
||||
→ 「📱🎨 檢測到移動端 + 前端元素」
|
||||
→ 「推薦方法：」
|
||||
→ 「[1] mobile 角色單独」
|
||||
→ 「[2] frontend 角色單独」
|
||||
→ 「[3] multi-role mobile,frontend」
|
||||
→ 「[4] role-debate mobile,frontend」
|
||||
```
|
||||
|
||||
### 問題分析時的建議
|
||||
|
||||
```bash
|
||||
$ /smart-review error.log
|
||||
→ 「⚠️ 檢測到錯誤日誌」
|
||||
→ 「使用 analyzer 角色開始根本原因分析」
|
||||
→ 「[自動執行] /role analyzer」
|
||||
|
||||
$ /smart-review slow-api.log
|
||||
→ 「🐌 檢測到性能問題」
|
||||
→ 「推薦：[1]/role performance [2]/role-debate performance,analyzer」
|
||||
```
|
||||
|
||||
### 復杂設計決策時的建議
|
||||
|
||||
```bash
|
||||
$ /smart-review architecture-design.md
|
||||
→ 「🏗️🔒⚡ 檢測到架構 + 安全 + 性能元素」
|
||||
→ 「由于設計決策復杂，推薦讨論形式」
|
||||
→ 「[推薦] /role-debate architect,security,performance」
|
||||
→ 「[替代] /multi-role architect,security,performance」
|
||||
```
|
||||
|
||||
### 建議邏輯詳情
|
||||
|
||||
### 優先級判定
|
||||
|
||||
1. **Security** - 認證、授權、加密相關最優先
|
||||
2. **Critical Errors** - 系統停機、數據丢失紧急處理
|
||||
3. **Architecture** - 大規模變更、技術選型慎重考虑
|
||||
4. **Performance** - 直接影響用戶體驗
|
||||
5. **Frontend/Mobile** - UI/UX 改進
|
||||
6. **QA** - 質量保證、測試相關
|
||||
|
||||
### 推薦讨論的條件
|
||||
|
||||
- 涉及 3 個以上角色時
|
||||
- 存在安全性與性能的權衡時
|
||||
- 包含架構大幅變更時
|
||||
- 同時影響移動端和 Web 時
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 分析當前目錄
|
||||
/smart-review
|
||||
「請建議最佳的角色和方法」
|
||||
|
||||
# 分析特定文件
|
||||
/smart-review src/auth/login.js
|
||||
「請建議此文件的最佳審查方法」
|
||||
|
||||
# 分析錯誤日誌
|
||||
/smart-review error.log
|
||||
「請建議解決此錯誤的最佳方法」
|
||||
```
|
||||
|
||||
### 實際示例
|
||||
|
||||
### 項目整體分析
|
||||
|
||||
```bash
|
||||
$ /smart-review
|
||||
→ 「📊 正在分析項目...」
|
||||
→ 「檢測到 React + TypeScript 項目」
|
||||
→ 「確認包含認證功能 + API + 移動端支持」
|
||||
→ 「」
|
||||
→ 「💡 推薦工作流程：」
|
||||
→ 「1. security 檢查認證系統」
|
||||
→ 「2. frontend 評估 UI/UX」
|
||||
→ 「3. mobile 確認移動端優化」
|
||||
→ 「4. architect 審查整體設計」
|
||||
→ 「」
|
||||
→ 「是否自動執行？ [y]es / [s]elect role / [c]ustom」
|
||||
```
|
||||
|
||||
### 特定問題分析
|
||||
|
||||
```bash
|
||||
$ /smart-review "JWT 有效期應该如何設置"
|
||||
→ 「🤔 檢測到技術設計決策」
|
||||
→ 「這是需要多個專業視角的問題」
|
||||
→ 「」
|
||||
→ 「推薦方法：」
|
||||
→ 「/role-debate security,performance,frontend」
|
||||
→ 「原因：需要平衡安全性、性能和用戶體驗」
|
||||
```
|
||||
|
||||
### 與 Claude 配合
|
||||
|
||||
```bash
|
||||
# 結合文件內容分析
|
||||
cat src/auth/middleware.js
|
||||
/smart-review
|
||||
「請結合此文件內容從安全角度分析」
|
||||
|
||||
# 結合錯誤分析
|
||||
npm run build 2>&1 | tee build-error.log
|
||||
/smart-review build-error.log
|
||||
「請建議構建錯誤的解決方法」
|
||||
|
||||
# 設計咨询
|
||||
/smart-review
|
||||
「請讨論應该選擇 React Native 還是 Progressive Web App」
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
- 建議仅供參考，最終決定由用戶做出
|
||||
- 復杂問題推薦使用讨論形式 (role-debate)
|
||||
- 簡單問題使用單一角色通常就足够
|
||||
- 安全相關問題必须推薦使用專業角色確認
|
||||
559
commands/spec.md
Normal file
559
commands/spec.md
Normal file
@@ -0,0 +1,559 @@
|
||||
## Spec
|
||||
|
||||
**「在編寫代碼之前赋予結構」** - 完全遵循 Kiro 的規格驅動開發
|
||||
|
||||
與傳統代碼生成工具不同，實現 Kiro 的規格驅動開發，重點是為開發的混沌赋予結構。從最少的需求輸入，逐步展開到產品經理級別的詳细規格和可實施的設計，**從原型到生產環境**保證一致的質量。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 請求 Claude 的 Spec Mode(最少需求輸入)
|
||||
「創建[功能描述]的 spec」
|
||||
|
||||
# Kiro 式分阶段展開：
|
||||
# 1. 簡單需求 → 自動生成詳细用戶故事
|
||||
# 2. 使用 EARS 記法的結構化需求描述
|
||||
# 3. 通過分阶段對話精细化規格
|
||||
# 4. 生成 3 個独立文件：
|
||||
# - requirements.md: EARS 記法的需求定義
|
||||
# - design.md: 包含 Mermaid 圖、TypeScript 接口的設計
|
||||
# - tasks.md: 自動應用最佳實践的實施計劃
|
||||
```
|
||||
|
||||
### 實證效果 (Kiro 實績)
|
||||
|
||||
**2 天完成安全文件共享應用**
|
||||
|
||||
```bash
|
||||
「創建文件共享系統 (支持加密) 的 spec」
|
||||
→ 2 天完成生產級別的加密文件共享應用
|
||||
→ 自動應用安全最佳實践
|
||||
→ 無需额外提示
|
||||
```
|
||||
|
||||
**新手一晚開發遊戲**
|
||||
|
||||
```bash
|
||||
「創建 2D 益智遊戲的 spec」
|
||||
→ 遊戲開發新手的開源開發者
|
||||
→ 一晚完成遊戲創建
|
||||
→ 實現邏輯由 Kiro 處理，開發者專注創造性
|
||||
```
|
||||
|
||||
**週末從原型到生產**
|
||||
|
||||
```bash
|
||||
「創建電商網站商品管理系統的 spec」
|
||||
→ 一個週末從概念到可運行的原型
|
||||
→ 從原型到生產環境的一致質量
|
||||
→ 通過 spec-driven development 的結構化方法
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 新功能的 spec 創建 (最少輸入)
|
||||
「商品評論系統
|
||||
- 星級評分功能
|
||||
- 評論發布
|
||||
- 圖片上傳」
|
||||
|
||||
# 系統功能的 spec 創建
|
||||
「用戶認證
|
||||
- OAuth 支持
|
||||
- 多因素認證」
|
||||
|
||||
# API 功能的 spec 創建
|
||||
「支付系統 API
|
||||
- Stripe 集成
|
||||
- 重視安全性」
|
||||
```
|
||||
|
||||
### 與 Claude 配合
|
||||
|
||||
```bash
|
||||
# 復杂功能 spec
|
||||
「創建聊天功能的 spec。包括 WebSocket、實時通知、歷史管理」
|
||||
|
||||
# 數據庫關聯功能 spec
|
||||
「創建電商網站庫存管理功能的 spec。包括商品添加、庫存更新、警報功能」
|
||||
|
||||
# 前端功能 spec
|
||||
「創建 React 儀表板的 spec。包括圖表顯示、筛選器、導出功能」
|
||||
|
||||
# 後端功能 spec
|
||||
「創建 RESTful API 的 spec。包括認證、驗證、日誌記錄」
|
||||
```
|
||||
|
||||
### Spec Mode 的特點
|
||||
|
||||
**分阶段對話工作流**
|
||||
|
||||
- 完全再現 Kiro 的核心價值——分阶段讨論
|
||||
- 在各阶段與用戶合作精细化規格
|
||||
- 經過疑問解決、選項讨論、批準流程後生成文件
|
||||
|
||||
**3 阶段的交互式展開**
|
||||
|
||||
- **Phase 1**: Requirements Discovery → 讨論 → 批準 → 生成 `requirements.md`
|
||||
- **Phase 2**: Design Exploration → 讨論 → 批準 → 生成 `design.md`
|
||||
- **Phase 3**: Implementation Planning → 讨論 → 批準 → 生成 `tasks.md`
|
||||
|
||||
**動態規格制定**
|
||||
|
||||
- 通過對話解決需求的模糊性
|
||||
- 提示和讨論技術選項
|
||||
- 說明權衡並確認判斷
|
||||
|
||||
### 詳细示例
|
||||
|
||||
```bash
|
||||
# 復杂系統功能
|
||||
「創建在線支付系統的 spec。包括 Stripe 集成、安全性、錯誤處理」
|
||||
|
||||
# 前端功能
|
||||
「創建 React 組件的 spec。包括狀態管理、属性設計、測試」
|
||||
|
||||
# 後端功能
|
||||
「創建 GraphQL API 的 spec。包括 Schema 設計、解析器、認證」
|
||||
|
||||
# DevOps 功能
|
||||
「創建 CI/CD 管道的 spec。包括測試自動化、部署、監控」
|
||||
```
|
||||
|
||||
### 分阶段對話工作流 (Phase by Phase)
|
||||
|
||||
#### Phase 1: Requirements Discovery & Discussion
|
||||
|
||||
**1. 從最少輸入自動擴展 (Kiro 式)**
|
||||
|
||||
```text
|
||||
用戶：「用戶管理系統
|
||||
- 登錄功能
|
||||
- 個人資料編輯
|
||||
- 管理员權限」
|
||||
|
||||
Claude：「從需求生成詳细用戶故事。
|
||||
這個理解正確吗？
|
||||
|
||||
自動生成的用戶故事：
|
||||
- 用戶注冊和認證功能 (支持 OAuth)
|
||||
- 個人資料管理功能 (头像、設置)
|
||||
- 權限管理功能 (RBAC)
|
||||
- 密碼重置功能
|
||||
- 安全審計日誌
|
||||
|
||||
已補充未明確的细节。還需要其他功能吗？」
|
||||
```
|
||||
|
||||
**2. 使用 EARS 記法的結構化需求描述**
|
||||
|
||||
```text
|
||||
Claude：「使用 Kiro 的 EARS 記法結構化需求：
|
||||
|
||||
EARS 記法需求定義：
|
||||
|
||||
WHEN 用戶尝試登錄時
|
||||
GIVEN 輸入正確的郵箱和密碼
|
||||
THEN 系統確認認證
|
||||
AND 成功時重定向到儀表板
|
||||
|
||||
WHILE 用戶在個人資料編輯页面時
|
||||
THE SYSTEM SHALL 實時執行驗證
|
||||
AND 預覽顯示更改內容
|
||||
|
||||
WHERE 需要管理员權限的功能
|
||||
IS 尝試訪問時
|
||||
THE SYSTEM SHALL 確認權限級別
|
||||
AND 不足時拒绝訪問」
|
||||
```
|
||||
|
||||
**3. 邊緣情况和安全需求的自動補充**
|
||||
|
||||
```text
|
||||
Claude：「基于 Kiro 的最佳實践，還考虑了以下情况：
|
||||
|
||||
安全需求 (自動補充)：
|
||||
- 暴力攻擊對策
|
||||
- 會話管理和超時
|
||||
- CSRF 保護和 XSS 對策
|
||||
- 密碼強度要求
|
||||
|
||||
邊緣情况 (自動檢測)：
|
||||
- 同時登錄限制
|
||||
- 账戶鎖定功能
|
||||
- 數據遷移時的一致性保證
|
||||
- 大量請求時的負載均衡
|
||||
|
||||
這些需求合適吗？」
|
||||
```
|
||||
|
||||
**5. Phase 1 完成和批準**
|
||||
|
||||
```text
|
||||
Claude：「Requirements Phase 已完成。
|
||||
可以生成 requirements.md 吗？」
|
||||
→ 「繼續」→ 生成 requirements.md
|
||||
```
|
||||
|
||||
#### Phase 2: Design Exploration & Discussion
|
||||
|
||||
**1. 代碼庫分析 + 自動設計建議 (Kiro 式)**
|
||||
|
||||
```text
|
||||
Claude：「分析現有代碼庫，提出最佳架構：
|
||||
|
||||
代碼庫分析結果：
|
||||
- 認證：JWT + Express.js(v4.18.x)
|
||||
- 數據庫：PostgreSQL(v14+)
|
||||
- 前端：React + TypeScript(v18+)
|
||||
- 現有模式：Repository 模式、Service 層分離
|
||||
|
||||
Kiro 推薦架構：
|
||||
- 符合 Clean Architecture
|
||||
- Domain-Driven Design 元素
|
||||
- 部分應用 CQRS 模式
|
||||
- 自動化的安全最佳實践
|
||||
|
||||
使用這個設計吗？」
|
||||
```
|
||||
|
||||
**2. 使用 Mermaid 圖的可視化設計**
|
||||
|
||||
```text
|
||||
Claude：「自動生成系統設計的 Mermaid 圖：
|
||||
|
||||
自動生成的架構圖：
|
||||
|
||||
graph TB
|
||||
Client[React Client] --> API[Express API Gateway]
|
||||
API --> Auth[Auth Service]
|
||||
API --> User[User Service]
|
||||
API --> Profile[Profile Service]
|
||||
|
||||
Auth --> AuthDB[(Auth Database)]
|
||||
User --> UserDB[(User Database)]
|
||||
Profile --> ProfileDB[(Profile Database)]
|
||||
|
||||
Auth --> JWT[JWT Service]
|
||||
Auth --> OAuth[OAuth Provider]
|
||||
|
||||
還需要生成數據流圖吗？」
|
||||
```
|
||||
|
||||
**3. TypeScript 接口自動生成**
|
||||
|
||||
```text
|
||||
Claude：「基于設計自動生成 TypeScript 接口：
|
||||
|
||||
自動生成的 TypeScript 接口：
|
||||
|
||||
// Domain entities
|
||||
interface User {
|
||||
readonly id: UserId;
|
||||
readonly email: Email;
|
||||
readonly profile: UserProfile;
|
||||
readonly auth: AuthSettings;
|
||||
readonly permissions: Permission[];
|
||||
readonly createdAt: Date;
|
||||
readonly updatedAt: Date;
|
||||
}
|
||||
|
||||
interface UserProfile {
|
||||
readonly displayName: string;
|
||||
readonly avatar: AvatarUrl;
|
||||
readonly preferences: UserPreferences;
|
||||
}
|
||||
|
||||
interface AuthSettings {
|
||||
readonly passwordHash: PasswordHash;
|
||||
readonly mfaEnabled: boolean;
|
||||
readonly lastLoginAt: Date;
|
||||
readonly failedAttempts: number;
|
||||
}
|
||||
|
||||
// Use cases
|
||||
interface UserRepository {
|
||||
findById(id: UserId): Promise<User | null>;
|
||||
findByEmail(email: Email): Promise<User | null>;
|
||||
save(user: User): Promise<void>;
|
||||
}
|
||||
|
||||
interface AuthenticationService {
|
||||
authenticate(credentials: LoginCredentials): Promise<AuthResult>;
|
||||
refreshToken(token: RefreshToken): Promise<AccessToken>;
|
||||
}
|
||||
|
||||
使用這個接口設計吗？」
|
||||
```
|
||||
|
||||
**4. Phase 2 完成和批準**
|
||||
|
||||
```text
|
||||
|
||||
Claude：「Design Phase 已完成。
|
||||
可以生成 design.md 吗？」
|
||||
→ 「繼續」→ 生成 design.md
|
||||
|
||||
```
|
||||
|
||||
#### Phase 3: Implementation Planning & Discussion
|
||||
|
||||
**1. 最佳實践自動應用 (Kiro 式)**
|
||||
|
||||
```text
|
||||
|
||||
Claude：「生成了自動應用 Kiro 最佳實践的實施計劃：
|
||||
|
||||
自動生成的實施策略：
|
||||
|
||||
1. 安全第一開發
|
||||
- 自動集成 OWASP Top 10 對策
|
||||
- 自動實現加密和哈希
|
||||
- 自動生成安全測試
|
||||
|
||||
2. 強制清洁架構
|
||||
- 自動實現層分離
|
||||
- 自動應用依賴倒置
|
||||
- 強制可測試設計
|
||||
|
||||
3. 性能優化
|
||||
- 自動實現緩存策略
|
||||
- 數據庫優化
|
||||
- 利用異步處理
|
||||
|
||||
使用這個方法吗？」
|
||||
|
||||
```
|
||||
|
||||
**2. 質量檢查點自動設置**
|
||||
|
||||
```text
|
||||
|
||||
Claude：「自動設置各實施阶段的質量檢查點：
|
||||
|
||||
自動質量保證流程：
|
||||
|
||||
Phase 3a: 後端實施
|
||||
|
||||
- [ ] 安全掃描 (SAST/DAST)
|
||||
- [ ] API 規範測試 (OpenAPI 合規)
|
||||
- [ ] 性能測試 (負載和響應)
|
||||
- [ ] 漏洞掃描 (依賴關系和 CVE)
|
||||
|
||||
Phase 3b: 前端實施
|
||||
|
||||
- [ ] 無障礙測試 (WCAG 2.1 AA)
|
||||
- [ ] 瀏覽器兼容性測試
|
||||
- [ ] 響應式設計驗證
|
||||
- [ ] 安全头確認
|
||||
|
||||
Phase 3c: 集成和部署
|
||||
|
||||
- [ ] E2E 測試套件
|
||||
- [ ] CI/CD 管道配置
|
||||
- [ ] 監控和日誌設置
|
||||
- [ ] 生產環境安全審計
|
||||
|
||||
全部自動執行。有额外的質量標準吗？」
|
||||
|
||||
```
|
||||
|
||||
**3. 依賴關系和風險緩解的自動分析**
|
||||
|
||||
```text
|
||||
|
||||
Claude：「自動分析實施顺序和風險緩解策略：
|
||||
|
||||
優化的實施顺序：
|
||||
|
||||
Week 1: 基礎設施和安全基礎
|
||||
|
||||
- 數據庫設計和模式創建
|
||||
- 認證基礎 (JWT + 會話管理)
|
||||
- 安全中間件實施
|
||||
- 基本 API 端點
|
||||
|
||||
Week 2: 核心功能實施
|
||||
|
||||
- 用戶管理功能
|
||||
- 個人資料管理功能
|
||||
- 權限管理系統
|
||||
- 驗證和錯誤處理
|
||||
|
||||
Week 3: 高級功能和優化
|
||||
|
||||
- 多因素認證實施
|
||||
- 審計日誌功能
|
||||
- 性能優化
|
||||
- 前端集成
|
||||
|
||||
自動檢測的風險緩解策略：
|
||||
|
||||
- 多因素認證：分阶段引入 (SMS→應用認證)
|
||||
- 會話管理：Redis 集群配置
|
||||
- 大量訪問：速率限制 + CDN 利用
|
||||
- 數據一致性：加強事務管理
|
||||
|
||||
這個計劃没有問題吗？」
|
||||
|
||||
```
|
||||
|
||||
**4. Phase 3 完成和批準**
|
||||
|
||||
```text
|
||||
|
||||
Claude：「Implementation Planning Phase 已完成。
|
||||
可以生成 tasks.md 吗？」
|
||||
→ 「繼續」→ 生成 tasks.md
|
||||
|
||||
```
|
||||
|
||||
### Kiro 特有的功能
|
||||
|
||||
**EARS 記法 (Easy Approach to Requirements Syntax)**
|
||||
|
||||
```text
|
||||
# Kiro 標準的 EARS 記法模式
|
||||
|
||||
WHEN [情况・觸發器]
|
||||
GIVEN [前提條件]
|
||||
THEN [系統行為]
|
||||
AND [额外行為]
|
||||
|
||||
WHILE [狀態・流程]
|
||||
THE SYSTEM SHALL [必须行為]
|
||||
AND [相關行為]
|
||||
|
||||
WHERE [功能・組件]
|
||||
IS [條件・狀態]
|
||||
THE SYSTEM SHALL [對應行為]
|
||||
```
|
||||
|
||||
**自動生成功能**
|
||||
|
||||
- **Mermaid 圖**: 自動生成架構和數據流圖
|
||||
- **TypeScript 接口**: 基于設計自動創建類型定義
|
||||
- **最佳實践**: 自動集成安全和性能對策
|
||||
- **質量檢查點**: 自動設置分阶段質量標準
|
||||
|
||||
**hooks 聯動**
|
||||
|
||||
- 文件保存時的自動質量檢查
|
||||
- 自動應用代碼標準
|
||||
- 自動執行安全掃描
|
||||
- 自動驗證 OWASP Top 10 對策
|
||||
|
||||
**原型→生產質量保證**
|
||||
|
||||
- 通過結構化方法的一致設計
|
||||
- 強制安全第一開發
|
||||
- 自動應用可擴展架構
|
||||
- 集成持續質量管理
|
||||
|
||||
### 注意事項
|
||||
|
||||
**適用範圍**
|
||||
|
||||
- Spec Mode 最適合功能實施
|
||||
- 簡單修復或小規模更改使用常規實施形式
|
||||
- 推薦用于新功能開發或復杂功能改造
|
||||
|
||||
**質量保證**
|
||||
|
||||
- 明確各阶段的完成標準
|
||||
- 實施前的設計審查
|
||||
- 包括測試和無障礙的全面質量標準
|
||||
|
||||
**執行注意事項**
|
||||
|
||||
- 解決需求的模糊性後再進入設計阶段
|
||||
- 設計完成後生成實施任務
|
||||
- 重視各阶段的批準流程
|
||||
|
||||
### 觸發短語和控制
|
||||
|
||||
#### 分阶段工作流控制
|
||||
|
||||
**開始觸發器**
|
||||
|
||||
- 「創建[功能名]的 spec」
|
||||
- 「想用 spec 驅動開發[功能名]」
|
||||
- 「從規格書設計[功能名]」
|
||||
|
||||
**阶段進度控制**
|
||||
|
||||
- **「繼續」**: 完成當前阶段並生成文件，進入下一阶段
|
||||
- **「修改」**: 在當前阶段內調整和改進內容
|
||||
- **「重做」**: 從头開始當前阶段
|
||||
- **「詳细說明」**: 提供更詳细的說明或選項
|
||||
- **「跳過」**: 跳過當前阶段進入下一個 (不推薦)
|
||||
|
||||
**文件生成時機**
|
||||
|
||||
```text
|
||||
Phase 1 完成 → 「繼續」 → 生成 requirements.md
|
||||
Phase 2 完成 → 「繼續」 → 生成 design.md
|
||||
Phase 3 完成 → 「繼續」 → 生成 tasks.md
|
||||
```
|
||||
|
||||
### 執行示例 (分阶段流程)
|
||||
|
||||
```bash
|
||||
# 使用示例
|
||||
用戶：「創建用戶管理系統的 spec」
|
||||
|
||||
# Phase 1: Requirements Discovery
|
||||
Claude: [開始需求確認和讨論]
|
||||
用戶: [響應・讨論・修改]
|
||||
Claude: 「Requirements Phase 已完成。可以繼續吗？」
|
||||
用戶: 「繼續」
|
||||
→ 生成 requirements.md
|
||||
|
||||
# Phase 2: Design Exploration
|
||||
Claude: [開始設計提案和讨論]
|
||||
用戶: [技術選擇・架構讨論]
|
||||
Claude: 「Design Phase 已完成。可以繼續吗？」
|
||||
用戶: 「繼續」
|
||||
→ 生成 design.md
|
||||
|
||||
# Phase 3: Implementation Planning
|
||||
Claude: [開始實施計劃讨論]
|
||||
用戶: [優先級・風險・工時讨論]
|
||||
Claude: 「Implementation Phase 已完成。可以繼續吗？」
|
||||
用戶: 「繼續」
|
||||
→ 生成 tasks.md
|
||||
|
||||
# 完成
|
||||
Claude: 「spec 驅動開發的準備已完成。可以開始實施。」
|
||||
```
|
||||
|
||||
### 與 /plan 的區別
|
||||
|
||||
| 特徵 | /plan | /spec |
|
||||
| -------- | ---------------- | --------------------------------------------------- |
|
||||
| 對象 | 一般實施計劃 | 功能規格驅動開發 |
|
||||
| 輸出格式 | 單一計劃文檔 | 3 個独立文件 (requirements.md、design.md、tasks.md) |
|
||||
| 需求定義 | 基本需求整理 | 使用 EARS 記法的詳细驗收標準 |
|
||||
| 設計 | 以技術選型為中心 | 基于代碼庫分析 |
|
||||
| 實施 | 一般任務分解 | 考虑依賴關系的序列 |
|
||||
| 質量保證 | 基本測試策略 | 全面質量要求 (測試、無障礙、性能) |
|
||||
| 同步 | 靜態計劃 | 動態 spec 更新 |
|
||||
|
||||
### 推薦用例
|
||||
|
||||
**推薦使用 spec**
|
||||
|
||||
- 新功能開發
|
||||
- 復杂功能改造
|
||||
- API 設計
|
||||
- 數據庫設計
|
||||
- UI/UX 實施
|
||||
|
||||
**推薦使用 plan**
|
||||
|
||||
- 系統整體設計
|
||||
- 基礎設施構建
|
||||
- 重構
|
||||
- 技術選型
|
||||
- 架構變更
|
||||
186
commands/style-ai-writing.md
Normal file
186
commands/style-ai-writing.md
Normal file
@@ -0,0 +1,186 @@
|
||||
## AI 寫作檢查
|
||||
|
||||
檢測 AI 生成文本的機械化模式，並提供更自然的中文改進建議。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
/ai-writing-check [選項]
|
||||
```
|
||||
|
||||
### 選項
|
||||
|
||||
- 無參數 : 分析當前文件或選中的文本
|
||||
- `--file <path>` : 分析特定文件
|
||||
- `--dir <path>` : 批量分析目錄內的文件
|
||||
- `--severity <level>` : 檢測級別 (all/high/medium)
|
||||
- `--fix` : 自動修復檢測到的模式
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 檢查文件的 AI 痕迹
|
||||
cat README.md
|
||||
/ai-writing-check
|
||||
「檢查這個文檔的 AI 痕迹並提供改進方案」
|
||||
|
||||
# 分析特定文件
|
||||
/ai-writing-check --file docs/guide.md
|
||||
「檢測 AI 風格的表達並建議自然的表達方式」
|
||||
|
||||
# 掃描整個項目
|
||||
/ai-writing-check --dir . --severity high
|
||||
「只報告項目中重要的 AI 痕迹問題」
|
||||
```
|
||||
|
||||
### 檢測模式
|
||||
|
||||
#### 1. 列表格式的機械化模式
|
||||
|
||||
```markdown
|
||||
檢測示例：
|
||||
|
||||
- **重要**: 這是重要的項目
|
||||
- 已完成的項目 (带勾選標記)
|
||||
- 熱門話題 (带火焰表情)
|
||||
- 準備啟動 (带火箭表情)
|
||||
|
||||
改進示例：
|
||||
|
||||
- 重要項目：這是重要的項目
|
||||
- 已完成的項目
|
||||
- 熱門話題
|
||||
- 準備啟動
|
||||
```
|
||||
|
||||
#### 2. 夸张和炒作表達
|
||||
|
||||
```markdown
|
||||
檢測示例：
|
||||
革命性的技術將改變行業。
|
||||
這完全解決了問題。
|
||||
像魔法一樣運行。
|
||||
|
||||
改進示例：
|
||||
有效的技術將為行業带來變化。
|
||||
解決了许多問題。
|
||||
運行流畅。
|
||||
```
|
||||
|
||||
#### 3. 機械化的強調模式
|
||||
|
||||
```markdown
|
||||
檢測示例：
|
||||
**想法**: 有新的提議 (带灯泡表情)
|
||||
**注意**: 重要警告事項 (带警告表情)
|
||||
|
||||
改進示例：
|
||||
想法：有新的提議
|
||||
注意事項：重要警告事項
|
||||
```
|
||||
|
||||
#### 4. 冗余的技術寫作
|
||||
|
||||
```markdown
|
||||
檢測示例：
|
||||
首先先進行設置。
|
||||
可以使用這個工具。
|
||||
大幅提升性能。
|
||||
|
||||
改進示例：
|
||||
首先進行設置。
|
||||
可以使用這個工具。
|
||||
性能提升 30%。
|
||||
```
|
||||
|
||||
### 與 Claude 配合
|
||||
|
||||
```bash
|
||||
# 文檔整體的 AI 痕迹分析
|
||||
cat article.md
|
||||
/ai-writing-check
|
||||
「從以下角度分析並提供改進方案：
|
||||
1. 機械化表達的檢測
|
||||
2. 自然中文的修改建議
|
||||
3. 按優先級排列的改進列表」
|
||||
|
||||
# 聚焦特定模式
|
||||
/ai-writing-check --file blog.md
|
||||
「特別關注夸张表達和冗余表達並提供改進建議」
|
||||
|
||||
# 批量檢查多個文件
|
||||
find . -name "*.md" -type f
|
||||
/ai-writing-check --dir docs/
|
||||
「分析整個文檔的 AI 痕迹並創建摘要」
|
||||
```
|
||||
|
||||
### 詳细示例
|
||||
|
||||
```bash
|
||||
# 改進前後對比
|
||||
/ai-writing-check --file draft.md
|
||||
「檢測 AI 風格的表達，按以下格式展示：
|
||||
- 問題位置 (带行号)
|
||||
- 問題類型和原因
|
||||
- 具體改進方案
|
||||
- 改進效果」
|
||||
|
||||
# 自動修復模式
|
||||
/ai-writing-check --file report.md --fix
|
||||
「自動修復檢測到的模式並報告結果」
|
||||
|
||||
# 項目 AI 痕迹報告
|
||||
/ai-writing-check --dir . --severity all
|
||||
「分析整個項目的 AI 痕迹：
|
||||
1. 統計資訊 (按模式分類的檢測數)
|
||||
2. 問題最多的文件 TOP 5
|
||||
3. 改進優先級矩阵
|
||||
4. 分阶段改進計劃」
|
||||
```
|
||||
|
||||
### 高級用法
|
||||
|
||||
```bash
|
||||
# 應用自定義規則
|
||||
/ai-writing-check --file spec.md
|
||||
「作為技術規格書，使用以下额外標準檢查：
|
||||
- 模糊表達 (適当的、根據需要)
|
||||
- 缺乏具體性 (高速 → 具體數值)
|
||||
- 術語使用不一致」
|
||||
|
||||
# CI/CD 集成檢查
|
||||
/ai-writing-check --dir docs/ --severity high
|
||||
「以可在 GitHub Actions 執行的格式輸出結果：
|
||||
- 錯誤數和文件名
|
||||
- 需要修復的行号
|
||||
- exit code 設置」
|
||||
|
||||
# 風格指南合規檢查
|
||||
/ai-writing-check --file manual.md
|
||||
「基于公司風格指南進行额外檢查：
|
||||
- 敬語使用 (統一礼貌用語)
|
||||
- 專業術語的適当使用
|
||||
- 對讀者的考虑」
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
- AI 痕迹的判定因上下文而異，建議仅作參考
|
||||
- 根據文檔類型 (技術文檔、博客、手冊等) 調整標準
|
||||
- 不必接受所有建議，選擇合適的即可
|
||||
- `--fix` 選項會自動修復檢測到的模式
|
||||
|
||||
### 命令執行時的行為
|
||||
|
||||
執行 `/ai-writing-check` 命令時，Claude 會進行以下處理：
|
||||
|
||||
1. **模式檢測**: 從指定的文件或文本中檢測 AI 風格的模式
|
||||
2. **具體修改建議**: 為每個問題提供带行号的修改方案
|
||||
3. **--fix 模式**: 自動修復檢測到的模式，並顯示結果摘要
|
||||
4. **報告生成**: 提供檢測數、改進優先級、修改前後對比
|
||||
|
||||
Claude 會讀取實際文件內容，基于 textlint-rule-preset-ai-writing 的規則進行分析。
|
||||
|
||||
### 參考
|
||||
|
||||
此命令參考了 [textlint-rule-preset-ai-writing](https://github.com/textlint-ja/textlint-rule-preset-ai-writing) 的規則集創建。這是一個 textlint 規則預設，用于檢測 AI 生成文本的機械化模式，促進更自然的表達。
|
||||
223
commands/task.md
Normal file
223
commands/task.md
Normal file
@@ -0,0 +1,223 @@
|
||||
## Task
|
||||
|
||||
啟動專用代理，自主執行復杂的搜索、調查和分析任務。通過組合多個工具進行大規模資訊處理，重視上下文效率。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 向 Claude 請求 Task
|
||||
「用 Task 調查[课題]」
|
||||
```
|
||||
|
||||
### Task 的特點
|
||||
|
||||
**自主執行**
|
||||
|
||||
- 自動組合多個工具執行
|
||||
- 分阶段資訊收集和分析
|
||||
- 結果整合和結構化報告
|
||||
|
||||
**高效資訊處理**
|
||||
|
||||
- 優化上下文消耗
|
||||
- 大規模文件搜索和解析
|
||||
- 從外部資訊源收集數據
|
||||
|
||||
**質量保證**
|
||||
|
||||
- 資訊源可靠性檢查
|
||||
- 多角度驗證
|
||||
- 自動補充缺失資訊
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 復杂代碼庫調查
|
||||
「用 Task 調查這個功能在哪些文件中實現」
|
||||
|
||||
# 大規模文件搜索
|
||||
「用 Task 識別配置文件的不一致」
|
||||
|
||||
# 外部資訊收集
|
||||
「用 Task 調查最新的 AI 技術趨勢」
|
||||
```
|
||||
|
||||
### 與 Claude 配合
|
||||
|
||||
```bash
|
||||
# 復杂問題分析
|
||||
「用 Task 分析內存洩漏的原因。包括性能分析結果和日誌」
|
||||
|
||||
# 依賴關系調查
|
||||
「用 Task 調查這個 npm 包的漏洞」
|
||||
|
||||
# 竞品分析
|
||||
「用 Task 調查竞品服務的 API 規格」
|
||||
|
||||
# 架構分析
|
||||
「用 Task 分析這個微服務的依賴關系」
|
||||
```
|
||||
|
||||
### 與其他命令的區別
|
||||
|
||||
#### Task vs 其他命令
|
||||
|
||||
| 命令 | 主要用途 | 執行方式 | 資訊收集 |
|
||||
| ------------------- | ---------------- | ---------- | -------------- |
|
||||
| **Task** | 調查・分析・搜索 | 自主執行 | 多源 |
|
||||
| ultrathink | 深度思考・判斷 | 結構化思考 | 以現有知識為主 |
|
||||
| sequential-thinking | 問題解決・設計 | 分阶段思考 | 按需 |
|
||||
| plan | 制定實施計劃 | 批準流程 | 需求分析 |
|
||||
|
||||
#### 判斷流程圖
|
||||
|
||||
```text
|
||||
需要資訊收集？
|
||||
├─ Yes → 多源・大規模？
|
||||
│ ├─ Yes → **Task**
|
||||
│ └─ No → 常規提問
|
||||
└─ No → 需要深度思考？
|
||||
├─ Yes → ultrathink/sequential-thinking
|
||||
└─ No → 常規提問
|
||||
```
|
||||
|
||||
### 有效場景・不需要的場景
|
||||
|
||||
**有效場景**
|
||||
|
||||
- 復杂代碼庫調查 (依賴關系、架構分析)
|
||||
- 大規模文件搜索 (特定實現模式、配置文件)
|
||||
- 外部資訊收集和整理 (技術趨勢、庫調查)
|
||||
- 多源資訊整合 (日誌解析、指標分析)
|
||||
- 重復調查工作 (安全審計、技術债務調查)
|
||||
- 想避免上下文消耗的大規模分析
|
||||
|
||||
**不需要的場景**
|
||||
|
||||
- 簡單問題或可用現有知識回答的內容
|
||||
- 短時間完成的單次工作
|
||||
- 需要交互式確認和咨询的工作
|
||||
- 實施或設計判斷 (plan 或思考類命令更合適)
|
||||
|
||||
### 分類詳细示例
|
||||
|
||||
#### 系統分析・調查
|
||||
|
||||
```bash
|
||||
# 復杂系統分析
|
||||
「用 Task 識別電商網站的瓶頸。調查數據庫、API、前端的整體」
|
||||
|
||||
# 架構分析
|
||||
「用 Task 分析這個微服務的依賴關系。包括 API 通信和數據流」
|
||||
|
||||
# 技術债務調查
|
||||
「用 Task 分析遗留代碼的技術债務。包括重構優先級」
|
||||
```
|
||||
|
||||
#### 安全・合規
|
||||
|
||||
```bash
|
||||
# 安全審計
|
||||
「用 Task 調查這個應用的漏洞。基于 OWASP Top 10」
|
||||
|
||||
# 许可證調查
|
||||
「用 Task 調查項目依賴的许可證問題」
|
||||
|
||||
# 配置文件審計
|
||||
「用 Task 識別安全配置的不一致。包括環境間的差異」
|
||||
```
|
||||
|
||||
#### 性能・優化
|
||||
|
||||
```bash
|
||||
# 性能分析
|
||||
「用 Task 識別應用中的慢查询。包括執行計劃和優化方案」
|
||||
|
||||
# 資源使用調查
|
||||
「用 Task 調查內存洩漏的原因。包括性能分析結果和代碼解析」
|
||||
|
||||
# 打包大小分析
|
||||
「用 Task 調查前端打包大小問題。包括優化建議」
|
||||
```
|
||||
|
||||
#### 外部資訊收集
|
||||
|
||||
```bash
|
||||
# 技術趨勢調查
|
||||
「用 Task 調查 2024 年的 JavaScript 框架動向」
|
||||
|
||||
# 竞品分析
|
||||
「用 Task 調查竞品服務的 API 規格。包括功能對比表」
|
||||
|
||||
# 庫評估
|
||||
「用 Task 調查狀態管理庫的比较。包括性能和學習成本」
|
||||
```
|
||||
|
||||
### 執行流程和質量保證
|
||||
|
||||
#### Task 的執行流程
|
||||
|
||||
```text
|
||||
1. 初始分析
|
||||
├─ 分解课題和確定調查範圍
|
||||
├─ 選擇必要的工具和資訊源
|
||||
└─ 制定執行計劃
|
||||
|
||||
2. 資訊收集
|
||||
├─ 文件搜索・代碼解析
|
||||
├─ 收集外部資訊
|
||||
└─ 數據結構化
|
||||
|
||||
3. 分析・整合
|
||||
├─ 分析收集資訊的關聯性
|
||||
├─ 識別模式和問題點
|
||||
└─ 驗證假設
|
||||
|
||||
4. 報告・建議
|
||||
├─ 結構化結果
|
||||
├─ 創建改進建議
|
||||
└─ 提示下一步行動
|
||||
```
|
||||
|
||||
#### 質量保證
|
||||
|
||||
- **資訊源可靠性檢查**: 通過多源確認事實
|
||||
- **完整性確認**: 檢查調查對象是否有遗漏
|
||||
- **一致性驗證**: 確認矛盾資訊的整合性
|
||||
- **實用性評估**: 評估建議的可行性和效果
|
||||
|
||||
### 錯誤處理和約束事項
|
||||
|
||||
#### 常見約束
|
||||
|
||||
- **外部 API 使用限制**: 速率限制和認證錯誤
|
||||
- **大文件處理限制**: 內存和超時約束
|
||||
- **訪問權限問題**: 文件和目錄的訪問限制
|
||||
|
||||
#### 錯誤時的處理
|
||||
|
||||
- **部分結果報告**: 仅使用獲取的資訊進行分析
|
||||
- **替代方案建議**: 在約束下的替代調查方法
|
||||
- **分阶段執行**: 分割執行大規模任務
|
||||
|
||||
### 注意事項
|
||||
|
||||
- Task 最適合復杂且自主的調查和分析任務
|
||||
- 簡單問題或需要即時回答時，請使用常規提問形式
|
||||
- 調查結果作為參考資訊，重要判斷必须驗證
|
||||
- 收集外部資訊時，注意資訊的時效性和準確性
|
||||
|
||||
### 執行示例
|
||||
|
||||
```bash
|
||||
# 使用示例
|
||||
「用 Task 調查 GraphQL Schema 的問題」
|
||||
|
||||
# 預期行為
|
||||
# 1. 啟動專用代理
|
||||
# 2. 搜索 GraphQL 相關文件
|
||||
# 3. 解析 Schema 定義
|
||||
# 4. 與最佳實践比较
|
||||
# 5. 識別問題並提出改進建議
|
||||
# 6. 創建結構化報告
|
||||
```
|
||||
185
commands/tech-debt.md
Normal file
185
commands/tech-debt.md
Normal file
@@ -0,0 +1,185 @@
|
||||
## Tech Debt
|
||||
|
||||
定量分析專案的技術債務，視覺化健康評分與開發效率的影響。透過趨勢分析追蹤改善狀況，計算時間成本並建立有優先順序的改善計劃。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 檢查專案配置以分析技術債務
|
||||
ls -la
|
||||
"分析此專案的技術債務並建立改善計劃"
|
||||
```
|
||||
|
||||
### 專案健康儀表板
|
||||
|
||||
```text
|
||||
專案健康評分: 72/100
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📊 各類別評分
|
||||
├─ 依賴關係新鮮度: ████████░░ 82% (最新: 45/55)
|
||||
├─ 文件完整度: ███░░░░░░░ 35% (缺少 README、API 文件)
|
||||
├─ 測試覆蓋率: ██████░░░░ 65% (目標: 80%)
|
||||
├─ 安全性: ███████░░░ 78% (漏洞: 2 個 Medium)
|
||||
├─ 架構: ██████░░░░ 60% (循環依賴: 3 處)
|
||||
└─ 程式碼品質: ███████░░░ 70% (高複雜度: 12 檔案)
|
||||
|
||||
📈 趨勢 (過去 30 天)
|
||||
├─ 整體評分: 68 → 72 (+4) ↗️
|
||||
├─ 改善項目: 12 個 ✅
|
||||
├─ 新債務: 3 個 ⚠️
|
||||
├─ 解決債務: 8 個 🎉
|
||||
└─ 改善速度: +0.13/天
|
||||
|
||||
⏱️ 債務的時間影響
|
||||
├─ 開發速度下降: -20% (新功能開發需要 1.25 倍正常時間)
|
||||
├─ Bug 修復時間: +15% (平均修復時間 2h → 2.3h)
|
||||
├─ 程式碼審查: +30% (複雜性增加理解時間)
|
||||
├─ 入職培訓: +50% (新成員理解所需時間)
|
||||
└─ 累積延遲時間: 相當於每週 40 小時
|
||||
|
||||
🎯 改善預期效果 (基於時間)
|
||||
├─ 立即效果: 開發速度 +10% (1 週後)
|
||||
├─ 短期效果: Bug 率 -25% (1 個月後)
|
||||
├─ 中期效果: 開發速度 +30% (3 個月後)
|
||||
├─ 長期效果: 維護時間 -50% (6 個月後)
|
||||
└─ ROI: 投資 40 小時 → 回收 120 小時 (3 個月)
|
||||
```
|
||||
|
||||
### 基本範例
|
||||
|
||||
```bash
|
||||
# 健康評分的詳細分析
|
||||
find . -name "*.js" -o -name "*.ts" | xargs wc -l | sort -rn | head -10
|
||||
"計算專案健康評分並依類別評估"
|
||||
|
||||
# TODO/FIXME 的債務影響分析
|
||||
grep -r "TODO\|FIXME\|HACK\|XXX\|WORKAROUND" . --exclude-dir=node_modules --exclude-dir=.git
|
||||
"以債務影響 (時間×重要性) 評估這些 TODO"
|
||||
|
||||
# 依賴關係健康檢查
|
||||
ls -la | grep -E "package.json|Cargo.toml|pubspec.yaml|go.mod|requirements.txt"
|
||||
"計算依賴關係新鮮度評分，分析更新的風險與效果"
|
||||
```
|
||||
|
||||
### 與 Claude 協作
|
||||
|
||||
```bash
|
||||
# 全面性技術債務分析
|
||||
ls -la && find . -name "*.md" -maxdepth 2 -exec head -20 {} \;
|
||||
"從這些角度分析此專案的技術債務:
|
||||
1. 程式碼品質 (複雜度、重複、可維護性)
|
||||
2. 依賴關係健康
|
||||
3. 安全風險
|
||||
4. 效能問題
|
||||
5. 測試覆蓋不足"
|
||||
|
||||
# 架構債務分析
|
||||
find . -type d -name "src" -o -name "lib" -o -name "app" | head -10 | xargs ls -la
|
||||
"識別架構層級的技術債務並提出重構計劃"
|
||||
|
||||
# 有優先順序的改善計劃
|
||||
"根據這些標準評估技術債務並以表格形式呈現:
|
||||
- 影響度 (高/中/低)
|
||||
- 修正成本 (時間)
|
||||
- 技術風險 (系統故障、資料遺失的可能性)
|
||||
- 改善帶來的時間節省效果
|
||||
- 建議實施時機"
|
||||
```
|
||||
|
||||
### 詳細範例
|
||||
|
||||
```bash
|
||||
# 自動偵測專案類型並分析
|
||||
find . -maxdepth 2 -type f \( -name "package.json" -o -name "Cargo.toml" -o -name "pubspec.yaml" -o -name "go.mod" -o -name "pom.xml" \)
|
||||
"基於偵測到的專案類型，分析:
|
||||
1. 語言/框架特有的技術債務
|
||||
2. 偏離最佳實務的部分
|
||||
3. 現代化機會
|
||||
4. 漸進式改善策略"
|
||||
|
||||
# 程式碼品質指標分析
|
||||
find . -type f -name "*" | grep -E "\.(js|ts|py|rs|go|dart|kotlin|swift|java)$" | wc -l
|
||||
"分析專案的程式碼品質並呈現這些指標:
|
||||
- 高循環複雜度的函數
|
||||
- 重複程式碼的偵測
|
||||
- 過長的檔案/函數
|
||||
- 缺乏適當的錯誤處理"
|
||||
|
||||
# 安全債務偵測
|
||||
grep -r "password\|secret\|key\|token" . --exclude-dir=.git --exclude-dir=node_modules | grep -v ".env.example"
|
||||
"偵測安全相關的技術債務，提出修正優先度與對策"
|
||||
|
||||
# 測試不足分析
|
||||
find . -type f \( -name "*test*" -o -name "*spec*" \) | wc -l && find . -type f -name "*.md" | xargs grep -l "test"
|
||||
"分析測試覆蓋率的技術債務並提出測試策略"
|
||||
```
|
||||
|
||||
### 債務優先順序矩陣
|
||||
|
||||
```text
|
||||
優先度 = (影響度 × 頻率) ÷ 修正成本
|
||||
```
|
||||
|
||||
| 優先度 | 對開發的影響 | 修正成本 | 時間節省效果 | 投資回報 | 回應期限 |
|
||||
| ----------------- | ------------ | -------- | ------------ | ----------------- | -------- |
|
||||
| **[P0] 立即回應** | 高 | 低 | > 5 倍 | 投資 1h→節省 5h+ | 立即 |
|
||||
| **[P1] 本週內** | 高 | 中 | 2-5 倍 | 投資 1h→節省 2-5h | 1 週內 |
|
||||
| **[P2] 本月內** | 低 | 高 | 1-2 倍 | 投資 1h→節省 1-2h | 1 個月內 |
|
||||
| **[P3] 本季內** | 低 | 低 | < 1 倍 | 投資=節省時間 | 3 個月內 |
|
||||
|
||||
### 債務類型別評估標準
|
||||
|
||||
| 債務類型 | 偵測方法 | 對開發的影響 | 修正時間 |
|
||||
| ------------------ | --------------------- | -------------------------- | -------- |
|
||||
| **架構債務** | 循環依賴、高耦合 | 變更時影響範圍大、測試困難 | 40-80h |
|
||||
| **安全債務** | CVE 掃描、OWASP | 漏洞風險、合規性 | 8-40h |
|
||||
| **效能債務** | N+1、記憶體洩漏 | 回應時間增加、資源消耗 | 16-40h |
|
||||
| **測試債務** | 覆蓋率 < 60% | Bug 偵測延遲、品質不穩定 | 20-60h |
|
||||
| **文件債務** | 缺少 README、API 文件 | 入職時間增加 | 8-24h |
|
||||
| **依賴關係債務** | 2+ 年未更新 | 安全風險、相容性問題 | 4-16h |
|
||||
| **程式碼品質債務** | 複雜度 > 10 | 理解/修正時間增加 | 2-8h |
|
||||
|
||||
### 技術債務影響度計算
|
||||
|
||||
```text
|
||||
影響度 = Σ(各元素權重 × 測量值)
|
||||
|
||||
📊 可測量的影響指標:
|
||||
├─ 對開發速度的影響
|
||||
│ ├─ 程式碼理解時間: +X% (與複雜度成正比)
|
||||
│ ├─ 變更時的影響範圍: Y 個檔案 (以耦合度測量)
|
||||
│ └─ 測試執行時間: Z 分鐘 (CI/CD 管道)
|
||||
│
|
||||
├─ 對品質的影響
|
||||
│ ├─ Bug 發生率: 複雜度每 10 增加 +25%
|
||||
│ ├─ 審查時間: 程式碼行數 × 複雜度係數
|
||||
│ └─ 測試不足風險: 覆蓋率 < 60% 時為高風險
|
||||
│
|
||||
└─ 對團隊效率的影響
|
||||
├─ 入職時間: 文件不足增加 +100%
|
||||
├─ 知識集中: 單一貢獻者比率 >80% 需注意
|
||||
└─ 程式碼重複造成的修正點: 重複率 × 變更頻率
|
||||
```
|
||||
|
||||
### 基於時間的 ROI 計算
|
||||
|
||||
```text
|
||||
ROI = (節省時間 - 投資時間) ÷ 投資時間 × 100
|
||||
|
||||
範例: 解決循環依賴
|
||||
├─ 投資時間: 16 小時 (重構)
|
||||
├─ 節省效果 (月):
|
||||
│ ├─ 編譯時間: -10 分/天 × 20 天 = 200 分
|
||||
│ ├─ 除錯時間: -2 小時/週 × 4 週 = 8 小時
|
||||
│ └─ 新功能開發: -30% 時間縮減 = 12 小時
|
||||
├─ 月節省時間: 23.3 小時
|
||||
└─ 3 個月 ROI: (70 - 16) ÷ 16 × 100 = 337%
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
- 自動偵測專案的語言與框架以進行特定分析
|
||||
- 以 0-100 分評估健康評分，70 分以上視為健康，50 分以下需要改善
|
||||
- 具體計算時間成本與改善效果，支援基於數據的決策制定
|
||||
- 如需金錢換算，請另外指定團隊平均時薪或專案特定係數
|
||||
242
commands/token-efficient.md
Normal file
242
commands/token-efficient.md
Normal file
@@ -0,0 +1,242 @@
|
||||
# Token 效率模式
|
||||
|
||||
AI 應答壓縮模式，將上下文使用量減少 30-50% 的效率化模式。
|
||||
|
||||
## 概述
|
||||
|
||||
Token 效率模式透過視覺符號和縮略語系統，壓縮 Claude 的應答內容。
|
||||
**產生的程式碼品質和內容完全不會改變**。改變的只是說明方式。
|
||||
|
||||
## 使用方法
|
||||
|
||||
```bash
|
||||
# 模式啟用
|
||||
「使用 Token 效率模式回應」
|
||||
「使用 --uc 模式」
|
||||
「使用簡潔模式」
|
||||
```
|
||||
|
||||
## 運作原理
|
||||
|
||||
### 1. 符號體系
|
||||
|
||||
#### 邏輯與流程
|
||||
|
||||
| 符號 | 意義 | 使用範例 |
|
||||
| ---- | ---------- | ------------------------------ |
|
||||
| → | 導致、引起 | `auth.js:45 → 🛡️ 安全風險` |
|
||||
| ⇒ | 轉換成 | `input ⇒ validated_output` |
|
||||
| ← | 回滾、返回 | `migration ← rollback` |
|
||||
| ⇄ | 雙向 | `sync ⇄ remote` |
|
||||
| & | 且、結合 | `🛡️ security & ⚡ performance` |
|
||||
| \| | 或、分隔 | `react\|vue\|angular` |
|
||||
| : | 定義、指定 | `scope: file\|module` |
|
||||
| » | 然後、序列 | `build » test » deploy` |
|
||||
| ∴ | 因此 | `tests ❌ ∴ code broken` |
|
||||
| ∵ | 因為 | `slow ∵ O(n²) algorithm` |
|
||||
|
||||
#### 狀態與進度
|
||||
|
||||
| 符號 | 意義 | 用途 |
|
||||
| ---- | ---------- | ------------ |
|
||||
| ✅ | 完成、成功 | 任務正常結束 |
|
||||
| ❌ | 失敗、錯誤 | 需要立即處理 |
|
||||
| ⚠️ | 警告 | 建議檢視 |
|
||||
| 🔄 | 進行中 | 目前活躍 |
|
||||
| ⏳ | 等待中 | 稍後執行 |
|
||||
| 🚨 | 緊急、重要 | 高優先級 |
|
||||
|
||||
#### 技術領域
|
||||
|
||||
| 符號 | 領域 | 用途 |
|
||||
| ---- | ------ | ------------ |
|
||||
| ⚡ | 效能 | 速度、最佳化 |
|
||||
| 🔍 | 分析 | 搜尋、調查 |
|
||||
| 🔧 | 設定 | 設置、工具 |
|
||||
| 🛡️ | 安全性 | 保護、安全性 |
|
||||
| 📦 | 部署 | 套件、打包 |
|
||||
| 🎨 | 設計 | UI、前端 |
|
||||
| 🏗️ | 架構 | 系統結構 |
|
||||
| 🗄️ | 資料庫 | 資料持久化 |
|
||||
| ⚙️ | 後端 | 伺服器處理 |
|
||||
| 🧪 | 測試 | 品質保證 |
|
||||
|
||||
### 2. 縮略語系統
|
||||
|
||||
#### 系統與架構
|
||||
|
||||
- `cfg` → configuration(設定)
|
||||
- `impl` → implementation(實作)
|
||||
- `arch` → architecture(架構)
|
||||
- `perf` → performance(效能)
|
||||
- `ops` → operations(運營)
|
||||
- `env` → environment(環境)
|
||||
|
||||
#### 開發流程
|
||||
|
||||
- `req` → requirements(需求)
|
||||
- `deps` → dependencies(相依性)
|
||||
- `val` → validation(驗證)
|
||||
- `auth` → authentication(認證)
|
||||
- `docs` → documentation(文件)
|
||||
- `std` → standards(標準)
|
||||
|
||||
#### 品質與分析
|
||||
|
||||
- `qual` → quality(品質)
|
||||
- `sec` → security(安全性)
|
||||
- `err` → error(錯誤)
|
||||
- `rec` → recovery(復原)
|
||||
- `sev` → severity(嚴重度)
|
||||
- `opt` → optimization(最佳化)
|
||||
|
||||
## 實例比較
|
||||
|
||||
### 例 1: 錯誤報告
|
||||
|
||||
**一般模式 (85 字元)**
|
||||
|
||||
```text
|
||||
認證系統的使用者驗證函式第 45 行發現了安全性弱點。
|
||||
```
|
||||
|
||||
**Token 高效 (34 字元)**
|
||||
|
||||
```text
|
||||
auth.js:45 → 🛡️ sec vuln in user val()
|
||||
```
|
||||
|
||||
### 例 2: 建置狀況
|
||||
|
||||
**一般模式 (120 字元)**
|
||||
|
||||
```text
|
||||
建置程序已正常完成。目前正在執行測試，之後將進行部署。
|
||||
```
|
||||
|
||||
**Token 高效 (32 字元)**
|
||||
|
||||
```text
|
||||
build ✅ » test 🔄 » deploy ⏳
|
||||
```
|
||||
|
||||
### 例 3: 效能分析
|
||||
|
||||
**一般模式 (95 字元)**
|
||||
|
||||
```text
|
||||
效能分析結果，演算法為 O(n²) 計算複雜度導致處理速度緩慢。
|
||||
```
|
||||
|
||||
**Token 高效 (40 字元)**
|
||||
|
||||
```text
|
||||
⚡ perf: slow ∵ O(n²) → optimize to O(n)
|
||||
```
|
||||
|
||||
## 適用場景
|
||||
|
||||
### ✅ 有效場合
|
||||
|
||||
- **長期除錯作業**：保持歷史記錄的同時提升效率
|
||||
- **大規模程式碼檢視**：簡潔分析大量檔案
|
||||
- **CI/CD 監控**：即時狀態更新
|
||||
- **專案進度報告**：一覽式列出多項任務狀態
|
||||
- **錯誤追蹤**：視覺化表現問題連鎖
|
||||
|
||||
### ❌ 應避免的場合
|
||||
|
||||
- 對初學者的說明
|
||||
- 詳細文件製作
|
||||
- 初次需求定義
|
||||
- 與非技術人員的溝通
|
||||
|
||||
## 實作範例
|
||||
|
||||
### 除錯作業
|
||||
|
||||
```text
|
||||
[14:23] breakpoint → vars: {user: null, token: expired}
|
||||
[14:24] step → auth.validate() ❌
|
||||
[14:25] check → token.exp < Date.now() ∴ expired
|
||||
[14:26] fix → refresh() → ✅
|
||||
[14:27] continue → main flow 🔄
|
||||
```
|
||||
|
||||
### 檔案分析結果
|
||||
|
||||
```text
|
||||
/src/auth/: 🛡️ issues × 3
|
||||
/src/api/: ⚡ bottleneck in handler()
|
||||
/src/db/: ✅ clean
|
||||
/src/utils/: ⚠️ deprecated methods
|
||||
/tests/: 🧪 coverage 78%
|
||||
```
|
||||
|
||||
### 專案狀態
|
||||
|
||||
```text
|
||||
Frontend: 🎨 ✅ 100%
|
||||
Backend: ⚙️ 🔄 75%
|
||||
Database: 🗄️ ✅ migrated
|
||||
Tests: 🧪 ⚠️ 68% (target: 80%)
|
||||
Deploy: 📦 ⏳ scheduled
|
||||
Security: 🛡️ 🚨 1 critical
|
||||
```
|
||||
|
||||
## 設定選項
|
||||
|
||||
```javascript
|
||||
// 壓縮等級
|
||||
--uc; // Ultra Compressed: 最大壓縮
|
||||
--mc; // Moderate Compressed: 中等壓縮
|
||||
--lc; // Light Compressed: 輕度壓縮
|
||||
|
||||
// 領域特化
|
||||
--dev; // 開發向壓縮
|
||||
--ops; // 營運向壓縮
|
||||
--sec; // 安全性向壓縮
|
||||
```
|
||||
|
||||
## 優點
|
||||
|
||||
1. **上下文節省**：30-50% 的 Token 減少
|
||||
2. **視覺理解**：符號讓直覺掌握變得容易
|
||||
3. **資訊密度提升**：相同空間內容納更多資訊
|
||||
4. **歷史保持**：維持更長的對話歷史
|
||||
5. **模式識別**：視覺模式讓問題發現更容易
|
||||
|
||||
## 注意事項
|
||||
|
||||
- 此模式僅改變 **AI 的回應風格**
|
||||
- 產生的**程式碼品質**不會改變
|
||||
- 需要時可以「使用一般模式說明」切換
|
||||
- 對初學者或非技術人員建議使用一般模式
|
||||
|
||||
## 命令範例
|
||||
|
||||
```bash
|
||||
# 啟用
|
||||
「Token 效率模式開啟」
|
||||
「簡潔回應」
|
||||
「使用 --uc 分析」
|
||||
|
||||
# 停用
|
||||
「回到一般模式」
|
||||
「詳細說明」
|
||||
「Token 效率模式關閉」
|
||||
```
|
||||
|
||||
## 實作的影響
|
||||
|
||||
| 項目 | 影響 |
|
||||
| -------------- | -------------- |
|
||||
| 產生程式碼品質 | 無變化 ✅ |
|
||||
| 實作正確性 | 無變化 ✅ |
|
||||
| 功能性 | 無變化 ✅ |
|
||||
| AI 說明方式 | 被壓縮 🔄 |
|
||||
| 上下文使用 | 減少 30-50% ⚡ |
|
||||
|
||||
---
|
||||
|
||||
💡 **專業提示**：長時間作業時，最初使用一般模式深化理解，之後切換到 Token 效率模式，可最佳化效率與上下文保持的平衡。
|
||||
65
commands/ultrathink.md
Normal file
65
commands/ultrathink.md
Normal file
@@ -0,0 +1,65 @@
|
||||
## Ultrathink
|
||||
|
||||
對復杂课題或重要決策執行分阶段的結構化思考過程。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 請求 Claude 進行深度思考
|
||||
「用 ultrathink 探讨[课題]」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 架構設計探讨
|
||||
「用 ultrathink 探讨應该選擇微服務還是單體架構」
|
||||
|
||||
# 技術選型分析
|
||||
「用 ultrathink 分析這個項目適合 Rust 還是 TypeScript」
|
||||
|
||||
# 問題解決深入探讨
|
||||
「用 ultrathink 探讨應用性能差的原因和改進方法」
|
||||
```
|
||||
|
||||
### 與 Claude 配合
|
||||
|
||||
```bash
|
||||
# 業務判斷
|
||||
「用 ultrathink 探讨新功能的優先級排序。從用戶價值、開發成本、技術風險的角度」
|
||||
|
||||
# 系統設計
|
||||
「用 ultrathink 探讨認證系統的設計。考虑安全性、可擴展性、可維護性」
|
||||
|
||||
# 權衡分析
|
||||
「用 ultrathink 分析 GraphQL vs REST API 的選擇。基于項目需求」
|
||||
|
||||
# 重構策略
|
||||
cat src/legacy_code.js
|
||||
「用 ultrathink 制定這個遗留代碼的重構策略」
|
||||
```
|
||||
|
||||
### 思考過程
|
||||
|
||||
1. **問題分解** - 將课題分解為組成要素
|
||||
2. **MECE 分析** - 無遗漏無重復地整理
|
||||
3. **多角度探讨** - 從技術、業務、用戶角度分析
|
||||
4. **交互式確認** - 在重要判斷點向用戶確認
|
||||
5. **有依據的建議** - 基于數據和邏輯的結論
|
||||
|
||||
### 詳细示例
|
||||
|
||||
```bash
|
||||
# 復杂技術债務的解決
|
||||
「用 ultrathink 探讨將 10 年的遗留系統現代化的策略。包括分阶段遷移、風險、ROI」
|
||||
|
||||
# 組織性课題
|
||||
「用 ultrathink 探讨開發團隊的擴展策略。假設從目前 5 人擴展到 20 人」
|
||||
|
||||
# 數據庫遷移
|
||||
「用 ultrathink 分析從 PostgreSQL 遷移到 DynamoDB。考虑成本、性能、運維」
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
ultrathink 最適合需要花時間深入思考的课題。對于簡單問題或需要即時回答的情况，請使用常規提問形式。
|
||||
202
commands/update-dart-doc.md
Normal file
202
commands/update-dart-doc.md
Normal file
@@ -0,0 +1,202 @@
|
||||
## 更新 Dart 文檔
|
||||
|
||||
系統地管理 Dart 文件的 DartDoc 注釋，維護高質量的中文文檔。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 同時執行新增和更新
|
||||
「為没有 DartDoc 注釋的類添加注釋，並更新不符合標準的注釋」
|
||||
|
||||
# 確認 PR 的更改文件
|
||||
「確認 PR #4308 中更改的文件是否有 Claude 標記」
|
||||
|
||||
# 特定目錄的文檔整理
|
||||
「為 packages/app/lib/ui/screen/ 下的 Widget 類添加 DartDoc」
|
||||
|
||||
# 不带標記執行
|
||||
/update-dart-doc --marker false
|
||||
「改進現有項目的 DartDoc(不添加 Claude 標記)」
|
||||
```
|
||||
|
||||
### 選項
|
||||
|
||||
- `--marker <true|false>` : 是否添加 Claude 標記 (默認：true)
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 1. 分析目標文件
|
||||
find . -name "*.dart" -not -path "*/.*" | grep -v "_test.dart" | grep -v "_vrt.dart"
|
||||
「識別缺少 DartDoc 的類 (注釋行數為 0 或少于 30 個字符)」
|
||||
|
||||
# 2. 添加文檔
|
||||
「為識別的類添加包含必要元素的 DartDoc 注釋」
|
||||
|
||||
# 3. 確認標記
|
||||
「確認所有添加或更新的 DartDoc 都有 Claude 標記」
|
||||
```
|
||||
|
||||
### 執行步骤
|
||||
|
||||
#### 1. 目標元素的優先級
|
||||
|
||||
1. 🔴 **最優先**: 没有 DartDoc 注釋的元素 (注釋行數為 0)
|
||||
2. 🟡 **次優先**: 不符合標準的元素 (少于 30 個字符或缺少必要元素)
|
||||
3. 🟢 **確認對象**: 没有 Claude 標記的現有注釋
|
||||
|
||||
**目標元素**：
|
||||
|
||||
- Class(所有類定義)
|
||||
- Enum(枚舉類型)
|
||||
- Extension(擴展方法)
|
||||
- 重要函數 (顶級函數，可選)
|
||||
|
||||
#### 2. DartDoc 編寫規則
|
||||
|
||||
**基本結構**：
|
||||
|
||||
```dart
|
||||
/// {元素的概要說明}(30-60 個字符，必需)
|
||||
///
|
||||
/// {詳细說明}(必须包含角色、使用場景、注意事項，50-200 個字符)
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
@注解 // 不更改現有注解
|
||||
class 類名 {
|
||||
```
|
||||
|
||||
**文體風格**：
|
||||
|
||||
- 礼貌用語 (敬語體)："顯示內容"、"管理狀態的類"
|
||||
- 使用中文標點："。"、"，"
|
||||
- 中文與半角英數字之間加半角空格
|
||||
- 技術術語使用英文："Authentication 狀態"
|
||||
- 每行不超過 80 個字符
|
||||
|
||||
#### 3. 按類別的描述示例
|
||||
|
||||
**狀態管理類 (Riverpod)**：
|
||||
|
||||
```dart
|
||||
/// 管理水平滑動手勢禁用狀態的 State。
|
||||
///
|
||||
/// 在需要禁用水平滑動的特定画面或操作中使用。
|
||||
/// 例如，轮播顯示或特定輸入時。
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
@Riverpod(keepAlive: true, dependencies: [])
|
||||
class HorizontalDragGestureIgnoreState extends _$HorizontalDragGestureIgnoreState {
|
||||
```
|
||||
|
||||
**Widget 類**：
|
||||
|
||||
```dart
|
||||
/// 顯示用戶個人資料的 Widget。
|
||||
///
|
||||
/// 垂直排列头像圖片、用戶名和狀態資訊，
|
||||
/// 點擊時跳轉到個人資料詳情页面。
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
class UserProfileWidget extends HookConsumerWidget {
|
||||
```
|
||||
|
||||
#### 4. 現有內容保留規則
|
||||
|
||||
1. **現有注釋符合標準時**: 保持原樣 (不新增)
|
||||
- 標準：30 個字符以上且包含必要元素 (概要、詳细、標記)
|
||||
2. **現有注釋不符合標準時**: 完全替換 (不重復)
|
||||
3. **没有現有注釋時**: 添加新注釋
|
||||
|
||||
**應保留的重要資訊**：
|
||||
|
||||
- URL 和鏈接：以 `See also:` 開头的引用
|
||||
- TODO 注釋：`TODO(user_name):` 格式
|
||||
- 注意事項：`注意:` 或 `Warning:` 等警告
|
||||
- 使用示例：以 `例:` 或 `Example:` 開头的代碼
|
||||
- 技術約束：性能或限制的描述
|
||||
|
||||
### Claude 標記管理
|
||||
|
||||
```bash
|
||||
# 標記格式
|
||||
/// Generated by Claude 🤖
|
||||
|
||||
# 在 PR 更改文件中確認標記
|
||||
gh pr diff 4308 --name-only | grep "\.dart$" | xargs grep -l "Generated by Claude"
|
||||
「為没有標記的文件添加標記」
|
||||
```
|
||||
|
||||
### 質量檢查清單
|
||||
|
||||
- ✅ **字符數**: 严格遵守概要 30-60 個字符、詳细 50-200 個字符
|
||||
- ✅ **必要元素**: 必须包含概要、詳细說明、Claude 標記三個元素
|
||||
- ✅ **完整性**: 記載角色、使用場景、注意事項
|
||||
- ✅ **一致性**: 統一使用礼貌用語 (敬語體)
|
||||
- ✅ **格式**: 中文與英文之間加半角空格
|
||||
- ✅ **準確性**: 分析實現，仅記載基于事實的描述
|
||||
- ✅ **結構**: 保留注解，注釋放在上方
|
||||
- ✅ **长度**: 每行不超過 80 個字符
|
||||
- ✅ **標記**: Claude 的更改必须添加標記
|
||||
|
||||
### 注意事項
|
||||
|
||||
**🔴 绝對禁止事項**：
|
||||
|
||||
- ❌ 更改文檔注釋以外的代碼
|
||||
- ❌ 推測實現细节 (仅記載事實)
|
||||
- ❌ 中英文不自然的混用
|
||||
- ❌ 刪除或更改現有注解
|
||||
- ❌ 與現有注釋重復
|
||||
- ❌ 為測試文件 (`*_test.dart`) 添加不符合字符數標準的注釋
|
||||
- ❌ 為 VRT 文件 (`*_vrt.dart`) 添加不符合字符數標準的注釋
|
||||
|
||||
**靜態分析和提交**：
|
||||
|
||||
```bash
|
||||
# 記錄執行結果
|
||||
ADDED_COMMENTS=0
|
||||
UPDATED_COMMENTS=0
|
||||
ERRORS=0
|
||||
|
||||
# 更改後確認
|
||||
melos analyze
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "🔴 錯誤：靜態分析失败"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 輸出執行摘要
|
||||
echo "📊 執行結果："
|
||||
echo "- 添加的注釋：$ADDED_COMMENTS 條"
|
||||
echo "- 更新的注釋：$UPDATED_COMMENTS 條"
|
||||
echo "- 錯誤數：$ERRORS 個"
|
||||
|
||||
# 提交示例
|
||||
git commit -m "docs: 添加和更新 DartDoc 注釋
|
||||
|
||||
- 為不符合標準的類、enum、extension 添加 DartDoc
|
||||
- 更新少于 30 個字符的注釋以符合標準
|
||||
- 統一添加 Claude 標記
|
||||
|
||||
執行結果：
|
||||
- 添加：$ADDED_COMMENTS 條
|
||||
- 更新：$UPDATED_COMMENTS 條
|
||||
|
||||
Generated by Claude 🤖"
|
||||
```
|
||||
|
||||
### 執行成功標準
|
||||
|
||||
1. **完成判定**: 满足以下所有條件時成功
|
||||
- `melos analyze` 顯示 PASSED
|
||||
- 錯誤數為 0
|
||||
- 添加和更新的注釋都符合標準
|
||||
|
||||
2. **部分成功**: 以下情况
|
||||
- 錯誤數少于 5 個
|
||||
- 90% 以上符合標準
|
||||
|
||||
3. **失败**: 以下情况
|
||||
- `melos analyze` 顯示 FAILED
|
||||
- 錯誤數為 5 個或以上
|
||||
306
commands/update-doc-string.md
Normal file
306
commands/update-doc-string.md
Normal file
@@ -0,0 +1,306 @@
|
||||
## 更新文檔字符串
|
||||
|
||||
系統地管理多語言的 docstring/注釋，維護高質量的文檔。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 自動檢測語言並執行
|
||||
「為没有 docstring 的類和函數添加注釋，並更新不符合標準的注釋」
|
||||
|
||||
# 指定語言執行
|
||||
/update-doc-string --lang python
|
||||
「按照 PEP 257 規範更新 Python 文件的 docstring」
|
||||
|
||||
# 特定目錄的文檔整理
|
||||
「為 src/components/ 下的函數添加 JSDoc」
|
||||
```
|
||||
|
||||
### 選項
|
||||
|
||||
- `--lang <en|zh-tw>` : 文檔記述語言 (默認：從現有注釋自動判定，無則為 en)
|
||||
- `--style <風格>` : 指定文檔風格 (有語言特定的默認值)
|
||||
- `--marker <true|false>` : 是否添加 Claude 標記 (默認：true)
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 1. 分析目標文件 (自動檢測編程語言)
|
||||
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.dart" -o -name "*.go" -o -name "*.rs" \) | grep -v test
|
||||
「識別缺少 docstring 的元素 (注釋行數為 0 或少于 30 個字符)」
|
||||
|
||||
# 2. 添加文檔 (自動判定語言)
|
||||
「為識別的元素添加包含語言特定必要元素的 docstring」
|
||||
# → 如果現有注釋中有中文則用中文，否則用英文
|
||||
|
||||
# 3. 添加文檔 (明確指定英文)
|
||||
/update-doc-string --lang en
|
||||
「Add docstrings with required elements to the identified elements」
|
||||
|
||||
# 4. 確認標記
|
||||
「確認所有添加或更新的 docstring 都有 Claude 標記」
|
||||
```
|
||||
|
||||
### 執行步骤
|
||||
|
||||
#### 1. 目標元素的優先級
|
||||
|
||||
1. 🔴 **最優先**: 没有 docstring/注釋的元素 (注釋行數為 0)
|
||||
2. 🟡 **次優先**: 不符合標準的元素 (少于 30 個字符或缺少必要元素)
|
||||
3. 🟢 **確認對象**: 没有 Claude 標記的現有注釋
|
||||
|
||||
**目標元素 (通用)**：
|
||||
|
||||
- Class/類定義
|
||||
- Function/函數和方法
|
||||
- Module/模塊 (Python, Go)
|
||||
- Enum/枚舉類型
|
||||
- Interface/接口 (TypeScript, Go)
|
||||
|
||||
#### 2. 語言特定編寫規則
|
||||
|
||||
**Python (PEP 257)**：
|
||||
|
||||
```python
|
||||
# 中文版 (默認)
|
||||
def calculate_total(items: List[Item]) -> float:
|
||||
"""計算商品列表的總金额。(30-60 個字符)
|
||||
|
||||
將每個商品的價格和數量相乘，返回含税總额。
|
||||
空列表時返回 0.0。(50-200 個字符)
|
||||
|
||||
Args:
|
||||
items: 要計算的商品列表
|
||||
|
||||
Returns:
|
||||
含税總金额
|
||||
|
||||
Generated by Claude 🤖
|
||||
"""
|
||||
|
||||
# 英文版 (--lang en)
|
||||
def calculate_total(items: List[Item]) -> float:
|
||||
"""Calculate the total amount for a list of items. (30-60 chars)
|
||||
|
||||
Multiplies the price and quantity of each item and returns
|
||||
the total with tax. Returns 0.0 for empty lists. (50-200 chars)
|
||||
|
||||
Args:
|
||||
items: List of items to calculate
|
||||
|
||||
Returns:
|
||||
Total amount with tax
|
||||
|
||||
Generated by Claude 🤖
|
||||
"""
|
||||
```
|
||||
|
||||
**JavaScript/TypeScript (JSDoc)**：
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* 顯示用戶個人資料的組件。(30-60 個字符)
|
||||
*
|
||||
* 顯示头像圖片、用戶名和狀態資訊，
|
||||
* 點擊時跳轉到個人資料詳情页面。(50-200 個字符)
|
||||
*
|
||||
* @param {Object} props - 組件属性
|
||||
* @param {string} props.userId - 用戶 ID
|
||||
* @param {boolean} [props.showStatus=true] - 狀態顯示標誌
|
||||
* @returns {JSX.Element} 渲染的組件
|
||||
*
|
||||
* @generated by Claude 🤖
|
||||
*/
|
||||
const UserProfile = ({ userId, showStatus = true }) => {
|
||||
```
|
||||
|
||||
**Go**：
|
||||
|
||||
```go
|
||||
// CalculateTotal 計算商品列表的總金额。(30-60 個字符)
|
||||
//
|
||||
// 將每個商品的價格和數量相乘，返回含税總额。
|
||||
// 空切片時返回 0.0。(50-200 個字符)
|
||||
//
|
||||
// Generated by Claude 🤖
|
||||
func CalculateTotal(items []Item) float64 {
|
||||
```
|
||||
|
||||
**Rust**：
|
||||
|
||||
```rust
|
||||
/// 計算商品列表的總金额。(30-60 個字符)
|
||||
///
|
||||
/// 將每個商品的價格和數量相乘，返回含税總额。
|
||||
/// 空向量時返回 0.0。(50-200 個字符)
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
pub fn calculate_total(items: &[Item]) -> f64 {
|
||||
```
|
||||
|
||||
**Dart (DartDoc)**：
|
||||
|
||||
```dart
|
||||
/// 顯示用戶個人資料的 Widget。(30-60 個字符)
|
||||
///
|
||||
/// 垂直排列头像圖片、用戶名和狀態資訊，
|
||||
/// 點擊時跳轉到個人資料詳情页面。(50-200 個字符)
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
class UserProfileWidget extends StatelessWidget {
|
||||
```
|
||||
|
||||
#### 3. 現有內容保留規則
|
||||
|
||||
1. **現有注釋符合標準時**: 保持原樣 (不新增)
|
||||
- 標準：30 個字符以上且包含必要元素 (概要、詳细、標記)
|
||||
2. **現有注釋不符合標準時**: 完全替換 (不重復)
|
||||
3. **没有現有注釋時**: 添加新注釋
|
||||
|
||||
**應保留的重要資訊**：
|
||||
|
||||
- URL 和鏈接：`See also:`、`@see`、`參照:` 等
|
||||
- TODO 注釋：`TODO:`、`FIXME:`、`XXX:` 格式
|
||||
- 注意事項：`Note:`、`Warning:`、`注意:` 等
|
||||
- 使用示例：`Example:`、`例:`、`# Examples` 等
|
||||
- 現有的參數和返回值說明
|
||||
|
||||
### 語言特定設置
|
||||
|
||||
```yaml
|
||||
# 語言特定默認設置
|
||||
languages:
|
||||
python:
|
||||
style: "google" # google, numpy, sphinx
|
||||
indent: 4
|
||||
quotes: '"""'
|
||||
|
||||
javascript:
|
||||
style: "jsdoc"
|
||||
indent: 2
|
||||
prefix: "/**"
|
||||
suffix: "*/"
|
||||
|
||||
typescript:
|
||||
style: "tsdoc"
|
||||
indent: 2
|
||||
prefix: "/**"
|
||||
suffix: "*/"
|
||||
|
||||
go:
|
||||
style: "godoc"
|
||||
indent: 0
|
||||
prefix: "//"
|
||||
|
||||
rust:
|
||||
style: "rustdoc"
|
||||
indent: 0
|
||||
prefix: "///"
|
||||
|
||||
dart:
|
||||
style: "dartdoc"
|
||||
indent: 0
|
||||
prefix: "///"
|
||||
```
|
||||
|
||||
### 質量檢查清單
|
||||
|
||||
- ✅ **字符數**: 严格遵守概要 30-60 個字符、詳细 50-200 個字符
|
||||
- ✅ **必要元素**: 必须包含概要、詳细說明、Claude 標記三個元素
|
||||
- ✅ **完整性**: 記載角色、使用場景、注意事項
|
||||
- ✅ **語言規範**: 遵循各語言的官方風格指南
|
||||
- ✅ **異常**: 錯誤和異常的說明 (如適用)
|
||||
- ✅ **準確性**: 分析實現，仅記載基于事實的描述
|
||||
|
||||
### 注意事項
|
||||
|
||||
**🔴 绝對禁止事項**：
|
||||
|
||||
- ❌ 更改文檔注釋以外的代碼
|
||||
- ❌ 推測實現细节 (仅記載事實)
|
||||
- ❌ 违反語言規範的格式
|
||||
- ❌ 刪除或更改現有的類型注解
|
||||
- ❌ 與現有注釋重復
|
||||
- ❌ 為測試文件添加不符合字符數標準的注釋
|
||||
|
||||
**執行和驗證**：
|
||||
|
||||
```bash
|
||||
# 記錄執行結果
|
||||
ADDED_COMMENTS=0
|
||||
UPDATED_COMMENTS=0
|
||||
ERRORS=0
|
||||
|
||||
# 從現有注釋自動判定語言
|
||||
# 檢測中文字符則為 zh-tw，否則為 en
|
||||
DOC_LANGUAGE="en" # 默認
|
||||
if grep -r '[一-龥]' --include="*.py" --include="*.js" --include="*.ts" --include="*.dart" --include="*.go" --include="*.rs" . 2>/dev/null | head -n 1; then
|
||||
DOC_LANGUAGE="zh-tw"
|
||||
fi
|
||||
|
||||
# 自動檢測編程語言並執行靜態分析
|
||||
if [ -f "*.py" ]; then
|
||||
pylint --disable=all --enable=missing-docstring .
|
||||
elif [ -f "*.js" ] || [ -f "*.ts" ]; then
|
||||
eslint . --rule 'jsdoc/require-jsdoc: error'
|
||||
elif [ -f "*.go" ]; then
|
||||
golint ./...
|
||||
elif [ -f "*.rs" ]; then
|
||||
cargo doc --no-deps
|
||||
elif [ -f "*.dart" ]; then
|
||||
melos analyze
|
||||
fi
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "🔴 錯誤：靜態分析失败"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 輸出執行摘要
|
||||
echo "📊 執行結果："
|
||||
echo "- 文檔語言：$DOC_LANGUAGE"
|
||||
echo "- 添加的注釋：$ADDED_COMMENTS 條"
|
||||
echo "- 更新的注釋：$UPDATED_COMMENTS 條"
|
||||
echo "- 錯誤數：$ERRORS 個"
|
||||
```
|
||||
|
||||
### 執行成功標準
|
||||
|
||||
1. **完成判定**: 满足以下所有條件時成功
|
||||
- 語言特定的靜態分析顯示 PASSED
|
||||
- 錯誤數為 0
|
||||
- 添加和更新的注釋都符合標準
|
||||
|
||||
2. **部分成功**: 以下情况
|
||||
- 錯誤數少于 5 個
|
||||
- 90% 以上符合標準
|
||||
|
||||
3. **失败**: 以下情况
|
||||
- 靜態分析顯示 FAILED
|
||||
- 錯誤數為 5 個或以上
|
||||
|
||||
### 與 Claude 配合
|
||||
|
||||
```bash
|
||||
# 分析整個項目 (自動判定語言)
|
||||
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" \)
|
||||
/update-doc-string
|
||||
「按照語言特定的最佳實践更新這個項目的 docstring」
|
||||
# → 如果現有注釋中有中文則用 ja，否則用 en
|
||||
|
||||
# 明確指定英文文檔
|
||||
/update-doc-string --lang en
|
||||
"Update docstrings following language-specific best practices"
|
||||
|
||||
# 明確指定中文文檔
|
||||
/update-doc-string --lang zh-tw
|
||||
「按照語言特定的最佳實践更新這個項目的 docstring」
|
||||
|
||||
# 不带標記執行 (自動判定語言)
|
||||
/update-doc-string --marker false
|
||||
"Improve existing docstrings without adding Claude markers"
|
||||
|
||||
# 英文文檔，不带標記
|
||||
/update-doc-string --lang en --marker false
|
||||
"Improve existing docstrings without adding Claude markers"
|
||||
```
|
||||
105
commands/update-flutter-deps.md
Normal file
105
commands/update-flutter-deps.md
Normal file
@@ -0,0 +1,105 @@
|
||||
## Flutter 依賴更新
|
||||
|
||||
安全地更新 Flutter 項目的依賴關系。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 確認依賴狀態並請求 Claude
|
||||
flutter pub deps --style=compact
|
||||
「將 pubspec.yaml 的依賴更新到最新版本」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 確認當前依賴
|
||||
cat pubspec.yaml
|
||||
「分析這個 Flutter 項目的依賴並告诉我可更新的包」
|
||||
|
||||
# 升級後確認
|
||||
flutter pub upgrade --dry-run
|
||||
「確認這個升級計劃中是否有破坏性變更」
|
||||
```
|
||||
|
||||
### 與 Claude 配合
|
||||
|
||||
```bash
|
||||
# 全面的依賴更新
|
||||
cat pubspec.yaml
|
||||
「分析 Flutter 的依賴並執行以下操作：
|
||||
1. 調查各包的最新版本
|
||||
2. 確認是否有破坏性變更
|
||||
3. 評估危險度 (安全・注意・危險)
|
||||
4. 提出必要的代碼更改
|
||||
5. 生成更新版 pubspec.yaml」
|
||||
|
||||
# 安全的分阶段更新
|
||||
flutter pub outdated
|
||||
「避免主版本升級，只更新可以安全升級的包」
|
||||
|
||||
# 特定包的更新影響分析
|
||||
「告诉我將 provider 更新到最新版本的影響和必要的更改」
|
||||
```
|
||||
|
||||
### 詳细示例
|
||||
|
||||
```bash
|
||||
# 包含 Release Notes 的詳细分析
|
||||
cat pubspec.yaml && flutter pub outdated
|
||||
「分析依賴，為每個包提供：
|
||||
1. 當前 → 最新版本
|
||||
2. 危險度評估 (安全・注意・危險)
|
||||
3. 主要變更 (來自 CHANGELOG)
|
||||
4. 必要的代碼修改
|
||||
以表格形式展示」
|
||||
|
||||
# Null Safety 遷移分析
|
||||
cat pubspec.yaml
|
||||
「識別不支持 Null Safety 的包，制定遷移計劃」
|
||||
```
|
||||
|
||||
### 危險度標準
|
||||
|
||||
```text
|
||||
安全 (🟢)：
|
||||
- 補丁版本升級 (1.2.3 → 1.2.4)
|
||||
- 仅修復 bug
|
||||
- 保證向後兼容
|
||||
|
||||
注意 (🟡)：
|
||||
- 次版本升級 (1.2.3 → 1.3.0)
|
||||
- 新增功能
|
||||
- 有弃用警告
|
||||
|
||||
危險 (🔴)：
|
||||
- 主版本升級 (1.2.3 → 2.0.0)
|
||||
- 破坏性變更
|
||||
- API 的刪除或更改
|
||||
```
|
||||
|
||||
### 執行更新
|
||||
|
||||
```bash
|
||||
# 創建備份
|
||||
cp pubspec.yaml pubspec.yaml.backup
|
||||
cp pubspec.lock pubspec.lock.backup
|
||||
|
||||
# 執行更新
|
||||
flutter pub upgrade
|
||||
|
||||
# 更新後確認
|
||||
flutter analyze
|
||||
flutter test
|
||||
flutter pub deps --style=compact
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
更新後必须進行功能測試。如果出現問題，使用以下命令恢復：
|
||||
|
||||
```bash
|
||||
cp pubspec.yaml.backup pubspec.yaml
|
||||
cp pubspec.lock.backup pubspec.lock
|
||||
flutter pub get
|
||||
```
|
||||
105
commands/update-node-deps.md
Normal file
105
commands/update-node-deps.md
Normal file
@@ -0,0 +1,105 @@
|
||||
## Node 依賴更新
|
||||
|
||||
安全地更新 Node.js 項目的依賴關系。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 確認依賴狀態並請求 Claude
|
||||
npm outdated
|
||||
「將 package.json 的依賴更新到最新版本」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 確認當前依賴
|
||||
cat package.json
|
||||
「分析這個 Node.js 項目的依賴並告诉我可更新的包」
|
||||
|
||||
# 確認可更新列表
|
||||
npm outdated
|
||||
「分析這些包更新的危險度」
|
||||
```
|
||||
|
||||
### 與 Claude 配合
|
||||
|
||||
```bash
|
||||
# 全面的依賴更新
|
||||
cat package.json
|
||||
「分析 Node.js 的依賴並執行以下操作：
|
||||
1. 調查各包的最新版本
|
||||
2. 確認是否有破坏性變更
|
||||
3. 評估危險度 (安全・注意・危險)
|
||||
4. 提出必要的代碼更改
|
||||
5. 生成更新版 package.json」
|
||||
|
||||
# 安全的分阶段更新
|
||||
npm outdated
|
||||
「避免主版本升級，只更新可以安全升級的包」
|
||||
|
||||
# 特定包的更新影響分析
|
||||
「告诉我將 express 更新到最新版本的影響和必要的更改」
|
||||
```
|
||||
|
||||
### 詳细示例
|
||||
|
||||
```bash
|
||||
# 包含 Release Notes 的詳细分析
|
||||
cat package.json && npm outdated
|
||||
「分析依賴，為每個包提供：
|
||||
1. 當前 → 最新版本
|
||||
2. 危險度評估 (安全・注意・危險)
|
||||
3. 主要變更 (來自 CHANGELOG)
|
||||
4. 必要的代碼修改
|
||||
以表格形式展示」
|
||||
|
||||
# TypeScript 項目的類型定義考虑
|
||||
cat package.json tsconfig.json
|
||||
「包括 TypeScript 的類型定義更新依賴，制定不會產生類型錯誤的更新計劃」
|
||||
```
|
||||
|
||||
### 危險度標準
|
||||
|
||||
```text
|
||||
安全 (🟢)：
|
||||
- 補丁版本升級 (1.2.3 → 1.2.4)
|
||||
- 仅修復 bug
|
||||
- 保證向後兼容
|
||||
|
||||
注意 (🟡)：
|
||||
- 次版本升級 (1.2.3 → 1.3.0)
|
||||
- 新增功能
|
||||
- 有弃用警告
|
||||
|
||||
危險 (🔴)：
|
||||
- 主版本升級 (1.2.3 → 2.0.0)
|
||||
- 破坏性變更
|
||||
- API 的刪除或更改
|
||||
```
|
||||
|
||||
### 執行更新
|
||||
|
||||
```bash
|
||||
# 創建備份
|
||||
cp package.json package.json.backup
|
||||
cp package-lock.json package-lock.json.backup
|
||||
|
||||
# 執行更新
|
||||
npm update
|
||||
|
||||
# 更新後確認
|
||||
npm test
|
||||
npm run build
|
||||
npm audit
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
更新後必须進行功能測試。如果出現問題，使用以下命令恢復：
|
||||
|
||||
```bash
|
||||
cp package.json.backup package.json
|
||||
cp package-lock.json.backup package-lock.json
|
||||
npm install
|
||||
```
|
||||
107
commands/update-rust-deps.md
Normal file
107
commands/update-rust-deps.md
Normal file
@@ -0,0 +1,107 @@
|
||||
## Rust 依賴更新
|
||||
|
||||
安全地更新 Rust 項目的依賴關系。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 確認依賴狀態並請求 Claude
|
||||
cargo tree
|
||||
「將 Cargo.toml 的依賴更新到最新版本」
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 確認當前依賴
|
||||
cat Cargo.toml
|
||||
「分析這個 Rust 項目的依賴並告诉我可更新的 crate」
|
||||
|
||||
# 確認可更新列表
|
||||
cargo update --dry-run
|
||||
「分析這些 crate 更新的危險度」
|
||||
```
|
||||
|
||||
### 與 Claude 配合
|
||||
|
||||
```bash
|
||||
# 全面的依賴更新
|
||||
cat Cargo.toml
|
||||
「分析 Rust 的依賴並執行以下操作：
|
||||
1. 調查各 crate 的最新版本
|
||||
2. 確認是否有破坏性變更
|
||||
3. 評估危險度 (安全・注意・危險)
|
||||
4. 提出必要的代碼更改
|
||||
5. 生成更新版 Cargo.toml」
|
||||
|
||||
# 安全的分阶段更新
|
||||
cargo tree
|
||||
「避免主版本升級，只更新可以安全升級的 crate」
|
||||
|
||||
# 特定 crate 的更新影響分析
|
||||
「告诉我將 tokio 更新到最新版本的影響和必要的更改」
|
||||
```
|
||||
|
||||
### 詳细示例
|
||||
|
||||
```bash
|
||||
# 包含 Release Notes 的詳细分析
|
||||
cat Cargo.toml && cargo tree
|
||||
「分析依賴，為每個 crate 提供：
|
||||
1. 當前 → 最新版本
|
||||
2. 危險度評估 (安全・注意・危險)
|
||||
3. 主要變更 (來自 CHANGELOG)
|
||||
4. trait 邊界的變更
|
||||
5. 必要的代碼修改
|
||||
以表格形式展示」
|
||||
|
||||
# 異步運行時的遷移分析
|
||||
cat Cargo.toml src/main.rs
|
||||
「展示從 async-std 遷移到 tokio，或 tokio 主版本升級所需的所有更改」
|
||||
```
|
||||
|
||||
### 危險度標準
|
||||
|
||||
```text
|
||||
安全 (🟢)：
|
||||
- 補丁版本升級 (0.1.2 → 0.1.3)
|
||||
- 仅修復 bug
|
||||
- 保證向後兼容
|
||||
|
||||
注意 (🟡)：
|
||||
- 次版本升級 (0.1.0 → 0.2.0)
|
||||
- 新增功能
|
||||
- 有弃用警告
|
||||
|
||||
危險 (🔴)：
|
||||
- 主版本升級 (0.x.y → 1.0.0、1.x.y → 2.0.0)
|
||||
- 破坏性變更
|
||||
- API 的刪除或更改
|
||||
- trait 邊界的變更
|
||||
```
|
||||
|
||||
### 執行更新
|
||||
|
||||
```bash
|
||||
# 創建備份
|
||||
cp Cargo.toml Cargo.toml.backup
|
||||
cp Cargo.lock Cargo.lock.backup
|
||||
|
||||
# 執行更新
|
||||
cargo update
|
||||
|
||||
# 更新後確認
|
||||
cargo check
|
||||
cargo test
|
||||
cargo clippy
|
||||
```
|
||||
|
||||
### 注意事項
|
||||
|
||||
更新後必须進行功能測試。如果出現問題，使用以下命令恢復：
|
||||
|
||||
```bash
|
||||
cp Cargo.toml.backup Cargo.toml
|
||||
cp Cargo.lock.backup Cargo.lock
|
||||
cargo build
|
||||
```
|
||||
Reference in New Issue
Block a user