Everything Claude Code Refactor Cleaner Agent 是一款生产级的死代码清理和重复代码合并专用 AI 代理，自动集成 knip、depcheck、ts-prune 等检测工具，系统性识别未被引用的导出、依赖和文件，并通过多重验证确保移除操作安全无回归。相比直接让 Claude 识别死代码，Refactor Cleaner Agent 能自动分类风险、批量处理、严格遵循测试与提交流程，适用于代码维护、技术债清理和持续集成等场景，是提升 AI 编程助手生产力的关键组件。

Everything Claude Code Refactor Cleaner Agent：运行 knip/depcheck/ts-prune 识别并安全删除死代码

在实际开发中，随着项目迭代和团队协作，代码库中难免积累未被引用的函数、过时的依赖包、重复实现的工具方法和无用文件。这些“死代码”不仅拖慢构建速度、增加维护成本，还可能埋下安全隐患。虽然你可以直接让 Claude、Cursor 等 AI 编程助手帮你查找和删除死代码，但这种方式依赖模型的上下文感知和推理能力，容易遗漏动态引用、公共 API 或误删关键逻辑，且缺乏系统性验证。

Everything Claude Code Refactor Cleaner Agent（以下简称 Refactor Cleaner Agent）正是为了解决这一痛点而设计。它不仅自动集成 knip、depcheck、ts-prune 等主流死代码检测工具，还内置多步安全验证和风险分级机制，确保每一次清理都可控、可回溯、无回归。本文将详细介绍 Refactor Cleaner Agent 的核心能力、使用流程、触发方式、与其他 Agent 的协作模式及实际对话示例，帮助你在 AI 编程助手生态中实现专业级的代码精简与安全重构。

1. Refactor Cleaner Agent 能解决什么问题？

Refactor Cleaner Agent 是 Everything Claude Code 插件体系中的专职死代码清理与重复实现合并代理（Agent）。它的核心用途包括：

• 自动识别并安全删除未被引用的导出、依赖和文件：通过 knip、depcheck、ts-prune 等工具全量扫描项目，找出未被使用的 TypeScript/JavaScript 导出、npm 依赖、文件和 ESLint 指令。
• 合并和消除重复实现：检测并归并功能重复的组件或工具函数，统一引用路径，减少冗余。
• 安全分级处理：将检测结果按风险分为 SAFE（安全）、CAREFUL（需谨慎）、RISKY（高风险/公共 API），只自动移除 SAFE 类别，其他需人工确认。
• 多步验证与自动化提交流程：每批次删除后自动运行测试、构建，确保无回归并生成详细提交记录。
• 与其他 Agent 协作：可与 code-reviewer、tdd-guide 等协同，形成完整的重构-验证-提交闭环。

典型适用场景：

• 版本迭代后大规模重构、模块拆分合并
• 技术债清理、准备开源或交付前的仓库瘦身
• 持续集成/自动化脚本中定期死代码扫描与清理

2. Refactor Cleaner Agent 能做什么、不能做什么？

能做的

• 批量识别未被引用的导出、依赖、文件，并自动分级
• 检测 npm 依赖实际使用情况，建议移除未用包
• 合并重复实现，统一引用并删除冗余代码
• 自动生成/更新提交信息，便于代码审查和回溯
• 严格遵循测试、构建、提交顺序，每步失败自动回滚
• 与其他 Agent（如 code-reviewer、tdd-guide）协作，形成安全闭环

不能做的

• 不建议在活跃开发分支或临近上线前使用，以免误删正在开发的代码
• 不能替代人工判断高风险（RISKY）项，如公共 API、动态引用等需人工确认
• 不在测试覆盖率不足时自动清理，需先确保测试完整
• 不会在不理解的代码区域盲目操作，始终以安全为前提

3. 触发方式：自动激活与手动调用

Refactor Cleaner Agent 支持两种触发模式：

