| name | code-refactoring |
| description | 系统化、安全地代码重构技能。能够识别代码坏味道、提供重构手法，支持制定计划、执行重构并验证结果。适用于代码质量提升、技术债清理、可维护性改进、代码优化、代码改进等场景。当用户请求重构代码、优化代码质量、修复代码问题或清理技术债时触发。 |
代码重构技能
本技能提供系统化、安全的代码重构指导，帮助改善既有代码的内部结构而不改变其外部行为。
核心原则
- 先测试，后重构：确保有足够的测试覆盖再开始重构
- 小步前进：每次只做一个小的重构动作，立即验证
- 保持行为不变：重构不应改变代码的外部行为
- 持续验证：每一步重构后都要运行测试验证
- 风格符合：重构的代码应符合项目规范
重构计划输出格式
在执行任何重构前，必须先输出详细的重构计划，格式如下：
## 重构计划
### 重构项 1
- **位置**：[文件路径]:[行号范围]，[函数/类/模块名称]
- **问题**：[描述当前存在的问题，标注坏味道类型]
- **方案**：[推荐的重构手法名称]
- **重构前**：
[重构前的关键代码片段]
- **重构后**：
[重构后的关键代码片段]
- **参考**：[参考资源]中的相关规则（如果涉及）
### 重构项 2
...
标准重构流程
步骤 1：确保测试覆盖
目的：建立安全网，确保重构不会破坏现有功能。
执行动作：
- 检查现有测试覆盖率
- 如果覆盖率不足（建议 >70%），优先为核心逻辑补充测试
- 运行全部测试，确保基线状态为绿色
验证标准：所有现有测试通过，关键路径有测试覆盖。
无测试环境时的处理
当无法执行测试（如缺少依赖、环境未配置）时，可暂时跳过测试执行，但必须：
风险告知：
- ⚠️ 重构可能引入隐藏的回归问题
- ⚠️ 无法验证行为一致性
- ⚠️ 可能破坏现有功能
替代验证方式：
- 静态检查：运行 linter、类型检查器（如 mypy、eslint、staticcheck）
- 代码审查：人工对比重构前后代码逻辑
- 编译验证：确保代码可编译/解析无误
后续验证建议：
- 在重构报告中明确标注"未执行测试验证"
- 列出需要在真实环境中验证的测试用例
- 建议用户在有测试环境后优先执行验证
- 提供回滚方案（如 git revert 命令）
步骤 2：识别代码坏味道
目的：系统性地发现代码中的问题点。
执行动作：
- 阅读代码，识别存在的坏味道
- 记录每个坏味道的位置、类型和严重程度
- 按优先级排序：先处理影响最大的问题
常见坏味道快速参考：
| 坏味道 | 说明 | 优先级 |
|---|
| 重复代码 | 相同代码出现在多处 | 高 |
| 过长函数 | 方法超过20-30行 | 高 |
| 过大类 | 类承担过多职责 | 中 |
| 过长参数列表 | 参数超过3-4个 | 中 |
| 数据泥团 | 多个数据项经常一起出现 | 中 |
| 特性依恋 | 方法对其他类数据更感兴趣 | 中 |
| Switch语句 | 复杂的条件分支 | 中 |
步骤 3：选择重构手法
目的：为每个坏味道匹配合适的重构手法。
执行动作：
- 根据坏味道类型选择对应重构手法
- 评估重构手法的风险和收益
- 选择最适合当前上下文的手法
常见映射关系：
| 坏味道 | 推荐重构手法 |
|---|
| 重复代码 | 提取方法、提取超类 |
| 过长函数 | 提取方法、以查询取代临时变量 |
| 过大类 | 提取类 |
| 过长参数列表 | 引入参数对象 |
| 特性依恋 | 移动方法 |
| Switch语句 | 以多态取代条件表达式 |
步骤 4：小步执行重构
目的：安全地执行重构，每一步都可验证。
执行动作：
- 按优先级选择一个重构项
- 执行单个重构手法，遵循原则：
- 一次只做一个改动
- 保持代码可编译/可运行状态
- 每步改动后立即运行测试
验证标准：每一步后测试通过，代码可正常运行。
步骤 5：审视与进一步优化
目的：检查重构效果，发现新的优化机会。
执行动作：
- 审视重构后的代码结构
- 检查是否有新的坏味道产生
- 如发现新问题，返回步骤2继续迭代
步骤 6：验证行为一致性
目的：确保重构未改变代码的外部行为。
执行动作：
- 运行完整的测试套件，确保全部通过
- 对于关键功能，进行手动验证
- 如有性能敏感代码，进行性能对比测试
验证标准：所有测试通过，功能行为与重构前一致，无新增的警告或错误。
参考资源
项目代码风格规范
重构后的代码必须符合项目代码风格规范：
重构知识参考
检查清单
重构前
重构中
重构后
输出报告
重构完成后，输出重构报告，报告内容包括：
- 重构摘要：重构项数量、涉及文件、代码行变化
- 重构详情：每个重构项的问题、方案、前后对比
- 验证结果：测试执行情况、静态检查结果
- 重构效果：重构前后的效果对比
- 后续建议：发现的潜在优化点、技术债清单
