tech-debt-tracker

技术债务跟踪器

Agent 使用 AST 解析、延迟成本分析和趋势仪表板，识别、评分、确定优先级并跟踪各代码库中的技术债务。

核心功能

• 检测 — 使用 AST 解析（Python）和正则表达式模式匹配（所有语言），检测六类债务：代码、架构、测试、文档、依赖项和基础设施。
• 严重程度评分 — 按速度、质量、生产力和业务影响为每个条目评分（1-10），并评估工作量（XS-XL）和风险。
• 延迟成本 — 计算利息率（Impact x Frequency）和延迟成本（Interest x Sprints x Team Multiplier）；还支持 WSJF 和 RICE 框架。
• 优先级排序 — 在延迟成本与工作量矩阵上绘制条目（立即处理 / 计划处理 / 机会处理 / 待办）。
• Sprint 分配 — 根据团队速度应用债务与功能的比例；为债务工作预留产能。
• 重构策略 — 绞杀榕、按抽象分支、功能开关、并行运行。
• 报告 — 生成高管和工程仪表板、趋势分析、速度跟踪，以及基于扫描快照的预测。

适用场景

• 跟踪并量化代码库中的技术债务。
• 确定重构工作的优先级并计算延迟成本。
• 规划 Sprint 中债务工作与功能开发的产能分配。
• 向高管汇报债务状况、趋势和投资建议。

先行确认

扫描或生成报告前，请确认以下信息。若有任何信息未知或含糊不清，请先询问，不要自行假设：

• 目标代码库 — 要扫描的目录（债务清单所针对的对象）
• 优先级框架和团队规模 — 延迟成本 / WSJF / RICE，以及团队人数（--framework、--team-size；会影响排序和 Sprint 分配）
• 报告受众 — 高管仪表板还是工程清单（决定报告格式和详略程度）

停止规则：只询问对输出影响最大的 2-3 项。如果用户说“先起草一份”，则继续，并在文档顶部列出假设。

工具

工具	用途	命令
debt_scanner.py	扫描目录中的债务信号；输出 JSON 清单和文本报告	python scripts/debt_scanner.py <dir> --output scan_results --format both
debt_prioritizer.py	使用延迟成本 / WSJF / RICE 和 Sprint 分配丰富清单	python scripts/debt_prioritizer.py scan_results.json --framework wsjf --team-size 8
debt_dashboard.py	分析多个快照的趋势、速度、预测并生成高管摘要	python scripts/debt_dashboard.py --input-dir ./debt_scans/ --period quarterly

参考资料

加载与任务匹配的参考资料——保持此文件精简，按需查阅详细内容：

• references/methodology.md — 7 步工作流、技术债分类表、严重程度评分框架、利息率／延迟成本公式、优先级矩阵、WSJF、冲刺分配比例、技术债条目 JSON 架构、重构策略和季度规划。评分、确定优先级或规划时阅读。
• references/tool-reference.md — 三个脚本的完整参数表、示例和输出格式详情，以及故障排查表。运行脚本或调试输出时阅读。
• references/dashboards-and-examples.md — 面向管理层和工程团队的仪表板布局、Python 微服务扫描示例，以及成功标准栏。生成报告或验证质量时阅读。
• references/debt-classification-taxonomy.md — 跨维度分类技术债的完整分类体系，以及各类别的检测启发式规则。校准检测或标注条目时阅读。
• references/prioritization-framework.md — 基于业务价值、风险、工作量和战略契合度的深入优先级排序方法。设计优先级评估标准时阅读。
• references/stakeholder-communication-templates.md — 面向不同利益相关方群体的技术债状态、影响和建议沟通模板与指南。向高管或产品团队汇报时阅读。

另请参阅技能根目录中的 REFERENCE.md，了解技术债象限（Fowler）和实施路线图阶段。

范围与限制

此技能涵盖：

• 通过 AST 解析（Python）和正则表达式模式匹配（所有语言），静态检测代码级、架构、测试、文档、依赖项和基础设施技术债。
• 使用延迟成本、WSJF 和 RICE 框架，对技术债条目进行量化优先级排序，并支持配置团队规模和冲刺容量。
• 基于多个扫描快照进行历史趋势分析、健康评分、技术债速度跟踪，以及管理层／工程团队仪表板生成。
• 制定冲刺分配计划，按容量安排待办事项，并按技术债类型估算工作量。

此技能不涵盖：

• 运行时性能分析或生产环境监控——相关内容请参阅 engineering/performance-profiler 和 engineering/observability-designer。
• 依赖项漏洞扫描（CVE 检测）或软件成分分析——安全方面的依赖项审查请参阅 engineering/dependency-auditor。
• 自动重构或代码转换——此技能会识别技术债并确定其优先级，但不会修改源代码。
• 数据库架构技术债、API 契约偏差或基础设施即代码偏差检测——相关领域请参阅 engineering/database-schema-designer、engineering/api-design-reviewer 和 engineering/migration-architect。

集成点

技能	集成方式	数据流
engineering/dependency-auditor	将依赖项审计结果作为 dependency_debt 条目输入扫描器，以便在一个清单中统一管理所有债务。	依赖项审计 JSON -> 扫描器配置，或手动合并到 debt_inventory.json
engineering/performance-profiler	将性能热点与高复杂度债务条目关联起来，优先重构以同时提升质量和速度。	Profiler 热点报告 -> 按文件路径与扫描器输出交叉比对
engineering/ci-cd-pipeline-builder	将 debt_scanner.py 添加为 CI 流水线步骤，当健康评分低于阈值或关键债务数量增加时，使构建失败。	扫描器 JSON 输出 -> 基于 summary.health_score 的 CI 门禁条件
engineering/pr-review-expert	在代码审查期间，根据拉取请求中涉及的文件查询债务清单，显示相关债务条目。	PR 变更文件列表 -> 按 file_path 筛选 debt_inventory.json
engineering/observability-designer	将基础设施债务条目（缺少监控、环境不一致）映射到可观测性技能识别出的可观测性缺口。	仪表板 category_distribution -> 可观测性缺口分析
engineering/migration-architect	利用优先级排序后的待办事项，规划大型迁移工作的范围和顺序，尤其是被评定为计划性举措的架构类别债务。	Prioritizer sprint_allocation -> 迁移规划时间线