audit-code-complexity

审查代码复杂度

找出那些比问题所需更难理解、修改或验证的代码，并提出更简单的结构，同时保持其行为不变。更简单意味着更容易理解和修改，同时保留所有实际需求；文件、函数或代码行更少，本身并不代表代码更简单。这是一项审查：除非用户要求，否则不要编辑代码。

1. 确定范围

• **当前状态：**审查指定代码的现状，无论其复杂度是在何时引入的。
• **变更：**仅审查指定提交、分支或拉取请求引入或加重的复杂度。阅读周边代码以了解上下文。
• **方案：**根据用户提出的需求，审查尚未实施的设计或代码方案。要求修改方案时，修改的是方案，而不是方案所描述的代码。

只有用户明确指定了变更时，才使用变更范围；仓库中的未提交工作不是切换范围的理由。如果用户要求同时审查两者，请分别报告。

对于大型目标，如果可使用并行只读子 Agent，请按模块拆分目标进行审查，并在报告前自行核实其发现。

2. 查找复杂度

阅读目标代码、仓库说明、调用方、测试和配置，并且只阅读理解需求行为所需的文档。使用 git log 查看哪些文件变更最频繁；这些文件中的复杂度代价最高。区分调用方依赖的行为和契约，以及无人要求的假设和锦上添花的功能；删除调用方或用户可察觉的行为由用户决定，因此应提出建议，而不是擅自决定。

查找以下问题：

• 当前需求不需要的间接层、包装器、通用代码、扩展点、依赖项或基础设施
• 重复实现了语言、框架、现有依赖项，或现有路径、辅助函数、类型或 API 已提供的功能
• 为局部错误重写代码、为简单状态引入状态机、为单个调用方搭建框架、推测性迁移，或为了内部便利而大幅修改 API
• 纠缠的控制流、标志组合、隐式状态，以及允许无效状态的类型
• 同一事实在多个地方存储或计算
• 职责归属不当的行为，例如入口点或控制器中包含业务规则，或单个模块混杂不相关的职责
• 一项变更需要修改多个文件，或调用方必须了解被调用方本应隐藏的细节
• 隐藏的副作用、大范围修改、误导性命名，以及密集或炫技式表达式
• 防护条件、回退逻辑、兼容路径，以及不再被使用的代码
• 仅因测试仍在调用而保留的旧 API
• 隐藏行为、在多个位置编码策略，或迫使生产代码引入间接层的测试设置、辅助函数或模拟对象

建议删除包装器之前，请阅读其调用方，包括测试。如果它负责实际行为或保护某项契约，就应保留。如果它只是转发调用，请建议将该调用移至负责该功能的模块。

判断代码未使用之前，请按符号和字面字符串搜索使用方，包括生成的代码、配置、反射、其他包和脚本。搜索无结果只是证据，并非证明；请说明搜索范围。

建议移除某个机制之前，请弄清楚它的使用方、它在运行和故障处理中的作用，以及移除后由什么替代。持久化队列、显式状态、重试和领域区分看起来往往很复杂，但仍可能是必要的。

确认某个问题后，请检查目标的其余部分是否也存在同类问题，并将相关位置一并报告。如果只检查了目标的一部分，请说明检查了哪些部分。

3. 只报告真实发现

仅当以下条件全部满足时，才报告一项发现：

1. 它会带来具体代价：代码更难理解、修改或测试，或者存在引发错误或运维问题的风险。
2. 代码、用法、测试或需求能够支持这一说法。
3. 存在一种具体且更简单的替代方案，能够保留所需行为和契约。
4. 替代方案带来的收益大于迁移和回归风险，并且不会把复杂性、风险或手动工作转移给调用方或运维人员。

代码行数、嵌套深度、复杂度指标和陌生程度都只是线索，不构成发现。只有当相似代码表达的是同一个概念时，才有理由为它们建立共享抽象。格式化工具或代码检查工具会强制执行的事项，一律跳过。

优先进行局部修改；但如果证据表明更大范围的重构能消除更多复杂性，则建议进行重构，并说明其迁移成本。所有替代方案都必须保留领域差异、数据语义、身份、验证、安全性、无障碍性、兼容性，以及持久性、恢复和运维保障。

只有当复杂性导致或掩盖了错误、安全问题或性能问题时，才在本报告中列出，并单独标注。测试仅作为复杂性的来源纳入审查。关于测试价值和覆盖率，请使用 test-quality-audit 技能。

替换接口时，找出所有使用方，包括测试，并将测试迁移到替代接口，同时检查相同的行为；不要仅为了测试而保留旧 API。若其他调用方或发布流程仍需要旧接口，则予以保留，并说明何时可以移除临时适配器。

应用发现

仅在用户要求时修改代码，之后应完成相应修改并进行验证，无需再次询问。重构前运行相关测试，并在重构后保留相同的受保护用例。只有在契约变更获准或已证明测试有误时，才更改预期结果；不得以隐藏失败为目的更改测试夹具、模拟对象或测试选择。如果工作包含行为修复，且有 tdd 技能可用，则使用该技能。如果遇到阻碍，则保留任何有效的失败测试，并报告缺少的决策及剩余工作。

4. 报告

使用以下格式，按收益相对于风险的高低排列发现，并省略空白部分：

**Verdict:** Needs simplification | Minor opportunities | No material findings. One sentence on why.

**Scope:** what was inspected, and what was not.

### 1. Short title

`path/to/file.ts:42`, plus other locations with the same problem.

- **Cost:** what is harder, and the evidence.
- **Simpler shape:** the concrete alternative.
- **Keep:** behavior and contracts that must not change.
- **Risk:** migration and regression risk, and how to verify the change.

**Justified complexity:** complex-looking code that earns its place, only when a reader would likely question it.

**Order:** which findings to do first, only when the order matters.