codebase-cleanup

代码库清理 — 8 轮重构

针对代码库进行 8 轮相互独立的专项检查，每轮专注于一个质量方面。建议将每轮作为单独的子 Agent 会话运行（也可以在一个会话中依次运行），这样每轮都能获得干净的上下文窗口，也不会越界干扰其他轮次。

每轮都遵循相同的三阶段流程，详见 reference/protocol.md。建议的轮次顺序及原因见 reference/pass-ordering.md。

始终遵循 codebase-design：将每项能力归于一处，提供完整的操作，并且只在拆分能够隐藏复杂性或实现有用复用时才进行提取。保留已配置的行数限制，并对有记录的针对性例外予以保留。文件数量和净删除行数都不是目标。

适用场景

• “清理代码库”／“处理一轮技术债”
• “发布前为代码库做质量重构”
• “查找并移除死代码／AI 垃圾代码／薄弱类型”
• 熟悉一个代码库，并想了解哪些部分真正承担关键职责
• 1.0 版本或正式发布前的质量检查
• 定期（每季度）进行代码卫生检查

不适用场景

• 范围狭窄的定向需求（“移除这个函数”“修复这个类型”）
• 开发全新功能
• 截止时间紧迫／只需最小可行修复的场景——这是一项需要审慎进行的全面检查
• 正由人工进行大规模重构的代码库（这些检查会与进行中的工作冲突）

8 轮检查

按此顺序运行（原因见 reference/pass-ordering.md）。每项都链接到完整的子 Agent 提示词：

1. AI 垃圾代码和过时注释 → reference/passes/01-ai-slop.md 移除生成的噪声、描述进行中工作的注释、装模作样的内容和无用的模板代码。
2. 遗留／已弃用／回退代码 → reference/passes/02-legacy-removal.md 移除死分支、已弃用的 API，以及不再回退到任何仍在使用的内容的回退路径。
3. 未使用的代码 → reference/passes/03-unused-code.md 进行 knip 类分析：找出没有被导入的导出项／文件／依赖项。
4. 循环依赖 → reference/passes/04-circular-deps.md 进行 madge 类分析：理顺导入循环。
5. 薄弱类型 → reference/passes/05-weak-types.md 通过研究结果作为依据，将 any／unknown／Object／dynamic／interface{} 替换为真实类型。
6. 类型整合 → reference/passes/06-type-consolidation.md 查找并统一重复或近乎重复的类型定义。
7. 防御式编程 → reference/passes/07-defensive-programming.md 移除无法处理真实输入边界的 try/catch 和空值保护。
8. DRY／去重 → reference/passes/08-dry.md 仅在能够降低复杂性（而非增加复杂性）时整合重复逻辑。

工具

每轮检查规范都会列出所需工具（knip、ts-unused-exports、madge、jscpd、特定语言的代码检查工具等）。此技能不附带脚本——编排工作由调用方的 Agent 运行时负责，该运行时已具备 bash/edit/grep 等工具。

参考资料

• reference/protocol.md — 每轮检查都遵循的三阶段研究／评估／实施流程
• reference/pass-ordering.md — 此顺序的原因，以及哪些检查可以并行运行
• reference/passes/*.md — 每轮检查各自独立的子 Agent 提示词