用途
cleanup-unused 用于检测并删除项目中未使用的代码、导出、文件和依赖。它只自动删除可验证为死代码的内容，并生成一份带置信度评级的批判性评估报告，将存在歧义的项目交由人工处理。
主要能力
- 按语言自动选择检测工具：TypeScript/JavaScript 使用 knip，Python 使用 vulture，Go 使用 staticcheck，Rust 使用 cargo-machete。
- 检测未使用的文件、导出、类型、依赖、devDependencies 等。
- 生成 Markdown 格式的评估报告，包含范围、摘要、发现表格、批判性分析和超出范围的项目。
- 按置信度分级处理：HIGH 自动应用，MEDIUM 仅报告，LOW 仅记录。
- 自动应用后运行类型检查、测试和 lint 进行验证，失败则回滚。
使用方式
预检
- 通过检查 package.json（TS/JS）、pyproject.toml/requirements.txt（Python）、go.mod（Go）、Cargo.toml（Rust）来检测语言，跳过不存在的语言。
- 检查 git 状态。若工作区不干净，拒绝自动应用，要求用户先 stash 或 commit。
- 创建报告目录：
mkdir -p .claude/cleanup-reports/，并将.claude/cleanup-reports/添加到 .gitignore。 - 扫描会破坏静态分析的动态导入模式，这些区域的发现将降为 MEDIUM 置信度。
检测
按语言运行对应工具，仅在询问后按需安装：
TypeScript / JavaScript：
bunx knip --reporter json > /tmp/knip.json 2>/dev/null || npx knip --reporter json > /tmp/knip.json
Python：
uvx vulture . --min-confidence 80 --json > /tmp/vulture.json 2>/dev/null || pipx run vulture . --min-confidence 80
Go：
go install honnef.co/go/tools/cmd/staticcheck@latest 2>/dev/null
staticcheck -checks=U1000 ./... > /tmp/staticcheck.txt
Rust：
cargo install cargo-machete 2>/dev/null
cargo machete --with-metadata > /tmp/machete.txt
cargo +nightly udeps 2>/dev/null || true
评估
写入 .claude/cleanup-reports/cleanup-unused-{YYYY-MM-DD}.md，包含范围、摘要、发现表格、批判性评估和超出范围的项目。
应用
仅自动应用 HIGH 置信度项目，将所有删除归入一个提交。
置信度标准：
- HIGH（自动应用）：工具标记且不在动态导入风险区域；不在公共 API 表面；在整个仓库中零引用（需用 grep 验证）；依赖未在任何脚本、配置或运行时 require 中使用。
- MEDIUM（仅报告，不应用）：工具标记但位于动态导入区域、公共 API 表面、有间接引用、是 .d.ts 中仅供外部使用的类型导出；vulture 置信度 60-79；出现在 peerDependencies 或由构建工具使用的依赖。
- LOW（报告中记录，不操作）：无工具支持的启发式猜测；用户之前拒绝删除的项目。
执行：删除文件用 rm <path>；移除导出用编辑去掉 export 关键字；卸载依赖用 bun remove <pkg> / pip uninstall <pkg> / cargo remove <pkg>。单次提交：git add -A && git commit -m "chore(cleanup): cleanup-unused — N items removed"。
验证
按顺序运行适用的类型检查、测试和 lint。首次失败即停止并回滚：
bun run typecheck 2>&1 || npx tsc --noEmit
mypy . 2>&1 || true
go build ./... 2>&1
cargo check 2>&1
bun test 2>&1 || npm test 2>&1
pytest 2>&1
go test ./... 2>&1
cargo test 2>&1
bunx biome check . 2>&1 || npx eslint . 2>&1
ruff check . 2>&1
golangci-lint run 2>&1
cargo clippy 2>&1
若任何失败：git revert HEAD --no-edit，将所有自动应用项目降为 MEDIUM，并在报告中追加“## Verify Failure”部分及错误输出。
输出
回合结束消息（≤4 行）：“Removed N unused items (X files, Y exports, Z deps). M deferred for review.”，报告路径，验证状态。
适用场景
适用于需要清理代码库中未使用代码、导出、文件和依赖的项目，支持 TypeScript/JavaScript、Python、Go 和 Rust。
限制
- 绝不删除 node_modules/、.next/、dist/、build/ 或其他生成目录中的内容。
- 绝不删除迁移文件（drizzle/*.sql、alembic/、migrations/），即使看起来未使用。
- 绝不基于 knip 标记删除测试夹具。
- 绝不在脏工作区上自动应用。
- 绝不盲目信任 knip 对框架约定目录（Next.js app/、pages/、Remix routes/ 等）中文件的判断。
- 若依赖移除导致解析问题，绝不运行 npm install --force 或任何绕过锁文件完整性的标志。