• 手动调用：适合在代码重构、技术债清理、准备开源等特定场景下，由开发者主动触发清理流程。例如在 Everything Claude Code 的命令面板或 CLI 中输入 run refactor-cleaner，即可启动全局死代码扫描与清理。
• 自动激活：可通过 Hooks 系统配置为定期自动运行，或在合并大 PR、完成阶段性重构后自动触发。例如配置 PostToolUse 钩子，在 code-reviewer 通过后自动调用 refactor-cleaner 进行收尾清理。

自动化示例：

hooks:
  PostToolUse:
    - if: agent == "code-reviewer" && result == "pass"
      then: run refactor-cleaner

4. 与其他 Agent 的协作模式

Refactor Cleaner Agent 通常与以下 Agent 组合使用，形成完整的安全重构闭环：

• 与 code-reviewer 协作：在清理死代码后，自动调用 code-reviewer 进行代码质量和安全性复查，确保无误删或潜在风险。
• 与 tdd-guide 协作：清理前后自动运行测试驱动开发流程，确保所有用例通过，防止回归。
• 与 build-error-resolver 协作：如清理后出现构建错误，自动调用 build-error-resolver 快速定位并修复问题。

这种多 Agent 协作模式，是 Everything Claude Code 插件体系的核心优势之一。你可以参考 Everything Claude Code 完全指南 和 高级技巧 了解更多自动化编排与安全保障实践。

5. 实际使用示例：完整对话流程

以下是一次典型的 Refactor Cleaner Agent 使用流程示例：

开发者输入：

帮我扫描并安全删除本项目中未被引用的 TypeScript 导出、无用依赖和重复实现，要求每一步都跑测试和构建，生成详细提交说明。

Refactor Cleaner Agent 自动执行：

1. 检测阶段

   npx knip
   npx depcheck
   npx ts-prune
   npx eslint . --report-unused-disable-directives

   输出检测报告，标记 SAFE/CAREFUL/RISKY 项。

2. 验证阶段

   • 对每个 SAFE 项执行全局 grep，确认无动态引用。
   • 检查是否为公共 API 或被外部依赖。
   • 查阅 git 历史，确认无特殊用途。

3. 安全移除（分批次）

   • 先删除无用依赖（deps），运行测试和构建。
   • 提交：chore: remove unused npm dependencies (depcheck)
   • 再删除未被引用的导出（exports），再次测试和构建。
   • 提交：refactor: remove unused TypeScript exports (ts-prune)
   • 检查并合并重复实现，统一引用路径。
   • 提交：refactor: consolidate duplicate utilities

4. 收尾复查

   • 自动调用 code-reviewer 复查变更。
   • 所有测试通过，构建无误，生成最终汇总报告。

开发者收到总结：

已安全删除 6 个未用依赖、14 个未被引用的导出、合并 2 组重复工具函数。所有测试和构建均通过，变更已分批提交。无回归风险，建议下次大版本发布前再次运行本流程。

6. 为什么要用专门的 Refactor Cleaner Agent，而不是直接问 Claude？

直接让 Claude、Cursor 等 AI 编程助手识别死代码，通常存在以下局限：

• 上下文窗口有限，难以全局扫描大型项目，容易遗漏跨文件的引用关系。
• 无法自动集成 knip/depcheck/ts-prune 等专业工具，检测结果不全面。
• 缺乏分级和多步验证机制，易误删动态引用或公共 API，风险不可控。
• 无法自动化测试、构建和分批提交，回滚和溯源困难。
• 不能与其他 Agent 协作，难以形成安全闭环。

Refactor Cleaner Agent 则通过专业工具链、风险分级、自动化验证和多 Agent 协作，真正实现了“安全、系统、可回溯”的死代码清理，极大提升了 AI 编程助手在生产环境下的可靠性和效率。

---

FAQ

Q: Refactor Cleaner Agent 需要项目有测试覆盖吗？ A: 是的，建议至少 80%+ 的测试覆盖率，否则无法确保移除后无回归风险。

Q: 可以只清理某个目录或文件吗？ A: 支持，调用时可指定扫描范围，Agent 会只处理目标区域并遵循同样的安全流程。

Q: 清理后发现误删怎么办？ A: 所有变更均分批提交，支持快速回滚。建议在独立分支操作并通过 code-reviewer 复查后再合并到主分支。

---