SuperAPI AI 工具集

scan-codebase-health

编程与开发

查看项目

更新于 11-06 09:09

技能介绍

用途

scan-codebase-health 是一个代码库健康扫描技能文档,目标是在 AI 辅助开发的代码库中检测结构性腐化,包括死代码、文档计数漂移、孤儿文件、过期配置引用、死特性开关和失效交叉引用,最终输出带证据的维护建议。

主要能力

该技能按阶段执行以下检测:

  1. 分类与工具检测:读取 docs/project-config.json 的 codebaseHealth 段(sourcePaths、docPaths、configPatterns、excludePaths),检测可用工具以决定启用哪些阶段。
  2. 文档计数漂移检测:扫描 docs/ 及 .claude/**/*.md、AGENTS.md、CLAUDE.md 等指令面中的数字声明(N files、N tests、N hooks 等),与实际文件系统计数比对。
  3. 过期配置引用检测:提取配置文件中引用的类名、模块名、连接字符串,用 grep 验证是否仍存在。
  4. 未使用导出检测(需 .code-graph/graph.db):通过 python .claude/scripts/code_graph query importers_of <symbol> --json 查找零导入者的导出符号。
  5. 孤儿文件检测(需 graph.db):查找零入边的源文件。
  6. 模式漂移检测:跨服务/模块比较同类模式(如仓储注册、服务配置、错误处理)的一致性。
  7. 死特性开关检测:对比配置与代码中的特性开关使用情况。
  8. 失效交叉引用检测:验证文档中的 Markdown 链接与 file:line 引用目标是否存在。
  9. 全新视角复核与报告生成:子代理抽查发现、验证 file:line 证据,报告写入 tmp/reports/codebase-health-scan-{YYMMDD}.md。

使用方式

按文档描述,执行流程为:分类范围与工具 → 运行七类检测 → 全新视角复核 → 生成报告 → 呈现带严重级别的可执行摘要。开始前需用 todo 跟踪把工作拆分为每阶段一个小任务。依赖 graph.db 的阶段缺失时记录跳过原因而非静默省略;特性开关、CI 等阶段依赖检测到的模式。报告每条发现必须带 file:line 证据,并按 HIGH(运行时失败风险)、MEDIUM(漂移/死代码)、LOW(清理候选)分级;计数漂移阈值:≤10% 为 LOW,>10% 且 ≤30% 为 MEDIUM,>30% 为 HIGH。复核为强制性步骤,最多三轮,误报率超 30% 升级给用户。文档还包含 review-policy、output-quality-principles 等协议的引用说明。

适用场景

适用于维护 AI 辅助开发的代码库,定期检查文档计数是否与实际工件同步、配置是否引用已删除工件、是否存在死代码与孤儿文件等。

限制

未使用导出与孤儿文件检测依赖 .code-graph/graph.db,缺失时相应阶段跳过;特性开关检测依赖发现已知模式;CI 健康检测为可选。文档未提供具体安装命令、收费信息或平台要求,暂未提供。