技术债务分析器

概览

系统地识别、分析、记录和跟踪JavaScript/TypeScript代码库中的技术债务。这项技能提供了自动化分析工具、全面的债务分类框架和文档模板，以维护技术债务登记册。

核心工作流程

1. 自动化分析

运行自动化脚本以检测代码库中的技术债务指标。

代码异味检测

使用自动化检测器识别代码质量问题：

python3 scripts/detect_code_smells.py src --output markdown

该脚本分析：

大文件： 超过500行的文件
复杂函数： 高圈复杂度（>10）或长函数（>50行）
债务标记： TODO, FIXME, HACK, XXX, BUG注释
控制台语句： 代码中留下的调试语句
弱类型： TypeScript中的any类型使用
长参数： 函数参数超过5个
深层嵌套： 代码嵌套超过4层
神奇数字： 硬编码的数值

输出示例：

# 技术债务分析报告

**文件分析：** 127
**总行数：** 15,432
**总问题数：** 89

### 按严重性划分的问题
- 高：23
- 中：41
- 低：25

## 大文件（12个问题）
### 高优先级
- src/components/Dashboard.tsx (847行)：文件过大
- src/services/DataProcessor.ts (623行)：文件过大
...

依赖项分析

检查依赖项中的债务指标：

python3 scripts/analyze_dependencies.py package.json

该脚本识别：

过时的包： 已知过时的库（request, tslint等）
重复功能： 多个包提供相同目的
版本问题： 过于宽松或严格的版本约束
安全问题： 已知易受攻击的包（需要审计数据）

输出示例：

# 依赖项分析报告

**包：** expense-tracker
**依赖项：** 24
**开发依赖项：** 18
**总问题数：** 7

## 过时/陈旧的包（3个）
### request [高]
使用过时的包 - 改用axios, node-fetch或got
- 当前版本：^2.88.0

## 重复功能（2个）
### HTTP客户端 [中]
多个HTTP客户端包：axios, node-fetch

2. 手动代码审查

用手动审查补充自动化分析，以识别需要人类判断的问题。

审查重点领域

架构债务：

组件之间的紧密耦合
缺少抽象
差劲的关注点分离
循环依赖

测试债务：

关键路径缺少测试覆盖
与实现耦合的脆弱测试
没有集成或E2E测试
测试执行缓慢

文档债务：

缺少README或设置说明
缺少架构文档
API文档过时
缺少重大决策的ADR

性能债务：

N+1查询问题
低效算法
内存泄漏
大型捆绑包大小

安全债务：

缺少输入验证
没有认证/授权
SQL注入漏洞
XSS漏洞
暴露的秘密

3. 分类和评估

使用标准化的债务类别组织发现。

债务类别

参考references/debt_categories.md了解详细的债务类型：

代码质量债务： 代码异味，复杂性，重复
架构债务： 结构，耦合，抽象
测试债务： 覆盖差距，脆弱测试
文档债务： 缺失或过时的文档
依赖债务： 过时或有问题的依赖
性能债务： 低效和瓶颈
安全债务： 漏洞和弱点
基础设施债务： DevOps和部署问题
设计债务： UI/UX不一致

严重性评估

根据影响和紧急性分配严重性：

关键：

安全漏洞
生产中断问题
数据丢失风险
行动： 需要立即修复

高：

显著的性能问题
阻碍功能的架构问题
高风险未测试代码
行动： 在当前/下一个冲刺中修复

中：

频繁更改文件中的代码质量问题
缺少文档
过时的依赖（非安全）
行动： 在本季度内解决

低：

轻微的代码异味
优化机会
锦上添花的改进
行动： 方便时解决

优先级矩阵

影响/努力	低努力	中等努力	高努力
高影响	首先做	第二做	计划并做
中等影响	第二做	计划并做	考虑
低影响	快速赢	考虑	避免

4. 文档化发现

创建技术债务的综合文档。

技术债务登记册

使用提供的模板维护债务登记册：

模板位置： assets/DEBT_REGISTER_TEMPLATE.md

结构：

## DEBT-001: 复杂的UserService，有847行

**类别：** 代码质量
**严重性：** 高
**位置：** src/services/UserService.ts

**描述：**
UserService增长到847行，有多个责任
包括认证，个人资料管理，和通知处理。

