Cm Refactor

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路径} {代码项目路径} 重构目标描述(哪块代码/为什么难维护)

两个路径校验通过后立即调用统一写入器记录 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: 可行性(人门)

1. 动机量化:动机必须落到可测指标——行数超限 / 重复块 N 处 / 依赖方向违规 / 圈复杂度。"代码不优雅"不构成动机
2. 认领待触发备忘:扫描 {SPECS_DIR}/LESSONS.md 的「待触发备忘」段,结构类条目(标记来源含"重构/拆分/看不惯")与本次目标相关的 → 列入范围并在输出注明认领;收口时销账(改状态为已认领,注档案路径)——备忘的回流出口(实跑教训:备忘只写不读,到期无人认领)
3. 波及面:谁引用这块代码(有业务地图查 03/08,无地图 grep 调用方)
4. 输出可行性摘要:范围清单 / 动机指标现值 / 波及面 / 预估轨道(轻量或批量)/ 预算可见乘法(批量道必填:文件数 × 单文件估耗 = 总预算,拍脑袋的总数不作数)。「不重构」是合法结论——收益盖不住风险就明说,命令到此收口
5. 🛑 人签核后才进下一步(签核=踢下一阶段;阶段内不再停车)

G0.5: 判官自验证(无判官不开工)

判官 = 能平等裁决改前改后代码的机械标准,分两层:

• 基线层:存量测试全量跑绿并记录;无测试资产 → 先写现状快照测试(B3 同款,锁行为不判对错)
• 差分层:对将被重构的入口函数/接口,构造代表性输入集(含边界值),记录改前输出;harness 的环境解析照抄项目既有测试的做法(依赖怎么找、浏览器怎么起)——自造解析必踩环境坑(实跑:playwright 全局安装,裸 import 失败,照抄 smoke.mjs 的 npm root -g 解析才通)(实证方法:12 组输入逐字节对比,json-keeper 拆 core.js 验证过)

自验证(判官没被验证过,就不配当判官):

• 在原代码上跑 → 必须全绿
• 在故意破坏的代码上跑(手动种 ≥2 处行为变异,如改一个返回值、删一个分支)→ 必须变红;不红的判官修到红为止,变异恢复后再开工
• 判官报大面积失败时先怀疑判官(比较器空白处理/序列化陷阱是已知假阳性源),"一个把所有东西都判失败的裁判,通常是它坏了"

规模门(客观判据,不是感觉)

• 范围 ≤3 个文件 且 无跨模块搬迁 且 无文件增删 → 轻量道
• 其余 → 批量道
• 版本控制 = none → 禁入批量道(批量改动无 git 回滚是裸奔):只许轻量道并输出强警告,或建议先 git init

轻量道(五步,一次跑完)

1. 重构:只动结构不动行为;禁止顺手修 bug(与 N3"禁止顺手重构"互为镜像)——发现缺陷 → 停下记录现象与位置进档案,收口后走 $cm-fix。夹带修复会毁掉差分判官:行为变了,是重构失手还是修复生效?无法归因
2. 等价验证:基线全绿 + 差分逐项一致;任何行为差异 = 该步失败回滚——"差异其实更合理"也不例外,那是行为变更,走 prd --change 立项后再做
3. 审查：执行下方「结构化审查门禁」；重点检查有无夹带行为变更、结构是否真的改善、差分覆盖是否充分
4. 落盘:档案 {SPECS_DIR}/refactors/{YYYYMMDD}-{slug}.md(动机指标改前改后对照 / 等价验证方式与结果 / 发现未修缺陷清单);METRICS 行 Feature 列写 refactor;delivery=diff 不提交，branch/draft-mr 才 commit refactor: {一句话} (档案: refactors/xxx.md)
5. 规则毕业:本次收敛出的持久约定(如"路由文件导出形态")→ 写进代码项目 .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。旧凭证、空壳凭证或文件存在检查 均不得放行。

批量道(五站 + 三条修上游回环)

> 教义:个别失败交给循环烧掉,重复失败控诉的是规则——修规则重新生成,不修产物。

站 1: 规则手册

• 建 {SPECS_DIR}/refactors/{slug}/RULEBOOK.md,meta 规则:两个 agent 会答得不同的问题,答案进手册(目标形态/命名映射/禁用模式/逃生舱标记 TODO(refactor):)
• 依赖图定批次顺序(文件粒度 + 模块粒度都查环)
• 手册在循环内只读:任何批内 diff 碰 RULEBOOK = 自动审查发现;修订排队给人,批间应用

