tech-debt-analyzer

Technical Debt Analyzer

系统化地识别、分析并记录技术债。

何时使用

适用场景：

• 分析代码质量问题
• 创建技术债登记册
• 评估代码可维护性
• 识别依赖问题
• 记录安全漏洞
• 规划重构工作

不适用场景：

• 编写新代码 → 使用 generic-feature-developer
• 代码审查 → 使用 generic-code-reviewer
• 编写测试 → 使用 test-specialist

快速分析命令

# Find large files (>500 lines)
find src -name "*.ts" -exec wc -l {} + | awk '$1 > 500' | sort -rn

# Find TODO/FIXME markers
grep -rn "TODO\|FIXME\|HACK\|XXX" src/

# Check for console.log in production code
grep -rn "console.log" src/ --include="*.ts" --include="*.tsx"

# Find TypeScript 'any' usage
grep -rn ": any" src/ --include="*.ts" --include="*.tsx"

# Check outdated dependencies
npm outdated

# Security vulnerabilities
npm audit

# Unused exports (requires ts-unused-exports)
npx ts-unused-exports tsconfig.json

债务类别

类别	示例
Code Quality	大文件、复杂函数、TODO/FIXME 标记
Architectural	紧耦合、缺少抽象、循环依赖
Test	缺少覆盖率、脆弱的测试、执行缓慢
Documentation	缺少 README、文档过期、没有 ADR
Dependency	过期包、安全漏洞
Performance	N+1 查询、内存泄漏、大打包体积
Security	缺少校验、暴露密钥、XSS/SQL 注入

分析工作流

1. 自动化检测

需要检查的代码异味：

• 大文件（超过 500 行）
• 复杂函数（圈复杂度大于 10）
• 债务标记（TODO、FIXME、HACK、XXX）
• 生产代码中的 console 语句
• TypeScript 中的 any 类型
• 过长参数列表（超过 5 个参数）
• 过深嵌套（超过 4 层）

依赖问题：

• 已弃用的包
• 功能重复
• 宽松的版本约束
• 已知漏洞

2. 严重性评估

严重性	判断标准	处理动作
Critical	安全漏洞、数据丢失风险	立即修复
High	性能问题、阻塞问题	当前迭代
Medium	代码质量、缺少文档	本季度
Low	轻微异味、优化	方便时

3. 优先级矩阵

影响 / 成本	低	中	高
高影响	Do First	Do Second	Plan & Do
中影响	Do Second	Plan & Do	Consider
低影响	Quick Win	Consider	Avoid

债务登记格式

## DEBT-001: Description

**Category:** Code Quality | **Severity:** High
**Location:** src/services/UserService.ts

**Description:** Brief description of the issue

**Impact:**

- Business: How it affects delivery
- Technical: Why it's problematic
- Risk: What could go wrong

**Proposed Solution:** What to do about it
**Effort:** Days/hours estimate
**Target:** Sprint/quarter

预防策略

自动化守卫

{
  "rules": {
    "complexity": ["error", 10],
    "max-lines-per-function": ["error", 50],
    "max-params": ["error", 5],
    "max-depth": ["error", 4]
  }
}

维护日程

频率	任务
每周	检查 TODO/FIXME，更新登记册
每月	依赖更新、技术债评审
每季度	全面分析、架构评审

自检清单

完成债务分析后：

• [ ] 所有自动化检查均已运行
• [ ] 已完成关键路径的人工审查
• [ ] 严重性评估有充分依据
• [ ] 提出的解决方案可执行
• [ ] 优先级矩阵应用一致
• [ ] 登记册条目完整

另见

• 代码审查标准 - 质量检查
• 项目 CLAUDE.md - 工作流规则