SuperAPI AI 工具集

ultra-clean

编程与开发

查看项目

更新于 10-16 07:00

技能介绍

用途

Ultra Clean 用于把宽泛的代码库清理请求转化为有纪律的审计加实施过程。其默认策略是证据优先、删除其次、抽象最后。除非用户明确要求产品变更,否则清理被视为保持行为的重构工作。

核心规则

  • 在编辑任何内容之前先建立仓库上下文:结构、语言、包管理器、验证命令、生成代码、框架入口点和公共接口。
  • 运行八条清理通道。如果平台限制并发子代理数量,可以分批运行,但保持通道边界完整。
  • 每条通道必须产出:批判性评估、具体证据、建议集合、已实施的高置信度修复、验证说明。
  • 只实施高置信度改动。中置信度想法记录在报告中,但不改动代码。
  • 优先删除而非抽象,优先简化而非取巧。
  • 删除或合并时绝不只依赖单一信号,需用代码搜索、运行时入口点、测试和公共 API 表面交叉验证工具输出。
  • 不要回退无关的用户改动,以当前工作树为准。

执行工作流

  1. 建立基线。
  2. 每条通道生成一个子代理。可用时,研究使用探索型代理,隔离编辑使用工作型代理。
  3. 每条通道先收集证据,再在编辑前写出批判性评估和建议。
  4. 在实施前集中合并重叠发现,尤其是共享类型、未使用代码、回退移除和循环依赖破除方面。
  5. 按通道或小批量集成方式实施高置信度改动。
  6. 每个有意义的批次后运行聚焦验证,最后运行仓库级验证。
  7. 报告改动了什么、有意保留了什么、以及哪些仍有风险。

基线检查

在通道工作开始前:

  • 映射仓库,忽略生成、第三方、编译或外部镜像内容。
  • 确定规范验证命令:测试、lint、类型检查、构建以及任何框架特定检查。
  • 在删除任何内容前,识别反射式或非显而易见的入口点:
    • Next.js 页面、API 路由、加载器、基于配置的钩子
    • CLI 命令注册表
    • 依赖注入容器
    • 插件系统
    • 基于字符串的导入或运行时解析
    • 序列化器、迁移、RPC 处理器、任务运行器
  • 标记高风险边界:
    • 公共 API
    • 持久化模式
    • 网络输入/输出
    • 认证与权限检查
    • 错误边界
    • 跨包契约
  • 在协调通道前阅读 references/baseline.md 和 references/report-template.md。

通道职责

运行全部八条通道:

  1. 仅在 DRY 能降低复杂度时去重与合并代码。参考:references/lane-1-dedupe.md
  2. 合并共享类型定义与契约。参考:references/lane-2-shared-types.md
  3. 在工具辅助确认下移除可证明未使用的代码。参考:references/lane-3-unused-code.md
  4. 以最小架构移动破除循环依赖。参考:references/lane-4-circular-deps.md
  5. 用经过研究的强类型替换弱类型。参考:references/lane-5-strong-types.md
  6. 移除不必要的 try/catch 和防御性回退逻辑。参考:references/lane-6-error-handling.md
  7. 删除已弃用、遗留、兼容性和回退路径。参考:references/lane-7-legacy-code.md
  8. 移除 AI 废话、桩代码、装样子代码和无用注释。参考:references/lane-8-comment-hygiene.md

建议通道顺序

除非仓库暗示更好的顺序,否则使用以下默认顺序:

  1. 基线与验证发现
  2. 通道 4:循环依赖
  3. 通道 2:共享类型
  4. 通道 5:强类型
  5. 通道 1:去重与合并
  6. 通道 3:未使用代码
  7. 通道 7:遗留与回退移除
  8. 通道 6:防御性错误处理清理
  9. 通道 8:注释与废话清理

理由:

  • 循环依赖扭曲导入边界,常阻碍最干净的去重或类型改动。
  • 共享类型应在强类型化和重复清理产生新契约之前先稳定下来。
  • 未使用代码与遗留代码移除高度重叠,应协调而非重复。
  • 注释清理通常最后进行,以反映最终代码。

子代理指导

委派时:

  • 给每个子代理单一通道和清晰范围。
  • 要求证据,而非意见。
  • 使用工作型代理时保持写入范围互不重叠。
  • 如果下一步本地操作立即依赖当前阻塞项,不要将其移交出去。
  • 如果只有六个并发子代理可用,先运行六条通道,等一两个完成后,再启动剩余通道。
  • 如果两条通道提出冲突编辑,先在本地解决契约,再让更多编辑落地。

证据标准

只有当建议具备该通道足够的证据时,才算高置信度:

  • 代码搜索确认使用形态
  • 相关时工具输出支持发现
  • 已检查入口点和运行时注册
  • 存在测试或类型覆盖,或存在直接验证路径
  • 改动简化代码且不会静默扩大行为

如果缺少任何一项,将建议保留在报告中,但不实施。

交付物

每条通道产出:

  • 当前状态的批判性评估。
  • 分为高、中、低置信度的建议列表。
  • 仅实施高置信度改动。
  • 验证摘要,包含运行的命令和剩余缺口。

默认使用 references/report-template.md 作为报告格式。

验证

在两个层面验证:

  • 每条通道或批次后的本地验证:针对性测试、类型检查、lint、聚焦运行时检查。
  • 集成后的最终验证:完整仓库测试或可用的最强等效验证。

如果验证不完整,不要声称仓库“干净”。准确说明已验证和未验证的内容。

参考资料

  • references/baseline.md:仓库设置、清单和安全门禁
  • references/report-template.md:标准输出结构
  • references/lane-1-dedupe.md
  • references/lane-2-shared-types.md
  • references/lane-3-unused-code.md
  • references/lane-4-circular-deps.md
  • references/lane-5-strong-types.md
  • references/lane-6-error-handling.md
  • references/lane-7-legacy-code.md
  • references/lane-8-comment-hygiene.md