Simplify — 系统性代码简化

入口/出口

• 入口: 可编译可测试的代码
• 出口: 行为不变的简化版本 + 测试验证
• 指向: 完成后回到 verify-workflow-review 或继续 build
• 前置加载: CANON.md
• 输出路径: 简化后的代码 + 测试验证 → verify-workflow-review（继续审查）或 build-workflow-execute（继续构建）

何时不使用

• 行为尚未稳定或测试不能保护重构
• 当前目标是补功能、修 bug 或满足 spec，而不是降低复杂度
• 简化需要改变公共 API、数据结构或用户可见行为

Iron Law

<HARD-GATE> 行为不变。简化前后测试必须全部通过。任何测试失败 = 回退。 </HARD-GATE>

核心理念

• Chesterton's Fence: 不理解一段代码为什么存在，就不要删它
• 三个相似代码行 > 一个过早抽象
• 500 行规则: 文件超过 500 行 = 简化候选
• 增量简化: 每步一个改动，每步验证

Phase 1: 识别简化目标

扫描代码，标记以下类型的简化目标：

重复代码

• 同一逻辑出现 3+ 次
• 复制粘贴后仅改了少量参数的代码块

过度抽象

• 使用场景 < 3 的抽象层
• 只有 1-2 个实现者的接口或策略模式
• 间接层没有带来复用收益

过长函数

• > 50 行的函数
• 函数内有 3+ 个不同层级的抽象

过深嵌套

• > 3 层缩进
• 嵌套的 if-else 链用 guard clause 消除

死代码

• 无引用的导出
• 未使用的变量
• 不可达的分支（if (false)、throw 后的代码）

冗余注释

• 代码已自解释的注释
• 注释重复了函数名或变量名表达的信息

Phase 2: 理解上下文

对每个目标，回答以下问题：

• 为什么存在？ 这段代码解决什么问题？是业务需求、技术约束还是历史遗留？
• 谁依赖？ 哪些模块、测试、外部接口依赖它？
• 最近有改动吗？ 活跃修改的代码比稳定代码风险更高。

对每个目标进一步判断：

• 删除/简化这个会不会影响其他模块？
• 有没有测试覆盖这段代码？

对不确定的目标：先标记，跳过，不要猜。

Phase 3: 增量简化

规则：每次只改一个目标。每次改动后跑测试，全绿才继续。

简化策略

重复代码 → 提取函数（仅第 3+ 次）

// 第 1 次出现：保持内联
// 第 2 次出现：保持内联，标记 TODO
// 第 3 次出现：提取为函数
function formatDateForDisplay(date: Date): string {
  // 三个地方都用的逻辑现在集中在一处
}

过度抽象 → 内联 + 删除

// 前：过度抽象（只有 1 个实现）
interface DataProcessor { process(data: Raw): Result }
class DefaultDataProcessor implements DataProcessor { ... }

// 后：直接使用
function processData(data: Raw): Result { ... }

过长函数 → 按职责拆分

// 前：一个函数做 3 件事
function handleRequest(req: Request): Response { /* 80 行 */ }

// 后：每个函数一个职责
function validateRequest(req: Request): Validated { ... }
function transformData(data: Validated): Processed { ... }
function buildResponse(data: Processed): Response { ... }

过深嵌套 → guard clause

// 前：4 层嵌套
function process(user: User) {
  if (user) {
    if (user.isActive) {
      if (user.hasPermission) {
        // 真正的逻辑
      }
    }
  }
}

// 后：提前返回，1 层
function process(user: User) {
  if (!user) return;
  if (!user.isActive) return;
  if (!user.hasPermission) return;
  // 真正的逻辑
}

死代码 → 确认后删除

# 确认无引用
grep -r "<symbol>" --include="*.ts" --include="*.tsx" --include="*.js"

确认无引用后，使用 AskUserQuestion 询问："是否删除 <symbol>？代码库中无引用。"

冗余注释 → 删除或改善命名

// 前：注释多余
// 设置用户名称
user.setName(name);

// 后 A：删除注释
user.setName(name);

// 后 B：如果删注释后不够清晰，改善命名
user.updateDisplayName(name);

Phase 4: 验证

简化完成后，依次验证：

• 全部测试通过
• Lint 无新警告
• 行为不变（关键路径手动验证）
• 代码行数减少或持平（不应增加）

如果任何一项不满足 → 回退最后一次改动，重新评估。

好坏示例

Good — 减少抽象 + 行为不变

过度抽象（只有 1 个实现的 DataProcessor 接口）→ 内联为 processData() 函数。行数减少、调用链缩短、行为不变（全量测试通过）。下次修改不需要跨 3-5 层间接调用。

Bad — 过度工程化的过早抽象

3 个相似代码行出现时就建抽象工厂 + 策略模式。使用场景 < 3 但抽象层永久存在，每次修改需追踪多层间接调用，理解负担反而增加。YAGNI 被违反。

输出模板

简化记录（可合并入审查报告或作为独立记录）：

# Simplify 记录: <feature-name>

## 简化目标清单
| 目标 | 类型 | 简化策略 | 原始行数 | 简化后行数 | 状态 |
|------|------|---------|---------|----------|------|
| <symbol-1> | 重复代码 | 提取函数 | X | Y | 完成 |
| <symbol-2> | 过度抽象 | 内联+删除 | X | Y | 完成 |
| <symbol-3> | 死代码 | 确认后删除 | X | 0 | 完成 |

## 验证结果
- 全部测试: PASS (列出命令和结果)
- Lint: 无新警告
- 行为验证: 关键路径手动确认无变化
- 行数变化: 总减少 N 行

## 被跳过的目标
| 目标 | 跳过原因 |
|------|---------|
| <symbol-4> | 不确定依赖关系，需要进一步调查 |

## 结论
- 简化完成 / 需继续（如有被跳过的目标）

验证证据

输出或记录必须包含：

• 输入/来源: 读取的 spec、plan、代码、反馈或发布上下文。
• 执行动作: 实际完成的检查、生成、修复、导出或发布步骤。
• 验证结果: 命令、审查结论、产物路径、截图或人工确认。
• 阻塞/回退: 未通过项、回退路径或需要 human partner 决策的问题。

常见说辞

违反字面规则就是违反精神。 没有灰色地带。

验证失败处理

红旗

<HARD-GATE> 以下任何一个出现，立即停止：

• 一次改多个目标
• 测试失败后继续改
• 删除不理解的代码（Chesterton's Fence）
• 抽象后行数更多（抽象失败）
• 简化引入新依赖
• 跳过 Phase 2 直接动手
• 简化后代码行为变化（Iron Law 违反）
• 不跑测试就标记完成

</HARD-GATE>

验证清单

• 每个目标已理解上下文（Phase 2 完成）
• 每步改后测试通过
• 行为不变（Iron Law）
• 总行数未增加
• 无新 lint 警告