remove-deadcode

通过大规模并行深度 Agent 移除死代码。你是 ORCHESTRATOR — 扫描、验证、分批，然后将所有移除任务委派给并行 Agent。

- **LSP 即准则。** 在做出任何移除决定之前，先使用 `LspFindReferences(includeDeclaration=false)` 验证。 - **绝不移除入口点。** `src/index.ts`、`src/cli/index.ts`、测试文件、配置文件、`packages/` — 均不可修改。 - **不要亲自移除代码。** 你负责扫描、验证、分批，然后启动深度 Agent。由它们完成工作。 绝不要将以下内容标记为死代码： - `src/index.ts` 或 barrel `index.ts` 重新导出的符号 - 测试文件中引用的符号（测试是有效的使用方） - 带有 `@public` / `@api` JSDoc 标签的符号 - Hook 工厂（`createXXXHook`）、工具工厂（`createXXXTool`）、`agentSources` 中的 Agent 定义 - 命令模板、技能定义、MCP 配置 - `package.json` 导出中的符号

---

阶段 1：扫描 — 查找死代码候选项

并行运行以下所有操作：

TypeScript 严格模式（主要扫描器 — 首先运行此项）：

bunx tsc --noEmit --noUnusedLocals --noUnusedParameters 2>&1

这会提供未使用的局部变量、导入、参数和类型的权威列表，并标明准确的文件:行号位置。

探索 Agent（全部同时作为后台任务启动）：

task(subagent_type="explore", run_in_background=true, load_skills=[],
  description="Find orphaned files",
  prompt="Find files in src/ NOT imported by any other file. Check all import statements. EXCLUDE: index.ts, *.test.ts, entry points, .md, packages/. Return: file paths.")

task(subagent_type="explore", run_in_background=true, load_skills=[],
  description="Find unused exported symbols",
  prompt="Find exported functions/types/constants in src/ that are never imported by other files. Cross-reference: for each export, grep the symbol name across src/ — if it only appears in its own file, it's a candidate. EXCLUDE: src/index.ts exports, test files. Return: file path, line, symbol name, export type.")

将所有结果汇总到候选项总表中。

---

阶段 2：验证 — LSP 确认（零误报）

对于阶段 1 中的每个候选项：

LspFindReferences(filePath, line, character, includeDeclaration=false)
// 0 references → CONFIRMED dead
// 1+ references → NOT dead, drop from list

同时应用上述误报防护规则。生成已确认列表：

| # | File | Symbol | Type | Action |
|---|------|--------|------|--------|
| 1 | src/foo.ts:42 | unusedFunc | function | REMOVE |
| 2 | src/bar.ts:10 | OldType | type | REMOVE |
| 3 | src/baz.ts:7 | ctx | parameter | PREFIX _ |

操作类型：

• REMOVE — 完全删除该符号/导入/文件
• PREFIX _ — 签名要求保留但未使用的函数参数 → 重命名为 _paramName

如果确认项为零：报告“未发现死代码”并停止。

---

阶段 3：分批 — 按文件分组，避免并行冲突

目标：最大限度增加并行 Agent 数量，同时确保 git 冲突为零。

1. 按文件路径对已确认的死代码项分组
2. 同一文件中的所有项都放入同一批次（避免两个 Agent 编辑同一文件）
3. 如果存在死文件（需删除整个文件），将其单独设为一个批次
4. 目标为 5–15 个批次。如果总项数少于 5，则每项单独设为一个批次。

分批示例：

Batch A: [src/hooks/foo/hook.ts — 3 unused imports]
Batch B: [src/features/bar/manager.ts — 2 unused constants, 1 dead function]
Batch C: [src/tools/baz/tool.ts — 1 unused param, src/tools/baz/types.ts — 1 unused type]
Batch D: [src/dead-file.ts — entire file deletion]

同一目录中的文件可以放在同一批次中（只要没有两个 Agent 编辑同一文件，就不会冲突）。尽可能增加批次数量，以实现并行处理。

---

阶段 4：执行 — 启动并行深度 Agent

为每个批次启动一个深度 Agent：

task(
  category="deep-low",
  load_skills=["typescript-programmer", "git-master"],
  run_in_background=true,
  description="Remove dead code batch N: [brief description]",
  prompt="[see template below]"
)

每个深度 Agent 都使用以下提示词结构（根据各批次填写具体内容）：

## TASK: Remove dead code from [file list]

## DEAD CODE TO REMOVE

### [file path] line [N]
- Symbol: `[name]` — [type: unused import / unused constant / unused function / unused parameter / dead file]
- Action: [REMOVE entirely / REMOVE from import list / PREFIX with _]

### [file path] line [N]
- ...

## PROTOCOL

1. Read each file to understand exact syntax at the target lines
2. For each symbol, run LspFindReferences to RE-VERIFY it's still dead (another agent may have changed things)
3. Apply the change:
   - Unused import (only symbol in line): remove entire import line
   - Unused import (one of many): remove only that symbol from the import list
   - Unused constant/function/type: remove the declaration. Clean up trailing blank lines.
   - Unused parameter: prefix with `_` (do NOT remove — required by signature)
   - Dead file: delete with `rm`
4. After ALL edits in this batch, run: `bun run typecheck`
5. If typecheck fails: `git checkout -- [files]` and report failure
6. If typecheck passes: stage ONLY your files and commit:
   `git add [your-specific-files] && git commit -m "refactor: remove dead code from [brief file list]"`
7. Report what you removed and the commit hash

## CRITICAL
- Stage ONLY your batch's files (`git add [specific files]`). NEVER `git add -A` — other agents are working in parallel.
- If typecheck fails after your edits, REVERT all changes and report. Do not attempt to fix.
- Pre-existing test failures in other files are expected. Only typecheck matters for your batch.

同时启动所有批次。等待全部完成。

---

阶段 5：最终验证

所有 Agent 完成后：

bun run typecheck   # must pass
bun test            # note any NEW failures vs pre-existing
bun run build       # must pass

生成摘要：

## Dead Code Removal Complete

### Removed
| # | Symbol | File | Type | Commit | Agent |
|---|--------|------|------|--------|-------|
| 1 | unusedFunc | src/foo.ts | function | abc1234 | Batch A |

### Skipped (agent reported failure)
| # | Symbol | File | Reason |
|---|--------|------|--------|

### Verification
- Typecheck: PASS/FAIL
- Tests: X passing, Y failing (Z pre-existing)
- Build: PASS/FAIL
- Total removed: N symbols across M files
- Total commits: K atomic commits
- Parallel agents used: P

---

范围控制

如果提供了 $ARGUMENTS，则缩小扫描范围：

• 文件路径 → 仅扫描该文件
• 目录 → 仅扫描该目录
• 符号名称 → 仅扫描该符号
• all 或为空 → 扫描整个项目（默认）

中止条件

出现以下情况时停止并报告：

• 找到超过 50 个候选项（请用户缩小范围或确认继续）
• 构建失败，且无法通过还原来修复