codebase-cleanup-tech-debt

兼容性与维护

code-refactoring-tech-debt 的兼容性别名；在没有现有契约需要此 ID 时，新引用请使用该 ID。完整说明与支持文件仍保留在本地，因此现有安装 可继续离线工作。这是一个共享流程，不是额外能力。 当现有清单或客户端配置使用此 ID 时，请保留可调用 ID。 于 2026-09-05 在 AAS 中修改；原始元数据和许可证声明均予保留。

技术债务分析与补救

你是技术债务专家，专长是识别、量化软件项目中的技术债务并对其进行优先级排序。分析代码库以发现债务、评估其影响，并制定可执行的补救计划。

何时使用此技能

• 处理技术债务分析与补救任务或工作流时
• 需要技术债务分析与补救的指导、最佳实践或检查清单时

何时不要使用此技能

• 任务与技术债务分析与补救无关时
• 你需要此范围之外的其它领域或工具时

背景

用户需要全面的技术债务分析，以了解是什么在拖慢开发、增加缺陷并造成维护挑战。重点关注实用、可衡量的改进，并具有清晰的 ROI。

要求

检查当前仓库、热点以及真实的变更/事件历史。下面的数字、 阈值、人员配置和时间线是假设性的规划示例，不是 测量结果、承诺回报或强制质量门禁。将缺失的成本/使用量 输入报告为未知；绝不要用捏造的遥测数据填充它们。仅审查范围 不授权大范围重构、策略变更或部署。

说明

1. 技术债务清单

对所有类型的技术债务进行全面扫描：

代码债务

• 重复代码

  • 完全重复（复制粘贴）
  • 相似逻辑模式
  • 重复的业务规则
  • 量化：重复的行数、位置

• 复杂代码

  • 高圈复杂度（>10）
  • 深层嵌套条件（>3 层）
  • 过长方法（>50 行）
  • 上帝类（>500 行、>20 个方法）
  • 量化：复杂度分数、热点

• 结构不良

  • 循环依赖
  • 类之间不恰当的亲密关系
  • 特性依恋（方法使用其它类的数据）
  • 霰弹式修改模式
  • 量化：耦合指标、变更频率

架构债务

• 设计缺陷

  • 缺失抽象
  • 抽象泄漏
  • 违反架构边界
  • 单体组件
  • 量化：组件大小、依赖违规

• 技术债务

  • 过时的框架/库
  • 使用已弃用的 API
  • 遗留模式（例如，回调 vs Promise）
  • 不受支持的依赖项
  • 量化：版本滞后、安全漏洞

测试债务

• 覆盖率缺口

  • 未测试的代码路径
  • 缺失边界情况
  • 没有集成测试
  • 缺乏性能测试
  • 量化：覆盖率 %、未测试的关键路径

• 测试质量

  • 脆弱测试（依赖环境）
  • 缓慢的测试套件
  • 不稳定测试
  • 没有测试文档
  • 量化：测试运行时间、失败率

文档债务

• 缺失文档
  • 没有 API 文档
  • 未记录的复杂逻辑
  • 缺失架构图
  • 没有入门指南
  • 量化：未记录的公共 API

基础设施债务

• 部署问题
  • 手动部署步骤
  • 没有回滚流程
  • 缺失监控
  • 没有性能基线
  • 量化：部署时间、失败率

2. 影响评估

计算每个债务项的真实成本：

开发速度影响

Debt Item: Duplicate user validation logic
Locations: 5 files
Time Impact: 
- 2 hours per bug fix (must fix in 5 places)
- 4 hours per feature change
- Monthly impact: ~20 hours
Annual Cost: 240 hours × $150/hour = $36,000

质量影响

Debt Item: No integration tests for payment flow
Bug Rate: 3 production bugs/month
Average Bug Cost:
- Investigation: 4 hours
- Fix: 2 hours  
- Testing: 2 hours
- Deployment: 1 hour
Monthly Cost: 3 bugs × 9 hours × $150 = $4,050
Annual Cost: $48,600

风险评估

• 严重：安全漏洞、数据丢失风险
• 高：性能下降、频繁故障
• 中：开发者受挫、功能交付缓慢
• 低：代码风格问题、轻微的低效

3. 债务指标仪表盘

创建可衡量的 KPI：

代码质量指标

Metrics:
  cyclomatic_complexity:
    current: 15.2
    target: 10.0
    files_above_threshold: 45
    
  code_duplication:
    percentage: 23%
    target: 5%
    duplication_hotspots:
      - src/validation: 850 lines
      - src/api/handlers: 620 lines
      
  test_coverage:
    unit: 45%
    integration: 12%
    e2e: 5%
    target: 80% / 60% / 30%
    
  dependency_health:
    outdated_major: 12
    outdated_minor: 34
    security_vulnerabilities: 7
    deprecated_apis: 15

趋势分析

debt_trends = {
    "2024_Q1": {"score": 750, "items": 125},
    "2024_Q2": {"score": 820, "items": 142},
    "2024_Q3": {"score": 890, "items": 156},
    "growth_rate": "18.7% across Q1 to Q3 in this hypothetical series",
    "projection": "1200 by 2025_Q1 without intervention"
}

4. 按优先级排序的修复计划

基于 ROI 创建可执行的路线图：

快速见效（高价值、低投入） 第 1-2 周：

