用途
Codebase Pruner 用于审计代码仓库中的死代码，评估删除风险，并仅移除高置信度的候选对象，且以小型、可验证的切片方式进行。它强调从真实入口点、配置引用和运行时接线出发进行推理，而不是根据文件名猜测。
主要能力
- 死代码检测：识别未使用的函数、孤立模块、未被引用的导出、过期配置、死路由、遗留适配器、注释掉的代码块、孤立测试、废弃的功能标志、死环境变量等。
- 图感知审计：当存在 codegraph 索引时，使用
codegraph sync、codegraph callers、codegraph node、codegraph impact、codegraph affected等命令辅助识别零调用者符号、孤立模块，并在删除共享符号前评估影响。 - 置信度评分：将候选对象分为 High（零引用、无动态风险、无配置提及）、Medium（零静态引用但附近存在动态模式）、Low（仅有弱证据如字符串提及、文档或命名冲突）。Execute 模式仅自动删除 High 置信度候选。
- 爆炸半径评估：对每个候选对象搜索直接和间接引用，分类为 Zero、Local、Cross-module 或 External。
- 切片式删除：将移除操作表达为小型、有序的切片，每个切片包含窄目标、涉及文件、保留的不变量、验证命令和回滚操作。
- 验证与回滚：每个切片后运行最窄的有用验证（如 lint、类型检查、针对性测试、聚焦构建），失败时仅回滚该切片并报告阻塞。
使用方式
该技能提供四种模式：
- Audit：仅扫描并报告，生成按优先级排序的死代码清单，包含置信度和爆炸半径。这是默认模式。
- Dry-Run：生成删除计划，包含有序切片、回滚点和验证命令，不编辑文件。
- Execute：逐片删除高置信度候选，每片后验证，失败即停止。
- Targeted：将相同工作流限定到文件、目录、模块或子系统。
工作流包括：澄清范围（仅在必要时）、映射活跃入口点、构建引用图、分类候选类型、评估爆炸半径、评分置信度、规划切片、运行删除前检查、执行并验证、清晰总结。
会话和连续性文档存放在仓库根目录的 .safe-code/ 文件夹中，供 Codex、Claude、Cursor 和 Windsurf 等共享。标记但未自动删除的候选会写入 .safe-code/safe-refactor-code.md。
适用场景
- 清理长期积累的死代码，降低维护负担。
- 在重构或迁移前识别可安全移除的代码。
- 审计代码库中未使用的导出、模块、路由和配置。
- 需要小步、可回滚、每步验证的谨慎删除流程。
限制
- 不删除生成的文件，应更新生成器或生成输出流程。
- 不将修剪与无关的功能工作或重构混合。
- 对存在动态分发风险、反射风险或外部集成风险的候选，标记而非自动删除。
- 不删除通过包导出或公共 API 暴露的模块，除非验证消费者风险。
- 不删除由 CI、Docker、cron、部署脚本或运行时配置命名的代码，除非直接检查这些引用。
- 不在验证失败后继续。
- 不假设“今天未使用”就意味着可以安全移除。
- codegraph 没有死代码命令，且 callers 按名称解析，同名方法会合并，因此死方法可能隐藏在活跃同名方法之后；每个候选需用 rg 加阳性对照确认。
- 若 codegraph 不可用、为空或失败，继续使用手动入口点和引用图工作流，不因缺少图数据而降低删除置信度。
- 删除文件时遵循安全不变量：一条 shell 命令一个目的；已跟踪文件用
git rm，未跟踪文件用备份或回收站，绝不使用rm。 - 在可能共享的检出中不使用破坏性 git 操作。
输出示例
Audit 输出包含文档文件夹、映射的入口点数量、扫描的文件数量、按类别和置信度列出的死代码清单、确认死亡总数、疑似死亡总数和建议的下一步。
Dry-Run 输出包含移除计划，每个切片列出文件、不变量、验证命令和回滚操作，以及标记供手动审查的候选。
Execute 输出包含每个切片的完成状态和验证结果，以及移除和标记的总结。