Initial commit

2025-11-30 09:05:49 +08:00
commit 6bdf233c6b
51 changed files with 11774 additions and 0 deletions
--- a/commands/tech-debt.md
+++ b/commands/tech-debt.md
@@ -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 分以下需要改善
+- 具體計算時間成本與改善效果，支援基於數據的決策制定
+- 如需金錢換算，請另外指定團隊平均時薪或專案特定係數