same-results-less-code

社区重构最佳实践：结果不变，代码更少

这份代码审查与重构指南聚焦于那些源自判断与建模偏差的代码量：抽象选择不当、隐藏的语义重复、防御性习惯以及过早追求通用性。本指南刻意跳过 knip、eslint、ruff、tsc --noUnusedLocals 等代码检查工具或格式化工具已经能发现的问题。这是第二轮审查：机械式清理之后，还剩下什么？

核心原则

1. 保持行为不变。 每次转换都必须产生完全相同的可观察行为——输出、错误、副作用和 API 表面均不变。
2. 早期错误会层层放大。 框架选错，会导致结构不当，进而造成逻辑重复。应从生命周期的上游开始优化。
3. 解释原因，而不只是做法。 每条规则都说明反模式的代价，让判断力能迁移到新场景。
4. 尽可能量化。 相比“更简洁”，优先说明“减少 N 行代码／避免 X 类 Bug”。
5. 不要过度重构。 遵循三次原则：重复实际出现三次后再提取抽象，而不是提前预想。

适用场景

在以下情况下使用此技能：

• 审查 PR 时思考“能否更简单？”（这是代码检查工具无法回答的问题）
• 重构代码量不断增加、能力却没有提升的代码
• 审查“感觉很臃肿”的模块——标志很多、层次很多、检查很多
• 熟悉不熟悉的代码库，尝试区分无意增加的代码量与必要的复杂性
• 设计新模块，希望避免常见的过度抽象陷阱
• 配合使用 knip / eslint / ruff，并希望补上这些工具无法提供的判断

以下情况不要使用此技能：

• 代码检查工具或格式化工具已能完成的机械式清理（未使用的导入、无效导出、代码风格）——请改用 knip、eslint、ruff 或 prettier/black。
• 算法复杂度／性能调优——请改用 complexity-optimizer。
• 不论是否存在思维模型偏差，都要对近期修改的代码进行常规清理——请改用 code-simplifier。

按优先级排列的规则类别

#	类别	前缀	影响	规则数	概述
1	重造已有功能	reinvent-	严重	5	重写平台／标准库已经提供的功能
2	框架选错	frame-	严重	5	抽象结构不当——明明函数就够，却用了类；采用管理器式命名；数据导向场景却使用面向对象
3	隐藏的重复	dup-	高	5	语法不同，语义相同的重复实现
4	存储派生状态	derive-	高	5	存储本应计算得出的内容
5	过程式重建	proc-	中高	5	用命令式代码重新实现声明式概念
6	投机性通用化	spec-	中	5	为从未出现的第二个使用者构建通用性
7	过度防御	defense-	中	4	检查类型或流程已排除的状态
8	未充分利用类型系统	types-	低至中	6	本应由类型表达的运行时防护

快速参考

1. 重造已有功能（严重）

• reinvent-stdlib-collection-ops — 编写循环前，先考虑使用 .map/.filter/.reduce
• reinvent-date-and-time — 不要手动实现日期和时间运算
• reinvent-deep-equality — 使用真正的深度相等比较工具，而不是手动递归遍历对象
• reinvent-explicit-state-machine — 明确呈现状态机，而不是来回切换布尔标志
• reinvent-builtin-data-structures — 识别自定义容器是否只是 Map、Set 或 Queue

2. 错误的框架（CRITICAL）

• frame-function-not-class — 如果类没有身份标识，就使用函数
• frame-manager-noun-is-a-verb — 重命名 Manager/Helper/Util 类，直到体现出真正的动词
• frame-composition-over-inheritance-for-shared-fields — 组合共享字段，而非通过继承复用
• frame-data-over-procedure — 先将问题建模为数据，再编写过程
• frame-monolith-by-cohesive-axis — 沿着内聚轴拆分巨型函数，而非按行数拆分

3. 隐藏的重复（HIGH）

• dup-parallel-types-same-shape — 合并结构相同的并行类型
• dup-near-twin-functions — 将仅在字面量上不同的两个函数参数化
• dup-mirrored-branches — 将镜像 if/else 分支中的共享代码提取出来
• dup-config-not-copies — 用一个表替代多处硬编码副本
• dup-cross-layer-shape — 合并相同的 DTO、数据库行和领域对象

