186 lines
7.3 KiB
Markdown
186 lines
7.3 KiB
Markdown
## 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 分以下需要改善
|
||
- 具體計算時間成本與改善效果，支援基於數據的決策制定
|
||
- 如需金錢換算，請另外指定團隊平均時薪或專案特定係數
|