ECC refactor-cleaner 死代码清理 Agent：检测工具链、风险分级与分批安全删除流程

本篇指南基于 ECC（Everything Claude Code）仓库中的 Kiro Agent 定义文件 refactor-cleaner.md，完整拆解该 Agent 的职责边界、工具权限、死代码检测命令、四阶段清理工作流与安全检查清单，并结合配套的 refactor-cleaner.json、refactor-clean.md 命令与 quality-gate.sh 质量门禁脚本，讲清楚如何在 Kiro 中落地一套"检测 → 分级 → 分批删除 → 每批验证"的 Agent 化死代码治理方案。

1. 定位：ECC 中负责 Code Maintenance 的专用 Agent

在 ECC 的 Agent 目录中，refactor-cleaner 被归类为代码维护（Code Maintenance）方向的专职 Agent，负责删除未使用的代码、依赖与重复实现。这一分工在多个地方得到印证：

• AGENTS.md 的 Agent 清单中，refactor-cleaner 对应 "Dead code cleanup"，分类为 "Code maintenance"；
• docs/COMMAND-AGENT-MAP.md 将斜杠命令 /refactor-clean 与该 Agent 建立了一对一映射（"Dead code removal"）；
• README.md 的功能表中同样记录了 "Remove dead code → /refactor-clean → refactor-cleaner" 这条调用链。

ECC 为同一 Agent 维护了三种形态，覆盖不同的宿主环境：

形态	文件	使用场景
Markdown（IDE）	.kiro/agents/refactor-cleaner.md	Kiro IDE 中通过 / 菜单选择或显式调用
JSON（CLI）	.kiro/agents/refactor-cleaner.json	kiro-cli 中通过 /agent swap 切换
Claude Code 变体	agents/refactor-cleaner.md	Claude Code 环境下的同名 Agent

.kiro/README.md 明确说明：.md 格式供 IDE 使用（自动选择或显式调用），.json 格式供 CLI 使用（/agent swap 命令切换），两种格式并存是为了最大化兼容；且 Agent 实际使用的模型由 Kiro 当前的模型选择决定，不由 Agent 配置决定。

2. Agent 定义文件：职责声明与工具权限

2.1 Markdown 定义的 Frontmatter

refactor-cleaner.md 的文件头如下：

---
name: refactor-cleaner
description: Dead code cleanup and consolidation specialist. Use PROACTIVELY
  for removing unused code, duplicates, and refactoring. Runs analysis tools
  (knip, depcheck, ts-prune) to identify dead code and safely removes it.
allowedTools:
  - read
  - write
  - shell
---

allowedTools 只开放了 read、write、shell 三项能力，恰好对应该 Agent 工作流的全部动作：读代码与运行检测命令（read）、执行 knip/depcheck/ts-prune 等 CLI 工具（shell）、删除与合并代码（write）。没有开放任何网络或 MCP 工具，属于最小权限设计。

2.2 JSON 变体中的配置字段

refactor-cleaner.json 是同一 Agent 的 CLI 配置，字段与 MD 变体一一对应，可从中读出该 Agent 的完整运行配置：

• "allowedTools": ["fs_read", "fs_write", "shell"] —— Kiro CLI 对 read/write/shell 的具体工具命名；
• "mcpServers": {}、"hooks": {}、"resources": [] —— 不挂载任何 MCP 服务器、钩子或外部资源；
• "prompt" 字段内嵌了与 MD 文件完全一致的完整提示词，保证 IDE 与 CLI 两种形态行为一致。

从 JSON 结构看，ECC 的 Agent 是一个自包含单元：描述、权限、提示词全部内聚在单个文件里，不依赖外部配置。

2.3 Claude Code 变体附加了提示词防御基线

