Tech Debt

---
description: "技术债务定量分析与改进计划。「分析技术债务」「检查项目健康度」「债务评分？」等触发。"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
---

# 技术债务定量分析与改进计划

分析项目的技术债务，创建按优先级排序的改进计划。

## 使用方法

```bash
# 确认项目结构并分析技术债务
ls -la
「分析这个项目的技术债务并创建改进计划」
```

## 基本示例

```bash
# 分析 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"
「分析项目的依赖关系，识别过时的依赖和风险」

# 检测大文件和复杂函数
find . -type f -not -path "*/\.*" -not -path "*/node_modules/*" -exec wc -l {} + | sort -rn | head -10
「识别过大的文件和复杂的结构，提出改进方案」
```

## 与 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
项目健康度评分：72/100
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 分类评分
├─ 依赖关系新鲜度：████████░░ 82%(最新：45/55)
├─ 文档完整度：███░░░░░░░ 35%(缺少 README、API 文档)
├─ 测试覆盖率：██████░░░░ 65%(目标：80%)
├─ 安全性：███████░░░ 78%(漏洞：2 个中等风险)
├─ 架构：██████░░░░ 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 个月)
```

## 优先级矩阵

| 优先级            | 开发影响 | 修复成本 | 时间节省效果 | 投资效率            | 响应期限 |
| ----------------- | -------- | -------- | ------------ | ------------------- | -------- |
| **[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 分以下需要改进
- 计算具体的时间成本和改进效果，支持基于数据的决策制定
- 如需货币换算，请单独指定团队平均时薪或项目特定系数