**影响：**
- 业务：功能开发速度降低30%
- 技术：难以测试，高错误率
- 风险：更改经常破坏不相关的功能

**建议的解决方案：**
分割成单独的服务：
- AuthenticationService
- UserProfileService
- NotificationService

**努力估计：** 3天
**优先级理由：** 高周转区域阻碍新功能
**目标解决：** Sprint 24

登记册部分：

活跃债务项： 需要关注的当前技术债务
已解决项： 已修复债务的历史记录
不修复项： 作为可接受的权衡而接受的债务
趋势： 按类别，严重性和年龄分析
审查计划： 定期维护计划

架构决策记录（ADRs）

使用ADRs记录重大技术决策，以防止未来的债务。

模板位置： assets/ADR_TEMPLATE.md

何时创建ADRs：

选择框架或库
架构变更
重大重构决策
技术迁移
性能优化策略

示例：

# ADR-003: 从Moment.js迁移到date-fns

**状态：** 接受
**日期：** 2024-01-15

## 上下文
Moment.js已弃用，增加了67KB的捆绑包大小。
团队需要一个支持tree-shaking的现代日期库。

## 决策
迁移到date-fns进行日期操作。

## 后果
- 积极：减少捆绑包60KB，现代API，活跃维护
- 消极：迁移工作量，团队的学习曲线
- 技术债务：无 - 这解决了现有的依赖债务

5. 优先排序和计划

创建可操作的计划来解决技术债务。

优先排序方法

关键项： 立即添加到当前冲刺
高项： 包括在冲刺计划中
中项： 添加到季度路线图
低项： 在相关工作中的机会性修复

时间分配

推荐分配：

冲刺能力的20%用于技术债务
交替冲刺：功能冲刺/债务冲刺
专门的季度“技术健康”冲刺

跟踪进度

随着时间的推移监控债务减少：

跟踪指标：

总债务项（趋势下降）
按严重性划分的债务（关键应为0）
债务年龄（旧债务令人担忧）
解决率（每个冲刺修复的项目数）
新债务率（每个冲刺添加的项目数）

6. 预防策略

实施做法以最小化新的技术债务。

代码审查清单

在批准PR之前，请验证：

[ ] 没有引入代码异味（复杂性，大小，嵌套）
[ ] 添加/更新了足够的测试覆盖
[ ] 文档更新（README，注释，ADRs）
[ ] 没有安全漏洞
[ ] 考虑了性能影响
[ ] 没有新的依赖项，除非有理由
[ ] 遵循团队约定和模式

自动化预防

Linting和格式化：

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

必需检查：

启用TypeScript严格模式
最低测试覆盖率阈值（80%）
没有高严重性安全漏洞
强制执行捆绑包大小限制

定期维护

每周：

审查和分类TODO/FIXME注释
更新债务登记册以包含新发现

每月：

依赖项更新（安全补丁）
债务登记册审查
计划修复高优先级项目

季度：

完整的代码库债务分析
架构审查
主要依赖项更新
趋势分析和策略调整

决策树

根据情况遵循此工作流程：

开始新分析？ → 运行自动化脚本（detect_code_smells.py, analyze_dependencies.py） → 审查输出中的高严重性问题 → 对脚本无法检测到的区域进行手动审查 → 前往文档化步骤

记录发现？ → 将DEBT_REGISTER_TEMPLATE.md复制到项目根目录 → 添加每个债务项的详细信息 → 按类型分类并分配严重性 → 估计工作量并确定优先级 → 前往计划步骤

计划减少债务？ → 按优先级矩阵（影响/努力）排序 → 分配冲刺能力（推荐20%） → 为前5个项目创建票证 → 安排定期审查

制定架构决策？ → 复制ADR_TEMPLATE.md → 记录上下文，选项和决策 → 确定由此产生的任何债务 → 如适用，添加到债务登记册

预防新债务？ → 实施代码审查清单 → 配置自动化linting/testing → 设置定期维护计划 → 跟踪指标随时间变化

工具和脚本

detect_code_smells.py

目的： 自动化代码质量分析

用法：

python3 scripts/detect_code_smells.py [src-dir] [--output json|markdown]

检测：