站 2: 压力测试(人门)

• 双译对比(bakeoff):同 2-3 个最难的文件派两个隔离 agent——一个严格守 RULEBOOK,一个从不知道手册存在;第三个 agent 逐处 diff,每处差异裁决为「规则正确 / 规则缺失 / 规则错误」——差异清单就是规则修订清单(比"跑一遍看看"锐利:每个 diff 都是对某条规则的判决)
• 试点:按批量道管线原样跑通(含站 3 禁令与站 4 裁决);试点产物可弃,唯一留下的是规则修订
• 采样规模:批量 ≥10 单元 → 取 2-3 个最难文件; 为什么比 feature 开发厚:新开发的失败是"没做出来",看得见;重构的失败是"悄悄改了行为",事后归因全靠明细。事件级日志答得了"发生过什么",答不了"这个行为差异是哪个文件、哪版规则、哪次批次引入的"。

• judge-report.md(refactors/{slug}/):判官档案——基线清单与结果、自验证变异清单(种了什么变异 / 抓到没有,漏抓的怎么修到抓到)、假阳性排查记录。判官的可信度证据,不是口头的"验证过了"
• diff-report.md:差分明细——每组输入 / 改前输出 / 改后输出 / 结论,逐组落盘(不是一句"全部一致");出现差异时该组全文保留,回滚后补记处置
• batch-log.jsonl(批量道):单文件粒度一行一条:{file, agent, model, rulebook_rev, diff_pass, todos, confidence, duration}——归因链的关键是 rulebook_rev:每个产物记录由哪版规则生成,行为差异出现时可精确定位"这批是坏规则的产物"而不是逐文件猜
• RULEBOOK 修订史(手册内置表):版本 | 日期 | 触发实例(哪个失败) | 旧条文 → 新条文 | 裁决人——规则演进必须可追溯,否则"修规则不修产物"就成了无账本的改法
• 回滚记录:每次回滚在档案记一节(回滚了哪批 / 回到哪个 commit / 触发差异的输入组 / 归因结论),并与主日志 error 事件双写互指

落盘物清单(审计链)

| 落盘物 | 位置 | | ---- | ---- | | 运行日志 + 状态 | {SPECS_DIR}/运行日志.jsonl 追加 · .cm-status.json(状态条自动显示 REFACTOR 进度) | | 明细层(判官/差分/批次/回滚) | refactors/{slug}/ 下 judge-report.md · diff-report.md · batch-log.jsonl(批量道) | | 可行性摘要 + 档案 | {SPECS_DIR}/refactors/{日期}-{slug}.md(批量道为同名目录) | | RULEBOOK(批量道) | refactors/{slug}/RULEBOOK.md | | 审查凭证 | {SPECS_DIR}/.reviews/refactor-{slug}-T-REFACTOR-{slug}-r{N}.md | | 度量 | METRICS.md 追加行,Feature 列 refactor | | 毕业规则 | 代码项目 .claude/rules/ 对应文件 | | 备忘销账 | LESSONS.md 待触发备忘状态更新 |

边界

• 不承接:缺陷(→ $cm-fix)、行为变更(→ $cm-prd --change)、架构级重设计(升级出口:交人经 $cm-prd 立项——重设计下规则手册变设计文档、试点对比失效,是另一种流程)
• 不触发 cm-qa-engineer:行为等价验证就是重构的 QA,行为没变就没有新 AC
• 没有 specs 目录的裸项目:档案落代码项目 docs/refactors/,凭证落 docs/refactors/.reviews/,METRICS 跳过(同 $cm-fix 惯例)

对上游方法论的三处有意改编(是取舍不是遗漏,放弃了什么留痕):

• kit 的重设计模式(规则手册变设计文档)→ 整体分流给 $cm-prd 立项——cm 已有方案对抗审查链,不重复造
• kit 的双对抗审查+第三方仲裁 → 用 cm 既有 N4 纪律(≤2 轮+分歧记录)——全框架审查纪律保持单一来源
• kit 的缺口清单(gap inventory)→ 不设——那是跨语言迁移特有物(目标语言强制要求表),同语言行为保持重构由波及面清单承担残余职能

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kingxiaozhe
• Source: kingxiaozhe/cm-workflow
• License: MIT

Install and usage instructions live in the source repository linked above.