SuperAPI AI 工具集

codebase-hygiene

编程与开发

查看项目

更新于 10-31 03:57

技能介绍

Codebase Hygiene 是一个面向代码库治理的只读诊断技能,包含两种工作模式,输出为诊断与候选建议,不直接修改代码。

一、用途

技能定位为“建议型、重读取”的诊断工具:负责发现问题并提出方案,不执行重构。任何实际改动都需通过 BUILD 流程并经过完整关卡。

二、模式一:重复检测

语义重复指功能相同但以不同名称独立实现的函数。复制粘贴检测器只能发现语法层面的重复,本模式寻找“意图相同、实现不同”的重复。

方法步骤:

  1. 先定范围:采用用户指定的目标;否则用 git log --oneline 找热点,并对近期变更的代码加权。
  2. 提取目录:用 Grep/Glob 查找导出函数,记录名称、文件行号、签名。
  3. 按领域分类:如校验、格式化、路径操作、HTTP 构造、日期处理等,通过机械分桶缩小比较空间。
  4. 丢弃函数少于 3 个的类别。
  5. 逐类检测重复:阅读实现、判断是否共享意图。检测阶段不得使用廉价模型层,以免受名称锚定而误判“看起来不同”。
  6. 输出发现:按置信度从高到低分组,每条包含重复内容、影响、修复建议及文件行号证据,并走 code-reviewer 的发现契约。

高风险区域包括:utils/helpers/lib 等杂物堆放处、校验代码、错误格式化、路径操作、字符串格式化、日期格式化、API 响应构造。

合并纪律:删除重复实现前必须同时满足三项条件——保留者有测试(若都无测试,先为选定的保留者写测试)、所有调用方已更新(用 Grep 枚举调用方)、合并后重跑测试套件与构建/类型检查并通过。

三、模式二:模块深化

针对代码可用但结构不佳的情况。LLM 生成的代码库容易积累浅模块:薄包装、透传层、近似重复的辅助函数。每个看似无害,合起来却把复杂度扩散到所有调用方。

深模块:以小接口隐藏大量行为。浅模块:接口复杂度接近实现本身,调用方学了东西却收益甚微。

删除测试:对每个候选模块,设想删除它并把代码内联到所有调用点,看复杂度去向。复杂度消失说明是透传/浅模块,属于深化候选(删除或加深接口);复杂度在 N 个调用点重现说明是深模块,应予保留。

典型气味与判断:薄包装、透传层、近似重复辅助函数通常为浅;配置/杠杆模块(小接口内含分支、重试、状态)为深,应保留。

诊断流程(只读):枚举导出面、标记浅形态、交叉引用近似重复(先跑重复检测模式,先合并再深化)、对每个存活者跑删除测试、输出候选列表而非重构。

提出接口前先呈现候选,并打标签:Strong(明确)、Worth-exploring(有真实成本/风险)、Speculative(猜测、低置信)。每个候选给出前后草图与删除测试结果,然后停下询问用户选择哪个,不为未选中的候选设计接口。

四、接缝放置的两适配器规则

设计更深接口时,端口(注入的外部依赖接缝)需要两个具体适配器,例如生产传输与测试替身。普通调用方或测试公开接口不算适配器;两适配器规则针对端口,而非所有接缝。对于非端口接缝(模块深化的常见情况):测试必须能触达该接口。若只有生产代码穿过接缝而无测试可达,则该接缝只是猜测,应把接口放在测试可达处或不引入。

五、交接

本技能止于:选定候选 + 更深接口提案 + 命名接缝。不编辑代码。重构走 planner → BUILD 工作流(builder → reviewer → verifier → doc-sync → memory)。深化需验证:保留者接口在其接缝处有测试、每个调用方已重新指向、合并后测试套件与类型检查通过。提出是只读的,修改是受关卡控制的。

六、限制

该技能仅做诊断与建议,不执行任何重构或代码修改;需要实际改动时必须走 BUILD 流程。