tech-debt-analyzer

技术债务分析器

概述

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

核心工作流

1. 自动化分析

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

代码异味检测

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

python3 scripts/detect_code_smells.py src --output markdown

该脚本会分析：

• 大型文件： 超过 500 行的文件
• 复杂函数： 圈复杂度较高（>10）或较长的函数（>50 行）
• 债务标记： TODO、FIXME、HACK、XXX、BUG 注释
• Console 语句： 留在代码中的调试语句
• 弱类型： 在 TypeScript 中使用 any 类型
• 过多参数： 参数超过 5 个的函数
• 嵌套过深： 嵌套层级超过 4 层的代码
• 魔法数字： 硬编码的数值

输出示例：

# Technical Debt Analysis Report

**Files Analyzed:** 127
**Total Lines:** 15,432
**Total Issues:** 89

### Issues by Severity
- HIGH: 23
- MEDIUM: 41
- LOW: 25

## Large Files (12 issues)
### High Priority
- src/components/Dashboard.tsx (847 lines): File too large
- src/services/DataProcessor.ts (623 lines): File too large
...

依赖项分析

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

python3 scripts/analyze_dependencies.py package.json

该脚本会识别：

• 已弃用的包： 已知弃用的库（request、tslint 等）
• 功能重复： 多个包实现相同用途
• 版本问题： 版本约束过于宽松或严格
• 安全问题： 已知存在漏洞的包（需要审计数据）

输出示例：

# Dependency Analysis Report

**Package:** expense-tracker
**Dependencies:** 24
**Dev Dependencies:** 18
**Total Issues:** 7

## Deprecated/Outdated Packages (3)
### request [HIGH]
Using deprecated package - use axios, node-fetch, or got instead
- Current version: ^2.88.0

## Duplicate Functionality (2)
### HTTP client [MEDIUM]
Multiple packages for HTTP client: axios, node-fetch

2. 手动代码审查

通过手动审查补充自动化分析，以发现需要人工判断的问题。

审查重点领域

架构债务：

• 组件之间耦合紧密
• 缺少抽象
• 关注点分离不佳
• 循环依赖

测试债务：

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

文档债务：

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

性能债务：

• N+1 查询问题
• 算法效率低下
• 内存泄漏
• 包体积过大

安全债务：

• 缺少输入验证
• 没有身份验证/授权
• SQL 注入漏洞
• XSS 漏洞
• 密钥泄露

3. 分类与评估

使用标准化的债务类别整理发现的问题。

债务类别

请参阅 references/debt_categories.md，了解以下类别的详细信息：

1. 代码质量债务： 代码异味、复杂度、重复
2. 架构债务： 结构、耦合、抽象
3. 测试债务： 覆盖缺口、脆弱的测试
4. 文档债务： 缺失或过时的文档
5. 依赖项债务： 过时或有问题的依赖项
6. 性能债务： 效率低下和瓶颈
7. 安全债务： 漏洞和弱点
8. 基础设施债务： DevOps 和部署问题
9. 设计债务： UI/UX 不一致

严重性评估

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

严重：

• 安全漏洞
• 导致生产环境故障的问题
• 数据丢失风险
• 操作： 需要立即修复

高：

• 严重的性能问题
• 阻碍功能开发的架构问题
• 未经测试且风险较高的代码
• 操作： 在当前或下一个冲刺周期内修复

中：

• 经常修改的文件中的代码质量问题
• 缺少文档
• 过时的依赖项（非安全问题）
• 操作： 在本季度内处理

低：

• 轻微的代码异味
• 优化机会
• 可有可无的改进
• 操作： 方便时处理

优先级矩阵

影响 / 工作量	低工作量	中等工作量	高工作量
高影响	优先处理	次优先处理	规划并实施
中等影响	次优先处理	规划并实施	考虑处理
低影响	快速见效	考虑处理	避免处理

4. 记录发现

全面记录技术债务。

技术债务登记表

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

模板位置： assets/DEBT_REGISTER_TEMPLATE.md

结构：

## DEBT-001: Complex UserService with 847 lines

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

**Description:**
UserService has grown to 847 lines with multiple responsibilities
including authentication, profile management, and notification handling.

**Impact:**
- Business: Slows down feature development by 30%
- Technical: Difficult to test, high bug rate
- Risk: Changes frequently break unrelated functionality

**Proposed Solution:**
Split into separate services:
- AuthenticationService
- UserProfileService
- NotificationService

**Effort Estimate:** 3 days
**Priority Justification:** High churn area blocking new features
**Target Resolution:** Sprint 24

登记表部分：

1. 待处理债务项： 当前需要关注的技术债务
2. 已解决项： 已修复债务的历史记录
3. 不予修复项： 已接受为合理权衡的债务
4. 趋势： 按类别、严重程度和存在时间进行分析
5. 审查计划： 定期维护计划

架构决策记录（ADR）

使用 ADR 记录重要技术决策，避免产生未来的债务。

模板位置： assets/ADR_TEMPLATE.md

创建 ADR 的时机：

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

示例：

# ADR-003: Migrate from Moment.js to date-fns

**Status:** Accepted
**Date:** 2024-01-15

## Context
Moment.js is deprecated and increases bundle size by 67KB.
Team needs a modern date library with tree-shaking support.

