dead-code-sweep

死代码清理

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

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

编码 Agent 在有限的上下文窗口内工作。重构时，它们经常会：

• 重新实现功能，却没有找到并移除原有实现
• 为已不存在的接口保留兼容性垫片
• 内联辅助函数的逻辑后，不再使用这些函数
• 创建新文件，却没有删除被替换的文件
• 在模块边界之间重复定义类型
• 重构到一半时，不再使用某些符号，却留下了对应的导入语句

这些冗余会不断累积。每个孤立文件都会误导下一个 Agent（或人工开发者），让其浪费上下文预算去阅读毫无作用的代码。

工作流

阶段 1：确定范围并清点内容

确定分析边界。

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

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

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

生成简要清单：

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. 追踪引用，验证每个候选项——只有当没有任何有效代码路径能触达某个符号时，它才算死代码 3b. 搜索 CI 脚本和 Shell 测试夹具中是否存在指向该候选项的路径引用：rg <filename> -- scripts/ tests/ .github/。即使没有源文件导入，以棘轮检查参数或 Bats 测试夹具形式使用的文件也不属于死代码。
4. 记录发现，并注明文件路径、行范围和证据

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

• 通过动态分派、反射或基于字符串的查找使用的符号
• 框架约定的导出（例如 Next.js 页面组件、pytest 夹具、Rails 约定）
• 供外部使用者使用的公共 API
• 特性标志或环境检查之后的条件导入
• 通过装饰器或插件注册的处理程序
• 在 package.json 的 bin 字段中引用的 CLI 入口点
• 在模板或 JSX 中以动态字符串形式引用的 CSS 类名
• 通过路径引用文件的 CI 脚本和 Shell 测试夹具——例如，scripts/ci/ 中的 check_file_contains "name" "path/to/file"，或 tests/**/*.bats 中的 cat "$PROJECT_ROOT/path/to/file"。这些是字符串参数，而非导入，因此导入追踪工具完全无法发现它们。

如无法确定，请标记为“需要审核”，而不是“已确认无用”。

阶段 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 追踪重命名并检测已被取代的文件。

检查 CI 和测试基础设施，而不只是源代码

文件可能没有任何源代码引用，却被 CI 脚本（scripts/ci/、.github/workflows/）、Shell 测试夹具（tests/**/*.bats）或验证工具（.verifier/）使用。这些引用会以字符串参数的形式出现在 Shell 函数中，无法通过导入追踪发现。将文件归类为孤立文件前，务必运行 rg <filename> -- scripts/ tests/ .github/。