code-refactoring

代码重构

当任务是在不改变预期行为的前提下改进结构时，使用此技能。

此技能的核心应保持精简且可重复：

1. 确认当前实际要处理的清理任务包，
2. 选择一种重构模式，
3. 明确行为护栏，
4. 将工作拆分为便于审查的阶段，
5. 验证并如实说明剩余工作该如何处理。

处理不熟悉的清理工作前，请阅读以下支持文档：

• references/intake-packets-and-route-outs.md
• references/refactor-modes.md
• references/handoff-boundaries.md
• references/safe-refactor-checklist.md

何时使用此技能

• 函数、组件、服务、脚本或模块过于纠缠，需要在不改变行为的前提下清理结构。
• 需要先冻结行为，再清理脆弱或理解不足的旧代码区域。
• 相同的 API、命名或结构变更在多个文件中反复出现，需要 codemod / 迁移说明。
• 差异中混入了过多语义层面的工作，需要拆分为更小、更便于审查的部分。
• 用户要求重构、分解、去重、安全重命名、分阶段清理，或规划保留行为的迁移。

何时不使用此技能

• 主要任务是证明行为为何出错、复现故障或定位回归问题 → debugging
• 主要任务是判断具体差异 / PR 是否可以安全合并 → code-review
• 主要任务是选择组织范围的验证深度、基准测试策略或发布门槛 → testing-strategies
• 主要任务是根据跟踪数据、火焰图、CWV 报告或分析器输出来查找瓶颈 → performance-optimization
• 主要任务是在选择任何清理策略前查找符号、调用点或影响范围 → codebase-search

指令

第 1 步：从清理任务包入手

使用 references/intake-packets-and-route-outs.md。

选择用户已有的任务包：

• 一个杂乱的文件 / 组件 / 服务
• 当前行为可信度较低的脆弱旧代码区域
• 跨多个文件重复出现的迁移模式
• 需要在审查前重新整理的、以清理工作为主的差异
• 只有“先找出所有位置”的模糊需求

简要输出任务接收信息：

## Cleanup Packet
- Current artifact:
- Why it is enough (or not enough):
- Missing evidence to collect next:

规则：如果眼下只需要搜索、诊断、审查或性能证据，不要强行制定庞大的重构计划。

第 2 步：选择一种主要重构模式

从 references/refactor-modes.md 中恰好选择一种主要模式。

主要模式：

• local-safe-refactor
• behavior-freeze-first
• repetitive-migration-codemod
• diff-shaping-cleanup

快速选择：

信号	模式
单个文件或范围较小的模块，意图明确，且至少存在一个快速护栏	local-safe-refactor
脆弱的旧代码区域，包含隐藏不变量，测试可信度较低	behavior-freeze-first
相同的 API 或结构在多个文件中重复出现	repetitive-migration-codemod
清理工作混入有风险的审查差异，需要拆分为更小的部分	diff-shaping-cleanup

规则：只选一种主要模式，可附加一条次要说明。不要在同一个回答中混用所有清理策略。

第 3 步：冻结行为护栏

大范围修改前，先确定如何证明预期行为保持不变。

护栏来源可以包括：

• 现有的单元测试 / 集成测试 / 端到端测试
• 类型检查和代码检查
• 特征测试或已捕获的示例
• 测试夹具快照或黄金输出
• UI 工作的屏幕截图 / 预览截图
• 修改前后样例输入输出表
• 自动化覆盖不足时的手动冒烟测试步骤

最低要求：

• 局部清理 → 至少一种快速验证方式
• 脆弱的旧代码清理 → 先冻结行为
• 重复迁移 → 先在少量有代表性的样本上试点
• 差异重塑 → 将机械清理与语义层面的后续修改分开

如果用户主要需要帮助设计完整的验证方案，请转交给 testing-strategies。

第 4 步：制定最小且可信的清理计划

让计划便于审查。

建议的切分方式：

1. 重命名 / 移动 / 提取工作
2. 清理重复代码或死代码
3. 机械迁移或代码修改工具的推广
4. 仅在仍有需要时进行语义层面的后续修改
5. 验证 + 交接

对每个切分部分，记录：

• 目标
• 需要保持不变的行为
• 证据 / 护栏
• 风险点
• 下一步是否由其他技能负责

规则：

