ECC /orch-refine-code：行为保持型重构的 Gated 编排工作流

2026-09-07 15:28:36作者：江焘钦

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

项目地址：https://gitcode.com/GitHub_Trending/ev/ECC

在 commands/orch-refine-code.md 所定义的 /orch-refine-code 命令中，ECC 把"重构"从一次性的代码修改变成了一条可审计的流水线：先用现有测试套件确认基线为绿，再小步重构、逐步保持绿灯，最后经过代码评审与人审关卡（Gate）才能提交。读完本文，你将掌握这条命令的完整调用链——从命令入口、orch-pipeline 共享引擎的阶段掩码与规模分级，到 refactor-cleaner 死代码清理代理和 code-reviewer 评审代理的具体分工，从而在自己的 Agent 工作流中复用这套"行为不变、结构变好"的受控重构模式。

一、命令定位：orch 家族中的"refactor"操作

/orch-refine-code 是一个手动触发的编排命令，其职责被 commands/orch-refine-code.md 的 frontmatter 一句话概括：

Orchestrate a behavior-preserving refactor — confirm tests green, restructure without changing behavior, keep green, review, gated commit.

命令本体非常薄：它把 $ARGUMENTS 作为请求传给 orch-refine-code 技能，真正的执行逻辑在 skills/orch-refine-code/SKILL.md 中定义，而该技能又只是共享引擎 skills/orch-pipeline/SKILL.md 之上的一个"薄包装"（thin wrapper）。整个调用关系是：

/orch-refine-code <what to restructure>
  → skills/orch-refine-code（声明操作设置：规模下限、阶段掩码、首步规则）
    → skills/orch-pipeline（共享引擎：分级、阶段、代理映射、两道 Gate）
      → planner / tdd-guide / refactor-cleaner / code-reviewer 等 ECC 代理

从 skills/orch-pipeline/SKILL.md 的"operation family"表格看，orch-refine-code 在五种操作中的定位是：

Skill	Operation	触发条件	首步（First move）
`orch-add-feature`	feature	能力尚不存在	研究 + 规划新切片
`orch-change-feature`	tweak	功能可用，但期望行为不同	先修改既有行为及其测试
`orch-fix-defect`	fix	已损坏，行为错误	先写出复现 bug 的失败测试，再修复
`orch-refine-code`	refactor	行为保持不变，结构改进	在保持测试全绿的前提下重构
`orch-build-mvp`	mvp	从设计/规格文档引导	读取文档 → 垂直切片

这张表给出了一个清晰的决策边界：只要行为有哪怕一丝改变，就不该用 /orch-refine-code——行为变更走 commands/orch-change-feature.md（先改测试再改实现），缺陷修复走 commands/orch-fix-defect.md（先写红测试再修绿），新能力走 orch-add-feature。

二、使用方法

命令格式与示例直接继承自 commands/orch-refine-code.md：

/orch-refine-code <what to restructure>

示例：

/orch-refine-code extract the NWS HTTP client out of poller.py
/orch-refine-code remove dead code and duplication in the dashboard module

两个要点：

参数为空时的兜底行为：若 $ARGUMENTS 为空，命令不会猜测，而是主动询问用户"要重构什么"（原文："If $ARGUMENTS is empty, ask the user what to refine."）；
适用前提：原文强调 "Use this only when behavior must not change"——只有行为必须保持不变时才使用它。这是整条流水线的契约：diff 必须做到"行为中性"（behavior-neutral），并以 refactor: 前缀提交。

三、流水线内部机制：从 orch-pipeline 引擎看四步工作流

命令文档列出的四步（分类规模 → 确认测试绿 → 小步重构 → 评审提交）背后，是 skills/orch-pipeline/SKILL.md 定义的完整阶段模型。orch-refine-code 在其"Operation settings"中声明了三条关键配置：

默认规模下限（Default size floor）：standard。理由是重构通常触及多个文件，不允许按 trivial 级别跳过规划；
阶段掩码（Phase mask）：0 → 2 → 4 → 5 → 6。即 Intake → Plan → Implement → Review → Commit，跳过阶段 1（Research）和阶段 3（Scaffold）——重构不需要外部研究，也不需要搭脚手架；
不写新的行为测试："No new behavior tests are written — the existing suite is the safety net"，既有测试套件就是安全网。这一条与 skills/tdd-workflow/SKILL.md 中"refactoring 也走 TDD"的原则相衔接，但方向相反：TDD 用新测试证明新行为，refine 用旧测试证明行为未变。

3.1 Step 1：规模分级（right-sizing）

引擎要求"仪式规模随爆炸半径缩放"：对请求按三个信号打分，取任一信号达到的最高档，并用一行文字把分级结果告知用户（用户可覆盖）。完整分级表：

