Tech Debt Report 是一个用于量化代码库技术债务的技能，目标是把“我们的代码很乱”这种模糊感受，转化为一份可量化、可排序的清单，供管理层和工程团队就债务偿还做出知情决策。
用途
该技能用于系统性地扫描代码库，识别并量化技术债务。它覆盖代码异味、过时依赖、复杂度热点、缺失测试、TODO、死代码等多个维度，最终生成一份结构化的技术债务报告。
主要能力
技能按结构化流程执行，包含以下扫描类别：
-
代码库概况：统计总代码行数（排除依赖和构建产物）、按语言统计文件数、源文件总数、测试文件总数、测试与源文件比例、代码库年龄（首次提交、最新提交、总提交数、贡献者数）、目录结构。
-
债务类别扫描：
- 代码复杂度债务：查找超过 500 行和 300 行的大文件、长函数、深层嵌套（缩进超过 4 层）、代码重复、TypeScript 中 any 类型滥用、@ts-ignore / @ts-expect-error / @ts-nocheck 数量。
- TODO / FIXME / HACK 债务：统计 TODO、FIXME、HACK、XXX、WORKAROUND、TEMPORARY、DEPRECATED 等标记数量，列出带上下文的标记，识别没有工单号的 TODO，以及通过 git log 查看 TODO 的添加时间。
- 依赖债务：检查过时包（npm outdated、pip list --outdated）、安全漏洞（npm audit、pip audit）、锁文件是否存在、未固定版本（^、~、*、latest）、Node.js 版本、已弃用包、直接依赖和开发依赖数量。
- 测试债务：运行测试覆盖率（jest、pytest、go test）、查找没有对应测试文件的源文件、统计未测试文件数、文件级测试覆盖率、空或极简测试文件、被跳过的测试。
- 文档债务：检查 README 是否存在及最后更新时间、API 文档（openapi、swagger）、架构文档、内联文档覆盖率（JSDoc、docstrings）、过时文档、.env.example、CONTRIBUTING.md、ADR/决策记录。
- 死代码债务：使用 ts-prune 查找未使用导出、使用 vulture 查找未使用 Python 代码、注释掉的代码块、未被引用的文件、遗留/弃用目录。
- 配置与基础设施债务：硬编码值（localhost、127.0.0.1）、魔法数字、环境特定配置、Docker 配置（未固定基础镜像）、CI/CD 配置年龄、代码中的密钥。
使用方式
该技能以结构化流程执行，包含具体的 shell 命令和扫描步骤。使用时需在项目根目录运行，技能会执行一系列 find、grep、git、npm、pip 等命令来收集数据。输出必须保存为 Markdown 文件，路径为项目根目录下的 project-decisions/ 目录，文件名为 YYYY-MM-DD-tech-debt-report.md。如果目录不存在，需先创建：mkdir -p project-decisions。
适用场景
适用于需要评估代码库健康状况、规划技术债务偿还、向管理层汇报技术债务情况的工程团队。特别适合在项目决策、重构规划、代码审查或技术评估时使用。
限制
该技能依赖项目中的工具和配置（如 npm、pip、jest、pytest、go test、ts-prune、vulture 等），部分扫描需要这些工具已安装并可用。扫描结果基于启发式方法，可能存在误报或漏报。技能未提供关于收费、价格、平台或具体效果的信息。