用途
hyper-cleanup 是用于“已经能正常工作”的代码库的清理技能,目标是产出行为保持型清理:更少的代码、更少的测试、更少的注释、更少的间接层,同时保持可观察行为和公共接口不变。触发场景包括要求清理、简化、去重、删除死代码,或删除无意义测试。
不适用于:新增行为、新文件或新公共 API;刻意改变签名、错误类型或模块边界的重构;依赖升级、锁文件变更或迁移;全仓库格式化、lint 自动修复或无逐片段推理的重命名;有明确目标的性能优化或基准比较;提交、推送、拉取请求或发布说明。
主要能力
- 按范围进入模式:请求指定文件或目录时进行范围清理;未指定路径时以当前 diff 为范围;仅要求“找出可删除内容”而不授权修改时进入“仅发现”模式。
- 行为锁:首次编辑前运行项目自身的相关命令,记录确切命令与结果;基线中已失败的项单独列出,不参与后续证明。
- 分类与证明:每个在范围内的单元要么归入具名类别并提供证明,要么作为保留项记录理由;没有证明的候选保持不动。
- 四级阶梯:每个单元依次考虑删除、复用、使用平台能力、原地简化;一次运行没有删除任何内容也是有效结果。
- 测试台账与变异证明:对测试文件中的每个声明做标记,对删除或合并的测试要求有“保留者”或类别证明,并用源码变异测试给出结论;每次变异后按字节恢复源文件,用 SHA-256 比对确认。
- 片段级纠错:门禁失败时在导致失败的片段处修正,并说明机制;同一片段两次修正失败则回滚该片段并记录为保留代码。禁止用整文件 checkout/restore/reset 回滚。
- 报告:生成 .hyper/cleanup/<slug>.md,包含范围、行为锁与基线红项、阶梯表、移除片段表、测试台账、检查表、保留代码说明,并以恰好一行 Result: 结尾,取值为 clean、no-change、awaiting_input 或 blocked。
使用方式
核心文件 SKILL.md 定义触发、模式、契约、流程与终止条件。配套规则文件分工:categories.md 负责九个类别、KEEP 例外及每项移除所需证明;existence-ladder.md 负责四级阶梯及删除需证明的内容;behavior-lock.md 负责基线记录与可观察行为定义;test-junk.md 负责测试标记、垃圾类别、保留标准、台账及两个脚本接口;correction-and-report.md 负责片段级纠错、两次尝试上限、报告布局和终止状态。脚本方面,scripts/scan-test-junk.sh 以 --json 和 --self-test 列出静态测试候选;scripts/mutation-proof.sh 应用一次文本变异、运行测试命令、恢复文件并报告 caught 或 survived。资源 assets/evals/hyper-cleanup-cases.jsonl 为触发与行为用例。
流程为:确定范围并记录基线提交与工作区状态;运行行为锁;分类每个单元;在阶梯上放置单元并只执行证明成立的裁剪;对测试文件做标记与变异证明;重跑同一命令并在片段处修正或回滚;审阅完整 diff;撰写报告。
适用场景
- 清理 AI 生成痕迹明显但功能正常的文件,行为保持不变。
- 删除 src/pricing/ 中无调用的辅助函数并证明无人调用。
- 删除永远不可能失败的测试,同时保留真正守护契约的测试。
- 合并模块中重复分支,测试仍全部通过。
- 清理 lib/parse 中过多注释而不改代码。
- 整理重复测试并用变异证明删除合理。
限制
仅在获得授权的文件或当前 diff 范围内编辑;安全裁剪需要触及范围外文件时只报告不扩大。不得删除基线中已失败的测试或修改其期望使其通过;不得放宽快照或断言以认可清理带来的行为变化;不得在未证明外层边界覆盖的情况下移除守卫、校验或 catch;不得在清理中安装依赖或更改锁文件;不得提交、推送、合并或写入生产目标。默认交付语言为韩语,用户明确要求时可改用其他语言。