Back to Details

tech-debt-analyzer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tech Debt Analyzer

技术债务分析器

Systematic technical debt inventory, prioritization, and remediation planning. Multi-pass analysis with confidence scoring and evidence-based findings.
Scope: Debt inventory and tracking only. NOT for code review (review), refactoring execution, or dependency updates.
系统化的technical debt清单、优先级排序与修复规划。 多轮分析，附带置信度评分和基于证据的发现结果。
适用范围： 仅用于债务清单整理与跟踪。不支持代码评审、重构执行或依赖更新。

Canonical Vocabulary

规范术语表

TermDefinition
debt itemA discrete tech debt finding with category, severity, confidence, and evidence
categoryDebt classification: design, test, documentation, dependency, infrastructure
severityImpact level: CRITICAL, HIGH, MEDIUM, LOW
confidenceScore 0.0-1.0 per item; >=0.7 report, 0.3-0.7 flag, <0.3 discard
complexityCyclomatic (decision paths) or cognitive (human comprehension difficulty)
dead codeFunctions, classes, or imports with no references in the codebase
stalenessDays since a dependency's current version was superseded
inconsistencySame pattern implemented differently across files
remediationSpecific fix action with effort estimate and risk level
debt scoreAggregate metric: sum of (severity_weight x confidence) across all items
baselinePrevious scan stored at ~/.{gemini
heatmapVisual density of debt items per file or directory
risk x effortPrioritization matrix: impact vs. remediation cost
TermDefinition
debt item一个离散的技术债务发现项，包含类别、严重程度、置信度和证据
category债务分类：设计、测试、文档、依赖、基础设施
severity影响级别：CRITICAL、HIGH、MEDIUM、LOW
confidence每个项的得分（0.0-1.0）；≥0.7则报告，0.3-0.7标记为待确认，<0.3则丢弃
complexity圈复杂度（决策路径数）或认知复杂度（人类理解难度）
dead code代码库中无引用的函数、类或导入语句
staleness依赖包当前版本被取代后的天数
inconsistency同一模式在不同文件中的实现方式不一致
remediation具体的修复操作，包含工作量估算和风险级别
debt score聚合指标：所有项的（严重程度权重 × 置信度）之和
baseline存储在`~/.{gemini
heatmap每个文件或目录中债务项的可视化密度图
risk x effort优先级矩阵：影响程度 vs 修复成本

Dispatch

命令模式

$ARGUMENTSMode
scan
or 
scan <path>
Full codebase debt inventory (or scoped to path)
analyze <file/dir>
Targeted deep analysis of specific file or directory
prioritize
Rank all debt items by risk x effort matrix
roadmap
Generate phased remediation plan
report
Render dashboard visualization
track
Compare current scan against previous baseline
EmptyShow mode menu with descriptions and examples
$ARGUMENTS模式
scan
or 
scan <path>
全代码库债务清单（或限定路径范围）
analyze <file/dir>
针对特定文件或目录的深度分析
prioritize
按风险×工作量矩阵对所有债务项排序
roadmap
生成分阶段修复计划
report
渲染仪表盘可视化界面
track
对比当前扫描结果与历史基准
Empty显示模式菜单及说明和示例

Mode: Scan

模式：扫描

Full codebase debt inventory. Run all 4 analysis scripts, aggregate results, assign categories and severities.
全代码库债务清单整理。运行全部4个分析脚本，汇总结果，分配类别和严重程度。

Scan Step 1: Project Profile

扫描步骤1：项目概况

Run 
uv run python scripts/complexity-scanner.py <path>
to get complexity metrics. Parse JSON output. Flag functions with cyclomatic_complexity > 10 as HIGH, > 5 as MEDIUM.
运行
uv run python scripts/complexity-scanner.py <path>
获取复杂度指标。 解析JSON输出。将圈复杂度>10的函数标记为HIGH，>5的标记为MEDIUM。

Scan Step 2: Dead Code Detection

扫描步骤2：死代码检测

Run 
uv run python scripts/dead-code-detector.py <path>
to find unused code. Parse JSON output. Each unused item becomes a debt item (category: design, severity by confidence).
运行
uv run python scripts/dead-code-detector.py <path>
查找未使用代码。 解析JSON输出。每个未使用项均成为债务项（类别：设计，严重程度由置信度决定）。

Scan Step 3: Dependency Staleness

扫描步骤3：依赖过期检查

Run 
uv run python scripts/dependency-staleness-checker.py <path>
to check outdated packages. Parse JSON output. Deprecated packages are CRITICAL. Staleness > 365 days is HIGH.
运行
uv run python scripts/dependency-staleness-checker.py <path>
检查过时包。 解析JSON输出。已废弃的包标记为CRITICAL。过期超过365天的标记为HIGH。

Scan Step 4: Pattern Consistency

扫描步骤4：模式一致性检测

Run 
uv run python scripts/pattern-consistency-checker.py <path>
to detect inconsistencies. Parse JSON output. Each inconsistency becomes a debt item (category: design).
运行
uv run python scripts/pattern-consistency-checker.py <path>
检测不一致情况。 解析JSON输出。每个不一致项均成为债务项（类别：设计）。

Scan Step 5: AI-Augmented Analysis

扫描步骤5：AI增强分析

After script-based detection, perform additional analysis:
  1. Documentation gaps — scan for undocumented public APIs, missing README sections, stale comments
  2. Test coverage gaps — Grep for untested modules, missing edge cases, test-to-code ratio
  3. Infrastructure debt — outdated CI configs, missing linting, inconsistent tooling
  4. Design smells — God classes, feature envy, shotgun surgery patterns
Assign confidence scores (0.0-1.0) per finding. Research-validate HIGH/CRITICAL items using Grep and codebase evidence.
基于脚本检测结果，执行额外分析：
  1. 文档缺失 — 扫描未文档化的公共API、缺失的README章节、过时注释
  2. 测试覆盖缺口 — 查找未测试模块、缺失的边缘用例、测试代码比
  3. 基础设施债务 — 过时的CI配置、缺失的代码检查、不一致的工具链
  4. 设计异味 — 上帝类、特性羡慕、霰弹式修改模式
为每个发现项分配置信度得分（0.0-1.0）。使用Grep和代码库证据对HIGH/CRITICAL级别的项进行验证。

Scan Step 6: Aggregate and Classify

扫描步骤6：汇总与分类

Merge all findings into a unified inventory:
  • Deduplicate across script outputs
  • Assign categories from debt taxonomy (references/debt-taxonomy.md)
  • Calculate debt score: sum of (severity_weight x confidence)
  • Store baseline at 
    ~/.{gemini|copilot|codex|claude}/tech-debt/<project-slug>-<date>.json
Present findings grouped by category, sorted by severity within each group.
将所有发现项合并为统一清单：
  • 去重脚本输出中的重复项
  • 根据债务分类法（参考references/debt-taxonomy.md）分配类别
  • 计算债务得分：所有项的（严重程度权重 × 置信度）之和
  • 将基准结果存储至
    ~/.{gemini|copilot|codex|claude}/tech-debt/<project-slug>-<date>.json
按类别分组展示发现项，每组内按严重程度排序。

Mode: Analyze

模式：分析

Targeted deep analysis of a specific file or directory. Run all 4 scripts scoped to the target. Apply the same 6-step scan process but with deeper per-function analysis. Include: function-level complexity breakdown, inline dead code, local pattern violations.
针对特定文件或目录的深度分析。在目标范围内运行全部4个脚本。 应用相同的6步扫描流程，但增加函数级的深度分析。 包含：函数级复杂度细分、内嵌死代码、本地模式违规情况。

Mode: Prioritize

模式：优先级排序

Rank debt items using risk x effort matrix. Load 
references/prioritization-framework.md
.
Low EffortMedium EffortHigh Effort
High RiskP0: Fix immediatelyP1: Schedule next sprintP2: Plan for next quarter
Medium RiskP1: Schedule next sprintP2: Plan for next quarterP3: Backlog
Low RiskP2: Quick wins batchP3: BacklogP4: Accept or defer
For each debt item, estimate:
  • Risk: blast radius x severity x confidence
  • Effort: LOC affected x complexity x dependency count
Output a ranked list with priority labels (P0-P4).
使用风险×工作量矩阵对债务项排序。加载
references/prioritization-framework.md
。
低工作量中工作量高工作量
高风险P0：立即修复P1：安排至下一个迭代P2：规划至下一季度
中风险P1：安排至下一个迭代P2：规划至下一季度P3：放入待办清单
低风险P2：批量快速处理P3：放入待办清单P4：接受或延后处理
为每个债务项估算：
  • 风险：影响范围 × 严重程度 × 置信度
  • 工作量：受影响代码行数 × 复杂度 × 依赖数量
输出带优先级标签（P0-P4）的排序列表。

Mode: Roadmap

模式：路线图

Generate a phased remediation plan. Requires a prior scan (reads baseline from 
~/.{gemini|copilot|codex|claude}/tech-debt/
).
Phase structure:
  1. Quick Wins (P0 + low-effort P1): immediate fixes, minimal risk
  2. Structural (remaining P1 + high-risk P2): design improvements, refactoring
  3. Maintenance (P2 + P3): documentation, test coverage, dependency updates
  4. Strategic (P3 + P4): architecture changes, long-term improvements
Each phase includes: items, estimated effort, dependencies, success criteria.
生成分阶段修复计划。需要先完成扫描（从
~/.{gemini|copilot|codex|claude}/tech-debt/
读取基准结果）。
阶段结构：
  1. 快速处理（P0 + 低工作量P1）：立即修复，风险极低
  2. 结构优化（剩余P1 + 高风险P2）：设计改进、重构
  3. 维护完善（P2 + P3）：文档补充、测试覆盖、依赖更新
  4. 战略升级（P3 + P4）：架构调整、长期改进
每个阶段包含：处理项、估算工作量、依赖项、成功标准。

Mode: Report

模式：报告

Render dashboard visualization. Requires a prior scan.
  1. Read the most recent baseline from 
    ~/.{gemini|copilot|codex|claude}/tech-debt/
  2. Copy 
    templates/dashboard.html
    to a temporary file
  3. Inject findings JSON into the 
    <script id="data">
    tag
  4. Open in browser or report the path
Dashboard sections: category pie chart, complexity heatmap, trend chart (if multiple baselines), prioritized backlog table.
渲染仪表盘可视化界面。需要先完成扫描。
  1. 从
    ~/.{gemini|copilot|codex|claude}/tech-debt/
    读取最新基准结果
  2. 将
    templates/dashboard.html
    复制到临时文件
  3. 将发现项JSON注入
    <script id="data">
    标签
  4. 在浏览器中打开或返回文件路径
仪表盘包含：类别饼图、复杂度热力图、趋势图（如有多个基准结果）、优先级待办清单表格。

Mode: Track

模式：跟踪

Compare current scan against previous baseline for longitudinal tracking.
  1. Run a fresh scan (Mode: Scan steps 1-6)
  2. Load previous baseline from 
    ~/.{gemini|copilot|codex|claude}/tech-debt/<project-slug>-*.json
    (most recent)
  3. Compute delta: new items, resolved items, changed severities, score trend
  4. Present comparison report with trend indicators
对比当前扫描结果与历史基准，实现纵向跟踪。
  1. 执行全新扫描（按「模式：扫描」步骤1-6）
  2. 从
    ~/.{gemini|copilot|codex|claude}/tech-debt/<project-slug>-*.json
    读取最新历史基准
  3. 计算差值：新增项、已解决项、严重程度变更、得分趋势
  4. 展示带趋势指标的对比报告

State Management

状态管理

  • State directory: 
    ~/.{gemini|copilot|codex|claude}/tech-debt/
  • Create directory on first use with 
    mkdir -p
  • Filename: 
    <project-slug>-<YYYY-MM-DD>.json
  • Project slug: sanitized basename of the project root directory
  • Store after every scan; track mode reads historical baselines
  • Schema: 
    { "project": str, "date": str, "score": float, "items": [...], "summary": {...} }
  • 状态目录：
    ~/.{gemini|copilot|codex|claude}/tech-debt/
  • 首次使用时通过
    mkdir -p
    创建目录
  • 文件名：
    <project-slug>-<YYYY-MM-DD>.json
  • 项目标识：项目根目录的标准化名称
  • 每次扫描后存储；跟踪模式读取历史基准
  • Schema：
    { "project": str, "date": str, "score": float, "items": [...], "summary": {...} }

Reference Files

参考文件

Load ONE reference at a time. Do not preload all references into context.
FileContentRead When
references/debt-taxonomy.md
5 debt categories with subcategories and remediation templatesScan Step 6, classifying findings
references/complexity-metrics.md
Cyclomatic and cognitive complexity definitions, thresholds, interpretationInterpreting complexity-scanner output
references/prioritization-framework.md
Risk x effort matrix, scoring rubric, priority definitionsPrioritize mode
references/remediation-templates.md
Fix patterns by issue type, effort estimates, risk ratingsRoadmap mode, generating fix plans
ScriptWhen to Run
scripts/complexity-scanner.py
Scan Steps 1, Analyze mode
scripts/dead-code-detector.py
Scan Step 2, Analyze mode
scripts/dependency-staleness-checker.py
Scan Step 3
scripts/pattern-consistency-checker.py
Scan Step 4, Analyze mode
TemplateWhen to Render
templates/dashboard.html
Report mode — inject findings JSON into data tag
每次仅加载一个参考文件。请勿预先加载所有参考文件至上下文。
文件内容加载时机
references/debt-taxonomy.md
5种债务类别，包含子类别和修复模板扫描步骤6，分类发现项时
references/complexity-metrics.md
圈复杂度与认知复杂度的定义、阈值、解读方式解析complexity-scanner输出时
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注入数据标签

Debt Item Structure

债务项结构

Every debt item follows this format:
  1. Location: 
    [file:line]
    or 
    [file:start-end]
    — exact source location
  2. Category: design | test | documentation | dependency | infrastructure
  3. Severity: CRITICAL | HIGH | MEDIUM | LOW
  4. Confidence: 0.0-1.0 score with evidence basis
  5. Description: What the debt is (1-2 sentences)
  6. Impact: Why it matters (blast radius, risk)
  7. Remediation: Recommended fix approach with effort estimate
每个债务项遵循以下格式：
  1. 位置：
    [file:line]
    或 
    [file:start-end]
    — 精确的源码位置
  2. 类别：design | test | documentation | dependency | infrastructure
  3. 严重程度：CRITICAL | HIGH | MEDIUM | LOW
  4. 置信度：0.0-1.0的得分，附带证据依据
  5. 描述：债务内容（1-2句话）
  6. 影响：债务的重要性（影响范围、风险）
  7. 修复方案：推荐的修复方式，包含工作量估算

Critical Rules

核心规则

  1. Run all 4 analysis scripts before presenting findings — partial scans are labeled as such
  2. Every finding must have a confidence score backed by evidence (script output or codebase grep)
  3. Confidence < 0.3 = discard; 0.3-0.7 = flag as uncertain; >= 0.7 = report
  4. Never execute remediation — this skill inventories and plans, not fixes
  5. Store baseline after every full scan — longitudinal tracking depends on it
  6. Do not report style preferences as debt — only structural, behavioral, or maintainability issues
  7. Deduplicate across script outputs — same file:line should not appear twice
  8. Prioritize mode requires a prior scan — prompt user to run scan first if no baseline exists
  9. Always present the debt score (aggregate metric) in scan output
  10. Track mode must show delta (new/resolved/changed) — raw numbers without comparison are useless
  11. Dead code detection requires high confidence (>= 0.8) — false positives erode trust
  12. Load ONE reference file at a time — do not preload all references
  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. 每次仅加载一个参考文件 — 请勿预先加载所有参考文件