ECC `/orch-change-feature` 完全指南：以测试先行的方式改造既有功能行为

本指南围绕 ECC（The agent harness performance optimization system）中用于"改造既有功能行为"的编排命令 /orch-change-feature 展开，说明其适用边界、编排阶段、双门禁（Gate）审批机制与底层源码实现。读完你可以判断一个需求究竟属于"改行为（tweak）""修缺陷（fix）"还是"加能力（feature）"，并能像真实 Agent 一样，以"先改测试、再改实现"的顺序驱动一次有评审、有门禁的改造闭环。

命令定位：为"改行为"而生的编排包装

在 ECC 的仓库中，commands/orch-change-feature.md 是一份典型的"操作编排包装器"（thin wrapper）命令文档。它本身不实现任何具体逻辑，而是把用户输入原样转交（$ARGUMENTS）给同名的 orch-change-feature skill，再由该 skill 委托给共享编排引擎 skills/orch-pipeline/SKILL.md 去执行。

其 frontmatter 中给出的定位非常精确：

Orchestrate altering an existing, working feature to new desired behavior — update tests to the new spec, change the implementation to match, review, and gated commit. Use when behavior is not broken but should be different.

一句话概括：当一个功能已经能工作（working），但你希望它的行为按新的规格发生变化时，用 /orch-change-feature。 它不属于 bug 修复（代码没有坏），也不属于从零新增能力（能力已经存在），而是介于两者之间的"定向微调"。

该命令在仓库的注册表 docs/COMMAND-REGISTRY.json（第 581–593 行）中被登记为 type: "orchestration"，其 skill 映射涵盖了 orch-add-feature、orch-change-feature、orch-fix-defect 三个家族成员，说明它与兄弟命令共用同一套能力底座。

命令使用方式与参数约定

基本用法

/orch-change-feature <the new desired behavior>

命令的入参是一段自然语言描述的新期望行为，而不是一个命令开关列表。仓库文档给出了两个典型例子：

/orch-change-feature make nws-poller alert at 2 warnings instead of 3
/orch-change-feature instead of sorting by date, sort by priority

第一个例子是把"NWS 轮询器在 3 次告警时才触发"改成"2 次就触发"——典型的行为阈值调整；第二个例子是把"按日期排序"改成"按优先级排序"——典型的排序策略变更。它们共同的特征是：功能本身在运行、没有报错，只是产出规则需要变化。

参数为空时的兜底

按照命令文档的约定，如果 $ARGUMENTS 为空，编排器应当向用户询问"期望改变什么行为"，而不是擅自猜测目标，避免在需求未明确时误改既有实现。

何时使用：与兄弟命令的边界判断

这是 /orch-change-feature 最容易用错的地方，命令文档专门划定了三个边界：

判断问题	属于	使用命令
功能正常工作，只是期望的行为不同（"改成…""调整为…""不要 X 而要 Y"）	tweak（微调）	/orch-change-feature
行为坏了/错了，需要修复	fix（缺陷）	/orch-fix-defect
能力还不存在，要新增	feature（新能力）	/orch-add-feature

skills/orch-change-feature/SKILL.md 进一步用否定句式强调了区分标准：不是 broken（所以不是 orch-fix-defect，没有 bug 需要复现）；不是 new（所以不是 orch-add-feature，该能力已经存在）。

同样的边界矩阵也出现在共享引擎 skills/orch-pipeline/SKILL.md 的"operation family"表中：orch-add-feature 的 first move 是"research + plan a new slice"，orch-fix-defect 的 first move 是"reproduce as a failing test, then fix"，而 orch-change-feature 的 first move 是 amend existing behavior and its tests——注意这里改的是"既有行为及其既有测试"，这与修 bug 时"新写一条失败的回归测试"在姿态上完全不同。

命令执行后的编排流程

/orch-change-feature 被触发后，真正干活的是被委托的 skill 与共享管道。命令文档给出的顶层流程如下：

1. 分类规模（默认下限：small），并用一行说明所处 tier；
2. 仅当新行为需要调研时做轻量计划 → 停在 GATE 1（批准改后的测试计划）；
3. 先更新既有测试以表达新行为，再修改实现直到全绿（先改测试，是它区别于"修复"的关键）；
4. 由 code-reviewer 评审（若触碰安全触发条件则追加 security-reviewer），随后提交 → 停在 GATE 2。

从源码看分层调用关系

这条调用链在仓库中是一层层"薄包装"叠加出来的，可以用下面的层次理解：

• 命令层：commands/orch-change-feature.md —— 用户入口，透传 $ARGUMENTS；
• Skill 层：skills/orch-change-feature/SKILL.md —— 定义操作参数（size floor、phase mask、first move），并明确它是 orch-pipeline 的 thin wrapper；
• 引擎层：skills/orch-pipeline/SKILL.md —— 定义 gated Research-Plan-TDD-Review-Commit 管道、规模分类器、Agent 映射和两道人工门禁；
• 执行层：各阶段进一步委托给仓库内既有的命令与 Agent（如 /code-review、/plan、tdd-workflow skill、code-reviewer 等）。