对比 agents/refactor-cleaner.md，核心提示词与 Kiro 版一致，Frontmatter 声明 tools: Read, Write, Edit, Bash, Grep, Glob 与 model: sonnet，并在正文最前面附加了一段 "Prompt Defense Baseline"，要求 Agent 不改变角色与身份、不泄露凭据、把外部获取的数据一律视为不可信输入并先行校验。从源码结构看，这是 ECC 跨宿主适配时对同一 Agent 做的安全加固层——在"允许删除代码"的高权限 Agent 上额外约束了输入信任边界。

3. 检测工具链：四条命令覆盖 JS/TS 项目的死代码盲区

Agent 提示词给出的检测命令是：

npx knip                                    # Unused files, exports, dependencies
npx depcheck                                # Unused npm dependencies
npx ts-prune                                # Unused TypeScript exports
npx eslint . --report-unused-disable-directives  # Unused eslint directives

四条命令分别覆盖四个不同粒度的死代码盲区：

工具	检测对象	说明
knip	未使用的文件、导出、依赖	基于入口文件（entry points）构建完整依赖图，能发现"整文件无人引用"的情况
depcheck	未使用的 npm 依赖	只扫 package.json 中声明但源码从未 import 的包
ts-prune	未使用的 TypeScript 导出	针对 .ts/.tsx 模块级导出，粒度到单个 export 符号
eslint --report-unused-disable-directives	失效的 eslint 禁用指令	清理历史遗留的 eslint-disable 注释

配套命令 commands/refactor-clean.md 把工具矩阵扩展到了多语言项目，可作为同一方法论在其他技术栈上的对照：

Tool	What It Finds	Command
knip	Unused exports, files, dependencies	npx knip
depcheck	Unused npm dependencies	npx depcheck
ts-prune	Unused TypeScript exports	npx ts-prune
vulture	Unused Python code	vulture src/
deadcode	Unused Go code	deadcode ./...
cargo-udeps	Unused Rust dependencies	cargo +nightly udeps

该文档还给出了无检测工具时的降级方案：用 Grep 找出所有 export，再逐一确认是否被 import。ECC 仓库自身的 package.json 中 devDependencies 声明了 eslint 10.6.0，lint 脚本为 eslint . && markdownlint '**/*.md' --ignore node_modules，engines 要求 node >= 18——在以 Node 为主的项目里，四条检测命令可以直接通过 npx 运行，无需预先安装。

4. 四阶段工作流：Analyze → Verify → Remove Safely → Consolidate

提示词将清理过程固化为四个阶段，这是整个 Agent 方法论的核心。

4.1 阶段一 Analyze：并行运行检测工具并按风险分级

要求并行（parallel）运行检测工具，然后把所有发现按风险分成三级：

风险等级	含义	典型对象
SAFE	可放心删除	未使用的导出、未使用的依赖
CAREFUL	需额外验证	通过动态 import() 加载的模块
RISKY	原则上不动	对外暴露的公共 API

commands/refactor-clean.md 中的分级表给出了更具体的映射：SAFE 包括"未使用的工具函数、测试辅助、内部函数"；CAUTION 包括"组件、API 路由、中间件"；DANGER 包括"配置文件、入口文件、类型定义"——后两者要求先调查再决定。

4.2 阶段二 Verify：对每个候选删除项做三重确认

对每一个准备删除的项，必须完成三项验证：

1. Grep 全部引用——包括通过字符串模式出现的动态导入（如 import('...')、require('...')）；
2. 确认是否属于公共 API——如果该符号从包入口导出，删除会破坏外部消费者；
3. 回看 git 历史——了解该代码当初为何存在，避免删掉"暂时没人用但属于演进方向"的代码。

配套命令文档补充了 CAUTION 项的四个具体检查动作：搜索 import()、require()、__import__ 等动态加载；搜索路由名、配置中的组件名字符串；确认是否从公共包 API 导出；若是已发布的包，检查依赖方（dependents）。

4.3 阶段三 Remove Safely：按固定顺序分批删除，每批测试加提交

删除阶段有三条硬约束：