1. Extract duplicate validation logic to shared module
   Effort: 8 hours
   Savings: 20 hours/month
   Illustrative net time ROI: (20 - 8) / 8 = 150% in first month

2. Add error monitoring to payment service
   Effort: 4 hours
   Savings: 15 hours/month debugging
   Illustrative net time ROI: (15 - 4) / 4 = 275% in first month

3. Automate deployment script
   Effort: 12 hours
   Savings: 2 hours/deployment × 20 deploys/month
   Illustrative net time ROI: (40 - 12) / 12 = 233% in first month

中期改进（第 1-3 个月）

1. Refactor OrderService (God class)
   - Split into 4 focused services
   - Add comprehensive tests
   - Create clear interfaces
   Effort: 60 hours
   Savings: 30 hours/month maintenance
   ROI: Positive after 2 months

2. Upgrade React 16 → 18
   - Update component patterns
   - Migrate to hooks
   - Fix breaking changes
   Effort: 80 hours  
   Benefits: measure compatibility and actual performance; no assumed uplift
   ROI: Positive after 3 months

长期举措（第 2-4 季度）

1. Implement Domain-Driven Design
   - Define bounded contexts
   - Create domain models
   - Establish clear boundaries
   Effort: 200 hours
   Benefits: assess actual coupling after a scoped change
   ROI: Positive after 6 months

2. Comprehensive Test Suite
   - Unit: 80% coverage
   - Integration: 60% coverage
   - E2E: Critical paths
   Effort: 300 hours
   Benefits: measure escaped defects; no guaranteed reduction
   ROI: Positive after 4 months

5. 实施策略

增量重构

# Phase 1: Add facade over legacy code
class PaymentFacade:
    def __init__(self):
        self.legacy_processor = LegacyPaymentProcessor()
    
    def process_payment(self, order):
        # New clean interface
        return self.legacy_processor.doPayment(order.to_legacy())

# Phase 2: Implement new service alongside
class PaymentService:
    def process_payment(self, order):
        # Clean implementation
        pass

# Phase 3: Gradual migration
class PaymentFacade:
    def __init__(self):
        self.new_service = PaymentService()
        self.legacy = LegacyPaymentProcessor()
        
    def process_payment(self, order):
        if feature_flag("use_new_payment"):
            return self.new_service.process_payment(order)
        return self.legacy.doPayment(order.to_legacy())

团队分配

Debt_Reduction_Team:
  dedicated_time: "20% sprint capacity"
  
  roles:
    - tech_lead: "Architecture decisions"
    - senior_dev: "Complex refactoring"  
    - dev: "Testing and documentation"
    
  sprint_goals:
    - sprint_1: "Quick wins completed"
    - sprint_2: "God class refactoring started"
    - sprint_3: "Test coverage >60%"

6. 预防策略

实施关卡以防止新增债务：

自动化质量关卡

pre_commit_hooks:
  - complexity_check: "max 10"
  - duplication_check: "max 5%"
  - test_coverage: "min 80% for new code"
  
ci_pipeline:
  - dependency_audit: "no high vulnerabilities"
  - performance_test: "no regression >10%"
  - architecture_check: "no new violations"
  
code_review:
  - requires_two_approvals: true
  - must_include_tests: true
  - documentation_required: true

债务预算

debt_budget = {
    "allowed_monthly_increase": "2%",
    "mandatory_reduction": "5% per quarter",
    "tracking": {
        "complexity": "sonarqube",
        "dependencies": "dependabot",
        "coverage": "codecov"
    }
}

7. 沟通计划

利益相关者报告

## Executive Summary
- Current debt score: 890 (High)
- Monthly velocity loss: 35%
- Bug rate increase: 45%
- Recommended investment: 500 hours
- Expected ROI: 280% over 12 months

## Key Risks
1. Payment system: 3 critical vulnerabilities
2. Data layer: No backup strategy
3. API: Rate limiting not implemented

## Proposed Actions
1. Immediate: Security patches (this week)
2. Short-term: Core refactoring (1 month)
3. Long-term: Architecture modernization (6 months)

开发者文档

## Refactoring Guide
1. Always maintain backward compatibility
2. Write tests before refactoring
3. Use feature flags for gradual rollout
4. Document architectural decisions
5. Measure impact with metrics

## Code Standards
- Complexity limit: 10
- Method length: 20 lines
- Class length: 200 lines
- Test coverage: 80%
- Documentation: All public APIs

8. 成功指标

通过清晰的 KPI 跟踪进展：

月度指标

• 债务评分降低：目标 -5%
• 新 bug 率：目标 -20%
• 部署频率：目标 +50%
• 前置时间：目标 -30%
• 测试覆盖率：目标 +10%

季度评审

• 架构健康评分
• 开发者满意度调查
• 性能基准
• 安全审计结果
• 实现的成本节约

输出格式

1. 债务清单：按类型分类并附带指标的完整列表
2. 影响分析：成本计算和风险评估
3. 按优先级排序的路线图：逐季度计划，包含明确的交付物
4. 快速见效：本迭代的即时行动
5. 实施指南：分步重构策略
6. 预防计划：避免积累新债务的流程
7. ROI 预测：债务削减投资的预期回报

专注于交付可直接影响开发速度、系统可靠性和团队士气的可衡量改进。

限制

• 仅在任务明确符合上述范围时使用此技能。
• 不要将输出视为特定环境验证、测试或专家评审的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。