正如 orch-pipeline 文档反复强调的：这些 wrapper 组合（compose）既有的 ECC 命令而不是替换它们——/feature-dev、/plan、/code-review、/build-fix、/refactor-clean、/gan-build，以及 tdd-workflow skill——orch-* 家族只是在它们之上增加了共享的规模分类器和两道门禁，用一把伞覆盖五种操作的一致体验。

双门禁机制：gated，而非 autonomous

整个 orch-* 家族有一个重要设计原则：管道是有门禁的，不是全自动的。两道人工门禁（human gates）分别卡住"写实现之前"和"提交之前"：

1. GATE 1 —— Plan 之后：向用户展示 task_list，在用户批准前不得编写任何实现代码；
2. GATE 2 —— Commit 之前：向用户展示 diff 摘要与拟提交信息，在用户确认前不得提交。

两道门禁之间的工作则一气呵成、不停顿。对 /orch-change-feature 而言，GATE 1 通常承载的是"改后的测试计划审批"——因为你改动的是既有行为，用户需要确认新的测试断言确实表达了他要的新规格；GATE 2 则是提交前的最终闸口。

该工程理念保证了"编排器再强大，关键决策点仍由人来拍板"，这也是它在 skills/orch-pipeline/SKILL.md 中被称为 gated, not autonomous 的原因。

共享引擎中的阶段细节（Step 0～6）

下面按共享引擎 skills/orch-pipeline/SKILL.md 展开每个阶段，帮助你理解一个请求从进入到提交内部经历了什么。

Step 0：规模分类（right-sizing）

原则：仪式感（ceremony）与爆炸半径（blast radius）成正比。 引擎对请求按三个信号打分，取任一信号到达的最高档位作为最终 tier，并用一行说明结果以便用户覆盖（override）：

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

Phase 0（Intake）永远执行，因此不体现在上面的 mask 列中。平手裁决规则：任何触碰安全触发条件或公共 API/契约的改动，无论文件数量多少，至少按 standard 处理。对 /orch-change-feature 而言，默认下限是 small——正如 SKILL 中所说，绝大多数 tweak 只是"一两个函数的事"。

Phase 0 — Intake：复述请求

任何请求都从这里开始：重述请求（restate the request），确保双方对"要改变什么行为"的理解一致。这也是为什么文档要求：如果 $ARGUMENTS 为空，先向用户问清楚要改什么，而不是贸然进入后续阶段。

Phase 1 — Research & Reuse：按需调研

遵循 rules/common/development-workflow.md 规定的检索顺序：gh search repos / gh search code → Context7 / 厂商文档 → 包注册表 → Exa。原则是优先采纳已被验证的实现，而不是从零写新代码。对 tweak 型改动，这一步通常是"light"模式——只有当新行为确实需要调研（例如引入新的库语义、不确定现有代码里哪里承载了旧行为）才完整执行。

Phase 2 — Plan：轻量计划

委托给 planner agent（涉及结构性决策时升级到 architect / code-architect），输出按**薄垂直切片（thin vertical slices）**排序的 task_list。对 /orch-change-feature，SKILL 明确"keep the plan light"——只有 standard 及以上规模才需要完整的 planner 流程。计划产出后停在 GATE 1。

Phase 4 — Implement (TDD)：先改测试，再改实现

这是 /orch-change-feature 的灵魂阶段。每个 task 都由 tdd-guide agent（或 tdd-workflow skill）按 red → green → refactor 驱动，并遵守操作自身的 first-move 规则：

First move (phase 4)： update the existing tests to express the new desired behavior, then change the implementation until they pass. Changing the tests first is what separates a tweak from a fix.

也就是说，你要做的第一步是修改既有测试的断言，让它们描述"新期望行为"——此时测试会变红（red）；然后修改实现直到测试全绿（green）；需要的话再做重构（refactor）。先改测试，是区分"tweak"与"fix"的分水岭：修 bug 是先写一条失败回归测试复现缺陷，而改行为是先改写既有断言来表达新规格。

对比一下家族内三种操作在实现阶段的差异会更清晰：

• orch-change-feature（tweak）：改既有测试 + 改实现；
• orch-fix-defect（fix）：新写一条失败的回归测试复现 bug，再修到绿；
• orch-refine-code（refactor）：行为不变，不新增行为测试，靠既有套件兜底，逐步重构。

Phase 5 — Review：代码评审

由 code-reviewer agent（或 /code-review 命令）执行评审；diff 触碰安全触发条件时追加 security-reviewer。语言级 reviewer（python-reviewer、typescript-reviewer 等）应按仓库自身的 CLAUDE.md 匹配。评审产出的 CRITICAL / HIGH 级问题必须在 GATE 2 前解决。

Phase 6 — Commit：Conventional Commits

采用 conventional commits 规范（feat: / fix: / refactor: 等），每个逻辑块一个提交。对 tweak 而言，提交信息应该反映的是"行为调整"而非"修复缺陷"或"新特性"。提交前停在 GATE 2。

