REFACTORING METHODOLOGY / ENGINE DESIGN

用 Harness 约束边界，用 Loop 推动执行

在大型核心系统重构场景中，研发团队面对的不只是单点代码修改，而是复杂的系统级不确定性。要让 AI Coding 安全有效地进入大型重构场景，核心不是给 AI 更大的自由度，而是先搭建一套**可执行、可验证、可回滚**的工程闭环。AI 在闭环里高频推进，人类工程师负责关键判断和风险控制。

---

## 1. 先理解两个关键词：Harness 和 Loop

**Harness 负责约束边界，Loop 负责反馈推进**

在大型 AI 重构方法论中，最重要的两个关键词是 **Harness** 和 **Loop**：

* **Harness 是约束系统**：它定义目标、边界、上下文、规则、可用工具和停止条件，决定 AI 可以做什么、不能做什么、遇到什么情况必须停下来。
* **Loop 是反馈系统**：它让每次执行都经历计划、修改、验证、分析、记录和判断，决定下一步是继续推进、重试修复，还是升级给人工确认。

没有 Harness，AI 很容易在边界不清时自作主张补齐假设；没有 Loop，自动执行就容易变成失控的连续改动。大型重构需要二者共同工作：**先把行动空间收敛，再让执行过程具备实时反馈**。

![图 1：Harness 约束系统 vs Loop 反馈系统](images/harness-vs-loop.svg)

---

## 2. 四阶段闭环：从目标到上线证据

**AI Coding 驱动系统重构的四阶段全流程闭环**

有了 Harness 和 Loop 之后，重构流程需要被组织成可持续推进的阶段闭环。大型重构拆为**规划、设计、执行、验收**四个阶段。只有执行阶段真正进入高频 AI Coding 自动化循环，前面的规划和设计主要用于把目标、边界、方案和验证条件清晰对齐。

1. **规划阶段 (Planning)**：明确重构目标、扫描系统链路、建立指标基线，先回答“为什么改、改到什么程度算成功”。
2. **设计阶段 (Design)**：完成技术方案、里程碑拆解、Phase / Task 规划和依赖关系梳理，回答“怎么改、按什么顺序改”。
3. **执行阶段 (Execution)**：按照 Task 逐步执行 AI Coding，每次改动都要验证、记录和判断，失败后进入分析与修复流程。
4. **验收阶段 (Acceptance)**：汇总测试结果、Diff 结论、指标效果和发布证据，判断是否具备上线收口条件。

![图 2：AI Coding 驱动系统重构的四阶段全流程闭环](images/four-stage-loop.svg)

---

## 3. 人机分工：人负责判断，AI 负责高频执行与沉淀

**人负责方向与风险判断，AI 负责高频执行与沉淀**

大型重构里，人和 AI 的分工必须极为清晰。AI 适合做信息整理、代码扫描修改、测试执行、Diff 分析和文档沉淀；人必须负责目标定义、边界划定、架构判断、风险接受和上线决策。

| 角色 | 主要职责 | 不能交出去的部分 |
| --- | --- | --- |
| **人 (Human)** | 目标定义、边界划定、架构判断、风险接受、上线决策 | 方向判断、方案取舍、是否继续推进 |
| **AI (Agent)** | 代码扫描、方案辅助、代码修改、测试执行、Diff 分析、报告沉淀 | 不能替代人确认业务目标和风险边界 |

人的工作不是退到流程之外，而是在关键节点做判断、设边界、看证据。AI 的价值则体现在高频执行和沉淀上，把大量重复、细碎、可验证的工作持续推进下去。

![图 3：重构工程中的人机分工模型](images/human-vs-ai-roles.svg)

---

## 4. 任务拆解：先里程碑，再 Task

**从重构目标拆到 AI 可稳定执行的 Task**

大型重构不能直接把“大目标”丢给 AI。目标越大，隐含假设越多，AI 越容易在不确定的地方自行补齐。更稳妥的做法是：**重构目标 ➔ 里程碑 (Milestone) ➔ 阶段 (Phase) ➔ 任务 (Task)**。

