用途
Code Refactoring 用于在改善代码结构的同时不改变预期行为。当任务的核心是“清理结构”而不是“判断行为是否正确”或“决定 PR 是否可合并”时使用它。典型触发场景包括：某个函数、组件、服务、脚本或模块过于纠缠，需要结构性清理但不改变行为；遗留区域行为脆弱或理解不足，需要冻结优先的清理；同一个 API、命名或结构变更重复出现在大量文件中，需要 codemod 或迁移简报；一个 diff 把清理和过多语义工作混在一起，需要拆成更小的可评审切片；用户要求重构、分解、去重、安全重命名、分阶段清理或规划保持行为的迁移。
何时不使用
- 主要工作是证明行为为何错误、复现失败或定位回归 → 交给 debugging
- 主要工作是判断某个具体 diff / PR 是否可安全合并 → 交给 code-review
- 主要工作是选择组织级验证深度、基准策略或发布门禁 → 交给 testing-strategies
- 主要工作是从 trace、火焰图、CWV 报告或 profiler 输出中找瓶颈 → 交给 performance-optimization
- 主要工作是在选择清理策略前查找符号、调用点或影响范围 → 交给 codebase-search
主要能力与流程
技能的中心保持在小型、可重复的循环：确认你实际拥有的清理素材；选择一个重构模式；显式确立行为护栏；把工作分阶段为可评审切片；验证并诚实分流剩余工作。
步骤 1：从清理素材出发。 先确认用户已有的素材类型：一个杂乱文件/组件/服务；行为置信度低的脆弱遗留区域；跨多文件的重复迁移模式；需要重塑后才能评审的清理密集型 diff；或仅仅是“先找出所有位置”的模糊诉求。输出简短 intake，包括当前产物、是否足够、下一步需收集的缺失证据。规则：当即时需求只是搜索、诊断、评审或性能证据时，不要强行给出庞大的重构方案。
步骤 2：选择一个主重构模式。 从四个主模式中恰好选择一个：local-safe-refactor（单文件或窄模块、意图清晰、已至少有一个快速护栏）、behavior-freeze-first（脆弱遗留区域、隐藏不变量、测试信任度低）、repetitive-migration-codemod（同一 API 或结构重复出现在多文件）、diff-shaping-cleanup（清理混入高风险评审 diff，需要更小切片）。规则：一个主模式，可附可选的次要说明，不要把每种清理策略都塞进一个答案。
步骤 3：冻结行为护栏。 在大范围编辑前决定如何证明意图未变。护栏来源可包括：现有单元/集成/端到端测试、类型检查与 linter、特征化测试或捕获的示例、fixture 快照或黄金输出、UI 工作的截图/预览捕获、前后样本输入输出表、自动化薄弱时的手动冒烟步骤。最低规则：局部清理→至少一条快速验证路径；脆弱遗留清理→先冻结行为；重复迁移→先在小规模代表性样本上试点；diff 重塑→把机械清理与语义后续分开。
步骤 4：构建最小可信清理计划。 首选切片顺序：重命名/移动/提取；重复或死代码清理；机械迁移或 codemod 推广；仅在仍需要时做语义后续；验证与交接。每个切片记录：目标、要保留的行为、证据/护栏、风险边界、下一步是否由其他技能负责。规则：优先一系列普通 diff 而非一次英雄式重写；尽量把结构清理与语义行为变更分开；迁移前先定义源模式、目标模式、已知例外和回滚路径。
步骤 5：使用对应模式的素材包。 按模式选取对应素材包并采取良好做法：local-safe-refactor → 重命名不清晰概念、提取纯逻辑、把副作用移到边缘、合并近似重复；behavior-freeze-first → 捕获示例、添加特征化测试、一次识别一个接缝并在该接缝后重构；repetitive-migration-codemod → 定义源/目标模式、先采样、检查误报、试点可信后再扩大；diff-shaping-cleanup → 拆分清理与语义变更、隔离生成或机械编辑、留下关于剩余热点的评审备注。
步骤 6：验证并分流剩余工作。 不要止步于“看起来更干净”。始终说明：哪些行为意图保持不变、用了什么证据验证、哪些仍有风险或超出范围、任务转向时哪个相邻技能应负责下一步。
使用方式
输出格式为结构化简报，包含：Cleanup Packet（当前产物、主模式、为何该模式适合）、Behavior Guardrail（要保留的意图行为、可用证据、缺失证据）、Planned slices（编号切片列表）、Verification（快速检查、高风险检查）、Route-outs（分别标明交给 debugging、code-review、testing-strategies、performance-optimization、codebase-search 的情形）。
示例
- 过大的服务处理器：选择 local-safe-refactor，显式保留优惠券/税费/缺货行为，提取校验、定价与持久化辅助函数，以测试/类型检查作为护栏，把结构清理与后续语义工作分开。
- 脆弱遗留模块：选择 behavior-freeze-first，在大范围清理前捕获特征化用例，一次识别一个接缝而非重新设计全部，若预期行为仍不明确则把深层失败调查交给 debugging。
- 重复 API 迁移：选择 repetitive-migration-codemod，定义源与目标模式，先在子集上试点变换，把机械重写与语义后续分开，用测试、类型检查和仓库搜索验证。
- 搜索优先分流：把主任务交给 codebase-search，不要把完整重构方案作为主要答案，待影响图存在后再把重构定位为清理通道。
适用场景与限制
适用于在不改变行为前提下的结构改善、遗留区域冻结清理、跨文件重复迁移、评审 diff 切片。不适用于以诊断、评审判断、测试策略设计、性能调优或符号清点为主的场景。使用支持文档前需阅读：references/intake-packets-and-route-outs.md、references/refactor-modes.md、references/handoff-boundaries.md、references/safe-refactor-checklist.md。参考资料还包括 Martin Fowler《Refactoring》、VS Code 与 IntelliJ IDEA 重构文档、OpenRewrite 文档、jscodeshift、ast-grep。具体安装命令、收费标准与平台支持信息暂未提供。