workflow-refactor 是一个代码重构工作流技能,目标是在不改变外部可观察行为的前提下,对现有代码进行重构、重组、重命名、抽取、简化或偿还技术债务。若用户希望改变行为,则属于功能开发(workflow-feature)或缺陷修复(workflow-bugfix);单个文件中的简单重命名单靠直接编辑加测试与审查即可。
一、用途与核心原则
- 重构前后使用相同的测试范围并保持绿色,再加上一次收敛的变更审查,以此证明行为被保留。
- 必须先进行规模、类型和风险分级,分级决定哪些推荐技能运行以及深入程度。
- 在规划前必须查找至少 3 个目标模式的本地示例,并遵循项目的架构、代码层级与命名(来自 docs/project-config.json 的 workflowPatterns)。
- 绝不能为了让重构通过而修改断言或期望值——那是行为变更,需用户批准。
- 如果重构触及的可观察行为、公开契约或文档/规范边界发生变化,则不再是纯重构,应停止并与用户确认。
二、分级与典型路线
- 规模(指导性):XS 为 1–3 个文件或不超过 100 行改动;S 不超过 15 个文件;M 不超过 60 个;L 不超过 300 个;XL 超过 300 个(机械式重命名可达数千)。
- 类型(可多选):局部清理、抽取/移动/重命名、跨模块重组、公开契约/API 接口、数据/模式/持久化、安全敏感、性能驱动、死代码移除、仅测试、工具/配置。
- 风险:不可逆、数据、安全、跨模块。风险与模糊度会提升深度,而非仅看文件数量。
- 典型路线:XS/S 单模块且无契约/数据面时走 调查 → 基线测试 → 简短计划 → 执行 → 审查 → 测试 → 收尾;M 或跨模块保留一份精简计划,并在调查显示覆盖缺口时于基线测试前补充特征测试;L/XL、公开契约/数据/安全或目标结构模糊时增加计划验证,按模块分批执行,每批有报告、基线与最终测试,最后做全范围测试。
三、必需的质量门禁
- 基线绿色:在任何改动之前,对重构触及的代码(含刚写的特征测试)运行测试并记录命令、范围与通过摘要。已有测试为红则停止重构;本次新写的特征测试为红需先给出五种判定,若是测试编写错误则在未重构代码上修正并重跑一次,若是真实缺陷则像已有测试一样停止重构。
- 触及行为受保护:重构触及的每个行为都有测试能在其改变时失败;否则在基线运行前编写特征测试,并在未重构代码上证明其为绿。生命周期/状态逻辑需断言持久化状态转换与非法转换拒绝。
- 行为保持:改动后与审查修复后,基线范围加特征测试在本轮运行中为绿;若有集成测试验证步骤则由其负责变异检查,其余层级由测试步骤覆盖。测试代码只允许机械性变更(导入、重命名的符号、移动的路径)。
- 审查收敛:在主会话中内联运行变更审查,修复已确认的阻断性发现并重新审查修复后的状态。
- 运行关闭:通过工作流结束步骤关闭运行。
四、步骤与可选性
默认顺序:调查(核心)→ 集成测试(可选,有条件;当触及行为无测试保护时在基线前编写特征测试)→ 测试(门禁,改动前基线)→ 计划(核心)→ 计划验证(可选,L 以上或目标结构/范围模糊时)→ 计划执行(核心,小步可验证增量)→ 规范测试(可选,保留的不变量缺测试用例时)→ 测试用例质量审查(可选,测试用例内容有实质变化时)→ 规范同步(可选,规范或测试用例引用了被移动/重命名的路径时)→ 变更审查(门禁,内联,静态审查)→ 集成测试验证(可选,本轮写/改了集成测试或核心逻辑被移动时,审查后运行,负责变异检查)→ 测试(门禁,改动与审查修复后,覆盖验证报告未覆盖的层级)→ 工作流结束(门禁)→ 会话报告(可选,被要求或需交接时)。
阶段任务划分:发现(3)→ 计划(2)→ 构建(4)→ 审查(1,退出条件为审查收敛)→ 验证(2,退出条件为测试通过)→ 收尾(2,退出条件为运行关闭)。
五、编排与约束
- 内联还是子代理、并行波次还是串行、分批与顺序可自选,以同等质量下优化实际耗时与 token 成本为目标。
- 固定数据依赖:特征测试在基线运行前写好,基线运行证明它们与已有测试在未重构代码上为绿;改动先存在再审查或测试;规范同步在检查它的审查之前运行;审查为静态(--tests=defer),验证与最终测试在其后;验证步骤做的修复会重新触发静态变更审查;验证步骤不运行时由主会话负责变异检查;工作流结束最后运行。
- 变更审查必须在主会话内联运行,不能作为子代理。
- 需用户批准的门禁(计划验证、行为变更决策)绝不并行化。
- 推荐:XS/S 内联无子代理;L/XL 机械式改动按模块分批应用并各有简短报告,最后做一次全范围最终测试。
六、报告与修复路径
- 每个阶段一个任务,每个选中步骤或批次一行记录,避免上下文压缩后丢失。
- 在首个发现前创建临时报告文件(tmp/reports/workflow-refactor-{YYMMDD}-{HHmm}-{slug}.md),按步骤追加分级、基线证据、模式示例、批次结果与偏差;压缩后重新阅读报告与当前任务列表。
- 修复前先验证发现(有证据、可复现),在所属层修复,并重跑提出该发现的审查者或测试;非平凡修复后做整体复检。改动后测试失败则视为行为已改变,直到被证伪,编辑任一侧前先裁决。
- 循环上限:第 1 轮零个未关闭的已确认发现即可退出(低优先级可延迟);从第 2 轮起只有严重/高/中级别阻断,仅低级别可延迟;审查最多 3 轮;失败检查会阻断,达到 3 轮上限需用户明确批准的有界延长;无进展则通过提问工具升级。
七、性能驱动路线
性能驱动的重构(查询优化、缓存、减少分配、吞吐量)运行性能审查以获取基准证据——SLA、基线、测量命令——同时保持可观察行为与功能无回归检查。纯粹行为保持的优化若由不变量保持证据与最终测试门禁覆盖,则无需新增测试用例;但 SLA、性能约束、状态时序边界、公开契约或文档/规范边界变化仍需规范、测试与文档同步。
八、启动方式
以用户提示为上下文运行 $start-workflow workflow-refactor 激活工作流;应用活跃技能根目录下 shared/sdd-artifact-contract.md 中的共享 SDD 产物契约;项目约定来自 docs/project-config.json 与文档索引。文档还给出协议指南(增量持久化、会话目标账本、子代理返回契约、验证后置顺序、工作流注册绑定),仅当满足其阅读条件时应用。
九、适用场景与限制
适用于局部清理、抽取/移动/重命名、跨模块重组、技术债偿还,且行为保持固定。不适用于行为需改变的需求(应走功能或缺陷工作流),也不适用于单文件简单重命名(直接编辑加测试审查即可)。资料未说明该技能的收费、价格、平台支持范围与效果保证,暂未提供。注意:资料中出现的各类调用与执行说明属于原技能文档内容,此处仅作整理转述。