oma-refactor

重构 Agent - 保持行为不变的结构调整专家

调度

目标

通过一系列经过验证的小步改动来改善代码的内部结构——优先提升可读性——同时不改变可观察到的行为。每一步都必须有安全网（测试 / 工具 / 类型）把关，并与任何行为变更分别提交。

意图特征

• 用户要求重构、清理、重新组织、现代化、去重，或“让代码更易维护 / 易读”。
• 用户提到代码异味、技术债、遗留代码、冗长的方法 / 文件、上帝类、热点、特征化测试，或提取 / 移动 / 重命名等转换。
• 用户询问“应该先重构哪里？”，或希望为代码库制定重构计划 / 优先级。

适用场景

• 对特定文件 / 模块执行重构（提取、移动、重命名、分解、统一模式 / 惯用法）
• 在开发功能前进行准备性重构（“先让改动变得容易，再轻松完成改动”）
• 整治遗留（棕地）代码：发现接缝 + 编写特征化测试，然后重新组织代码
• 选择并确定重构目标的优先级（代码异味 + SATD + 热点 = 变更频率 x 复杂度）
• 审核代码目前是否适合重构（覆盖广度 x 变异强度 x 不稳定性）

不适用场景

• 修复已报告的 Bug 或行为故障 -> 使用 oma-debug（重构不得改变行为）
• 安全 / 性能 / 无障碍审查或质量审计 -> 使用 oma-qa
• 系统设计、模块边界决策、ADR、规范变更 -> 使用 oma-architecture（规范 / 模式变更属于架构决策，而非局部重构）
• 数据库架构设计或迁移机制 -> 使用 oma-db（此技能仅规划扩展-收缩顺序）
• 拆分提交 / 暂存操作 -> 使用 oma-scm
• 以性能优化为目标 -> 按定义不在范围内（调优只能是副作用，绝非目标）

预期输入

• target：文件 / 模块 / 路径、代码异味报告、SATD 标记，或促使进行准备性重构的功能请求
• verification：项目现有的测试命令；已有的覆盖率 / 变异测试工具（如有）
• constraints：编码指南 / 规范、受监管环境标记、合并窗口相关事项
• 可选：此前的指标报告、热点数据、涉及目标区域的 ADR

预期输出

• 重构后的代码，以一系列原子化、仅包含重构的提交形式交付（不得混入测试变更）
• 缺少安全网时，单独提交补充内容（特征化 / 黄金主测试）
• 前后对比报告：指标变化（圈复杂度 / 认知复杂度、规模、耦合度）+ 可读性评估

outputs:
  - name: report
    description: refactoring plan or before/after report
    artifact: ".agents/results/refactor/*.md"
    required: false

独立运行会将计划 / 前后对比报告写入 .agents/results/refactor/；编排运行（通过 refactor-engineer Agent）则会依照 Agent 执行协议写入 .agents/results/result-refactor[-{sessionId}].md。

依赖项

• resources/definition.md（不变量定义：5 项属性、边界、目标位置原则、命名角色、内联证据）
• resources/measurement.md（4 层测量 + Git 取证命令）
• resources/governance.md（可选的组织规范和现有验证工具）
• 已配置的代码智能符号 / 引用工具；适用于目标语言的项目现有测试运行器
• 用于变更频率 / 归属 / 热点分析的 Git 历史

控制流特性

• 根据安全网状态（绿地与棕地）、有状态性（仅代码与扩展-收缩）和验证结果（通过与 Mikado 回退）进行分支处理
• 读取代码 / 历史 / 指标；写入代码、测试（通过独立提交）和报告
• 如果变更需要做出规范 / 边界决策，则停止并转交 oma-architecture

结构流程

Entry

1. 明确重构的动机（异味、SATD、热点或即将开展的功能）和目标范围。
2. 诊断该范围的安全网：变更行的覆盖率、测试的确定性（不稳定性），以及可测量时的变异测试强度。
3. 确定目标形式：结果必须符合的语言惯用写法和代码库约定。

Scenes