* **里程碑 (Milestone)**：表达阶段性业务目标（例如先保证行为一致，再做性能优化，最后做灰度收口）。
* **阶段 (Phase)**：表达一组有共同验收目标的任务集合，便于阶段性 Go / No-Go 判断。
* **任务 (Task)**：AI 可稳定执行的最小工程单元，接近一次小需求改动，且能独立验证、独立回滚。

![图 4：大型重构任务拆解层级 (Milestone ➔ Phase ➔ Task)](images/task-breakdown.svg)

---

## 5. Task 文件：先约束输入，再沉淀证据

**Task 文件必须定义执行输入、验证标准和风险出口**

要让 AI 稳定执行，Task 文件（Task Spec）不能只写一句“实现某能力”。它必须提前定义 6 大要素：

1. **01 做什么**：写清任务目标、业务背景、交付物和成功状态。
2. **02 改哪里**：写清允许修改范围、涉及模块、代码改动清单与入口文件。
3. **03 不改哪里**：写清不能触碰的链路、接口语义、配置项与历史兼容逻辑（减少“顺手优化”带来的风险）。
4. **04 怎么验**：写清编译、单测、自动化测试、行为 Diff 等验证标准。
5. **05 失败怎么办**：写清回滚方案、兜底策略与失败记录。
6. **06 什么时候停**：写清停止条件、Human Gate 与人工升级规则。

### 沉淀 4 类执行产物：

Task 执行完成后，还必须沉淀执行证据。代码写完不代表 Task 完成，真正完成的标准是执行文档、验证结果和判断结论可以被后续任务复用：
* **Task 执行记录**：修改文件、修改原因、改动摘要、不修改内容。
* **验证结果**：编译、单测、自动化测试、Diff 分析、性能数据。
* **风险判断**：遗留风险、失败原因、是否需要人工确认。
* **产物链接**：方案文档、代码变更、测试报告、部署记录。

![图 5：Task Spec 可执行任务规格书与三大维度](images/task-spec.svg)

---

## 6. 项目总览文件与自动化执行

**项目总览文件  是 AI 项目的状态源**

当 Task 数量变多后，单轮对话不可能承载全部上下文。大型 AI Coding 项目需要一个项目总览文件 ，作为文档导航页、状态页、上下文恢复入口和自动化执行入口：

* **项目定义**：记录背景、目标、范围边界、关键约束与最终验收标准。
* **过程产物链接**：聚合静态扫描、系统架构、方案文档、验证报告和部署记录。
* **执行状态源**：记录 Task Graph、Task 执行列表、当前进度、阻塞点与下一步动作。
* **上下文恢复**：让 AI 在新会话里秒级定位当前项目状态，无需重新理解整套系统。

自动化执行引擎按项目总览读取进度并找到下一个 Task，进入 Harness + Loop 执行；完成后将执行记录、验证结果写回总览文件。

![图 6：项目总览文件 refactor-overview.md 与自动化执行架构](images/refactor-overview.svg)

---

## 7. 发布级质量控制

**把“开发正确”推进到“生产可控”**

Task 级验证只能证明单次改动在局部范围内可控，发布级验证要证明新流程在真实流量下行为一致、指标稳定、异常可回退：

* **影子双跑**：新旧流程同时运行，用 Diff 对比核心结果，在不影响线上行为的前提下收集差异。
* **灰度切流**：逐步提高新流程真实流量占比，避免一次性全量切换带来的不可控风险。
* **监控放量**：持续观察成功率、耗时、错误率、资源消耗和核心业务指标。
* **异常止损**：指标超过阈值时自动切回原流程，并保留排障证据，保证问题可定位、可恢复。

---

## 总结

AI Coding 在大型系统重构中的核心价值，**不是替代工程治理，而是把工程治理变得更细、更连续、更容易被执行**。

通过 Harness 明确约束边界，通过 Loop 建立自动化反馈闭环，团队才能在不中断业务交付的前提下，把高风险的大型重构收敛为可控、可验证的连续工程迭代。