dead-code-sweep

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dead Code Sweep

死代码扫描清理

Systematic identification and removal of dead code, redundant implementations, and orphaned artifacts in codebases — particularly those maintained by coding agents with limited context windows.

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

Why Agent-Maintained Codebases Accumulate Cruft

为何Agent维护的代码库会积累无效代码残留

Coding agents operate within narrow context windows. When refactoring, they often:

Re-implement functionality without finding and removing the original
Leave compatibility shims for interfaces that no longer exist
Abandon helper functions after inlining their logic
Create new files without deleting the ones they replace
Duplicate type definitions across module boundaries
Leave imports for symbols they stopped using mid-refactor

This cruft compounds. Each orphaned artifact misleads the next agent (or human), who wastes context budget reading code that does nothing.

编码Agent在狭窄的上下文窗口内运行。进行重构时，它们通常会：

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

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

Workflow

工作流程

Phase 1: Scope and Inventory

阶段1：范围界定与清单整理

Determine the analysis boundary.

If the user provides a scope (directory, file pattern, module), constrain all analysis to that scope.

If no scope is provided, analyze the full codebase. Start by reading the project structure:

Identify the primary language(s) and framework(s)
Map entry points (main files, route definitions, exported modules, test runners)
Note the build system and dependency configuration
Check for monorepo structure — analyze each package as a unit

Produce a brief inventory:

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

确定分析边界。

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

若未提供范围，则分析整个代码库。首先读取项目结构：

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

生成简要清单：

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

Phase 2: Detection

阶段2：检测

Launch parallel sub-agents to scan for different categories of dead code. Read

references/cruft-patterns.md

for the full catalog of detection patterns.

Organize detection into these parallel tracks:

Track	What It Finds
Orphaned files	Files not imported, required, or referenced by any other file
Unused exports	Exported symbols (functions, classes, types, constants) never imported elsewhere
Redundant implementations	Multiple functions/classes doing the same thing under different names
Stale compatibility code	Shims, adapters, wrappers, and re-exports that bridge interfaces that no longer differ
Dead branches	Conditional paths that can never execute (always-true/false guards, unreachable returns)
Orphaned tests	Test files testing functions or modules that no longer exist
Orphaned dependencies	Packages in dependency manifests not imported anywhere in source

For each track, the sub-agent should:

Read
```
references/cruft-patterns.md
```
for detection strategies specific to that track
Search the codebase using Grep and Glob
Verify each candidate by tracing references — a symbol is only dead if zero live code paths reach it
Record findings with file path, line range, and evidence

Verification is critical. Common false positives to watch for:

Symbols used via dynamic dispatch, reflection, or string-based lookups
Framework-magic exports (e.g., Next.js page components, pytest fixtures, Rails conventions)
Public API surface intended for external consumers
Conditional imports behind feature flags or environment checks
Decorator-registered or plugin-registered handlers
CLI entry points referenced in package.json
```
bin
```
fields
CSS class names referenced in templates or JSX as dynamic strings

When uncertain, mark as "needs review" rather than "confirmed dead."

启动并行子Agent扫描不同类别的死代码。阅读

references/cruft-patterns.md

获取完整的检测模式目录。

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

任务轨道	检测内容
孤立文件	未被任何其他文件导入、引用的文件
未使用的导出符号	导出后未在其他地方导入的符号（函数、类、类型、常量）
冗余实现	不同名称但功能相同的多个函数/类
过时兼容性代码	用于桥接已无差异接口的垫片、适配器、包装器和重导出代码
无效分支	永远无法执行的条件路径（始终为真/假的判断、不可达的返回语句）
孤立测试用例	测试已不存在的函数或模块的测试文件
孤立依赖	依赖清单中存在但源代码中从未导入的包

每个任务轨道的子Agent需执行以下操作：

阅读
```
references/cruft-patterns.md
```
获取该轨道专属的检测策略
使用Grep和Glob扫描代码库
通过追踪引用验证每个候选对象——只有当零活跃代码路径指向某个符号时，才判定其为死代码
记录检测结果，包含文件路径、行号范围和证据

验证至关重要。需注意常见的误报情况：

通过动态调度、反射或基于字符串的查找使用的符号
框架魔法导出（如Next.js页面组件、pytest夹具、Rails约定）
面向外部消费者的公开API接口
功能标志或环境检查后的条件导入
装饰器注册或插件注册的处理器
package.json的
```
bin
```
字段中引用的CLI入口点
模板或JSX中作为动态字符串引用的CSS类名

