dead-code-sweep

死代码清理

系统地识别并移除代码库中的死代码、冗余实现和孤立产物——尤其是由上下文窗口有限的编码 Agent 维护的代码库。

Agent 维护的代码库为何会积累冗余

编码 Agent 在狭窄的上下文窗口中工作。重构时，它们经常会：

• 在未找到并移除原有实现的情况下重新实现功能
• 为已不存在的接口留下兼容性垫片
• 内联辅助函数的逻辑后，弃用这些函数
• 创建新文件，却不删除被替代的文件
• 在模块边界间重复定义类型
• 在重构过程中停止使用某些符号后，仍保留相应的导入语句

这些冗余会不断累积。每个孤立产物都会误导下一个 Agent（或人类），让他们浪费上下文预算去阅读毫无作用的代码。

工作流

阶段 1：确定范围并盘点

确定分析边界。

如果用户提供了范围（目录、文件模式、模块），则将所有分析限制在该范围内。

如果用户未提供范围，则分析整个代码库。首先阅读项目结构：

1. 确定主要语言和框架
2. 梳理入口点（主文件、路由定义、导出模块、测试运行器）
3. 记录构建系统和依赖配置
4. 检查是否采用 monorepo 结构——将每个软件包作为一个整体进行分析

生成简要清单：

Language(s): TypeScript, Python
Entry points: src/index.ts, src/cli.ts
Build: esbuild via package.json scripts
Packages: 1 (single package)
Estimated LOC: ~4,200

阶段 2：检测

启动多个并行子 Agent，扫描不同类别的死代码。阅读 references/cruft-patterns.md，了解完整的检测模式目录。

将检测工作分为以下并行任务：

任务	查找内容
孤立文件	未被任何其他文件导入、要求或引用的文件
未使用的导出	从未在其他地方导入的导出符号（函数、类、类型、常量）
冗余实现	以不同名称执行相同操作的多个函数或类
过时的兼容代码	用于衔接已不再存在差异的接口的垫片、适配器、包装器和重新导出
死分支	永远不会执行的条件路径（始终为真或假的守卫条件、不可达的返回语句）
孤立测试	测试已不存在的函数或模块的测试文件
孤立依赖	依赖清单中未在任何源代码中导入的软件包

对于每项任务，子 Agent 应：

1. 阅读 references/cruft-patterns.md，了解该任务对应的检测策略
2. 使用 Grep 和 Glob 搜索代码库
3. 通过追踪引用来验证每个候选项——只有在没有任何活动代码路径能到达某个符号时，它才属于死代码
4. 记录发现，并注明文件路径、行范围和证据

验证至关重要。 注意以下常见误报：

• 通过动态分发、反射或基于字符串的查找使用的符号
• 框架约定的导出（例如 Next.js 页面组件、pytest 固件、Rails 约定）
• 供外部使用者使用的公共 API
• 由功能标志或环境检查控制的条件导入
• 通过装饰器或插件注册的处理器
• 在 package.json 的 bin 字段中引用的 CLI 入口点
• 在模板或 JSX 中以动态字符串形式引用的 CSS 类名

如果无法确定，应标记为“需要审核”，而非“已确认是死代码”。

阶段 3：报告

将所有发现汇总为结构化报告，保存至 .claude/dead-code-report.md。

先按置信度级别组织发现，再按类别排列：

# Dead Code Sweep Report

**Scope:** [full codebase | specific path]
**Date:** [date]
**Estimated removable lines:** [count]

## Confirmed Dead (high confidence)

### Orphaned Files
- `src/utils/old-parser.ts` — Not imported anywhere. Superseded by `src/parser/index.ts`.
- ...

### Unused Exports
- `formatDate()` in `src/helpers.ts:42-58` — Exported but zero imports across codebase.
- ...

[...other categories...]

## Needs Review (uncertain)

### Possibly Dynamic
- `handleLegacyEvent()` in `src/events.ts:91` — No static imports, but may be registered dynamically.
- ...

对于每项发现，请注明：

• 文件路径和行范围
• 对象类型（函数、类、文件、类型、常量、依赖）
• 疑似无用的原因（无导入、无引用、已被 X 替代）
• 置信度（已确认／需要审核）

阶段 4：经批准后清理

向用户展示报告摘要，并在移除任何内容前征求批准。

使用 AskUserQuestion 按类别展示发现：

Found 12 confirmed dead items and 3 needing review.

Confirmed dead by category:
- 3 orphaned files (~280 lines)
- 5 unused exports (~120 lines)
- 2 redundant implementations (~90 lines)
- 2 orphaned dependencies

Which categories should I clean up?

选项：移除所有已确认项 / 选择类别 / 逐项审核 / 跳过清理

对于每个获批类别：

1. 移除无用代码
2. 清理引用了已移除代码的导入
3. 移除清理后留下的空文件
4. 从清单中移除不再需要的依赖项
5. 运行项目的 lint/typecheck/build 命令，确认没有问题

如果任何移除操作导致构建或类型错误，立即还原该项移除，并将其移至“需要审核”。

清理后，更新报告，说明移除了哪些内容以及保留了哪些内容。

检测原则

从入口点追踪，而不是从疑似项开始

从已知入口点开始，追踪哪些内容可达，而不是从疑似符号入手并试图证明其已被使用。可达性方法产生的漏报更少。

尊重模块边界

从包的公共 API 导出的符号，可能被此代码库中不可见的外部代码使用。在分析有外部使用者的库或包时，只将内部（非公共 API）的无用代码标记为“已确认”。将公共 API 中的无用代码标记为“需要审核”。

留意成簇出现的问题，而不只是个别项

Agent 生成的冗余代码往往成簇出现。发现一个无用函数时，检查其周边代码——Agent 可能在重构期间放弃了整个代码段。一个无用文件通常还有在同一提交中创建的同级无用文件。

将 git 历史作为判断依据

如果条件允许，检查疑似代码上次发生实质性修改的时间。跨越多个重构提交都未改动的代码更可能已无用。使用 git log --follow 追踪重命名并检测已被取代的文件。