# Code Refactoring

> 系统化、安全地代码重构技能。能够识别代码坏味道、提供重构手法，支持制定计划、执行重构并验证结果。适用于代码质量提升、技术债清理、可维护性改进、代码优化、代码改进等场景。当用户请求重构代码、优化代码质量、修复代码问题或清理技术债时触发。

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

---


# 代码重构技能

本技能提供系统化、安全的代码重构指导，帮助改善既有代码的内部结构而不改变其外部行为。

## 核心原则

1. **先测试，后重构**：确保有足够的测试覆盖再开始重构
2. **小步前进**：每次只做一个小的重构动作，立即验证
3. **保持行为不变**：重构不应改变代码的外部行为
4. **持续验证**：每一步重构后都要运行测试验证
5. **风格符合**：重构的代码应符合项目规范

## 重构计划输出格式

在执行任何重构前，必须先输出详细的重构计划，格式如下：

```
## 重构计划

### 重构项 1
- **位置**：[文件路径]:[行号范围]，[函数/类/模块名称]
- **问题**：[描述当前存在的问题，标注坏味道类型]
- **方案**：[推荐的重构手法名称]
- **重构前**：
  [重构前的关键代码片段]
- **重构后**：
  [重构后的关键代码片段]
- **参考**：[参考资源]中的相关规则（如果涉及）

### 重构项 2
...
```

## 标准重构流程

### 步骤 1：确保测试覆盖

**目的**：建立安全网，确保重构不会破坏现有功能。

**执行动作**：
1. 检查现有测试覆盖率
2. 如果覆盖率不足（建议 >70%），优先为核心逻辑补充测试
3. 运行全部测试，确保基线状态为绿色

**验证标准**：所有现有测试通过，关键路径有测试覆盖。

#### 无测试环境时的处理

当无法执行测试（如缺少依赖、环境未配置）时，可暂时跳过测试执行，但必须：

**风险告知**：
- ⚠️ 重构可能引入隐藏的回归问题
- ⚠️ 无法验证行为一致性
- ⚠️ 可能破坏现有功能

**替代验证方式**：
1. **静态检查**：运行 linter、类型检查器（如 mypy、eslint、staticcheck）
2. **代码审查**：人工对比重构前后代码逻辑
3. **编译验证**：确保代码可编译/解析无误

**后续验证建议**：
1. 在重构报告中明确标注"未执行测试验证"
2. 列出需要在真实环境中验证的测试用例
3. 建议用户在有测试环境后优先执行验证
4. 提供回滚方案（如 git revert 命令）

### 步骤 2：识别代码坏味道

**目的**：系统性地发现代码中的问题点。

**执行动作**：
1. 阅读代码，识别存在的坏味道
2. 记录每个坏味道的位置、类型和严重程度
3. 按优先级排序：先处理影响最大的问题

**常见坏味道快速参考**：

| 坏味道 | 说明 | 优先级 |
|--------|------|--------|
| 重复代码 | 相同代码出现在多处 | 高 |
| 过长函数 | 方法超过20-30行 | 高 |
| 过大类 | 类承担过多职责 | 中 |
| 过长参数列表 | 参数超过3-4个 | 中 |
| 数据泥团 | 多个数据项经常一起出现 | 中 |
| 特性依恋 | 方法对其他类数据更感兴趣 | 中 |
| Switch语句 | 复杂的条件分支 | 中 |

### 步骤 3：选择重构手法

**目的**：为每个坏味道匹配合适的重构手法。

**执行动作**：
1. 根据坏味道类型选择对应重构手法
2. 评估重构手法的风险和收益
3. 选择最适合当前上下文的手法

**常见映射关系**：

| 坏味道 | 推荐重构手法 |
|--------|-----------|
| 重复代码 | 提取方法、提取超类 |
| 过长函数 | 提取方法、以查询取代临时变量 |
| 过大类 | 提取类 |
| 过长参数列表 | 引入参数对象 |
| 特性依恋 | 移动方法 |
| Switch语句 | 以多态取代条件表达式 |

### 步骤 4：小步执行重构

**目的**：安全地执行重构，每一步都可验证。

**执行动作**：
1. 按优先级选择一个重构项
2. 执行单个重构手法，遵循原则：
   - 一次只做一个改动
   - 保持代码可编译/可运行状态
   - 每步改动后立即运行测试

**验证标准**：每一步后测试通过，代码可正常运行。

### 步骤 5：审视与进一步优化

**目的**：检查重构效果，发现新的优化机会。

**执行动作**：
1. 审视重构后的代码结构
2. 检查是否有新的坏味道产生
3. 如发现新问题，返回步骤2继续迭代

### 步骤 6：验证行为一致性

**目的**：确保重构未改变代码的外部行为。

**执行动作**：
1. 运行完整的测试套件，确保全部通过
2. 对于关键功能，进行手动验证
3. 如有性能敏感代码，进行性能对比测试

**验证标准**：所有测试通过，功能行为与重构前一致，无新增的警告或错误。

## 参考资源

### 项目代码风格规范

重构后的代码必须符合项目代码风格规范：

| 文件 | 内容 | 适用场景 |
|------|------|----------|
| [cpp-coding-style-guide.md](references/cpp-coding-style-guide.md) | C++ 编程规范 | 重构 C++ 代码时 |
| [python-coding-style-guide.md](references/python-coding-style-guide.md) | Python 编程规范 | 重构 Python 代码时 |
| [go-coding-style-guide.md](references/go-coding-style-guide.md) | Go 编程规范 | 重构 Go 代码时 |

### 重构知识参考

| 文件 | 内容 | 加载时机 |
|------|------|----------|
| [code-smells.md](references/code-smells.md) | 22种坏味道详解 | 需要识别特定坏味道时 |
| [refactoring-techniques.md](references/refactoring-techniques.md) | 25种重构手法 | 需要执行特定重构时 |

## 检查清单

### 重构前

- [ ] 是否有足够的测试覆盖？
- [ ] 是否理解要重构的代码？
- [ ] 是否有清晰的重构目标？

### 重构中

- [ ] 是否每次只做一个改动？
- [ ] 是否每步都运行测试？
- [ ] 是否保持代码可编译/可运行？

### 重构后

- [ ] 所有测试是否通过？
- [ ] 功能行为是否保持不变？
- [ ] 是否符合项目的代码规范？

## 输出报告

重构完成后，输出重构报告，报告内容包括：

1. **重构摘要**：重构项数量、涉及文件、代码行变化
2. **重构详情**：每个重构项的问题、方案、前后对比
3. **验证结果**：测试执行情况、静态检查结果
4. **重构效果**：重构前后的效果对比
5. **后续建议**：发现的潜在优化点、技术债清单