Tier	触及文件	新依赖/契约	设计歧义	运行的阶段
trivial	1 个文件、几行	无	无——改动显然	4 → 5 → 6
small	1 文件 / 1 函数	无	读一遍代码就清楚	(1 light) → 4 → 5 → 6
standard	2–5 个文件	可能有新内部模块	有一个真实的设计抉择	1 → 2 → 4 → 5 → 6
large	大量/跨切面	新外部依赖、公共 API 或规格文档	多个开放问题	1 → 2 → (3) → 4 → 5 → 6

阶段 0（Intake）始终运行。另有一条平局裁决规则：凡触及安全触发条件（见 3.4 节）或公共 API/契约的改动，无论文件数多少，至少按 standard 处理。对 /orch-refine-code 而言，即使只是"删几行死代码"，只要涉及公共 API，也必须走完整的 Plan → Implement → Review → Commit 流程并在 Gate 1 停下等待批准。

3.2 Step 2：首步规则——先证绿，再动刀

命令文档第 2 步与技能文档的"First move（phase 4）"共同构成了这条流水线最具约束力的规则：

确认相关测试存在且在动代码之前就是绿的；如果覆盖太薄，先补 characterization tests（特征测试）。然后规划重构。→ GATE 1

这里的 characterization test（特征测试）是关键细节：当既有测试没有覆盖你要重构的代码路径时，先写一批"记录当前行为"的测试（不是验证新行为的测试），把这些路径钉死，再开始搬移代码。这样后面每一次小步重构，测试红绿就是行为是否改变的最直接信号。

规划本身委托给 planner 代理（结构类决策升级给 architect / code-architect），产出按"薄垂直切片"排序的 task_list，并在此处停下等用户批准——这就是 GATE 1。

3.3 Step 3：小步重构与死代码委派

实施阶段由 tdd-guide 代理驱动（或 skills/tdd-workflow/SKILL.md 技能），但 refine 操作对它有一个明确的变形要求：

小步走，每步重跑测试。命令文档原文："Restructure in small steps, re-running tests after each"。任意一步测试转红，就意味着行为被改动，应立即回退该步；
死代码/重复清扫委派给 refactor-cleaner。这一点在 skills/orch-refine-code/SKILL.md 的 "How It Works" 中写明。

refactor-cleaner 的实际工作规范见 agents/refactor-cleaner.md，它是一个专注"删得安全"的清理代理：

检测命令（按项目类型选择）：

npx knip                                    # 未使用的文件、导出、依赖
npx depcheck                                # 未使用的 npm 依赖
npx ts-prune                                # 未使用的 TypeScript 导出
npx eslint . --report-unused-disable-directives  # 未使用的 eslint 指令

姊妹命令 commands/refactor-clean.md 还补充了跨语言工具表：Python 用 vulture src/、Go 用 deadcode ./...、Rust 用 cargo +nightly udeps；没有任何工具可用时，退化为 Grep 找"零引用的导出"。

风险分级与删除节奏是其安全模型的核心：

Tier	示例	动作
SAFE	未使用的工具函数、测试助手、内部函数	放心删除
CAUTION	组件、API 路由、中间件	先确认无动态导入/外部消费者
DANGER	配置文件、入口点、类型定义	先调查再碰

删除循环要求：先跑全量测试建基线 → 单项删除（每次只删一类：deps → exports → files → duplicates）→ 重跑测试 → 失败则 git checkout -- <file> 回退并跳过该项 → 通过则继续。安全清单要求删除前逐项确认：检测工具确认未使用、Grep 确认无引用（含字符串形式的动态引用）、不属于公共 API、删除后测试通过；并且"宁可留着死代码，也不破坏生产"（Skip if uncertain）。

3.4 Step 4：评审与 GATE 2 提交

重构完成后进入阶段 5（Review）与阶段 6（Commit）：

code-reviewer 评审。该代理的定义在 agents/code-reviewer.md，其评审风格与"行为中性 diff"天然契合：只有 >80% 确信是真问题才上报；要求精确到文件行号、能描述具体失败模式、已读过周围上下文、严重级别可辩护，四条不满足任一条就降级或丢弃该发现。对一个纯重构 diff，"零发现 + APPROVE"是被明确鼓励的正常结果（"A clean review is a valid review"）——这防止了评审噪声淹没真正的问题。评审按 CRITICAL（安全）→ HIGH（代码质量）→ MEDIUM（性能）→ LOW（最佳实践）分层，并输出带严重度统计的 Review Summary 与 Verdict。

这里有一个值得注意的细节：refactor-cleaner 的 v1.8 AI-Generated Code Review Addendum 要求对 AI 生成的变更优先检查"行为回归与边缘情况"，并建议对确定性重构默认走低成本模型档位——正对应 refine 这种"确定性高、创造性低"的任务。
安全触发条件。按 skills/orch-pipeline/SKILL.md 的 "Security-review trigger"（依据 rules/common/security.md），当 diff 触及以下任一项时，评审阶段必须额外拉上 security-reviewer：认证/授权、用户输入处理、数据库查询、文件系统路径、外部 API 调用、加密、密钥/凭据。重构虽然"不改行为"，但搬移代码完全可能误伤上述敏感路径，所以这条规则在 refine 流程中同样生效。
以 refactor: 前缀提交，diff 必须行为中性。提交发生在 GATE 2 之后：先向用户展示 diff 摘要与拟定的提交信息，用户确认后才落盘。