大文件（>500行）
复杂函数（复杂度>10）
技术债务标记（TODO, FIXME, HACK）
控制台语句
弱TypeScript类型
长参数列表（>5个参数）
深层嵌套（>4层）
神奇数字

输出： 用于程序处理的Markdown报告或JSON

analyze_dependencies.py

目的： 依赖项健康分析

用法：

python3 scripts/analyze_dependencies.py [package.json-path]

检测：

过时的包（request, tslint, node-sass等）
重复功能（多个日期库，HTTP客户端等）
不安全的版本约束（*，latest）
过于严格的版本（没有^或~的确切版本）

输出： 带有建议的Markdown报告

参考文档

debt_categories.md

全面的技术债务类型指南，包括：

9个主要债务类别
每个类别的指标和示例
影响评估标准
严重性级别定义
测量指标
预防策略

何时加载此参考：

需要特定债务类型的详细示例
评估严重性和影响
了解根本原因
规划预防策略

文档模板

DEBT_REGISTER_TEMPLATE.md

完整的技术债务登记册模板，包括：

债务项结构
状态跟踪
影响评估格式
趋势分析部分
审查计划

使用此模板：

开始新的债务登记册
标准化债务文档
跨团队/项目跟踪债务

ADR_TEMPLATE.md

架构决策记录模板，包括：

上下文和问题声明
考虑的选项
决策理由
后果（积极和消极）
实施计划

使用此模板：

记录重大技术决策
防止未来的“我们为什么要这样做？”问题
跟踪决策产生的技术债务

最佳实践

分析最佳实践

定期运行分析（每周或每两周）
结合自动化+手动审查以获得全面覆盖
首先关注高周转区域以获得最大影响
让团队参与债务识别
客观 - 所有代码库都有债务

文档化最佳实践

具体 - 包括文件名，行号，示例
解释影响 - 为什么这很重要？
提出解决方案 - 不要只是抱怨，建议修复
估计工作量 - 有助于优先级排序
跟踪趋势 - 债务是增加还是减少？

补救最佳实践

立即修复关键项 - 特别是安全问题
分配一致的时间 - 冲刺能力的20%
庆祝胜利 - 跟踪并认可债务减少
不要让完美成为好的敌人 - 逐步改进
预防新债务 - 比修复旧债务更容易

沟通最佳实践

使债务可见 - 与利益相关者分享指标
教育影响 - 将债务与业务结果联系起来
获得认同 - 解释债务减少的投资回报率
定期更新 - 包括在冲刺审查中
避免责备 - 专注于改进，而不是过错

示例工作流程

从分析到解决的完整工作流程：

第1周：分析

# 运行自动化分析
python3 scripts/detect_code_smells.py src --output markdown > debt_analysis.md
python3 scripts/analyze_dependencies.py package.json >> debt_analysis.md

# 手动审查关键区域
# - 认证逻辑
# - 支付处理
# - 数据模型

第1-2周：文档化

# 从模板创建债务登记册
cp assets/DEBT_REGISTER_TEMPLATE.md TECHNICAL_DEBT.md

# 添加发现到登记册，包括：
# - 类别和严重性
# - 影响评估
# - 工作量估计
# - 优先级分配

第2周：优先排序

# 团队审查会议
# - 审查所有高/关键项
# - 讨论快速获胜（高影响，低努力）
# - 分配冲刺能力
# - 为前5个项目创建票证

第3-6周：补救

# 冲刺工作
# - 每个冲刺修复2-3个债务项
# - 更新解决项目的债务登记册
# - 为重大重构决策创建ADRs
# - 监控指标

每月：审查

# 趋势分析
# - 总债务（应减少）
# - 新债务率（应低）
# - 最旧项目的债务年龄（应减少）
# - 最受影响的类别

# 根据趋势调整策略

成功指标

跟踪这些指标以衡量债务减少的有效性：

数量指标：

总债务项（趋势下降）
按严重性划分的债务（零关键）
每1000 LOC的债务项

质量指标：

测试覆盖率（趋势上升）
圈复杂度（趋势下降）
平均文件/函数大小（稳定或下降）

速度指标：

每个冲刺解决的债务项
每个冲刺的新债务项（应低）
解决时间（应减少）

业务指标：

错误率（应减少）
功能交付速度（应增加）
开发人员满意度（应增加）