mcpField
T
tech-debt-analyzer

tech-debt-analyzer

github.com/wyattowalsh测试与质量548 次安装8 周前更新
代码仓库

关于 tech-debt-analyzer

用于系统盘点、评估和规划技术债务的技能，面向需要掌握代码库可维护性状况的开发团队。它结合脚本与证据置信度，支持基线追踪和风险—工作量排序，但不执行修复。

主要功能

  1. 01多轮代码库债务扫描
  2. 02置信度与证据记录
  3. 03风险—工作量排序
  4. 04分阶段修复路线图
  5. 05基线对比与仪表盘

适用场景

  1. 01盘点代码复杂度与死代码
  2. 02识别依赖陈旧和模式不一致
  3. 03比较扫描结果并追踪债务变化
  4. 04制定分阶段的债务处理计划

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wyattowalsh/agents --skill tech-debt-analyzer

安装后在 Claude Code 中输入/tech-debt-analyzer确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

evals/
evals.json
explicit-scan.json
implicit-trigger.json
negative-control.json
prioritize-mode.json
roadmap-mode.json
track-mode.json
references/
complexity-metrics.md
debt-taxonomy.md
prioritization-framework.md
remediation-templates.md
scripts/
check.py
complexity-scanner.py
dead-code-detector.py
dependency-staleness-checker.py
pattern-consistency-checker.py
scripts/asset_toolkit/
__init__.py
_shared.py
common.py
package.py
validate_evals.py
validate_hooks.py
validate_skill.py
templates/
dashboard.html

详细介绍

技术债务分析器

系统性地梳理技术债务、确定优先级并规划修复方案。 通过多轮分析，结合置信度评分和基于证据的发现。

**范围：**仅用于债务梳理和跟踪。不适用于代码审查（review）、重构执行或依赖项更新。

标准术语