4. 存储派生状态（HIGH）

• derive-dont-store-computed — 能计算的就计算；只存储无法计算的内容
• derive-single-source-of-truth — 选定一个事实来源；从中派生其余内容
• derive-boolean-from-data — 从数据派生布尔值，不要单独跟踪它们
• derive-cache-as-getter-not-field — 将缓存字段改为 getter，直到性能分析证明另有必要
• derive-url-as-state — 让 URL 或路由成为状态，而不是状态的镜像

5. 过程式重建（MEDIUM-HIGH）

• proc-mutation-builder-over-pipeline — 当变更构建器掩盖了意图时，改用管道组合
• proc-if-chain-as-lookup — 用查找表替代返回常量的 if/elif 链
• proc-manual-recursion-of-walk — 使用公认的树/对象遍历方式，而非手写递归
• proc-build-vs-declarative-template — 框架提供声明式形式时，就使用它
• proc-sequential-awaits-could-be-parallel — 并行执行彼此独立的 await

6. 投机性通用设计（MEDIUM）

• spec-interface-of-one — 避免为单一实现定义接口
• spec-options-bag-of-one — 所有调用方都传入相同值时，避免使用选项集合
• spec-flag-driven-paths — 将被布尔标志拆成两种路径的函数拆分开
• spec-no-extension-point-without-extender — 删除没有第二个使用方的扩展点
• spec-generic-over-one-type — 只有一种具体类型使用时，移除泛型参数

7. 防御过度（中）

• defense-guard-against-impossible — 不要防范类型或流程已排除的状态
• defense-validate-once-at-boundary — 在边界处验证一次，内部直接信任
• defense-let-it-throw — 让异常继续传播；不要捕获自己无法处理的异常
• defense-null-pollution-from-bad-modelling — 修正导致必须进行空值检查的类型

8. 类型系统利用不足（低至中）

• types-discriminated-union-over-flags — 使用可辨识联合，而不是可选字段加标签
• types-literal-union-over-string — 当取值集合固定时，将 string 收窄为字面量联合
• types-no-any-to-silence — 避免使用 any/as 来压制类型错误
• types-branding-over-runtime-checks — 为已验证的值添加品牌，避免重复验证
• types-exhaustive-switch-not-default — 使用穷尽性检查，而不是兜底的 default
• types-readonly-and-immutable-by-default — 在确实需要修改之前，将数据标记为 readonly

如何应用（工作流）

使用此技能审查或重构代码时：

1. 先进行机械检查。 knip/eslint/ruff/tsc --noUnusedLocals 可以发现死代码、未使用的导入和风格问题。不要在这里重复这些工作。
2. 阅读文件或 PR，理解其意图。 思考：这段代码试图做什么？判断的关键在于识别实现是否超出了意图。
3. 按优先级依次检查各类别。
   • 从 重新造轮子 和 框定问题 开始——最大的改进空间就在这里。
   • 然后检查 重复 和 派生状态。
   • 接着检查 过程式重建 和 推测性通用化。
   • 最后检查防御和类型系统问题——这类问题出现频率高，但影响范围较局部。
4. 提出最小差异的改动。 每条规则都通过紧凑的差异展示错误做法 → 正确做法；建议也应保持这一特点。
5. 验证行为。 输出、错误和副作用必须保持一致，测试也必须通过。
6. 不要捆绑无关改动。 每项改动都应对应一个类别。混在一起会让审查变得困难。

不适用的情况

• 代码尚未达到“三次法则”（只有一处或两处重复）——此时提取还为时过早。
• 该模式确实属于已知例外（参见每条规则中的“何时不应使用此模式”部分）。
• 重构会变成大型、高风险的改写，且缺少明确可靠的测试保障——应提出建议，而不是直接执行。
• 对性能至关重要的热点路径中，“更简单”的形式会带来可测量的成本——先进行测量。

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则的模板
metadata.json	版本和参考信息

相关技能

• code-simplifier — 机械式简化（命名、无用代码、嵌套）。可作为互补的初步处理。
• complexity-optimizer — 算法与性能复杂度。关注维度不同。
• refactor — 通用重构工作流。
• clean-code — 更广泛的整洁代码原则。本技能是其中范围更窄、更注重判断的子集。