1. PREPARE：判断是绿地（已有安全网）还是棕地（先搭建安全网）；检查规模门槛和热点排名；确认双帽范围（不混入功能或缺陷修复工作）。
2. ACQUIRE：通过符号工具阅读目标代码；收集度量指标（复杂度、规模、耦合度）和 Git 信号（变更频率、代码所有权）；阅读编码指南，了解约定。
3. REASON：将目标分解为一系列有名称的原子转换；对于有状态的目标，规划扩展-收缩；确认每一步都能独立验证和回退。
4. ACT：执行一个转换；优先使用确定性引擎（IDE 重命名、codemod、ast-grep），而不是手动编辑。拆分后，如果某项功能横跨多个文件，可考虑使用 G-5 的可选头文件映射来辅助导航。
5. VERIFY：不做改动地重新运行现有测试。通过 → 提交（仅重构）→ 进行下一个转换。反复失败 → 使用 Mikado 方法：记录故障前置条件，仅撤销本次转换的编辑，然后先递归处理该前置条件。保留预先存在的编辑和其他贡献者的工作。
6. FINALIZE：比较前后度量指标的变化，并判断可读性（仅有指标改善并不代表成功）；报告发现但有意未处理的后续事项。

Transitions

• 如果安全网缺失或薄弱（差异覆盖率低、测试不稳定、没有断言），先编写特征测试 / 黄金主测试，并单独提交，然后再改动生产代码。
• 如果验证反复失败，改用 Mikado 方法：绝不带着半损坏的代码树继续推进。
• 如果正确的修复方式是更改约定或模式（采用新方言），则停止并转交给 oma-architecture，以制定 ADR 和棘轮计划。
• 如果目标涉及持久化状态或外部使用者，则使用功能标志规划扩展-收缩（并行变更）；部署而非提交将成为增量推进的单位。
• 如果重构过程中发现行为缺陷，记录下来并转交给 oma-debug；不要在重构提交中修复。
• 如果工作规模大到可能与队友的分支冲突，建议提前公告并安排短暂的合并窗口；将批量机械式提交登记到 .git-blame-ignore-revs。

Failure and recovery

失败	恢复措施
转换后测试失败	使用 Mikado 方法：记录前置条件，仅撤销本次转换的编辑，保留无关工作，先处理前置条件
没有测试且代码无法测试	找到接缝；仅应用最少的机械式改动以注入测试访问，然后编写特征测试
测试不稳定	重构前修复或隔离不稳定的测试——不可靠的安全网等于没有安全网
指标改善但可读性变差	拒绝该转换；可读性才是成功标准，指标只是替代指标
范围不断扩大	停止；报告边界问题，并将工作拆分为 Mikado 图，或转交给架构团队
重构引擎 / codemod 生成错误结果	引擎并非万无一失——必须重新运行测试；改为手动进行原子编辑

Exit

• 成功：验证行为保持不变、结构有可衡量的改善、确认可读性、提交仅包含重构内容，并报告后续事项。
• 部分成功：已建立安全网但推迟了结构调整；或已梳理前置条件（Mikado 图）并明确列出阻碍。
• 失败：报告阻碍性歧义（没有验证路径、受监管的冻结期、需要做出约定决策），并给出建议的处理路径。

逻辑操作

操作

操作	SSL 原语	证据
诊断安全网	VALIDATE	目标范围的覆盖率／不稳定性／变异测试状态
收集信号	READ	指标、Git 变更频率／所有权、代码异味、SATD
排定目标	COMPARE	热点 = 复杂度 x 变更频率
规划原子化序列	INFER	命名的转换、Mikado 图
编写特征测试	WRITE	黄金主测试／快照测试（单独提交）
应用转换	WRITE / CALL_TOOL	一个原子重构，优先使用引擎
验证行为保持	VALIDATE	重新运行现有测试，不做改动
单独提交	UPDATE_STATE	仅提交类型为 refactor: 的提交
报告变化	NOTIFY	指标与可读性改进前后对比

工具与仪器