术语定义
债务项一项具体的技术债务发现，包含类别、严重程度、置信度和证据
类别债务分类：设计、测试、文档、依赖项、基础设施
严重程度影响级别：CRITICAL、HIGH、MEDIUM、LOW
置信度每项的评分为 0.0-1.0；>=0.7 时报告，0.3-0.7 时标记，<0.3 时舍弃
复杂度圈复杂度（决策路径）或认知复杂度（人类理解难度）
死代码在代码库中没有引用的函数、类或导入项
陈旧度某个依赖项的当前版本被后续版本取代至今的天数
不一致同一模式在不同文件中的实现方式不同
修复方案具体的修复操作，包含工作量估算和风险级别
债务分数汇总指标：所有债务项的（严重程度权重 x 置信度）之和
基线存储在 ~/.{gemini
热力图按文件或目录显示债务项的可视化密度
风险 x 工作量优先级矩阵：影响与修复成本的对比

调度

$ARGUMENTS模式
scan 或 scan <path>全代码库债务梳理（或限定为指定路径）
analyze <file/dir>对指定文件或目录进行有针对性的深度分析
prioritize使用风险 x 工作量矩阵对所有债务项排序
roadmap生成分阶段修复计划
report渲染仪表板可视化
track将当前扫描结果与先前基线对比
空显示模式菜单及说明和示例

模式：扫描

梳理全代码库债务。运行全部 4 个分析脚本，汇总结果并指定类别和严重程度。

扫描步骤 1：项目概况

运行 uv run python scripts/complexity-scanner.py <path> 获取复杂度指标。 解析 JSON 输出。将 cyclomatic_complexity > 10 的函数标记为 HIGH，> 5 的标记为 MEDIUM。

扫描步骤 2：死代码检测

运行 uv run python scripts/dead-code-detector.py <path> 查找未使用的代码。 解析 JSON 输出。每个未使用项都成为一个债务项（类别：设计；严重程度根据置信度确定）。

扫描步骤 3：依赖项陈旧度

运行 uv run python scripts/dependency-staleness-checker.py <path> 检查过时的软件包。 解析 JSON 输出。已弃用的软件包为 CRITICAL。陈旧度 > 365 天为 HIGH。

扫描步骤 4：模式一致性

运行 uv run python scripts/pattern-consistency-checker.py <path> 检测不一致。 解析 JSON 输出。每项不一致都成为一个债务项（类别：设计）。

扫描步骤 5：AI 增强分析

基于脚本的检测完成后，进行额外分析：

  1. 文档缺失——扫描缺少文档的公共 API、README 中缺失的章节、过时的注释
  2. 测试覆盖缺口——搜索未经测试的模块、缺失的边缘用例，以及测试与代码的比例
  3. 基础设施债务——过时的 CI 配置、缺失的 lint 工具、不一致的工具链
  4. 设计异味——上帝类、特性嫉妒、霰弹式修改模式

为每项发现指定置信度评分（0.0-1.0）。使用 Grep 和代码库证据对 HIGH/CRITICAL 项进行研究验证。

扫描步骤 6：汇总和分类

将所有发现合并到统一清单中：

  • 对不同脚本输出中的重复项进行去重
  • 根据债务分类体系指定类别（参见 references/debt-taxonomy.md）
  • 计算债务分数：（严重程度权重 x 置信度）之和
  • 将基线存储在 ~/.{gemini|copilot|codex|claude}/tech-debt/<project-slug>-<date>.json

按类别分组展示发现，并在每组内按严重程度排序。

模式：分析

针对特定文件或目录进行深入分析。对目标运行全部 4 个脚本。 应用相同的 6 步扫描流程，但深入分析每个函数。 包括：函数级复杂度细分、行内死代码、局部模式违规。

模式：优先级排序

使用风险 × 工作量矩阵为技术债项排序。加载 references/prioritization-framework.md。

低工作量中等工作量高工作量
高风险P0：立即修复P1：安排在下一个冲刺P2：规划在下一季度
中等风险P1：安排在下一个冲刺P2：规划在下一季度P3：加入待办事项
低风险P2：批量处理易修复项P3：加入待办事项P4：接受或暂缓

对每项技术债估算：

  • 风险：影响范围 × 严重性 × 置信度
  • 工作量：受影响的代码行数 × 复杂度 × 依赖项数量

输出带优先级标签（P0-P4）的排序列表。

模式：路线图

生成分阶段的修复计划。需要先完成扫描（从 ~/.{gemini|copilot|codex|claude}/tech-debt/ 读取基线）。

阶段结构：

  1. 快速见效（P0 + 低工作量 P1）：立即修复，风险最小
  2. 结构性改进（其余 P1 + 高风险 P2）：设计改进、重构
  3. 维护（P2 + P3）：文档、测试覆盖率、依赖项更新
  4. 战略性改进（P3 + P4）：架构变更、长期改进

每个阶段包括：事项、预估工作量、依赖项、成功标准。

模式：报告

生成仪表板可视化。需要先完成扫描。

  1. 从 ~/.{gemini|copilot|codex|claude}/tech-debt/ 读取最新基线
  2. 将 templates/dashboard.html 复制到临时文件
  3. 将发现项 JSON 注入 <script id="data"> 标签
  4. 在浏览器中打开，或报告文件路径

仪表板板块：类别饼图、复杂度热图、趋势图（若有多个基线）、按优先级排序的待办事项表。

模式：跟踪

将当前扫描结果与先前基线比较，进行纵向跟踪。

  1. 执行一次全新扫描（模式：扫描，步骤 1-6）
  2. 从 ~/.{gemini|copilot|codex|claude}/tech-debt/<project-slug>-*.json 加载先前基线（最新一份）
  3. 计算差异：新增项、已解决项、严重性变化、评分趋势
  4. 输出带趋势指标的对比报告

状态管理

  • 状态目录：~/.{gemini|copilot|codex|claude}/tech-debt/
  • 首次使用时使用 mkdir -p 创建目录
  • 文件名：<project-slug>-<YYYY-MM-DD>.json
  • 项目标识：项目根目录名称的净化版本
  • 每次扫描后保存；跟踪模式读取历史基线
  • 架构：{ "project": str, "date": str, "score": float, "items": [...], "summary": {...} }

参考文件

每次只加载一个参考文件。不要将所有参考文件预先加载到上下文中。

文件内容读取时机
references/debt-taxonomy.md5 种技术债类别，包含子类别和修复模板扫描步骤 6：对发现项分类
references/complexity-metrics.md圈复杂度和认知复杂度的定义、阈值及解读解读复杂度扫描器的输出
references/prioritization-framework.md风险 × 工作量矩阵、评分标准、优先级定义优先级排序模式
references/remediation-templates.md按问题类型划分的修复模式、工作量估算、风险评级路线图模式，生成修复计划
脚本运行时机
scripts/complexity-scanner.py扫描步骤 1、分析模式
scripts/dead-code-detector.py扫描步骤 2、分析模式
scripts/dependency-staleness-checker.py扫描步骤 3
scripts/pattern-consistency-checker.py扫描步骤 4、分析模式
模板渲染时机
templates/dashboard.html报告模式——将发现项 JSON 注入 data 标签

债务条目结构

每个债务条目都遵循以下格式：

  1. 位置：[file:line] 或 [file:start-end] — 精确的源代码位置
  2. 类别：设计 | 测试 | 文档 | 依赖项 | 基础设施
  3. 严重程度：CRITICAL | HIGH | MEDIUM | LOW
  4. 置信度：0.0-1.0 分，并注明证据依据
  5. 描述：说明债务内容（1-2 句话）
  6. 影响：说明其重要性（影响范围、风险）
  7. 修复方案：建议的修复方法及工作量估算

关键规则

  1. 呈现发现之前，运行全部 4 个分析脚本 — 部分扫描必须标注为部分扫描
  2. 每项发现都必须有置信度评分，并由证据支持（脚本输出或代码库 grep）
  3. 置信度 < 0.3 = 丢弃；0.3-0.7 = 标记为不确定；>= 0.7 = 报告
  4. 绝不执行修复 — 此技能用于盘点和规划，而非修复
  5. 每次完整扫描后都要保存基线 — 长期跟踪依赖于此
  6. 不要将风格偏好报告为债务 — 只报告结构、行为或可维护性问题
  7. 对脚本输出进行去重 — 同一个 file:line 不得重复出现
  8. 优先级模式需要先前的扫描记录 — 如果没有基线，提示用户先运行扫描
  9. 扫描输出中始终呈现债务评分（综合指标）
  10. 跟踪模式必须显示差异（新增/已解决/已变更）— 只有原始数字而没有比较毫无意义
  11. 死代码检测需要高置信度（>= 0.8）— 误报会削弱信任
  12. 一次只加载一个参考文件 — 不要预加载所有参考文件

评论

支持 Markdown