oma-refactor

重构 Agent——保持行为的结构调整专家

调度

目标

改进代码内部结构，优先提升可读性，同时不改变可观察到的行为；通过小步验证的转换逐步完成，每一步都由安全网（测试 / 工具 / 类型）把关，并与任何行为变更分开提交。

意图特征

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

适用场景

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

不适用场景

• 添加或完成用户已要求的行为 → 使用合适的现有实现技能；先根据 Entry 判断范围。
• 修复已报告的缺陷或行为异常 → 使用 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 历史记录

控制流特性

• 根据安全网状态（绿地 vs 棕地）、有状态性（仅代码 vs 扩展-收缩）和验证结果（通过 vs Mikado 回退）进行分支
• 读取代码 / 历史记录 / 指标；编写代码、测试（分别提交）和报告
• 当变更需要规范 / 边界决策时停止并转交 oma-architecture

结构流程

入门

1. 根据实际目标代码对请求的结果进行分类，而不是只看“重构”一词。保持行为不变的结构调整属于此处。请求中已包含的实现或 Bug 修复，应继续使用相应的现有实现技能或 oma-debug，遵循现有授权，无需重新审批。对于混合请求，区分行为变更与结构调整，并仅对后者应用此技能。
2. 对重构范围，明确其动机并诊断安全网：变更行的覆盖率、测试确定性（不稳定性），以及可测量时的变异强度。
3. 确定目标形式：结果必须符合的语言惯用法和代码库约定。

缺少代码或代码只是存根，本身并不授权新增行为。若没有可供调整的实现，纯重构应报告缺少目标，而不是凭空创造目标。若检查现有任务和项目证据后，正确性所需的某项契约事实仍不明确，应根据共享执行策略和澄清流程，就该具体事实提出询问。区分信息缺失与授权缺失：保留现有权限，仅暂停依赖该信息的工作，并继续其他已获授权的工作。

阶段

1. 准备：在重构范围内，分类为绿地（已有安全网）或棕地（先构建安全网）；检查规模门槛和热点排名；确认双帽范围（不混入功能或 Bug 工作）。
2. 获取：通过符号工具阅读目标代码；收集度量指标（复杂度、规模、耦合度）和 Git 信号（变更频率、所有权）；阅读编码指南，了解约定。
3. 推理：将目标分解为一系列命名的原子转换；对于有状态的目标，规划扩展-收缩；验证每一步都可独立验证和回退。
4. 执行：应用一个转换。优先使用确定性工具（IDE 重命名、codemod、ast-grep），而非手动编辑。拆分后若某项功能横跨多个文件，可考虑使用 G-5 的可选头部映射，前提是它有助于导航。
5. 验证：不做更改地重新运行现有测试。通过 -> 提交（仅限重构）-> 进行下一项转换。若反复失败，采用 Mikado 方法：记录损坏的前置条件，仅撤销本次转换所做的编辑，先递归处理该前置条件。保留已有编辑和其他贡献者的工作。
6. 收尾：报告前后度量差异，并评估可读性（仅有度量指标改善并不代表成功）；报告发现但有意未处理的后续事项。

转换

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

失败与恢复

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

退出

• 成功：行为已验证且保持不变，结构有可衡量的改善，可读性得到确认，仅包含重构的提交，已报告后续事项。
• 部分成功：已建立安全网，但推迟了结构调整；或已梳理前置条件（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. 先应用 Entry 的范围分流。对于剩余的重构范围，运行覆盖率检查并检查测试确定性；将代码归类为 greenfield 或 brownfield。
2. 如果是 brownfield：找到接缝，为当前行为编写特征化（黄金主）测试，然后提交。
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（代码搜索／导航）

• 授权和契约歧义：../_shared/core/execution-policy.md 和 ../_shared/core/clarification-protocol.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（缺陷）、oma-qa（审计）、oma-architecture（边界／ADR）、oma-db（架构）、oma-scm（提交）