# Verify Quality Simplify

> 系统性代码简化。当代码变得复杂、重复、过度抽象需要简化，或提到"简化""重构""太复杂""重复代码"

- Skill: `zeroz-lab/verify-quality-simplify` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zeroz-lab/verify-quality-simplify`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zeroz-lab/verify-quality-simplify/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zeroz-lab (https://skillmd.com/u/zeroz-lab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zeroz-lab/verify-quality-simplify

---


# 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+ 次出现 |
| 过度抽象 | 内联回调用处，删除抽象层 | 使用场景 < 3 |
| 过长函数 | 按职责拆分，每个函数一个职责 | > 50 行 |
| 过深嵌套 | 提前返回（guard clause）减少缩进 | > 3 层 |
| 死代码 | 确认无引用后用 `AskUserQuestion` 确认后删除 | 无引用 |
| 冗余注释 | 删除；删除后不够自解释则改善命名 | 代码已自解释 |

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

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

### 过度抽象 → 内联 + 删除

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

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

### 过长函数 → 按职责拆分

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

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

### 过深嵌套 → guard clause

```typescript
// 前：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;
  // 真正的逻辑
}
```

### 死代码 → 确认后删除

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

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

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

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

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

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

## Phase 4: 验证

简化完成后，依次验证：

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

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

## 好坏示例

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

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

## 输出模板

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

```markdown
# Simplify 记录: <feature-name>

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

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

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

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

## 验证证据

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

## 常见说辞

| 说辞 | 现实 | 后果 |
|------|------|------|
| "这样更优雅" | 优雅不是目标，简单才是。可读、可维护比聪明重要。 | "优雅"代码下次修改时无人敢动——看不懂、怕改坏。3 个月后连作者自己也读不懂。 |
| "先重构再说" | 不理解就动手 = 制造 bug。先 Phase 2 理解上下文。 | 不理解就重构引入 bug 的概率 > 50%（行业经验）。每个引入的 bug 又需要一轮调试，总时间 > 先理解再动手。 |
| "以后会用到" | YAGNI。等第三个使用场景出现再抽象。 | 预先建的抽象 80% 永远不会有第二个使用场景，但每个使用者都要理解它的存在和约束。认知负担永久增加。 |
| "这段代码太难看了" | 丑但正确 > 漂亮但有 bug。先理解为什么丑。 | 为了"美化"而改动的代码引入回归，丑代码背后的隐藏约束没有被理解。修复新 bug 的时间 > 忍受丑代码的代价。 |
| "抽象一下更干净" | 抽象有成本。使用场景 < 3 的抽象增加理解负担。 | 过早抽象让后续修改需要追踪 3-5 层间接调用，下次重构时无人敢删这段代码。 |

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

## 验证失败处理

| 失败场景 | 处理方式 |
|---------|---------|
| 简化后测试失败 | 立即回退最后一次改动，重新评估简化策略，不可继续改其他目标 |
| 简化后行为变化 | 回退改动，Iron Law 违反 — 行为不变是硬门，行为变化 = 简化失败 |
| 不理解的代码被删除 | 回退删除，按 Chesterton's Fence 原则先理解再决定是否删除 |
| 抽象后代码行数增加 | 回退抽象，重新评估是否真的需要这个抽象（使用场景 < 3 = 不需要） |
| 简化引入新依赖 | 回退改动，简化不应引入新依赖，新依赖 = 增加而非减少复杂度 |

## 红旗

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

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

## 验证清单

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