• 只从 SAFE 项开始，任何一批都不碰 CAREFUL/RISKY；
• 一次只处理一个类别，且类别顺序固定：deps -> exports -> files -> duplicates（依赖 → 导出 → 文件 → 重复代码）；
• 每批删除后必须跑测试，并通过后提交一次 commit。

"类别顺序"的设计值得注意：先删依赖（只改 package.json，影响面最小），再删导出（单文件内符号级修改），最后才删整文件和合并重复实现（跨文件引用面最大）。这是一个由小到大、由浅入深的回滚难度递增序列。

commands/refactor-clean.md 把"安全删除循环"细化成了可操作的五步：

1. 先跑完整测试套件，建立全绿的基线；
2. 删除死代码，用编辑工具做外科手术式的最小改动；
3. 重跑测试套件，验证没有破坏任何东西；
4. 测试失败则立即回滚（git checkout -- <file>），跳过该项；
5. 测试通过则进入下一项。

这保证了任何一次失败删除都能被单步回退，而不会污染后续批次。

4.4 阶段四 Consolidate Duplicates：重复代码合并

死代码清理完成后，再处理重复实现：

• 找出重复的组件/工具函数，选择最完整、测试最好的实现作为保留方；
• 更新所有 import 指向保留方，删除重复实现；
• 验证测试通过。

配套命令给出了识别重复的量化标准：相似度超过 80% 的近似函数应合并；冗余类型定义应整合；不增值的包装函数应内联；无意义的 re-export 应去掉这层间接引用。命令文档还特别强调"Don't refactor while cleaning"——清理与重构是两件事，清理阶段只删不改逻辑，避免一次变更混合两种意图。

5. 安全检查清单与"何时不该用"

Agent 提示词内嵌了两张可勾选的检查清单，分别约束删除前与每批之后：

Before removing（删除前）：

• [ ] 检测工具确认该符号未被使用
• [ ] Grep 确认无引用（包括动态引用）
• [ ] 不属于公共 API
• [ ] 删除后测试通过

After each batch（每批之后）：

• [ ] 构建成功
• [ ] 测试通过
• [ ] 使用描述性信息完成提交

五条关键原则（Key Principles）进一步收束了行为边界：

1. Start small —— 一次只处理一个类别；
2. Test often —— 每一批之后都测；
3. Be conservative —— 拿不准就不删；
4. Document —— 每个批次都写描述性 commit message；
5. Never remove during active feature development or before deploys —— 活跃特性开发期间和发布前绝不删除。

"何时不该用"清单把这最后一条展开成四个明确的禁入场景：正在开发特性时、生产发布前夕、测试覆盖不足时、以及对不理解的代码。配套的 commands/refactor-clean.md 的 Rules 部分同样强调 "Never delete without running tests first" 与 "Skip if uncertain — Better to keep dead code than break production"（宁可留着死代码，也不让生产环境出故障）。

6. 批次验证的落地机制：quality-gate.sh 质量门禁

"每批之后跑测试"在 ECC 的 Kiro 集成里有一个现成的自动化载体：.kiro/scripts/quality-gate.sh。该脚本由 .kiro/hooks/quality-gate.kiro.hook 手动触发，执行 build、类型检查、lint、测试四类检查：

• 包管理器探测（quality-gate.sh#L17-L36）：依次检查 pnpm-lock.yaml、yarn.lock、bun.lockb/bun.lock、package-lock.json，兜底按 PATH 中可用的命令判断，保证测试命令用项目实际的包管理器运行；
• Build（quality-gate.sh#L57-L63）：仅当 package.json 中定义了 "build" 脚本时运行，否则优雅跳过；
• Type check（quality-gate.sh#L65-L80）：有 tsconfig.json 时跑 npx tsc --noEmit，Python 项目则回退到 pyright/mypy；
• Lint（quality-gate.sh#L82-L94）：按 Biome → ESLint → Ruff → golangci-lint 的优先级选择；
• Tests（quality-gate.sh#L96-L106）：优先 $PM run test，其次 pytest、go test ./...。