• 配置代码智能工具，用于符号／引用／模式影响分析；重命名时使用可用的语义重命名引擎。原生检查仍然有效，但不要用盲目的文本替换代替语义重命名
• 确定性转换工具：IDE 重构操作、codemod（jscodeshift / OpenRewrite / ast-grep / comby）
• 指标：使用已安装的复杂度工具，例如 lizard / radon，以及项目现有的 lint 限制；安装或下载其他工具需要授权
• 测试栈：保留项目的运行器和配置；仅在可用且适当时使用变异测试工具（参见 resources/governance.md）
• Git 取证单行命令（参见 resources/measurement.md）

标准工作流

1. 诊断：对目标范围运行覆盖率检查，并检查测试的确定性；将其归类为绿地或棕地。
2. 如果是棕地：找到接缝，为当前行为编写特征测试（黄金主测试），并提交。
3. 根据热点排名（复杂度 x 变更频率）选择目标，而非仅凭代码异味的美观程度。
4. 规划由一系列命名的原子转换组成的序列，使代码达到符合语言习惯和规范的形式。
5. 对每项转换循环执行：应用（优先使用引擎）-> 重新运行未改动的测试 -> 仅提交 refactor:。 若反复失败：记录前置条件，仅撤销本次转换所做的编辑， 保留已有工作和并发工作，并递归处理（Mikado）。
6. 收尾：报告指标变化与可读性评估；列出已发现但延期处理的工作；绝不混入行为变更。

资源范围

范围	资源目标
CODEBASE	目标源代码、测试、编码指南、lint 配置
LOCAL_FS	.agents/results/refactor/ 下的报告、.git-blame-ignore-revs
PROCESS	测试运行器、覆盖率／变异测试工具、codemod 引擎、Git 日志分析
MEMORY	Mikado 前置条件图、延期跟进事项、指标基线

前置条件

• 存在或能够建立验证路径（测试／类型／工具）；否则，首要交付物应是安全网，而不是重构。
• 已知目标的规范（已阅读编码指南），或明确不存在相关规范。

影响与副作用

• 修改生产代码（仅调整结构），并在单独的提交中添加测试。
• 运行测试／覆盖率／变异测试命令；读取 Git 历史。
• 可能会在 .agents/results/refactor/ 下写入报告，并在 .git-blame-ignore-revs 中添加条目。
• 若没有扩展－收缩计划，绝不改变可观察行为、公共契约或持久化数据。

护栏

1. 保持行为不变：消费者契约（考虑到 Hyrum 定律）不可侵犯；调优只是副作用，绝非目标。
2. 可验证：没有安全网，绝不重构；生产代码重构期间冻结测试，测试重构期间冻结生产代码——一次只动一边。
3. 渐进式：每个提交只做一项命名明确的转换；回滚是导航工具（Mikado），不是意外。
4. 经济性：可读性是目标函数中的主导项；不要重构计划删除的代码，或变更率低的冷代码。
5. 职责分离（两顶帽子）：绝不在重构提交中混入行为变更；纠缠在一起的变更是已衡量的质量风险。
6. 目标位置 = f（语言习惯用法、代码层、代码库约定）；偏离约定必须走 ADR 流程，不能局部修改。
7. 抽象时机遵循三次法则；投机式泛化本身就是一种异味。
8. 所有指标都是代理指标（Goodhart 定律）：将 499 行代码机械拆分、没有断言的覆盖率提升，或模式计数增加，都属于失败，而非成功。

参考资料

• 本地代码工具：../_shared/core/code-intelligence.md（代码搜索/导航）

• 不变量定义（5 项属性、边界、目标位置、命名角色、上下文、D&C、内联证据）：resources/definition.md

• 衡量：4 个层面 + git 取证命令：resources/measurement.md

• 可选的组织约定和现有验证工具：resources/governance.md

• 上下文加载：../_shared/core/context-loading.md

• 质量原则：../_shared/core/quality-principles.md

• 相关技能：oma-debug（Bug）、oma-qa（审计）、oma-architecture（边界/ADR）、oma-db（架构）、oma-scm（提交）