name: qa-refactoring description: “安全重构遗留或复杂代码库：在改进结构、减少技术债务和加强质量门的同时保留行为。用于特性测试、接缝/适配器、增量重构循环、绞杀者迁移、重构PR大小调整和CI护栏（lint/类型/合同测试）。”

QA重构安全

使用此技能安全重构：保留行为、降低风险，并在提高可维护性和交付速度的同时保持CI绿色。

默认：首先建立基线，然后执行最小安全步骤，并通过测试/合同/可观测性证明，而非直觉。

快速开始（10分钟）

确认基线：main分支绿色；复现必须保留的行为。
选择边界：API表面、模块边界、数据库边界或请求处理程序。
添加安全网：在该边界添加特性/合同/集成测试。
微步骤重构：每个提交/PR块一个行为保留的更改。
证明：本地运行最小相关套件，然后完整CI；保持失败确定。

核心QA（默认）

安全重构循环（行为优先）

建立基线：获取main绿色；复现必须保留的行为。
定义不变式：输入/输出、错误模式、权限、数据形状、性能预算。
添加安全网：围绕将接触的边界编写特性/合同/集成测试。
创建接缝：引入注入点/适配器以隔离副作用和外部依赖。
微步骤重构：一次一个行为保留的更改；保持差异可审查。
证明：本地运行最小相关套件，然后完整CI；保持失败可调试和确定。
安全发布：当重构触及生产关键路径时，使用金丝雀/暗启动/功能标志。

风险级别（选择安全网）

风险	示例	最小所需安全网
低	重命名、提取方法、仅格式化	单元测试 + lint/类型检查
中	跨模块移动逻辑、依赖反转	单元 + 边界集成/合同测试
高	认证/权限路径、并发、迁移、金钱/数据丢失路径	集成 + 合同测试、可观测性检查、金丝雀 + 回滚计划

重构测试策略

优先在边界周围使用合同和集成测试以保留行为。
仅当输出稳定且经过审查时使用快照/黄金主副本（避免“批准一切”循环）。
对于不变式，考虑基于属性的测试或表驱动案例（输入、边界情况、错误模式）。
避免将E2E/UI测试作为重构的主要安全网；保持大部分安全在UI以下。
对于不稳定区域：首先修复确定性（种子、时间、顺序、网络）再信任结果。

CI经济性和调试人体工程学

保持重构PR小且可审查；避免在一个PR中混合重构和功能。
要求测试守护重构的失败工件（日志、跟踪ID、确定性种子、复现步骤）。
减少差异噪音：隔离仅格式化更改（或一次性应用格式化到整个仓库并获得同意）。
保持git bisect可行：除非必要，避免混合“机械 + 语义”更改。

做 / 避免

做：

在重构高风险区域前添加缺失测试。
添加护栏（linter、类型检查、合同检查、静态分析/安全检查）使重构不会静默破坏接口。
当需要安全交换实现时，优先“抽象分支”/适配器。

避免：

将大型结构重构与行为更改结合。
使用不稳定的E2E作为重构的主要安全网。

快速参考

任务	工具/模式	命令/方法	何时使用
长方法（>50行）	提取方法	拆分为更小函数	单个方法做太多
大类（>300行）	拆分类	创建专注单一职责类	上帝对象做太多
重复代码	提取函数/类	DRY原则	多个地方相同逻辑
复杂条件	用多态替换条件	使用继承/策略模式	基于类型的switch语句
长参数列表	引入参数对象	创建DTO/配置对象	函数参数>3个
遗留代码现代化	特性测试 + 绞杀者模式	先写测试，增量迁移	无测试，旧代码库
自动化质量门	ESLint、SonarQube、Prettier	`npm run lint`、CI/CD流水线	防止质量回归
技术债务跟踪	SonarQube、CodeClimate	跟踪趋势 + 热点	优先重构工作

决策树：重构策略

代码问题：[重构场景]
    ├─ 检测到代码异味？
    │   ├─ 重复代码？ → 提取方法/函数
    │   ├─ 长方法（>50行）？ → 提取更小方法
    │   ├─ 大类（>300行）？ → 拆分为专注类
    │   ├─ 长参数列表？ → 参数对象
    │   └─ 特性羡慕？ → 将方法移近数据
    │
    ├─ 遗留代码（无测试）？
    │   ├─ 高风险？ → 先写特性测试
    │   ├─ 需要大型重写？ → 绞杀者模式（增量迁移）
    │   ├─ 未知行为？ → 特性测试 + 小重构
    │   └─ 生产系统？ → 金丝雀部署 + 监控
    │
    ├─ 质量标准？
    │   ├─ 新项目？ → 设置linter + 格式化器 + 质量门
    │   ├─ 现有项目？ → 添加预提交钩子 + CI检查
    │   ├─ 复杂度问题？ → 设置圈复杂度限制（<10）
    │   └─ 技术债务？ → 跟踪在注册表，20%冲刺容量

操作深度探讨

共享基础

…/software-clean-code-standard/references/clean-code-standard.md - 规范清洁代码规则（CC-*）用于引用
遗留代码手册：…/software-clean-code-standard/references/code-quality-operational-playbook.md - RULE-01–RULE-13、决策树和操作程序
…/software-clean-code-standard/references/refactoring-operational-checklist.md - 重构异味到动作映射、安全重构护栏
…/software-clean-code-standard/references/working-effectively-with-legacy-code-operational-checklist.md - 接缝、特性测试、增量迁移模式

技能特定

查看references/operational-patterns.md获取详细重构目录、自动化质量门、技术债务手册和遗留现代化步骤。

模板

使用assets/中的复制粘贴模板用于清单和质量门配置：

重构：assets/process/refactoring-checklist.md, assets/process/code-review-quality.md
技术债务：assets/tracking/tech-debt-register.md
质量门：assets/quality-gates/javascript/eslint-config.js, assets/quality-gates/platform-agnostic/sonarqube-setup.md

资源

使用references/中的深度指南（按需加载）：

操作模式：references/operational-patterns.md - 核心重构目录、质量门和遗留现代化
重构目录：references/refactoring-catalog.md
代码异味指南：references/code-smells-guide.md
技术债务管理：references/tech-debt-management.md
遗留代码现代化：references/legacy-code-strategies.md

可选：AI / 自动化

做：

使用AI提议机械重构（重命名/提取/移动），仅当你能通过测试和合同证明行为保留时。
使用AI总结差异和风险热点；通过运行目标特性测试验证。
当可用时，优先工具辅助重构（IDE/编译器感知、代码修改）而非自由文本编辑。

避免：

接受未明确要求且无回归测试的行为更改重构。
让AI通过削弱断言使CI绿色来“修复测试”。

查看data/sources.json获取精选外部引用。

QA重构安全 qa-refactoring