tech-debt

技术债务分析

调查代码库的 8 个类别，按影响和工作量为每项发现评分，并生成按优先级排序的 TECH_DEBT.md 整改计划。直接分析其中 4 个类别；另外 4 个类别委托给专门的技能。

前置条件检查

git --version 2>/dev/null && git rev-parse --is-inside-work-tree 2>/dev/null

如果当前目录不在 git 仓库中，请发出警告，但继续执行——届时无法分析 git 历史，但其他检查仍可进行。

步骤 1：项目背景

开始分析前，先收集基准指标：

echo "Project: $(basename $(pwd))"
echo "Files: $(find . -type f -name '*.go' -o -name '*.js' -o -name '*.ts' \
  -o -name '*.py' -o -name '*.rs' -o -name '*.cs' | grep -v node_modules \
  | grep -v vendor | grep -v .git | wc -l)"
echo "Branch: $(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
echo "Last commit: $(git log -1 --format='%h %s' 2>/dev/null)"

根据现有配置文件判断项目类型（Go、Node、Python、.NET、Rust、混合）。

步骤 2：委托分析类别

对于由专门技能负责的类别，请进行委托，或注明以便日后委托：

代码质量——如果 scout 技能可用，请针对近期更改的文件运行。Scout 会使用“影响 × 低风险”评分，为每个文件找出 3 个最值得改进之处。

Lint——如果 lint-fix 技能可用，请运行其检测模式（仅第 1 步），以确定已配置哪些 lint 工具，以及是否缺少任何工具。不要运行完整的修复流程。

安全——如果 security-audit 技能可用，请运行它，分析 OWASP Top 10、检测密钥、评估供应链并进行威胁建模。将安全评分纳入技术债务评分卡。

依赖项——如果 dep-upgrade 技能可用，请运行其审计步骤（仅第 1–2 步），按优先级识别过时和存在漏洞的软件包。将依赖项健康评分纳入技术债务评分卡。

设计原则——如果 design-principles 技能可用，请以委托模式针对整个代码库运行。该技能会依据 SOLID、DRY、YAGNI、KISS、得墨忒耳法则、关注点分离、组合优于继承，以及与代码相关的 12-Factor 子集进行审计。将整体设计健康评分纳入技术债务评分卡，并将 P1 发现纳入整改路线图。

步骤 3：架构分析（直接）

调查代码库中的结构性问题。详细模式请参阅 references/analysis-patterns.md。

1. 检查上帝文件——找出超过 500 行且职责混杂的文件
2. 检查耦合——找出导入超过 10 个软件包的文件
3. 检查分层违规——查找出现在错误层中的数据库/HTTP 逻辑
4. 检查循环依赖——追踪导入模式
5. 找出影响最大的 3–5 个架构问题——重点关注阻碍新功能开发或导致错误的问题

步骤 4：测试分析（直接）

衡量测试健康状况。详细模式请参阅 references/analysis-patterns.md。

1. 衡量覆盖率——如果有可用的覆盖率工具，请运行
2. 计算测试/代码比例——统计测试文件与代码文件的数量
3. 识别关键的未测试路径——追踪入口点，并检查每一步是否有测试覆盖
4. 标记测试反模式——没有断言的测试、使用 sleep 进行同步、共享状态、测试实现细节
5. 检查缺失的测试类型——是否只有单元测试？是否有集成测试？端到端测试？

步骤 5：文档分析（直接）

检查文档完整性。详细模式请参阅 references/analysis-patterns.md。

1. 必备文件——README.md、CONTRIBUTING.md、CHANGELOG.md、架构文档、API 文档
2. API 文档覆盖率——有文档说明的公共函数/类型占总数的比例
3. 过时文档——引用已不存在的文件、函数或模式的内容
4. 缺失的 ADR——没有记录决策依据的重要架构决策

步骤 6：基础设施分析（直接）

评估运维就绪情况。详细模式请参阅 references/analysis-patterns.md。

1. CI/CD——检查工作流配置、测试自动化和部署自动化
2. 部署——Dockerfile、容器配置、部署脚本
3. 可观测性——结构化日志记录、错误追踪、指标、告警
4. 配置——环境变量与硬编码值、密钥管理

第 7 步：为每个类别评分

使用 references/scoring-guide.md 中的评分标准，为每个类别评定 0–10 分。为每项发现指定影响程度（LOW/MEDIUM/HIGH/CRITICAL）和工作量（S/M/L/XL）。

计算优先级：从 P1（高影响、低工作量）到 P4（低影响、高工作量）。

第 8 步：生成 TECH_DEBT.md

使用 references/scoring-guide.md 中的模板撰写报告。 包括：

• 执行摘要，包含总体健康评分（9 个类别的总分，满分 90 分）
• 包含全部 9 个类别的评分表
• 每个类别的详细发现，包含证据和修复措施
• 按优先级（P1 → P4）排列的修复路线图
• 包含当前值和目标值的成功指标

对生成的文件运行 markdownlint。

第 9 步：展示摘要

向用户展示：

1. 评分表（8 个类别、分数、每个类别的首要问题）
2. 总体健康评分（X/80）
3. 需要立即处理的 P1 项目
4. 优先级最高的 5 项修复工作及预估工作量
5. 询问用户想先处理哪些项目