{"slug":"cm-refactor","title":"cm-refactor","summary":"用户明确要求“只整理结构，不改变行为”时使用。执行边界分流、行为判官、分批重构和独立审查；缺陷修复转交 cm-fix，新增或变化的业务行为转交 cm-prd。","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-24T15:43:03.460261Z","repo":{"url":"https://github.com/kingxiaozhe/cm-workflow","stars":27,"forks":0,"license":"MIT","updatedAt":"2026-09-24T10:35:03Z"},"bodyHtml":"
\n

name: cm-refactor\ndescription: 用户明确要求“只整理结构，不改变行为”时使用。执行边界分流、行为判官、分批重构和独立审查；缺陷修复转交 cm-fix，新增或变化的业务行为转交 cm-prd。

\n

cm-refactor — 重构闭环（行为保持）

\n

执行前读取 ../../runtime/project-context.md、../../runtime/orchestration.md、\n../../runtime/review.md、../../runtime/model-efficiency.md 与\n../../runtime/logging.md。Codex 入口为 $cm-refactor；Claude Code 跨平台入口为\n/cm-refactor，macOS/Linux 另有历史别名 /cm:refactor。

\n

用户明确要求外部专家，或为本次重构开启 AUTO 时，按\n../../runtime/external-expert.md 执行 ../external-expert/SKILL.md 的任务路由。\n重构写入、行为判官与审查保持 LOCAL；复杂方案比较可 CONSULT，权威事实可 VERIFY。\n外部结果只进入候选方案和风险清单，不得修改行为基线、代跑判官或满足独立审查。

\n

用法:$cm-refactor {specs路径} {代码项目路径} 重构目标描述(哪块代码/为什么难维护)

\n

JS 只读分流

\n

在读取项目内容、解析角色、写 run_start、建立行为基线或修改代码前，先确认本轮有非空目标描述，\n并按下方“分流门”将意图归为 defect、behavior-change、gradual-adoption 或\nstructure-only；不要把描述正文拼进 shell。随后执行：

\n
node \"{CM_WORKFLOW_ROOT}/scripts/cm-refactor-entry.mjs\" \\\n  --skill-dir \"{CM_WORKFLOW_ROOT}/skills/cm-refactor\" --project \"{CODE_PROJECT}\" \\\n  [--specs \"{SPECS_DIR}\"] --intent \"{四类意图之一}\" [--target-present]\n
\n

没有 specs 的裸项目省略 --specs；有非空描述才传 --target-present。缺描述时入口返回\nblocked / target_required。defect、behavior-change、gradual-adoption 分别只返回既有\n$cm-fix、$cm-prd --change、普通改动出口并停止本流程，出口不构成执行授权；只有\nstructure-only 才继续校验项目/specs，ready / g0_feasibility 才进入 G0，且继续要求行为完全不变\n与 G0 人签核。返回的角色、日志和\nLearning 均为 pending，执行/写入权限为 false；入口不读取项目正文、不跑判官、不调用\nprovider/browser/外部专家、不写日志/档案/RULEBOOK，也不替代后续轻量道或批量道。

\n

JS 流程执行

\n

只读分流返回 ready / g0_feasibility 后，按 当前会话 JS 宿主\n启动同一轻量/批量控制器；批量、准备、写回与恢复协议在需要时读取。\nJS 宿主负责日志与状态，不再手工重复写 run_start。恢复保留原配置、结果和审查轮次；未知调用先核对。\n批量默认串行、worker 只提议文本；真实宿主须保证 bakeoff 隔离和最终独立审查，不能用 header 自证。

\n

不使用 JS 宿主时，两个路径校验通过后立即调用统一写入器记录 run_start；暂停/续跑沿用同一\n.cm-run.json，完成收口人门后写 run_done。不得直接拼 JSON。

\n

项目角色路由

\n

从代码项目根解析 coder、tester、reviewer，并按\nruntime/workflow-routing.md 写 decision/phase: route。角色配置只选择请求的\n实现、等价验证和独立审查适配器/模型别名；它不允许子代理提交 Git、改变规则手册、\n跳过判官或把 declared-adapter 当成已执行。resolver 返回非零或配置错误时立即\nBLOCKED，不得进入 G0、扇出或修改代码；配置缺失时使用当前默认执行方式。\nmanaged-adapter 按 runtime/model-efficiency.md 返回文本建议并自动记录真实 usage；\n行为基线、代码改动与独立审查仍保持本地。

\n

角色调用按 runtime/model-efficiency.md 只传当前批次的行为基线、范围、diff、验证与\n审查证据；不得重复发送其他批次或完整历史。精简仅影响模型上下文与输出，不降低\n行为判官、独立审查或回归门禁。

\n

结构调整专用闭环。前提:什么都没坏,行为一丝不变——设计依据见 docs/重构流程设计/(cm 小闭环纪律 × Anthropic 迁移方法论,核心教义:修规则,不修产物)。

\n

分流门(先于一切,答错门就是错流程):

\n\n

$cm-ai 全局规则同等生效：灾难级才暂停、多方案自主决策留痕、状态落盘（node 写 REFACTOR）、运行日志照记、审查按 runtime/review.md 执行。

\n

续跑检测(先于 G0):{SPECS_DIR}/refactors/ 下存在未收口 slug(档案无收口节 / 运行日志该 slug 无 run_done 事件)→ 按磁盘状态定位续跑站点(RULEBOOK 版本、batch-log 完成集、队列缺口),G0 不重问、判官按 G0.5 重验后继续;无在制状态才走全新 G0。\"队列=磁盘\"的可恢复性必须有恢复入口才算数(对照系:cm:ai 有 tasks 断点、fix 有 slug 续跑,最长时的批量重构反而没有——本条补齐)。

\n

G0: 可行性(人门)

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

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

\n

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

\n\n

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

\n\n

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

\n\n

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

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

结构化审查门禁（两条轨道共用）

\n

{slug} 先规范成跨平台安全的 ASCII kebab；令\nREVIEW_FEATURE=refactor-{slug}、REVIEW_TASK=T-REFACTOR-{slug}。主执行者按真实\ndiff 和判官证据写\n{SPECS_DIR}/.reviews/refactor-{slug}-T-REFACTOR-{slug}-a{attempt}-handoff.json，\n先按完整 changed_files 运行\ncm-task-gate.py hash-implementation --project-root {CODE_PROJECT} --file ... 并把返回的\nimplementation_sha256 写入 handoff，然后真跑：

\n
python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py check-n4 \\\n  --handoff {HANDOFF_PATH} --reviews-dir {SPECS_DIR}/.reviews \\\n  --feature refactor-{slug} --task T-REFACTOR-{slug} --project-root {CODE_PROJECT}\n
\n

独立审查投喂全部 diff + RULEBOOK（批量道）+ judge-report/diff-report 摘要；凭证严格落\n{SPECS_DIR}/.reviews/refactor-{slug}-T-REFACTOR-{slug}-r{attempt}.md 并绑定当前\nhandoff SHA。审查后必须真跑：

\n
python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py check-n5 \\\n  --handoff {HANDOFF_PATH} --reviews-dir {SPECS_DIR}/.reviews \\\n  --feature refactor-{slug} --task T-REFACTOR-{slug} --project-root {CODE_PROJECT}\n
\n

只有当前 attempt 的 verdict: approved 才能落盘/提交；changes_requested 生成\nattempt 2 并复审，第 2 轮仍有阻断项写 blocked。旧凭证、空壳凭证或文件存在检查\n均不得放行。

\n

第一轮要求补判官或测试时，审查返回 judgeRevision:{paths,reason}，只列启动时\ntestSetup.paths 内的文件；第二轮由宿主提议文本、控制器登记写入。先在启动时的业务原稿上\n重建答案并重做判官自验证，再与第二轮重构稿比较；详见 判官修订与恢复。

\n

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

\n
\n

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

\n
\n

站 1: 规则手册

\n\n

站 2: 压力测试(人门)

\n\n

站 3: 批量执行

\n\n

站 3.5: 装配(主流程职责,不派 agent)

\n\n

站 4: 机械裁决

\n\n

站 5: 行为等价

\n\n

收口(同轻量道 3-5 + 追加)

\n\n

收口人门(轻量道与批量道共用,全流程第三处签核)

\n

\uD83D\uDED1 双计数呈签核后本命令才算闭环:基线 项全绿 + 差分 组一致,连同档案、动机指标改前改后对照、预算对账(G0 预估 vs 实耗:agent 调用次数/时长,写入 METRICS 备注)一并打给人——不对账的预算永远是拍脑袋。与 G0、站 2 构成全流程恰好三处人门——门在阶段之间,签核=踢下一阶段,阶段内零停车(与 docs/重构流程设计/ 的图一致,图与实现不得漂移)。

\n

运行日志必记事件(node 写 REFACTOR,格式同 cm:ai 全局规则)

\n\n

重构专属明细日志(事件层之下的第二层,轻量道不豁免只减薄)

\n
\n

为什么比 feature 开发厚:新开发的失败是\"没做出来\",看得见;重构的失败是\"悄悄改了行为\",事后归因全靠明细。事件级日志答得了\"发生过什么\",答不了\"这个行为差异是哪个文件、哪版规则、哪次批次引入的\"。

\n
\n\n

落盘物清单(审计链)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
落盘物位置
运行日志 + 状态{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 待触发备忘状态更新
\n

边界

\n\n

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

\n\n","files":[{"path":"references/js-batch.md","sizeBytes":6926,"isText":true},{"path":"references/js-host.md","sizeBytes":9779,"isText":true},{"path":"SKILL.md","sizeBytes":20097,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-24T15:43:57.311368Z","sha256":"3448371852F10E1AA69B86F036ED2D636F6B149486717BF8CD528D54CC19A388","sizeBytes":20264},"review":null,"source":{"repositoryUrl":"https://github.com/kingxiaozhe/cm-workflow","path":"skills/cm-refactor","license":"MIT","commit":"3f79f657e2e9e21f1300efe8e5c0bd5d4d6d208c","subtreeSha":"0CB3D2DF241C95D069A0554527B25FF38B4B7D73CD0E2821F0C44D9423138CE0","lastSyncedAt":"2026-09-24T15:42:59.811488Z"},"reviewedAt":"2026-09-24T15:46:38.390628Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/kingxiaozhe/cm-workflow/tree/main/skills/cm-refactor"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kingxiaozhe-cm-workflow@llmmart"},{"target":"git","command":"git clone https://github.com/kingxiaozhe/cm-workflow.git"}]}