## Decision
Migrate to date-fns for date manipulation.

## Consequences
- Positive: Reduce bundle by 60KB, modern API, active maintenance
- Negative: Migration effort, learning curve for team
- Technical Debt: None - this resolves existing dependency debt

5. 确定优先级并制定计划

制定可执行的计划来处理技术债务。

优先级方法

1. 关键项： 立即加入当前迭代
2. 高优先级项： 纳入迭代规划
3. 中优先级项： 加入季度路线图
4. 低优先级项： 在处理相关工作时顺带修复

时间分配

建议的分配方式：

• 将 20% 的迭代容量用于技术债务
• 迭代交替进行：功能迭代／债务迭代
• 每季度安排一个专门的“技术健康”迭代

跟踪进展

持续监控债务的减少情况：

跟踪指标：

• 债务项总数（趋势应下降）
• 按严重程度划分的债务（关键项应为 0）
• 债务存在时间（旧债务值得关注）
• 解决率（每个迭代修复的项目数）
• 新增债务率（每个迭代新增的项目数）

6. 预防策略

实施实践，尽量减少新增技术债务。

代码审查清单

批准 PR 前，请确认：

• 未引入代码异味（复杂度、规模、嵌套）
• 已添加／更新测试，覆盖率充足
• 已更新文档（README、注释、ADR）
• 不存在安全漏洞
• 已考虑对性能的影响
• 未添加缺乏正当理由的新依赖项
• 符合团队约定和模式

自动化预防

Lint 和格式化：

{
  "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%） → 为优先级最高的项目创建工单 → 安排定期审查

做出架构决策？ → 复制 ADR_TEMPLATE.md → 记录背景、选项和决策 → 确定由此产生的任何债务 → 如适用，将其添加到债务登记表

预防新增债务？ → 实施代码审查清单 → 配置自动化 Lint 和测试 → 建立定期维护计划 → 持续监控指标

工具和脚本

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

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

• 背景和问题陈述
• 考虑过的选项
• 决策依据
• 后果（正面和负面）
• 实施计划

使用此模板来：

• 记录重要的技术决策
• 避免日后出现“我们当初为什么这么做？”的问题
• 跟踪决策产生的技术债务

最佳实践

分析最佳实践

1. 定期运行分析（每周或每两周一次）
2. 结合自动化分析和人工审查，实现全面覆盖
3. 优先关注变更频繁的区域，以取得最大成效
4. 让团队参与债务识别
5. 客观看待——所有代码库都有债务

文档编写最佳实践

1. 具体明确——包含文件名、行号和示例
2. 说明影响——这为什么重要？
3. 提出解决方案——不要只抱怨，要建议修复方法
4. 估算工作量——有助于确定优先级
5. 跟踪趋势——债务是在增加还是减少？

修复最佳实践

1. 立即修复关键问题——尤其是安全问题
2. 持续分配时间——占冲刺容量的 20%
3. 庆祝成果——跟踪并认可债务减少
4. 不要因追求完美而放弃良好改进——循序渐进地改进
5. 防止新增债务——这比修复旧债务更容易

沟通最佳实践

1. 让债务一目了然——与利益相关者分享指标
2. 说明影响——将债务与业务成果联系起来
3. 争取支持——解释减少债务的投资回报
4. 定期更新——在冲刺评审中汇报
5. 避免指责——聚焦改进，而非追究过错

示例工作流

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

第 1 周：分析

# Run automated analysis
python3 scripts/detect_code_smells.py src --output markdown > debt_analysis.md
python3 scripts/analyze_dependencies.py package.json >> debt_analysis.md

# Manual review of critical areas
# - Authentication logic
# - Payment processing
# - Data models

第 1–2 周：文档记录

# Create debt register from template
cp assets/DEBT_REGISTER_TEMPLATE.md TECHNICAL_DEBT.md

# Add findings to register with:
# - Category and severity
# - Impact assessment
# - Effort estimation
# - Priority assignment

第 2 周：确定优先级

# Team review session
# - Review all high/critical items
# - Discuss quick wins (high impact, low effort)
# - Allocate sprint capacity
# - Create tickets for top 5 items

第 3–6 周：修复

# Sprint work
# - Fix 2-3 debt items per sprint
# - Update debt register as items resolved
# - Create ADRs for major refactoring decisions
# - Monitor metrics

每月：审查

# Trend analysis
# - Total debt (should decrease)
# - New debt rate (should be low)
# - Age of oldest items (should decrease)
# - Categories most affected

# Adjust strategy based on trends

---

成功指标

跟踪以下指标，以衡量债务减少的成效：

数量指标：

• 债务项总数（呈下降趋势）
• 按严重程度划分的债务（严重级别为零）
• 每 1000 行代码的债务项数

质量指标：

• 测试覆盖率（呈上升趋势）
• 圈复杂度（呈下降趋势）
• 文件／函数平均大小（保持稳定或逐渐减小）

速度指标：

• 每个冲刺解决的债务项数
• 每个冲刺新增的债务项数（应保持较低）
• 解决所需时间（应逐渐缩短）

业务指标：

• Bug 率（应降低）
• 功能交付速度（应提高）
• 开发者满意度（应提高）