| name | nextclaw-dead-code-governance |
| description | 当用户要求扫描、识别、清理、常态化治理 NextClaw 仓库里的死代码、无用代码、unused files、unused exports、unused dependencies，尤其是核心包越来越臃肿、想删旧实现或做定期减债时使用。 |
NextClaw 死代码治理
目标
把“感觉项目越来越臃肿”变成可重复、低误删风险的清理流程。
这个 skill 只负责死代码治理：找出并删除无引用、重复、过期、被新路径替代的代码。它不负责一般性能优化、功能重构或目录治理战役；若任务扩大到长期自治推进，再联动 autonomous-maintainability-campaign。
使用前提
本 skill 命中后拥有本次死代码扫描、删除与实现结果，不拥有阶段切换；完成当前 slice 后返回生命周期，由 Validation、Review、Delivery 和 Retrospective 各自处理后续合同。长期自治战役、迭代留痕或规则修改只有条件实际成立时才加载对应 owner，不重新加载上游 lifecycle。
核心判断
死代码候选分三类：
确定可删：生产代码无引用、无 package exports、无 bin/脚本入口、无动态注册、无文档要求保留，且已有替代路径或本身无行为价值。疑似可删：机器扫不到引用，但可能是公共 API、插件入口、协议类型、测试入口、构建资源、CLI/bin、动态 import 或外部包消费表面。暂不删除：NCP 协议类型、SDK/export 表面、runtime/plugin 注册点、CLI/bin 入口、构建产物、资源文件、测试入口噪声、兼容迁移仍需要的旧路径。
默认只删除 确定可删。疑似可删 先列入报告或下一批验证，不在同一刀里硬删。
扫描流程
1. 先读上下文
先确认：
- 用户要的是只读审计，还是直接清理。
- 作用域是全仓库、核心包，还是某个 package。
- 当前工作区是否已有无关改动：
git status --short。
核心包优先级通常是：
packages/nextclawpackages/nextclaw-corepackages/nextclaw-runtimepackages/nextclaw-app-runtimepackages/nextclaw-serverpackages/ncp-packages/*packages/nextclaw-ui
2. 只读扫描
优先使用仓库已有信号：
pnpm metrics:local
pnpm lint:maintainability:hotspots
再用 knip 扫死代码，按作用域收窄：
pnpm dlx knip --workspace <package-or-path> --include files,exports,dependencies --reporter compact --no-exit-code --max-show-issues 200
对生产路径可补：
pnpm dlx knip --production --workspace <package-or-path> --include files,exports,dependencies --reporter compact --no-exit-code --max-show-issues 200
对局部未用符号可补：
pnpm -C <package> exec tsc -p tsconfig.json --noEmit --noUnusedLocals --noUnusedParameters
3. 降噪过滤
knip 常见误报必须先过滤：
*.test.*、tests/：多半是测试入口未配置，不等于可删。ui-dist/、dist/、public/sw.js、资源目录：可能是构建或发布资源。- package
exports 指向的类型和入口：可能被外部用户消费。
- CLI
bin、scripts、worker entry、dynamic import、plugin manifest、runtime registry：不能只看静态 import。
index.ts barrel 暴露的公共类型：先判断是否属于 API surface，再决定是否收窄导出。
4. 反查证据
删除前必须至少做一次源码反查：
rg -n "<symbol-or-file-stem>" packages scripts apps docs -g '!**/dist/**' -g '!**/ui-dist/**' -g '!**/node_modules/**'
同时检查：
package.json 的 exports、bin、files、scriptstsconfig.json path alias- 相关
index.ts barrel
- docs/logs 中是否只是历史记录，历史记录不能单独证明代码仍需保留
删除策略
优先顺序：
- 重复实现：保留已有 canonical owner，删除旧复制品。
- 无引用生产文件：确认没有入口或动态加载后删除。
- 未使用 helper / 局部函数：直接删，避免为了修 lint 做空包装。
- 旧 UI 组件 / 旧 hook：只有测试引用而生产无引用时，连同对应孤立测试一起评估。
- unused dependency：最后处理；先确认源码、脚本、构建、peer/发布合同都不用。
每一刀要小，默认只做同一责任链的一组删除。不要把“死代码清理”顺手扩大成架构重构。
不要做的事
- 不要用
knip --fix 或自动删除文件。
- 不要删除用户未提交的无关改动。
- 不要因为机器标 unused 就删除公共 API、协议类型或插件入口。
- 不要靠压缩格式、缩短命名、折叠空白来满足非功能净减。
- 不要在同一批里混删多个无关 feature root，除非用户明确要求大规模治理。
验证闭环
触达 TypeScript 源码、类型或导入导出边界时，必须跑：
pnpm -C <package> tsc
源码清理还要跑 package lint：
pnpm -C <package> lint
如果 package lint 或全量治理被无关工作区改动阻塞，改跑当前触达文件的 targeted 版本，并在最终回复说明阻塞来源：
pnpm lint:new-code:governance -- --files <touched-files...>
定向测试优先跑被删除路径的替代 owner 或邻近行为测试：
pnpm -C <package> exec vitest run <relevant-tests...>
收尾必须跑：
node .agents/skills/development-review/scripts/check-maintainability.mjs --non-feature --paths <touched-files...>
pnpm check:governance-backlog-ratchet
删除后可复扫：
pnpm dlx knip --workspace <package-or-path> --include files,exports --reporter compact --no-exit-code --max-show-issues 120
汇报格式
最终汇报必须包含：
- 删除了什么，以及为什么确认可删。
- 保留了什么疑似项，以及为什么暂不删。
tsc、lint、测试、maintainability guard、governance 的结果。- 总代码增减、非测试代码增减。
- 正向减债动作，通常是
删除 或 简化。
- 是否新增或更新
docs/logs 迭代记录。
- 若全量治理被无关改动阻塞，说明 targeted 验证已覆盖本次触达范围。
常态化节奏
常态治理时，每轮只选择一个高置信批次：
- 先扫核心包生产 unused files。
- 再扫重复实现和旧 owner。
- 再收敛 unused exports。
- 最后处理 unused dependencies。
每完成一批，记录剩余候选和下一刀建议。若剩余项需要产品/API 兼容判断，停止并向用户报告，不要强行继续。