• 优先采用一系列平稳、易审查的差异，而不是一次大刀阔斧的重写。
• 尽可能将结构清理与语义行为变更分开。
• 对于迁移，在扩大规模前定义源模式、目标模式、已知例外和回滚路径。

第 5 步：使用合适的模式说明

使用 references/intake-packets-and-route-outs.md 中匹配的说明：

• 局部清理说明
• 脆弱旧代码 / 先冻结行为说明
• 重复迁移 / 代码修改工具说明
• 差异整形说明

各模式的有效做法：

• local-safe-refactor → 重命名含义不清的概念、提取纯逻辑、将副作用移至边界、合并高度相似的重复代码
• behavior-freeze-first → 捕获示例、添加特征测试、找出一个接缝，在该接缝后进行重构
• repetitive-migration-codemod → 定义源模式 / 目标模式，先抽样，检查误报，只有在试点结果可信后才扩大范围
• diff-shaping-cleanup → 将清理与语义变更分开，隔离生成的或机械修改的内容，并留下审查备注，指出尚存的热点问题

第 6 步：验证并转交剩余工作

不要以“看起来更整洁”作为结束。

验证摘要：

## Refactor Brief
- Primary mode:
- Behavior to preserve:
- Guardrail used:
- Smallest planned slices:
- Risks still open:
- Recommended next move:

务必说明：

• 预期保持不变的行为
• 用于验证的证据
• 仍有风险或超出范围的内容
• 工作方向改变时，下一步应由哪个相邻技能负责

输出格式

## Cleanup Packet
- Current artifact:
- Primary mode:
- Why this mode fits:

## Behavior Guardrail
- Intended behavior to preserve:
- Evidence available:
- Missing evidence:

## Planned slices
1. ...
2. ...
3. ...

## Verification
- Fast checks:
- Higher-risk checks:

## Route-outs
- Use `debugging` for:
- Use `code-review` for:
- Use `testing-strategies` for:
- Use `performance-optimization` for:
- Use `codebase-search` for:

示例

示例 1：过大的服务处理程序

输入：“将这个 180 行的结账处理程序重构得更易读，同时不改变行为。”

良好的响应形式：

• 选择 local-safe-refactor
• 明确保留优惠券 / 税费 / 缺货相关行为
• 提取验证、定价和持久化辅助函数
• 将测试 / 类型检查作为护栏
• 将结构清理与之后的语义层面修改分开

示例 2：脆弱的旧模块

输入：“这个报表服务简直无法维护，但我们几乎不相信测试。请帮我安全地重构它。”

良好的响应形式：

• 选择 behavior-freeze-first
• 在大范围清理前捕获特征用例
• 一次找出一个接缝，而不是重新设计所有内容
• 如果预期行为仍不明确，将深入的故障调查转交给 debugging

示例 3：重复的 API 迁移

输入：“在框架升级前，我们需要在 220 个 TypeScript 文件中替换一个已弃用的客户端 API。”

良好的响应形式：

• 选择 repetitive-migration-codemod
• 定义源模式和目标模式
• 先在一部分代码上试运行转换
• 将机械重写与语义层面的后续修改分开
• 通过测试、类型检查和仓库搜索进行验证

示例 4：优先搜索，明确转交

输入：“在重构任何内容之前，先找出这个旧辅助函数的所有调用位置和封装层，这样我们就能了解影响范围。”

理想回复结构：

• 将主要任务交给 codebase-search
• 不要把完整的重构计划作为主要回答
• 将 code-refactoring 定位为影响范围图绘制完成后的清理环节

最佳实践

1. 从用户实际拥有的信息包出发，而不是理想化的清理工作流。
2. 提出行动前，先选定一种主要模式。
3. 明确说明会保留原有行为；不要想当然地认为如此。
4. 优先采用小而易于审查的步骤，而不是一次性提交庞大的清理改动。
5. 只有在重复模式足以抵消准备成本时，才使用 codemod 或结构化重写。
6. 将诊断、审查判断、测试策略设计、性能调优和符号清单交给相邻技能处理，不要将其一并纳入。
7. 保留已验证内容和仍存在风险的证据。

参考资料

• 信息包与任务转交
• 重构模式
• 交接边界
• 安全重构检查清单
• Martin Fowler — 重构
• VS Code 重构文档
• IntelliJ IDEA 重构文档
• OpenRewrite 文档
• jscodeshift
• ast-grep