ECC 死代码清理实战指南用 /refactor-clean 在测试验证下安全删除无用代码【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC导读本文将系统讲解 ECCEngineer Command Center提供的/refactor-clean命令如何在每一步都经过测试验证的前提下安全识别并删除项目中的死代码dead code、重复代码与未使用依赖。你将在文中掌握 knip、depcheck、ts-prune 等多语言死代码检测工具的组合用法、SAFE/CAUTION/DANGER 三级风险分层方法以及一次一删、测试先行、失败即回滚的原子化清理循环并了解 ECC 中该命令与 refactor-cleaner 专用 Agent 的协作机制可直接套用于实际代码库的清理工作。命令定位ECC 的死代码清理入口在 ECC 的命令体系中/refactor-clean是一条面向代码库清理的斜杠命令。根据 docs/COMMAND-AGENT-MAP.md 的命令映射表/refactor-clean的主执行者是refactor-cleaner专用 Agent用途为 Dead code removal死代码移除。在项目根目录 README.md 中它被列为 Cleaning a codebase代码库清理场景的推荐命令并在 README.md 中与 refactor-cleaner 绑定出现。从命令注册信息看docs/COMMAND-REGISTRY.json 将refactor-clean归类为type: testing类型描述为 Safely identify and remove dead code with verification after each change.在每次变更后通过验证安全识别并删除死代码——这印证了该命令的核心属性清理不是凭直觉的删除而是以测试为验收标准的受控过程。配套的 agents/refactor-cleaner.md 将 Agent 的职责定义为四项死代码检测、重复代码消除、依赖清理与安全重构其核心使命就是找出并删除未使用的代码、重复项与未使用的导出。该 Agent 拥有 Read、Write、Edit、Bash、Grep、Glob 工具默认使用 sonnet 模型。第一步按项目类型检测死代码/refactor-clean的第一步是运行死代码分析工具。命令文档根据项目技术栈给出了工具选型表需要原样继承并正确使用工具查找内容命令knip未使用的导出、文件、依赖项npx knipdepcheck未使用的 npm 依赖项npx depcheckts-prune未使用的 TypeScript 导出npx ts-prunevulture未使用的 Python 代码vulture src/deadcode未使用的 Go 代码deadcode ./...cargo-udeps未使用的 Rust 依赖项cargo nightly udeps其中前三项knip、depcheck、ts-prune是 JS/TS 生态的主推组合也与 agents/refactor-cleaner.md 中 Agent 的检测命令清单一一对应。该 Agent 的 Detection Commands 还额外补充了一条npx eslint . --report-unused-disable-directives # 未使用的 eslint 禁用指令这条命令用于发现代码中被声明但从未触发的eslint-disable注释属于检测的第四种武器。Agent 的工作流建议将这些检测工具并行运行一次性获得全面清单而不是逐个串行等待。如果项目中没有可用的分析工具命令文档提供了兜底方案用 Grep 查找零次导入的导出——即先通过正则找出所有export声明再逐一搜索这些标识符是否在代码库中被import引用对于没有导入记录的可疑导出再人工确认是否为公共 API 或存在字符串形式的动态引用。这一兜底手段虽然原始但在无工具可用的环境下依然有效。第二步生成报告并按安全层级分类检测结果需要落盘为可追溯的报告commands/refactor-clean.md 指定输出到.reports/dead-code-analysis.md形成一份全面的死代码分析文档供后续清理决策与复盘使用。随后将所有发现按删除风险分为三个安全层级层级示例操作SAFE安全未使用的工具函数、测试辅助函数、内部函数放心删除CAUTION谨慎组件、API 路由、中间件验证没有动态导入或外部使用者DANGER危险配置文件、入口点、类型定义在操作前仔细调查这套分层的思想核心是导出面越宽、被引用方式越隐蔽删除风险越高。未使用的内部工具函数删除风险极低而组件、API 路由、中间件这类对象常被框架以约定/字符串方式隐式加载工具无法静态感知配置文件与入口点更是整个应用的生命线。refactor-cleaner Agent 使用了几乎等价的三级描述——SAFE未使用的导出/依赖、CAREFUL动态导入、RISKY公共 API并在其工作流的 Analyze 阶段要求并行运行检测工具后立即按风险分类。第三步SAFE 项的安全删除循环对于每个 SAFE 层级的项目命令文档规定了一套原子化删除循环这也是整个/refactor-clean最核心的纪律运行完整测试套件—— 先建立全绿基线删除死代码—— 使用编辑工具进行外科手术式的精确删除重新运行测试套件—— 验证没有破坏任何功能如果测试失败—— 立即使用git checkout -- file回滚并跳过此项如果测试通过—— 继续处理下一项这个循环的每一步都有明确的验收标准删除前先测确认基线删除后再测确认无回归失败即回滚保证任何时刻代码库都处于可运行状态。refactor-cleaner Agent 将这条纪律进一步细化为一次只处理一个类别按 依赖 → 导出 → 文件 → 重复项 的顺序逐批删除每批之后运行测试并提交且每次提交附带描述性提交信息。这既保证了回滚的粒度也让清理历史清晰可审计。第四步处理 CAUTION 项CAUTION 层级的项目不能直接删除命令文档要求在动手前完成四项核查搜索动态导入import()、require()、__import__——这些调用无法被静态分析工具感知删除后可能在运行时才暴露问题搜索字符串引用配置中的路由名称、组件名称——框架常通过字符串约定注册路由或组件检查是否从公共包 API导出——若该包已发布导出即契约验证没有外部使用者——如果包已发布需检查下游依赖方dependents。refactor-cleaner Agent 的 Verify 阶段与此呼应对每个待删除项先 Grep 全部引用包括通过字符串模式出现的动态引用再确认是否属于公共 API并通过 git 历史了解该代码的上下文——历史提交往往能揭示一段看似无用代码曾被移除后又被恢复的教训。第五步合并重复项死代码清除完毕后/refactor-clean还承担重复项整合的职责。命令文档列出四类典型目标近似重复的函数80% 相似—— 合并为一个冗余的类型定义—— 整合没有增加价值的包装函数—— 内联它们没有作用的重新导出—— 移除间接引用refactor-cleaner Agent 对重复组件/工具函数的整合流程是找出重复实现 → 挑选最完整、测试覆盖最好的那个作为保留版本 → 更新所有导入点并删除其余重复项 → 运行测试确认通过。值得注意的是命令文档特别强调清理时不重构见下文规则即删除重复代码属于清理范畴而重写逻辑属于重构范畴两者必须分阶段进行避免在清理过程中引入行为变更。第六步输出清理总结清理完成后命令文档给出了标准的报告模板用于汇总成果与未决项无用代码清理 ────────────────────────────── 已删除 12 个未使用函数 3 个未使用文件 5 个未使用依赖项 已跳过 2 个项目测试失败 已节省 ~450 行代码被移除 ────────────────────────────── 所有测试通过 PASS:这份总结一方面量化了清理收益删除数量与行数节省另一方面如实记录已跳过的项——被跳过的往往是测试失败或证据不足的项目如实披露它们既是诚实的要求也是为后续人工介入留下入口。Agent 的成功指标同样以可验证结果为准所有测试通过、构建成功、无回归、打包体积减小。红线规则四条不可逾越的纪律命令文档以规则清单收束整个流程这四条是/refactor-clean的底线切勿在不先运行测试的情况下删除代码——测试是唯一的安全网一次只删除一个——原子化的变更便于回滚如果不确定就跳过——保留死代码总比破坏生产环境好清理时不要重构——分离关注点先清理后重构。refactor-cleaner Agent 在此基础上补充了更细的何时不要使用清单可作为该命令的适用边界正在积极开发新功能时紧邻生产环境部署之前测试覆盖不足的代码库你尚不理解的代码这些边界与命令本身同样重要死代码清理是一项低风险高回报但并非零风险的维护活动选错时机反而会引入回归。小结一条可复用的受控清理流水线回顾整个/refactor-clean流程它本质上是一条检测 → 分层 → 原子删除 → 验证 → 汇总的受控流水线多语言检测工具负责发现必要时以 Grep 兜底SAFE/CAUTION/DANGER 分层决定处理策略删除循环用测试-删除-再测试-失败回滚保证每一步可逆重复项整合负责收敛代码体积最后以量化报告收尾。而 agents/refactor-cleaner.md、docs/COMMAND-AGENT-MAP.md、docs/COMMAND-REGISTRY.json 这些仓库文档则共同构成了该命令的人-机协作上下文命令定义流程纪律Agent 承载执行智能。对于任何希望在不破坏生产环境的前提下收缩代码库的团队这套以测试为盾、以原子化为原则的方法论都值得直接落地复用。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考