/tech-debt

Tech Debt

定量分析專案的技術債務，視覺化健康評分與開發效率的影響。透過趨勢分析追蹤改善狀況，計算時間成本並建立有優先順序的改善計劃。

使用方法

# 檢查專案配置以分析技術債務
ls -la
"分析此專案的技術債務並建立改善計劃"

專案健康儀表板

專案健康評分: 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 個月)

基本範例

# 健康評分的詳細分析
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 協作

# 全面性技術債務分析
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
"識別架構層級的技術債務並提出重構計劃"

# 有優先順序的改善計劃
"根據這些標準評估技術債務並以表格形式呈現:
- 影響度 (高/中/低)
- 修正成本 (時間)
- 技術風險 (系統故障、資料遺失的可能性)
- 改善帶來的時間節省效果
- 建議實施時機"

詳細範例

# 自動偵測專案類型並分析
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"
"分析測試覆蓋率的技術債務並提出測試策略"

債務優先順序矩陣

優先度 = (影響度 × 頻率) ÷ 修正成本

優先度	對開發的影響	修正成本	時間節省效果	投資回報	回應期限
[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

技術債務影響度計算

影響度 = Σ(各元素權重 × 測量值)

📊 可測量的影響指標:
├─ 對開發速度的影響
│  ├─ 程式碼理解時間: +X% (與複雜度成正比)
│  ├─ 變更時的影響範圍: Y 個檔案 (以耦合度測量)
│  └─ 測試執行時間: Z 分鐘 (CI/CD 管道)
│
├─ 對品質的影響
│  ├─ Bug 發生率: 複雜度每 10 增加 +25%
│  ├─ 審查時間: 程式碼行數 × 複雜度係數
│  └─ 測試不足風險: 覆蓋率 < 60% 時為高風險
│
└─ 對團隊效率的影響
   ├─ 入職時間: 文件不足增加 +100%
   ├─ 知識集中: 單一貢獻者比率 >80% 需注意
   └─ 程式碼重複造成的修正點: 重複率 × 變更頻率

基於時間的 ROI 計算

ROI = (節省時間 - 投資時間) ÷ 投資時間 × 100

範例: 解決循環依賴
├─ 投資時間: 16 小時 (重構)
├─ 節省效果 (月):
│  ├─ 編譯時間: -10 分/天 × 20 天 = 200 分
│  ├─ 除錯時間: -2 小時/週 × 4 週 = 8 小時
│  └─ 新功能開發: -30% 時間縮減 = 12 小時
├─ 月節省時間: 23.3 小時
└─ 3 個月 ROI: (70 - 16) ÷ 16 × 100 = 337%

注意事項

• 自動偵測專案的語言與框架以進行特定分析
• 以 0-100 分評估健康評分，70 分以上視為健康，50 分以下需要改善
• 具體計算時間成本與改善效果，支援基於數據的決策制定
• 如需金錢換算，請另外指定團隊平均時薪或專案特定係數