---
name: fec-refactoring
description: 用于在不改变可观察行为的前提下重组既有前端代码，包括职责提炼、模块搬移、条件逻辑简化、API 整理和数据组织。不要用于新增功能、改变行为的缺陷修复、依赖或框架迁移，以及已经证实的死代码清理。
---

# 技能：保持行为的重构

## 用途

以小步、可验证、可回滚的方式重组仍在使用的前端代码，同时保持用户、调用方、测试、路由和集成能够观察到的行为不变。

## 核心契约

每次执行都遵守以下规则：

1. **行为保持**：纯重构只改变内部结构，不主动改变可观察行为。
2. **修改前基线**：编辑前先记录当前可用验证结果。
3. **一次只做一个主要重构**：每一步只有一个主要结构意图。
4. **每一步都验证**：完成一步后立即运行最小但有效的验证。
5. **先回滚当前步骤，再讨论修复**：若当前步骤引入回归，先恢复到上一步，再缩小或重排方案。
6. **重构与功能修改分离**：新增行为或改变行为的缺陷修复不属于纯重构。
7. **优先最小安全重构**：有局部、可逆方案时，不直接扩大为架构重写。
8. **遵守差异预算**：实际修改范围明显超出计划时必须停止并重新评估。

纯重构采用 **GREEN → REFACTOR → GREEN**，不为了形式上的 TDD 人为制造失败行为测试。

## 流程

1. 分类请求，确认目标是结构调整且要求行为保持。
2. 读取项目配置、受影响模块、公开导出、路由、状态边界、测试和当前 diff。
3. 记录相关可观察契约：输入、输出、异常、副作用、UI 状态、事件、网络请求、状态迁移、路由和公开 API。
4. 建立修改前基线；既有失败要单独记录，不能算到后续重构头上。
5. 基于证据诊断结构问题，并检查可能的误判。
6. 建立安全网：优先复用已有测试，风险较高且覆盖不足时再补当前行为的特征测试。
7. 把方案拆成有顺序的小步，每步记录手法、原因、前置条件、风险、差异预算、验证和回滚边界。
8. 每次只执行一个主要结构变换，不夹带无关清理、格式化和重新设计。
9. 立即验证，并比较实际修改范围与差异预算。
10. 若出现新回归，先回滚当前步骤，确认基线恢复，再缩小或调整顺序。
11. 最后按需要运行类型检查、测试、构建、E2E、无障碍或其他专项门禁。
12. 根据证据给出 PASS、PARTIAL 或 NOT PROVEN，不夸大验证强度。

## 风险分级

| 风险 | 常见范围 | 默认动作 |
| --- | --- | --- |
| `SAFE` | 局部私有代码、契约稳定、容易回滚 | 可执行，并逐步验证 |
| `CAUTION` | 跨模块、共享状态、导入、Hook/Composable、生命周期 | 安全证据充分时执行，否则先规划 |
| `DANGER` | 公开 API、路由、持久化、网络契约、认证、SSR/水合、大范围状态或继承改造 | 默认先规划并停止等待明确授权 |

风险由上下文决定，不能只凭手法名称判定安全级别。

## 差异预算

每个可执行步骤先写清：

```text
预期文件数：N
预期函数/组件数：N
预期公开 API 变化：0
预期行为变化：0
```

如果实际 diff 明显超出预算，停止并重新评估，不能静默扩大成重新设计。

## 参考资料

- 安全规则、证据模型和风险语言见 [principles.md](references/principles.md)。
- 状态机、基线、回滚和报告契约见 [workflow.md](references/workflow.md)。
- 判断何时重构或何时延后见 [when-to-refactor.md](references/when-to-refactor.md)。
- 区分重构、功能、缺陷、清理、迁移和评审见 [refactoring-vs-feature-change.md](references/refactoring-vs-feature-change.md)。

## 约束

- 不修改测试来接受被重构意外改变的业务行为。
- 未有充分证据时，不把认证、权限、路由、持久化、协议或公开包契约变化标为 `SAFE`。
- 当前步骤出现新失败后，不继续叠加结构修改。
- 项目没有测试框架时，不自动安装新框架。
- 行数、复杂度、注释、一个 switch 或链式调用都不能单独证明存在坏味道。
- 默认不执行远程 Git 写入。

## 预期输出

输出带证据、风险、差异预算、逐步验证和必要回滚记录的重构方案或实现，并给出 PASS、PARTIAL 或 NOT PROVEN 的行为保持结论。