用途
Ultra Clean 用于把宽泛的代码库清理请求转化为有纪律的审计加实施过程。其默认策略是证据优先、删除其次、抽象最后。除非用户明确要求产品变更,否则清理被视为保持行为的重构工作。
核心规则
- 在编辑任何内容之前先建立仓库上下文:结构、语言、包管理器、验证命令、生成代码、框架入口点和公共接口。
- 运行八条清理通道。如果平台限制并发子代理数量,可以分批运行,但保持通道边界完整。
- 每条通道必须产出:批判性评估、具体证据、建议集合、已实施的高置信度修复、验证说明。
- 只实施高置信度改动。中置信度想法记录在报告中,但不改动代码。
- 优先删除而非抽象,优先简化而非取巧。
- 删除或合并时绝不只依赖单一信号,需用代码搜索、运行时入口点、测试和公共 API 表面交叉验证工具输出。
- 不要回退无关的用户改动,以当前工作树为准。
执行工作流
- 建立基线。
- 每条通道生成一个子代理。可用时,研究使用探索型代理,隔离编辑使用工作型代理。
- 每条通道先收集证据,再在编辑前写出批判性评估和建议。
- 在实施前集中合并重叠发现,尤其是共享类型、未使用代码、回退移除和循环依赖破除方面。
- 按通道或小批量集成方式实施高置信度改动。
- 每个有意义的批次后运行聚焦验证,最后运行仓库级验证。
- 报告改动了什么、有意保留了什么、以及哪些仍有风险。
基线检查
在通道工作开始前:
- 映射仓库,忽略生成、第三方、编译或外部镜像内容。
- 确定规范验证命令:测试、lint、类型检查、构建以及任何框架特定检查。
- 在删除任何内容前,识别反射式或非显而易见的入口点:
- Next.js 页面、API 路由、加载器、基于配置的钩子
- CLI 命令注册表
- 依赖注入容器
- 插件系统
- 基于字符串的导入或运行时解析
- 序列化器、迁移、RPC 处理器、任务运行器
- 标记高风险边界:
- 公共 API
- 持久化模式
- 网络输入/输出
- 认证与权限检查
- 错误边界
- 跨包契约
- 在协调通道前阅读 references/baseline.md 和 references/report-template.md。
通道职责
运行全部八条通道:
- 仅在 DRY 能降低复杂度时去重与合并代码。参考: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
- 移除不必要的 try/catch 和防御性回退逻辑。参考:references/lane-6-error-handling.md
- 删除已弃用、遗留、兼容性和回退路径。参考:references/lane-7-legacy-code.md
- 移除 AI 废话、桩代码、装样子代码和无用注释。参考:references/lane-8-comment-hygiene.md
建议通道顺序
除非仓库暗示更好的顺序,否则使用以下默认顺序:
- 基线与验证发现
- 通道 4:循环依赖
- 通道 2:共享类型
- 通道 5:强类型
- 通道 1:去重与合并
- 通道 3:未使用代码
- 通道 7:遗留与回退移除
- 通道 6:防御性错误处理清理
- 通道 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