# Necessary Code Audit

> 审计“仍有消费者的代码”是否真的需要继续存在，重点是 wrapper/facade、兼容层、陈旧公共 API、防御分支、fallback、默认值、配置、重复来源和假设性扩展点。用于已被使用但必要性不足的代码、遗留兼容清理、无意义包装、防御代码移除、无兼容要求清理、深度必要性检查，以及“这个还需要吗？”类请求；不要把它作为纯 unused/dead-code 证明工具。

- Skill: `danhuaxiansheng/necessary-code-audit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add danhuaxiansheng/necessary-code-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/danhuaxiansheng/necessary-code-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: danhuaxiansheng (https://skillmd.com/u/danhuaxiansheng)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/danhuaxiansheng/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、浏览器存储可用性、配额、权限、加载/错误/空态生命周期、外部输入或合法领域可空状态。
- `仅文档`：注释或文档。除非过期、误导或被代码变更孤立，否则保留。

## 必要性问题

每个候选在编辑前回答：

1. 当前代码真的需要这个行为吗？
2. 如果它有调用方，调用方需要这个抽象吗，还是能直接调用现有 primitive？
3. 它保护的是真实运行/领域状态，还是历史兼容/假设？
4. 如果无需向后兼容，公共类型、导出或配置能否删除？
5. 删除是否改变当前产品行为？如果会，这是否符合请求意图？
6. 删除后哪些方法、import、export、注释、测试或文档会变得无意义？

当用户想删的其实是真实约束而非防御代码时，要明确指出。

## 清理顺序

1. 先删除 wrapper、facade 和兼容层。
2. 将调用点替换为直接 primitive。
3. 删除新孤立的方法、helper、import、export 和公共类型。
4. 删除无用配置 key、默认值、可选字段、feature flag 和因代码删除而孤立的旧注释。
5. 删除只隐藏不可能或过期状态的防御分支。
6. 每次删除来源或公共 API 后重新做残留搜索。

不要为了删除旧抽象而创建新抽象。

注释清理只是代码清理的附带动作。不要把“低价值注释”纳入清理顺序，除非它错误或已孤立。

## 证据

结构证据：

- 目标目录或功能的文件清单。
- wrapper、方法和导出符号的 import/export 搜索。
- manifest、re-export 文件、框架约定、生成文件和类型声明。
- 可用时使用语言工具：编译诊断、测试覆盖、依赖分析或 IDE 引用。
- 每个改动过的公共 helper 至少检查每个消费包/app 的一个代表调用点。
- 根据真实导入图选择下游 package/app typecheck，而不是只检查定义包。

文本残留搜索：

- 删除的文件 stem 和 import path。
- 删除的符号名和成员名。
- 兼容相关词：`legacy`、`deprecated`、`backward`、`compat`、`fallback`、`debug`、旧格式注释、注释掉的代码。
- 防御模式：`try`、`catch`、可选字段、可选链、`as any`、恒定布尔参数、默认配置值。
- 重复字面量和等价本地 helper，这可能说明共享 primitive 没被复用。

自动 unused-export 或依赖分析工具只能作为候选生成器。发现零消费者候选后，进入 `unused-code-audit` 的证明流程；本技能继续处理“仍被使用但不必要”的候选。

## 验证

运行覆盖改动边界的最窄检查：

- 公共 API 变更后，先跑定义模块或库的 typecheck/build。
- 直接消费者 package 的 typecheck 或窄 eslint。
- import、公共导出或共享校验/格式化行为变更时，跑下游 app/package typecheck。
- 对删除符号和旧 import path 做残留 `rg`。
- `git diff --check -- <scope>`；若有 staged 变更，也跑 `git diff --cached --check -- <scope>`。

如果广义 typecheck 失败，要说明失败是否与本次清理相关。

## 报告

报告：

- 已删除：wrapper、兼容面、防御分支、陈旧公共 API 和直接替代。
- 已保留：真实运行/领域约束，以及为什么它不是无意义防御代码。
- 已验证：命令、结果、残留搜索、无关 dirty 文件或无关失败。

要明确说明哪些候选交给了 `unused-code-audit` 证明，哪些候选是“仍被使用但不再必要”并由本技能处理。