nextclaw-dead-code-governance

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。

核心判断

死代码候选分三类：

1. 确定可删：生产代码无引用、无 package exports、无 bin/脚本入口、无动态注册、无文档要求保留，且已有替代路径或本身无行为价值。
2. 疑似可删：机器扫不到引用，但可能是公共 API、插件入口、协议类型、测试入口、构建资源、CLI/bin、动态 import 或外部包消费表面。
3. 暂不删除：NCP 协议类型、SDK/export 表面、runtime/plugin 注册点、CLI/bin 入口、构建产物、资源文件、测试入口噪声、兼容迁移仍需要的旧路径。

默认只删除 确定可删。疑似可删 先列入报告或下一批验证，不在同一刀里硬删。

扫描流程

1. 先读上下文

先确认：

• 用户要的是只读审计，还是直接清理。
• 作用域是全仓库、核心包，还是某个 package。
• 当前工作区是否已有无关改动：git status --short。

核心包优先级通常是：

• packages/nextclaw
• packages/nextclaw-core
• packages/nextclaw-runtime
• packages/nextclaw-app-runtime
• packages/nextclaw-server
• packages/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、scripts
• tsconfig.json path alias
• 相关 index.ts barrel
• docs/logs 中是否只是历史记录，历史记录不能单独证明代码仍需保留

删除策略

优先顺序：

1. 重复实现：保留已有 canonical owner，删除旧复制品。
2. 无引用生产文件：确认没有入口或动态加载后删除。
3. 未使用 helper / 局部函数：直接删，避免为了修 lint 做空包装。
4. 旧 UI 组件 / 旧 hook：只有测试引用而生产无引用时，连同对应孤立测试一起评估。
5. 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 验证已覆盖本次触达范围。

常态化节奏

常态治理时，每轮只选择一个高置信批次：

1. 先扫核心包生产 unused files。
2. 再扫重复实现和旧 owner。
3. 再收敛 unused exports。
4. 最后处理 unused dependencies。

每完成一批，记录剩余候选和下一刀建议。若剩余项需要产品/API 兼容判断，停止并向用户报告，不要强行继续。