若存在不确定性，标记为“需要复核”而非“确认死代码”。

Phase 3: Report

阶段3：报告

Consolidate all findings into a structured report at

.claude/dead-code-report.md

Organize findings by confidence level, then by category:

markdown

undefined

将所有检测结果整合到结构化报告

.claude/dead-code-report.md

中。

按置信度、再按类别组织结果：

markdown

undefined

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

```
src/utils/old-parser.ts
```
— 未被任何地方导入，已被
```
src/parser/index.ts
```
取代。
...

Unused Exports

未使用的导出符号

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

[...other categories...]

```
src/helpers.ts:42-58
```
中的
```
formatDate()
```
— 已导出但整个代码库中无导入。
...

[...其他类别...]

Needs Review (uncertain)

需要复核（不确定）

Possibly Dynamic

可能为动态使用

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


For each finding, include:

- **File path and line range**
- **What it is** (function, class, file, type, constant, dependency)
- **Why it appears dead** (no imports, no references, superseded by X)
- **Confidence** (confirmed / needs review)

```
src/events.ts:91
```
中的
```
handleLegacyEvent()
```
— 无静态导入，但可能通过动态方式注册。
...


每个检测结果需包含：

- **文件路径和行号范围**
- **类型**（函数、类、文件、类型、常量、依赖）
- **判定为死代码的原因**（无导入、无引用、被X取代）
- **置信度**（确认/需要复核）

Phase 4: Cleanup with Approval

阶段4：经批准后清理

Present the report summary to the user and ask for approval before removing anything.

Use AskUserQuestion to present findings by category:

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?

Options: Remove all confirmed / Select categories / Review each item / Skip cleanup

For each approved category:

Remove the dead code
Clean up any imports that referenced the removed code
Remove empty files left after cleanup
Remove orphaned dependencies from the manifest
Run the project's lint/typecheck/build commands to verify nothing broke

If any removal causes a build or type error, immediately revert that specific removal and move the item to "needs review."

After cleanup, update the report with what was removed and what was kept.

向用户展示报告摘要，在移除任何代码前请求批准。

使用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?

可选操作：移除所有确认项 / 选择特定类别 / 逐项复核 / 跳过清理

对于每个获批准的类别：

移除死代码
清理引用了已移除代码的导入语句
删除清理后遗留的空文件
从依赖清单中移除孤立依赖
运行项目的lint/类型检查/构建命令，验证未引入任何问题

若某次移除导致构建或类型错误，立即回滚该特定移除操作，并将该项移至“需要复核”类别。

清理完成后，更新报告，记录已移除和保留的内容。

Detection Principles

检测原则

Trace from entry points, not from suspects

从入口点追踪，而非从可疑代码入手

Start from known entry points and trace what's reachable, rather than starting from a suspect symbol and trying to prove it's used. The reachability approach has fewer false negatives.

从已知的入口点开始追踪可访问的代码，而非从可疑符号入手尝试证明其被使用。可达性分析的假阴性更少。

Respect the module boundary

尊重模块边界

A symbol exported from a package's public API may be consumed by external code not visible in this repository. When analyzing libraries or packages with external consumers, only flag internal (non-public-API) dead code as "confirmed." Flag public API dead code as "needs review."

从包的公开API导出的符号可能被此仓库外的外部代码使用。分析面向外部消费者的库或包时，仅将内部（非公开API）死代码标记为“确认”，公开API中的死代码标记为“需要复核”。

Look for clusters, not just individuals

寻找集群，而非单个孤立项

Agent-generated cruft tends to cluster. When one dead function is found, examine its neighbors — the agent likely abandoned the entire section during a refactor. A dead file often has sibling dead files created in the same commit.

Agent生成的无效代码残留往往成簇出现。当发现一个死函数时，检查其邻近代码——Agent可能在重构期间弃用了整个代码段。一个死文件通常有在同一提交中创建的兄弟死文件。

Use git history as a signal

将Git历史作为信号

When available, check when suspect code was last meaningfully modified. Code untouched across several refactor commits is more likely dead. Use

git log --follow

to trace renames and detect superseded files.

若可用，检查可疑代码最后一次有意义的修改时间。在多次重构提交中未被触碰的代码更可能是死代码。使用

git log --follow

追踪重命名并检测被取代的文件。