SuperAPI AI 工具集

technical-debt-auditor

编程与开发

查看项目

更新于 11-11 03:26

技能介绍

用途

Technical Debt Auditor 用于对一个代码库进行系统性的技术债务审计。它的目标不是笼统的“代码审查”,而是产出量化、可执行的报告,告诉团队债务在哪里、有多严重、应该先修什么。该技能把技术债务类比为金融债务:今天的一个临时取巧方案,半年后当三个功能依赖它时,修复成本可能变成十倍。因此它要在“利息”滚起来之前发现债务、量化债务,并给出与功能开发相对比的优先级和现实的偿还计划。

扫描的债务类别

该技能覆盖八类债务:

  1. 标记债务:TODO、FIXME、HACK、XXX、TEMP、WORKAROUND、KLUDGE、DEPRECATED 等注释。开发者自己标记过的已知捷径,属于自报债务,其中 HACK/FIXME 严重性高于 TODO。
  2. 死代码:无人引用的导出、不可达分支、被注释掉的代码块、无引用的文件、未使用的变量和导入。死代码会误导阅读者、增加认知负担,有时还隐藏缺陷。
  3. 依赖债务:过时的包、已弃用的 API、锁定在旧主版本、清单中未使用的依赖。陈旧依赖会累积安全漏洞并阻碍升级。
  4. 复杂度热点:大文件(超过 300 行)、大函数(超过 50 行)、深层嵌套(超过 3 层)、高圈复杂度、过长参数列表(超过 5 个)、承担过多职责的“上帝类/模块”。
  5. 重复信号:跨文件的近似相同代码块、复制粘贴的错误处理、应抽取为共享工具类的重复业务逻辑。关注的是有实质意义的重复(约 10 行以上近似逻辑),不是细枝末节。
  6. 测试缺口:源文件没有对应测试文件、断言密度低、只测正常路径的测试、被跳过的测试(.skip、@Ignore 等)。
  7. 过时模式:与项目自身约定矛盾的写法、已弃用的语言特性、遗留 API 用法、跨模块不一致的错误处理策略。
  8. 配置债务:过期配置、相互冲突的设置、含未使用变量的环境文件、本应可配置却硬编码的值。

使用方式(四阶段流程)

阶段一:侦察。 在开始扫描前先理解项目:读取 package.json、Cargo.toml、pyproject.toml、go.mod 等确定技术栈、框架、包管理器和构建系统;找到应用入口和主要模块;检查已有的 lint、格式化、类型检查、测试和 CI 配置,了解哪些问题已有工具负责,避免重复报告;阅读项目文档了解约定;记录项目规模(文件数、大致代码行数)以校准后续工作量估计。技能明确指出:在获得这些上下文之前不要开始扫描,因为 200 行 CLI 脚本里的“大函数”和 5 万行企业应用里的含义不同。

阶段二:系统扫描。 按类别逐一扫描,跳过 node_modules、vendor 和构建产物等目录。例如:标记债务要记录文件、行号和上下文,并按严重性分类,若含日期则更老的标记提示被遗忘的债务;死代码要找从未被其它地方导入的导出、超过两行连续被注释的代码(非文档注释)、不可达代码和未被 lint 捕获的未用变量;依赖债务要对照实际导入检查清单中的未使用包、查看锁文件中的弃用警告、检查主版本差距;复杂度热点列出最大的 10 个文件及其中的最大函数、深层条件嵌套和上帝类;重复信号寻找结构相似的代码块和复制的错误处理;测试缺口建立源文件与测试文件的映射、检查测试是否只测正常路径、是否被跳过;过时模式比较代码库中多数代码的写法与少数文件的弃用写法;配置债务对照 .env.example 与实际用法、检查冲突配置和硬编码值。

阶段三:量化与评分。 为每项发现指定严重级别和修复工作量。严重级别分为 Critical(正在引发缺陷、安全风险或阻塞升级)、High(很快会造成显著痛苦、会迅速累积)、Medium(真实拖慢开发但不紧急)、Low(改进质量但影响范围小的清理工作)。工作量分为 Trivial(30 分钟以内,如删死代码、清陈旧 TODO、移除未用依赖)、Small(1–4 小时,如抽取重复逻辑、补模块测试、更新依赖)、Medium(1–3 天,如重构复杂模块、跨代码库迁移弃用模式)、Large(1–2 周,如重写上帝类、带破坏性变更的主版本升级)。

阶段四:报告。 按固定结构输出《Technical Debt Audit Report》,包含:执行摘要(项目名称与技术栈、扫描文件数、发现总数、各级别数量、估计总修复工作量、前三优先级);债务热力图(按严重性加权分数排序的文件表,公式为 Critical=8、High=4、Medium=2、Low=1,逐文件求和得到可排序的单一分数);按类别列出的发现(每项包含文件与行号、问题描述、为什么重要、建议修复、工作量);修复计划(立即/本冲刺、短期/未来 2–4 周、中期/下季度、待办积压);指标汇总(每千行标记密度、死代码比例、测试覆盖比例、依赖新鲜度、平均文件大小、最大文件、超过 3 层嵌套的文件数等)。

行为准则

技能要求审计结果具体而非笼统:每条发现都必须引用确切文件和行号。不要报告已有工具能处理的问题(例如项目已配置 eslint 的 no-unused-vars,就不必报告未用变量)。根据项目规模和阶段校准严重程度,不要给周末项目推荐企业级模式。尊重有意的取舍:注释中写明“因某原因故意使用 X”或文档中说明的选型,不应被标记为债务。修复计划是最重要的部分,要现实且排序合理(不要建议先重构被依赖的模块之前去重构依赖它的模块)。报告中的计数必须准确,说“42 项发现”就应恰好有 42 项。

适用场景与限制

适用于在开发新功能前评估技术债务、规划重构优先级、识别依赖升级阻塞风险、为新接手团队梳理代码库状况等场景。注意:该技能本身是提示词/技能定义,实际运行需在支持技能调用的 AI 编程环境中使用;具体的支持平台、配置参数和安装方式暂未提供。报告质量依赖模型对代码库的实际访问和统计能力,行数、文件数等指标需要实际清点而非估计。