用途
cleanup-codebase 是一个代码简化技能,定位为“局部简洁,被坚决执行”。它针对的是代码的向下腐化:死状态、冗余间接层、投机性仪式代码不断堆积。其做法不是安排专门的清理 PR,而是在你本来就因其他原因要修改某个文件时,顺手移除那些不真正发挥作用的东西。
资料提到两个 2025 年的观点:Kent Beck 的 Tidy First? 与 Casey Muratori 的数据流优先设计启发式,都指向同一结论——嵌入在活跃提交流中的小型、频繁、原子化清理,优于定期安排的“清理 PR”。原因是定时清理会把不相关的关注点捆在一起,变得难以评审;而嵌入式清理的作用域就是手里这个文件,因此保持可评审。
主要能力与准则
资料将以下内容定义为强制规则而非建议:
- 最小化概念、重复与仪式。读者需要记住的每个概念都有成本;每份重复逻辑都有两个地方会漂移;不保护真实边界的包装器、工厂、构建器都是对未来读者的税。减少概念不等于减少行数,而是减少读者需要追踪的不同事物数量。
- 每个契约只有一个真实所有者。不得镜像,不得添加不消除真实耦合的包装器。镜像(两个结构持同一字段、两个服务维护同一缓存状态)是必然的未来缺陷模式;只改名或转发的包装器属于仪式。
- 本地简洁优先于投机抽象。只有当间接层消除现有耦合或保护现有边界时才引入。“以后可能需要”的间接层会让实际的未来变更更难。
- 调用方与被调用方都在本地且无真实边界时,直接同时修改两者。不要为了“保留内部函数接口”而犹豫,内部函数的接口就是它的调用者。
- 在触碰附近代码时移除死代码、字段、配置与陈旧状态。死代码会误导读者、污染 grep 结果、让评审者“以防万一”地保留它。删除应做成独立原子提交,让评审者清楚看到消失的内容。
真实边界的定义
间接层在以下位置才值得存在:公共 API 表面、进程/网络缝隙(RPC、HTTP、队列)、不可信输入边界、异步/同步缝隙、运行时缝隙(FFI、WASM、JNI),以及测试/生产缝隙中 mock 合理替代之处。可替换实现的契约只有在今天就有多于一个真实实现时才算数,而不是“以后可能会有”。不属于边界的情况包括:同一 crate/包内的内部模块、同一文件内的辅助函数、没有防止共同修改约束的跨模块调用。
使用方式
资料给出的工作流:
- 识别候选——在因其他原因进入文件时,发现死代码或冗余代码。
- 确认已死——用
git --no-pager grep -n(或 ast-grep)验证没有消费者;检查测试、文档、配置、错误信息。 - 检查耦合影响——删除是否破坏构建、是否迫使唯一消费者重构;这是单独决策,需记录下来。
- 对照
~/.claude/claude/system-prompt-baseline.md的<git>章程——清理是独立原子提交;若与行为变更混在一起,用git move --fixup/git split拆分。 - 执行删除——用
git rip删除文件,或用精确 Edit 做局部移除;绝不要注释掉。 - 验证——构建、测试、类型检查仍然通过。如果某个测试是死代码的唯一消费者,该测试很可能在测试死代码。
- 搜索幽灵——检查文档、错误信息、配置键、环境变量、日志行中提及被移除概念的字符串引用。
决策规则要点
资料给出了一张模式与动作的对照表,内容包括:只改名的包装器应内联后删除;构造函数中设置但从未读取的字段应删除;两个分支都已死亡的配置开关应删除并保留胜出路径;结构等价的本地类型之间的适配器应合并为一个类型;真正命名共享概念且被 3 处以上使用的辅助函数应保留;只在一处使用且包装两行代码的辅助函数应内联;跨两个服务/结构镜像的状态应选定一个所有者;与代码矛盾的注释应更新或删除;超过 6 个月的 TODO 应开 issue 或删除。
适用场景
- 为不相关功能编辑 foo.py 时,读到文件里有个死字段。
- 某次重构提交刚移除一条代码路径,残留的包装器、死分支或过期开关应随之离开。
- 评审 PR diff 时发现新增了不必要的包装器或重复状态,标记并请求就地简化。
- 新人熟悉代码库时,标出候选供原作者确认为死代码。
限制与不适用场景
- 独立的“清理扫荡” PR——会混合不相关变更、难以评审,并违反“一次提交一个关注点”。
- 你本来没有触碰的文件——机会性编辑会变成不可评审的噪音;清理必须搭载在让你进入该文件的工作上。
- 无法证明安全的投机性删除——若不能 grep 确认无人读取某字段,不要删除,先调查。
- 公共 API 表面——属于兼容性重构的范畴,需要迁移计划。
强制规则与验证
资料列出三条不可协商的规则:不得把清理与行为变更捆绑在同一提交;清理期间不得新增抽象;不得把清理扩展到活跃变更已触碰文件之外。
验证门槛包括:原子提交(独立于行为变更)、死确认(grep/ast-grep 确认代码、测试、文档、配置中无消费者)、不新增抽象(diff 仅为净删除或内联后删除)、构建与测试通过、幽灵搜索(文档、错误信息、环境变量中无残留引用)。
资料还给出退出码:0 表示干净落地;11 表示 grep 之外发现消费者;12 表示构建/测试回归需回滚;13 表示混合关注点提交需拆分;14 表示引入了新抽象;15 表示发现幽灵引用、清理不完整。
暂未提供的信息
资料未说明该技能的安装方式、支持的具体平台、收费情况或性能数据。