cleanup-legacy

用途

cleanup-legacy 用于查找并移除代码库中已废弃、遗留以及零调用方的回退代码路径。它在删除前会通过仓库 grep 与 LSP 验证调用方，并识别不可达的回退分支（例如已翻转的特性开关默认值、针对不再支持运行时的版本检查）。

主要能力

• 检测多语言废弃标记：@deprecated JSDoc/TSDoc、Python 的 # deprecated 注释与 warnings.warn(DeprecationWarning)、Go 的 // Deprecated: 约定、Rust 的 #[deprecated] 属性，以及 legacy/、old/、v1/、_old.ts 等文件/目录命名。
• 读取特性开关配置：100% 开启且无反向测试的开关，其 else 分支可被删除。
• 调用方验证：TS/JS 使用 ts-server / LSP（不可用时回退到 grep）；Python 通过 grep 检查 import。
• 回退分支识别：环境变量恒为 true 的旧分支、版本阈值已提升后的旧分支、针对不支持环境的浏览器/运行时检查。
• 生成评估报告，按 HIGH（零调用方，可安全删除）、MEDIUM（1-5 个调用方，需迁移）、LOW（大量使用，废弃标记可疑）分级。
• 仅自动删除 HIGH 级别项，执行级联清理（删除代码后重新检查其内部辅助函数是否变为死代码，迭代至稳定），并移除已删除分支对应的特性开关声明。
• 单次提交：chore(cleanup): cleanup-legacy — removed N deprecated symbols and M dead branches.
• 验证：运行 bun run check、npx tsc --noEmit、npx eslint .、bun test、pytest、go test ./...、cargo test，以及可选的 bunx knip。验证失败则回滚并降级。

使用方式

该技能以预检、检测、评估、应用、验证、输出为流程。预检包括语言检测、Git 状态检查（脏工作树时拒绝执行）、确保报告目录存在、读取项目使用的废弃标记与特性开关配置。检测阶段使用 grep 与 find 命令收集废弃标记、遗留目录与文件。评估阶段将结果写入 .claude/cleanup-reports/cleanup-legacy-{YYYY-MM-DD}.md，包含摘要、发现项与关键评估。应用阶段仅自动删除 HIGH 级别项。验证阶段运行项目对应的检查与测试命令。输出为删除数量、延迟迁移项数量、报告路径与验证状态。

适用场景

适用于需要清理技术债、移除已废弃代码、删除死回退分支的代码库维护场景，尤其适合有明确废弃标记与特性开关配置的项目。

限制

• 绝不删除仍有调用方的 @deprecated 符号，即使迁移看起来“显而易见”。
• 未检查所有配置环境（.env*、config/*.json、开关服务设置）前，不删除特性开关分支。
• 不删除仍被其他生产代码导入的 legacy/ 目录文件。
• 不删除支持多运行时版本的库中的版本检查分支（如 polyfill）。
• 不删除迁移文件，即使它们“很旧”。
• 不删除针对运行时条件（网络故障、缺失环境变量等）的回退分支。
• 当 CI/CD 或基础设施（Terraform、GitHub Actions、部署脚本）引用特性开关定义时，不自动移除该定义。
• 验证失败时回滚并降级；级联步骤是最可能的失败来源。