安全触发条件与评审追加

什么时候需要额外的 security-reviewer？共享引擎给出了明确的触发清单：当 diff 触碰以下任意一类内容时——认证/授权、用户输入处理、数据库查询、文件系统路径、外部 API 调用、加密、密钥/凭据。该清单源自 rules/common/security.md。也就是说，即使你只是把 NWS 轮询器的告警阈值从 3 改成 2，只要改动恰好落在上述敏感路径上，编排器就会自动把 security-reviewer 拉进评审环节，而不只依赖常规的 code-reviewer。

Agent / 命令映射表

共享引擎为每个阶段预设了"主角色 + 兜底/升级路径"：

阶段	主角色	兜底 / 升级
Intake / 理解	code-explorer	做 tweak/fix/refactor 前先追踪既有代码路径
Plan	planner	结构性决策升级 architect / code-architect
Implement	tdd-guide（或 tdd-workflow skill）	构建失败时 build-error-resolver / /build-fix
Review	code-reviewer / /code-review	语言级 reviewer（python-reviewer、typescript-reviewer…）
Security	security-reviewer	—
MVP 内循环	/gan-build "<brief>" --skip-planner	驱动 gan-generator → gan-evaluator；可调 --max-iterations / --pass-threshold

上表中与 /orch-change-feature 场景关系最密切的是 code-explorer（动手前先摸清旧行为散落在哪些路径）、tdd-guide（承载"先改测试"的纪律）与 code-reviewer（提交前把一道关）。

无隐藏状态：交接物即文档

orch 家族的设计强调 管道不携带任何隐藏状态——计划文档本身就是交接物（handoff artifacts）：

• task_list（来自 Plan 阶段）驱动 Implement 循环；
• 较大规模的工作可能还会在仓库 docs/ 下产出 PRD / architecture / system_design（按 rules/common/development-workflow.md 约定）；
• 评审发现（CRITICAL / HIGH）必须在 GATE 2 之前全部解决。

这意味着你可以随时中断或复盘一次 /orch-change-feature 会话：只要看 task_list 与评审记录，就能知道改到哪一步、卡在哪道门禁。

完成度验证清单

一次合格的 tweak 编排，应当能通过 skills/orch-pipeline/SKILL.md 给出的 Verification 清单逐项核对：

• 规模档位（tier）已被陈述，且与实际工作量匹配；
• GATE 1（plan）与 GATE 2（commit）都被遵守；
• security-reviewer 在且仅在触碰安全触发条件时运行；
• 提交符合 conventional commits 规范，且每个提交只承载一个逻辑变更；
• 新的/被改变的行为都有测试，且按 rules/common/testing.md 的要求覆盖率 ≥ 80%。

这最后一条尤其值得注意：它意味着"改行为"不允许裸改实现而不动测试——测试覆盖既是改造的起点，也是改造完成的验收标准。

实际演练示例

结合仓库文档中的例子，一次完整的 /orch-change-feature 会话大致长这样：

/orch-change-feature make nws-poller alert at 2 warnings instead of 3

编排器内部执行路径：

1. 分类：改动集中在 nws-poller 的告警判定逻辑，属于 1 个文件/1 个函数级别的调整 → 声明 tier = small；
2. 轻量计划：定位承载阈值 3 的常量/配置与断言"3 次才告警"的既有测试；若无需额外调研，直接给出改后测试计划 → GATE 1 请用户批准；
3. 先改测试：把既有测试中断言告警触发次数的 3 改为 2（此时测试红）→ 修改实现中阈值判断到 2 → 测试全绿；
4. 评审：code-reviewer 检查 diff（若告警逻辑触碰外部 API 调用或文件系统路径，追加 security-reviewer）；
5. 提交：以 conventional commit 提交一个逻辑变更 → GATE 2 请用户确认后落盘。

小结

/orch-change-feature 把"改造一个能工作但行为需调整的功能"这件事，收敛成一条纪律严明的流水线：规模分类定轻重 → 轻量计划过 GATE 1 → 先改测试表达新规格 → 改实现跑到绿 → 评审（必要时加安全评审）→ conventional commit 过 GATE 2。它不是替代工程师思考的魔法，而是一套把"既有行为变更"做成可评审、可回滚、有测试护栏的工程化流程——当你下一次想对代码说"能不能让它换个行为"时，记得先分清这是 tweak、fix 还是 new feature，再选择对应的编排入口。

延伸阅读（仓库内相对路径）

• 命令本体：commands/orch-change-feature.md
• Skill 定义：skills/orch-change-feature/SKILL.md
• 共享编排引擎：skills/orch-pipeline/SKILL.md
• 家族兄弟命令：commands/orch-add-feature.md、commands/orch-fix-defect.md、commands/orch-refine-code.md
• 命令注册表：docs/COMMAND-REGISTRY.json（orch-change-feature 条目位于第 581–593 行）
• 支撑规则：rules/common/development-workflow.md、rules/common/security.md、rules/common/testing.md