necessary-code-audit

必要性代码审计

原则

优化目标是“当前是否必要”，不只是“是否零引用”。一个符号即使仍有调用，也可能只是包装层、兼容面、防御分支、陈旧公共 API 或假设性的扩展点。

核心问题是：这个代码被用了，但当前代码真的还需要它吗？

不要删除真实运行约束。必须保留代表加载、空数据、错误、权限、生命周期、浏览器、SSR、配额、外部输入或领域可空状态的分支。

不要把普通注释当作清理目标。只有注释已经过期、错误、误导，或因为代码删除而孤立时，才删除或改写注释。

不要在发现第一个明显清理点后停止。对于用户指定的目录或功能，必须先审完整个作用域，再报告“没有更多”或要求用户继续。

技能协作

本技能是三个清理技能的主入口：

• 用 necessary-code-audit 判断“已被使用的代码是否仍然必要”。
• 用 unused-code-audit 证明删除候选是否仍有消费者。
• 目标涉及页面状态、查询/变更流、权限、错误或用户可见行为时，用 page-flow-cleanup-audit。

不依赖仓库专属图工具。优先使用当前环境可用的文件列表、语言工具、构建/类型检查、manifest、导入图和文本搜索。

边界

本技能只回答“即使有人在用，这个抽象/行为/API 是否仍然必要？”。

适合本技能：

• 有调用方的 wrapper、facade、兼容别名、默认值、fallback、可选字段或配置。
• 多处调用但调用方可以直接使用更基础 primitive 的 helper。
• 公共 API 仍被 import，但只是历史兼容面或陈旧入口。
• 防御分支、try/catch、可选链、as any 或旧格式兼容是否代表真实约束。
• 两份 source of truth、重复 cache/store/query/派生计算是否需要合并。

不适合本技能单独完成：

• 只想证明某文件、导出或类型是否零消费者；改用 unused-code-audit。
• 删除没有调用方的死代码；先用 unused-code-audit 完成消费者证明。
• 页面状态、权限、查询/变更链路或用户可见流程清理；改用 page-flow-cleanup-audit。

协作规则：

• 若候选看起来零消费者，暂停必要性判断，转为 unused-code-audit 的删除证明。
• 若候选仍有消费者，再继续判断是否必要、是否能替换调用方、是否应收缩公共面。
• unused-code-audit 的结论只能说明“能否安全删除未使用项”，不能替代本技能对“已使用但不必要”的判断。

基线

开始时必须收集：

• git status --short --untracked-files=all
• git diff --name-status -- <scope>
• git diff --cached --name-status -- <scope>
• 目标作用域文件清单，优先用 rg --files <scope>。
• 当前导入、导出、公共入口和直接消费者。
• 作用域符号清单：导出的函数/类型/常量、非导出 helper、配置字段和重复字面量。
• 影响面图：同包消费者、包入口、直接 app/package import，以及 manifest 中的下游包。

不要假设 staged 或 dirty 变更是自己造成的。不要回滚无关变更。

深度门槛

编辑前和完成前都必须完成这些检查：

1. 盘点作用域内每个文件和有意义的导出/helper，而不是只看用户最先提到的文件。
2. 将候选分成“零消费者候选”和“有消费者但可能不必要候选”；零消费者候选交给 unused-code-audit 证明。
3. 对有消费者的候选，至少检查每个消费区域的一个代表调用点，再判断抽象是否必要。
4. 对可替换候选，确认调用方能否直接使用现有 primitive，以及替换后会孤立哪些 export/helper/type。
5. 对公共 API 变更，确认 package exports 以及能覆盖变更面的下游包/app typecheck。
6. 每批清理后重新搜索残留名称、旧 import path、重复字面量和新孤立 helper。
7. 只有剩余候选都已归类为真实约束、刻意保留的公共 API，或超出当前请求风险范围时，才停止。

如果这些检查发现更多工作，要在同一轮继续处理。不要要求用户说“继续深度检查”才推进。

候选分类

对目标作用域中的每个有意义文件、导出、方法、字段、选项、fallback 和分支分类：

• 当前必要：当前产品行为或平台/运行时约束需要。
• 可直接替代：调用方可以直接使用底层 primitive 的 wrapper/facade。
• 兼容面：为外部或历史消费者保留的旧导出、可选字段、默认值、别名、工厂、配置或公共类型。
• 防御分支：try/catch、fallback、可选链、空值保护、特性检测或脏数据处理。
• 假设性能力：没有当前调用方，或只有假想未来价值的 API 面。
• 重复来源：第二份 cache、store、query、invalidation 路径、状态源或派生计算。
• 疑似死代码：看起来没有真实消费者；不要在本技能内直接删除，转交 unused-code-audit 证明。
• 真实约束：SSR、浏览器存储可用性、配额、权限、加载/错误/空态生命周期、外部输入或合法领域可空状态。
• 仅文档：注释或文档。除非过期、误导或被代码变更孤立，否则保留。