clean-ai-slop

AI 赘余清理器

一种用于清理 AI 生成代码的纠偏规范。在代码生成后运行——无论代码来自 run-plan、手动会话还是其他来源。

核心问题：大模型生成的代码虽然能运行，却带有明显的异味。注释过多、不必要的抽象、对不可能场景的过度防御，以及冗长的命名。如果放任不管，这些问题会不断累积，使代码库比手写代码更难阅读和维护。

此技能会按类别逐一系统性地清除这些异味，同时不改变行为。

硬性关卡

这些规则没有例外。

1. 清理前锁定行为。 运行现有测试。如果覆盖不足，就为即将修改的代码添加回归测试。没有测试覆盖，就不进行清理。
2. 每轮只处理一类异味。 不要把死代码清理和命名修正混在一起。完成一轮并验证后，再开始下一轮。
3. 每轮后都运行测试。 如果测试失败，撤销本轮修改并调查原因。不要继续处理下一类。
4. 限定范围。 只修改 AI 生成或修改过的文件。不要扩展到看起来也可以改进的“周边”代码。
5. 原样保留行为。 如果清理改变了可观察到的行为——即使你认为新行为“更好”——也要撤销修改。行为变更需要单独处理。

适用场景

• run-plan 完成后，实现可用但读起来像是 AI 写的
• 任何重要的代码生成会话之后
• 审查 AI 生成的 PR 时
• 用户明确要求清理或去除代码中的 AI 赘余时

不适用场景

• 人工编写的代码（异味不同，处理方式也不同）
• 测试不存在且无法快速补充时（先锁定行为）
• 实现过程中——先完成功能，再进行清理

异味类别

按以下顺序执行各轮。每轮都必须完整结束后，才能开始下一轮。

第 1 轮：死代码

删除没有用途的代码。

• 未使用的导入
• 未使用的变量和参数
• 无法到达的分支
• 注释掉的代码块
• 会吞掉异常的空错误处理器

检测方式：编译器警告、代码检查器输出、IDE 中灰显的符号。相信工具的判断。

第 2 轮：注释过多

删除重复说明代码已有含义的注释。

目标：

• let counter = 0 上方的 // Initialize the counter
• return result 上方的 // Return the result
• 没有额外说明的、重复函数签名的 JSDoc
• 不提供信息的分隔注释（// --- Helper Functions ---）
• 描述文件名已明确内容的文件头注释

保留：解释原因而非内容的注释、说明非显而易见约束的注释，以及指向外部文档或问题的链接。

第 3 轮：不必要的抽象

删除没有实际用途的间接层。

目标：

• 只调用一次的辅助函数（将其内联）
• 所有操作都委托给一个内部对象的包装类
• 永远不会需要配置的配置对象
• 总是生成相同内容的工厂函数
• 只有单个实现使用且没有新增实现计划的接口／类型定义

判断标准：如果删除抽象后代码更短，且可读性不变，那么这个抽象就是不必要的。

第 4 轮：过度防御

删除对不可能发生的情形所做的错误处理。

目标：

• 对类型系统保证非空的值进行空值检查
• 对不会抛出异常的代码使用 try-catch 块
• 验证内部函数参数（只在系统边界处进行验证）
• 为必填字段设置回退值
• 冗余的类型断言

保留：系统边界处的验证（用户输入、外部 API、文件 I/O），以及运行时确实可能失败时的错误处理。

第 5 轮：冗长命名

缩短包含冗余信息的名称。

目标：

• getUserDataFromDatabase → getUser（数据还能从哪里来？）
• userAccountStatus → status（在 User 类中使用时，前缀是多余的）
• handleButtonClickEvent → onClick
• responseDataObject → response
• tempVariableForCalculation → temp 或直接内联

规则：名称应尽可能短，同时在其作用域内保持明确。作用域越大，名称越长；作用域越小，名称越短。

第 6 轮：大模型赘语

移除大模型生成风格的痕迹。

目标：

• 代码、注释或提交消息中的表情符号（除非项目有意使用）
• 注释中的对话式语气（“我们来……”“现在我们需要……”“太好了！”）
• 为“调试”而添加的过多 console.log / print 语句
• 可通过类型推断得出的冗余类型注解
• 过度结构化、遵循模板模式而非问题自然形态的代码

流程

1. Identify scope (which files to clean)
2. Run existing tests — all must pass before starting
3. Add regression tests if coverage is thin
4. Execute Pass 1 → verify → commit
5. Execute Pass 2 → verify → commit
6. ... continue through all relevant passes
7. Run full test suite
8. Report summary of changes

并非每一轮都适用于每个代码库。没有发现问题的轮次可以跳过。但必须按顺序执行，绝不可跳过前面的轮次。

反模式

想法	失败原因
“我要一口气清理所有内容”	测试失败时，混杂的改动难以调试
“这个抽象不好，我来重新设计”	重新设计是单独的任务，不属于清理
“测试通过了，所以我跳过每轮验证”	后续轮次可能会与前面的改动相互影响
“附近这段代码看起来也很糟糕”	范围蔓延。只清理范围内的内容
“反正行为本来就不对，我顺便在清理时修掉”	行为变更需要单独的任务和测试
“不用回归测试，这段代码很简单”	简单代码也会出问题。先锁定行为

警示信号

如果发现自己在想以下内容，请停下来重新考虑：

• “这花的时间太久了，我把剩下的轮次一起处理吧”
• “我顺手再快速修一下另一个文件”
• “测试应该没问题，不用再跑一遍”
• “这个行为本来就应该有所不同”
• “这不需要测试，只是删除注释而已”

完成标准

满足以下条件时，清理才算完成：

• 已按顺序执行所有适用的轮次
• 每轮单独执行后，测试均通过
• 最终完整测试套件通过
• 行为没有发生变化
• 改动仅涉及已确定的文件

如果有任何一项不满足，清理就尚未完成。

最简检查清单

清理期间，请根据以下清单进行核对：

• 开始前已通过测试锁定行为
• 当前轮次仅针对一种代码异味
• 当前轮次完成后测试通过
• 未触及既定范围之外的文件
• 未改变任何行为

后续步骤

清理完成后：

• 如果代码由 run-plan 生成 → 向用户报告结果
• 如果生成过程中缺乏实现纪律 → 考虑在未来会话中应用 karpathy，从源头避免产生劣质代码