cm-refactor
用户明确要求“只整理结构,不改变行为”时使用。执行边界分流、行为判官、分批重构和独立审查;缺陷修复转交 cm-fix,新增或变化的业务行为转交 cm-prd。
kingxiaozhe · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add kingxiaozhe/cm-workflow --skill cm-refactorAbout this skill
name: cm-refactor description: 用户明确要求“只整理结构,不改变行为”时使用。执行边界分流、行为判官、分批重构和独立审查;缺陷修复转交 cm-fix,新增或变化的业务行为转交 cm-prd。
cm-refactor — 重构闭环(行为保持)
执行前读取 ../../runtime/project-context.md、../../runtime/orchestration.md、
../../runtime/review.md、../../runtime/model-efficiency.md 与
../../runtime/logging.md。Codex 入口为 $cm-refactor;Claude Code 跨平台入口为
/cm-refactor,macOS/Linux 另有历史别名 /cm:refactor。
用户明确要求外部专家,或为本次重构开启 AUTO 时,按
../../runtime/external-expert.md 执行 ../external-expert/SKILL.md 的任务路由。
重构写入、行为判官与审查保持 LOCAL;复杂方案比较可 CONSULT,权威事实可 VERIFY。
外部结果只进入候选方案和风险清单,不得修改行为基线、代跑判官或满足独立审查。
用法:$cm-refactor {specs路径} {代码项目路径} 重构目标描述(哪块代码/为什么难维护)
JS 只读分流
在读取项目内容、解析角色、写 run_start、建立行为基线或修改代码前,先确认本轮有非空目标描述,
并按下方“分流门”将意图归为 defect、behavior-change、gradual-adoption 或
structure-only;不要把描述正文拼进 shell。随后执行:
node "{CM_WORKFLOW_ROOT}/scripts/cm-refactor-entry.mjs" \
--skill-dir "{CM_WORKFLOW_ROOT}/skills/cm-refactor" --project "{CODE_PROJECT}" \
[--specs "{SPECS_DIR}"] --intent "{四类意图之一}" [--target-present]
没有 specs 的裸项目省略 --specs;有非空描述才传 --target-present。缺描述时入口返回
blocked / target_required。defect、behavior-change、gradual-adoption 分别只返回既有
$cm-fix、$cm-prd --change、普通改动出口并停止本流程,出口不构成执行授权;只有
structure-only 才继续校验项目/specs,ready / g0_feasibility 才进入 G0,且继续要求行为完全不变
与 G0 人签核。返回的角色、日志和
Learning 均为 pending,执行/写入权限为 false;入口不读取项目正文、不跑判官、不调用
provider/browser/外部专家、不写日志/档案/RULEBOOK,也不替代后续轻量道或批量道。
JS 流程执行
只读分流返回 ready / g0_feasibility 后,按 当前会话 JS 宿主
启动同一轻量/批量控制器;批量、准备、写回与恢复协议在需要时读取。
JS 宿主负责日志与状态,不再手工重复写 run_start。恢复保留原配置、结果和审查轮次;未知调用先核对。
批量默认串行、worker 只提议文本;真实宿主须保证 bakeoff 隔离和最终独立审查,不能用 header 自证。
不使用 JS 宿主时,两个路径校验通过后立即调用统一写入器记录 run_start;暂停/续跑沿用同一
.cm-run.json,完成收口人门后写 run_done。不得直接拼 JSON。
项目角色路由
从代码项目根解析 coder、tester、reviewer,并按
runtime/workflow-routing.md 写 decision/phase: route。角色配置只选择请求的
实现、等价验证和独立审查适配器/模型别名;它不允许子代理提交 Git、改变规则手册、
跳过判官或把 declared-adapter 当成已执行。resolver 返回非零或配置错误时立即
BLOCKED,不得进入 G0、扇出或修改代码;配置缺失时使用当前默认执行方式。
managed-adapter 按 runtime/model-efficiency.md 返回文本建议并自动记录真实 usage;
行为基线、代码改动与独立审查仍保持本地。
角色调用按 runtime/model-efficiency.md 只传当前批次的行为基线、范围、diff、验证与
审查证据;不得重复发送其他批次或完整历史。精简仅影响模型上下文与输出,不降低
行为判官、独立审查或回归门禁。
结构调整专用闭环。前提:什么都没坏,行为一丝不变——设计依据见 docs/重构流程设计/(cm 小闭环纪律 × Anthropic 迁移方法论,核心教义:修规则,不修产物)。
分流门(先于一切,答错门就是错流程):
- 有缺陷要修 →
$cm-fix - 行为要变(哪怕"变得更合理")→
$cm-prd --change - 渐进式采用(如 JS→TS 逐文件、加类型注解)→ 不用本命令,直接改
- 结构问题且行为保持 → 本命令
$cm-ai 全局规则同等生效:灾难级才暂停、多方案自主决策留痕、状态落盘(node 写 REFACTOR)、运行日志照记、审查按 runtime/review.md 执行。
续跑检测(先于 G0):{SPECS_DIR}/refactors/ 下存在未收口 slug(档案无收口节 / 运行日志该 slug 无 run_done 事件)→ 按磁盘状态定位续跑站点(RULEBOOK 版本、batch-log 完成集、队列缺口),G0 不重问、判官按 G0.5 重验后继续;无在制状态才走全新 G0。"队列=磁盘"的可恢复性必须有恢复入口才算数(对照系:cm:ai 有 tasks 断点、fix 有 slug 续跑,最长时的批量重构反而没有——本条补齐)。
G0: 可行性(人门)
- 动机量化:动机必须落到可测指标——行数超限 / 重复块 N 处 / 依赖方向违规 / 圈复杂度。"代码不优雅"不构成动机
- 认领待触发备忘:扫描
{SPECS_DIR}/LESSONS.md的「待触发备忘」段,结构类条目(标记来源含"重构/拆分/看不惯")与本次目标相关的 → 列入范围并在输出注明认领;收口时销账(改状态为已认领,注档案路径)——备忘的回流出口(实跑教训:备忘只写不读,到期无人认领) - 波及面:谁引用这块代码(有业务地图查 03/08,无地图 grep 调用方)
- 输出可行性摘要:范围清单 / 动机指标现值 / 波及面 / 预估轨道(轻量或批量)/ 预算可见乘法(批量道必填:文件数 × 单文件估耗 = 总预算,拍脑袋的总数不作数)。「不重构」是合法结论——收益盖不住风险就明说,命令到此收口
- 🛑 人签核后才进下一步(签核=踢下一阶段;阶段内不再停车)
G0.5: 判官自验证(无判官不开工)
判官 = 能平等裁决改前改后代码的机械标准,分两层:
- 基线层:存量测试全量跑绿并记录;无测试资产 → 先写现状快照测试(B3 同款,锁行为不判对错)
- 差分层:对将被重构的入口函数/接口,构造代表性输入集(含边界值),记录改前输出;harness 的环境解析照抄项目既有测试的做法(依赖怎么找、浏览器怎么起)——自造解析必踩环境坑(实跑:playwright 全局安装,裸 import 失败,照抄 smoke.mjs 的 npm root -g 解析才通)(实证方法:12 组输入逐字节对比,json-keeper 拆 core.js 验证过)
自验证(判官没被验证过,就不配当判官):
- 在原代码上跑 → 必须全绿
- 在故意破坏的代码上跑(手动种 ≥2 处行为变异,如改一个返回值、删一个分支)→ 必须变红;不红的判官修到红为止,变异恢复后再开工
- 判官报大面积失败时先怀疑判官(比较器空白处理/序列化陷阱是已知假阳性源),"一个把所有东西都判失败的裁判,通常是它坏了"
规模门(客观判据,不是感觉)
- 范围 ≤3 个文件 且 无跨模块搬迁 且 无文件增删 → 轻量道
- 其余 → 批量道
- 版本控制 = none → 禁入批量道(批量改动无 git 回滚是裸奔):只许轻量道并输出强警告,或建议先 git init
轻量道(五步,一次跑完)
- 重构:只动结构不动行为;禁止顺手修 bug(与 N3"禁止顺手重构"互为镜像)——发现缺陷 → 停下记录现象与位置进档案,收口后走
$cm-fix。夹带修复会毁掉差分判官:行为变了,是重构失手还是修复生效?无法归因 - 等价验证:基线全绿 + 差分逐项一致;任何行为差异 = 该步失败回滚——"差异其实更合理"也不例外,那是行为变更,走 prd --change 立项后再做
- 审查:执行下方「结构化审查门禁」;重点检查有无夹带行为变更、结构是否真的改善、差分覆盖是否充分
- 落盘:档案
{SPECS_DIR}/refactors/{YYYYMMDD}-{slug}.md(动机指标改前改后对照 / 等价验证方式与结果 / 发现未修缺陷清单);METRICS 行 Feature 列写refactor;delivery=diff 不提交,branch/draft-mr 才 commitrefactor: {一句话} (档案: refactors/xxx.md) - 规则毕业:本次收敛出的持久约定(如"路由文件导出形态")→ 写进代码项目
.claude/rules/对应文件——一次重构的规则,变成项目的永久基因;项目无.claude/rules/(未经 $cm-init)→ 降级记入 LESSONS[仅记忆]并在档案注明,提示补跑 $cm-init 后迁入(实跑 DEV-003:diff-lens 未 init,毕业规则无处可去)
结构化审查门禁(两条轨道共用)
{slug} 先规范成跨平台安全的 ASCII kebab;令
REVIEW_FEATURE=refactor-{slug}、REVIEW_TASK=T-REFACTOR-{slug}。主执行者按真实
diff 和判官证据写
{SPECS_DIR}/.reviews/refactor-{slug}-T-REFACTOR-{slug}-a{attempt}-handoff.json,
先按完整 changed_files 运行
cm-task-gate.py hash-implementation --project-root {CODE_PROJECT} --file ... 并把返回的
implementation_sha256 写入 handoff,然后真跑:
python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py check-n4 \
--handoff {HANDOFF_PATH} --reviews-dir {SPECS_DIR}/.reviews \
--feature refactor-{slug} --task T-REFACTOR-{slug} --project-root {CODE_PROJECT}
独立审查投喂全部 diff + RULEBOOK(批量道)+ judge-report/diff-report 摘要;凭证严格落
{SPECS_DIR}/.reviews/refactor-{slug}-T-REFACTOR-{slug}-r{attempt}.md 并绑定当前
handoff SHA。审查后必须真跑:
python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py check-n5 \
--handoff {HANDOFF_PATH} --reviews-dir {SPECS_DIR}/.reviews \
--feature refactor-{slug} --task T-REFACTOR-{slug} --project-root {CODE_PROJECT}
只有当前 attempt 的 verdict: approved 才能落盘/提交;changes_requested 生成
attempt 2 并复审,第 2 轮仍有阻断项写 blocked。旧凭证、空壳凭证或文件存在检查
均不得放行。
第一轮要求补判官或测试时,审查返回 judgeRevision:{paths,reason},只列启动时
testSetup.paths 内的文件;第二轮由宿主提议文本、控制器登记写入。先在启动时的业务原稿上
重建答案并重做判官自验证,再与第二轮重构稿比较;详见 判官修订与恢复。
批量道(五站 + 三条修上游回环)
Read the complete source ↗教义:个别失败交给循环烧掉,**重复失败控诉的是规则