3.5 两道 Gate：gated, not autonomous

整条流水线的控制权模型是"有关卡、非自主"（"This family is gated, not autonomous"）：

Gate	位置	停下等什么
GATE 1	Plan 之后（阶段 2 末尾）	展示 `task_list`，用户批准前不写任何实现代码
GATE 2	Commit 之前（阶段 6 入口）	展示 diff 摘要与拟提交信息，用户确认前不提交

两道 Gate 之间的一切（实施、测试、评审）连续流动、不停顿。这意味着一次典型会话的交互节奏是：给出重构目标 → 批准规划 → （中间自动跑完）→ 确认提交，共两次人工介入。

四、阶段代理映射：谁在哪个阶段干活

从 skills/orch-pipeline/SKILL.md 的 "Agent / command map" 看，refine 流程实际会触及的代理（均已确认存在于本仓库）：

阶段	主代理	兜底/升级
Intake / 理解现状	code-explorer	在 tweak/fix/refactor 前先追踪既有代码路径
Plan	planner	结构性决策升级到 `architect` / `code-architect`
Implement	tdd-guide（或 `tdd-workflow` 技能）	构建中断时走 `build-error-resolver` / `/build-fix`
Review	code-reviewer / commands/code-review.md	按语言匹配的语言评审代理（`python-reviewer`、`typescript-reviewer`…）
Security	`security-reviewer`	—

两个衔接点值得展开：

Intake 阶段的 code-explorer。重构前"先读懂现状"由 code-explorer 负责，orch-pipeline 明确要求"trace existing paths before a tweak, fix, or refactor"——这解释了为什么 GATE 1 展示的 task_list 能具体到"薄垂直切片"：切片来自对既有调用路径的实际追踪，而非凭空规划。
语言评审代理的匹配规则。orch-pipeline 要求"Match the language reviewer to the repo (see the repo's own CLAUDE.md)"，即评审阶段先读目标仓库的 CLAUDE.md 确定语言栈，再选对应的 reviewer。对本仓库而言，CLAUDE.md 即该规则的信息源。

五、与姊妹命令的边界对照

三组 orch 命令的首步规则（first move）差异是区分它们的最佳标尺，三者共同点是都经过同一引擎、同样的两道 Gate、同样的 refactor: / fix: / 对应前缀提交：

维度	`/orch-refine-code`	`/orch-change-feature`	`/orch-fix-defect`
规模下限	standard（多文件）	small	small（常为 trivial）
首步	确认既有测试动码前为绿；覆盖薄先补特征测试	先修改既有测试表达新行为，再改实现	先写新失败回归测试复现 bug
测试方向	不写新行为测试，旧套件证明行为未变	改测试 = tweak 的本质	先红后绿 = fix 的本质
提交前缀	`refactor:`（diff 行为中性）	行为变更类提交	`fix:`
根因定位	不需要（目标明确）	轻规划（仅在需研究时）	可用 `code-explorer` 界定根因

orch-pipeline 强调 orch 家族是"组合既有 ECC 命令而非替代"：底层复用 /feature-dev、/plan、/code-review、/refactor-clean、/gan-build 等命令与 tdd-workflow 技能，orch 家族在其上加统一的大小分级器和两道 Gate，"一个伞盖住五种操作且保持一致性"。

六、完成判据：Verification 清单

引擎为每次运行定义了可自查的验收条件（skills/orch-pipeline/SKILL.md "Verification" 节）：

规模档位已被明示，且与实际工作量匹配；
Gate 1（计划）与 Gate 2（提交）都被遵守；
当且仅当 diff 触及安全触发条件时，security-reviewer 被拉入；
提交遵循 Conventional Commits，且每个提交只覆盖一个逻辑变更；
新增/变更行为都有测试；覆盖率按 rules/common/testing.md 要求达到 ≥ 80%。

最后一项对 refine 操作有一个微妙之处：80% 覆盖率是引擎的通用判据，而 refine 的具体承诺更窄——既有套件在每一步之后都保持全绿。两者结合，才构成"行为保持"的完整证据链。

七、小结与延伸阅读

/orch-refine-code 的价值不在任何单点技巧，而在于它把"重构不改变行为"这一口头承诺固化成了可验证的流程：动码前证绿、覆盖薄先补特征测试、小步走每步重跑、删除类工作委派给带风险分级的 refactor-cleaner、评审允许零发现、两次人工 Gate、refactor: 提交封口。所有环节都能在当前仓库中溯源：