脚本汇总 pass/fail/skip 计数，任一失败则输出 Quality gate: FAILED 并以非零码退出（quality-gate.sh#L108-L120）。这与提示词"每批：Build succeeds / Tests pass / Committed"的清单项一一对应——在 refactor-cleaner 的批次循环中，该脚本就是每批删除后的验证门禁。

7. 安装与调用：如何在 Kiro 项目中启用该 Agent

7.1 安装

ECC 的 Kiro 集成通过 .kiro/install.sh 一键安装到任意项目：

cd .kiro
./install.sh /path/to/your/project   # 安装到指定项目
./install.sh                          # 安装到当前目录
./install.sh ~                        # 全局安装（~/.kiro/）

安装器是非破坏性复制：install.sh#L54-L64 中对每个 agent 文件（.json 与 .md 两种格式都复制）先检查目标路径是否已存在，存在则跳过，因此重复安装不会覆盖你的自定义修改。

7.2 调用方式

按 .kiro/README.md 的说明：

# CLI：以指定 Agent 启动会话
kiro-cli --agent refactor-cleaner
> "Remove unused code and consolidate duplicate functions"

# CLI：会话中切换
> /agent swap
# 选择 refactor-cleaner

# IDE：/ 菜单直接调用
> /refactor-cleaner

README 的 "Example 9: Refactoring and Cleanup" 给出了标准使用节奏：先用 refactor-cleaner 识别死代码、发现重复实现、执行安全重构，然后紧接 /verification-loop 做收尾验证（build、类型检查、lint、全量测试、安全扫描、diff 审查，循环直到全部通过）。这与 Agent 提示词"每批测试"的内建要求形成双层保险。

7.3 与 ECC 生态的协作点

从仓库引用关系看，refactor-cleaner 并非孤立存在：

• 命令侧：commands/refactor-clean.md 提供了多语言扩展版的工作流，是同一方法论的命令化表述；
• Agent 侧：agents/build-error-resolver.md 的交接规则写明 "Code needs refactoring → use refactor-cleaner"，即构建修错误 Agent 遇到需要重构的代码时会把任务移交过来；
• 文档侧：docs/COMMAND-AGENT-MAP.md 把 /refactor-clean 与 refactor-cleaner 登记为固定映射。

可以推断，ECC 的设计意图是让"清理"成为一个可被其他 Agent 明确路由到的专职角色，而不是混在通用重构对话里。

8. 成功指标：如何判断一次清理是成功的

提示词给出的验收标准（Success Metrics）有四条：

1. All tests passing —— 测试全绿；
2. Build succeeds —— 构建通过；
3. No regressions —— 无功能回归；
4. Bundle size reduced —— 产物体积下降（这是清理工作的直接收益体现）。

commands/refactor-clean.md 还规定了收尾汇报的固定格式，便于把结果沉淀为可审计的记录：

Dead Code Cleanup
──────────────────────────────
Deleted:   12 unused functions
           3 unused files
           5 unused dependencies
Skipped:   2 items (tests failed)
Saved:     ~450 lines removed
──────────────────────────────
All tests passing PASS:

注意汇报中显式包含 "Skipped" 行——因测试失败而被回滚跳过的项目也要如实上报，这与 "Be conservative" 原则互为印证。

9. 小结

refactor-cleaner 的价值不在"删代码"这个动作本身，而在于它为 Agent 化的死代码治理定义了一套可复制的纪律：检测工具给出候选 → 风险三级分类限定删除范围 → Grep/公共 API/git 历史三重验证 → 按 deps→exports→files→duplicates 的固定顺序分批删除 → 每批测试加提交、失败立即回滚 → 收尾用验证循环兜底。这套流程全部内聚在 refactor-cleaner.md 这一个文件里，配合 quality-gate.sh 的自动化门禁，即可在 Kiro 项目中直接落地。对需要把同类方法论移植到其他语言栈的读者，commands/refactor-clean.md 中 vulture/deadcode/cargo-udeps 的工具矩阵给出了现成的对照。