Harness设计重构实战
很多小伙伴已经会用 AI 写接口、补单元测试、排查报错，也能跟着 AI 做出一个完整项目。但是面试官再往下问几句，难度马上就变了：
- 这个项目哪些地方是你设计的，哪些地方交给了 AI？
- 一次改造涉及几十个模块时，你怎么把大任务拆开？
- 会话聊了几十轮、上下文压缩了很多次，前面的关键结论怎么保证不忘？
- AI 改错以后，怎么让它自己发现问题、回到正确位置继续修正？
- 单元测试通过了，你怎么确认真实数据库、索引和运行进程也使用了新代码？
- 经过几个月持续修改，怎么避免项目里堆满临时判断和兼容代码？
只展示最终代码，很难回答这些问题。面试官想听的是你怎样分析问题、设计方案、控制风险，以及怎样让 AI 长时间参与一个真实项目。
我在 Nexus Agent Pro 的改造过程中，把这部分也完整保留了下来。除了学习项目本身，小伙伴还可以看到我怎样设计一套 AI Harness 工作流，再让 AI 按照这套工作流逐步完成整个 RAG 系统重构。
如果你第一次接触 Harness，可以先把它理解成一套放在项目仓库里的长期工作流。它会管理 AI 每次从哪里开始、当前能改什么、怎样证明修改有效、什么时候停下来找用户，以及后续发现旧问题时怎样恢复施工顺序。
这套课程来自一次真实的项目重构
Nexus Agent Pro 的后端同时涉及 Java、Python、文档解析、异步任务、五类检索、候选融合、重排、提示词、引用、归档，以及 MySQL、Redis、Kafka、PostgreSQL、Elasticsearch、MinIO、Neo4j 等存储和中间件。
一次回答出现问题，原因可能落在任何一段。正确内容也许没有召回，也许在融合时丢了，也许进入重排后被窗口截断了，还有可能已经交给模型，却在引用绑定或归档时出现偏差。
这样的项目很适合学习 AI 怎样参与大型重构，因为它同时具备几个特点：
- 修改会跨越很多模块和两种语言；
- 一个问题经常要追踪很长的调用链；
- 自动测试无法覆盖全部真实运行环境；
- 上传文档、重建索引、产生真实对话会写入业务数据；
- 后续验收可能推翻前面已经完成的判断；
- 整个过程会经历很多次新会话和上下文压缩。
我把这次改造拆成了 S00～S18，一共十九个阶段。每个阶段都有单独的目标、修改边界、测试要求、人工操作边界和退出条件。课程文章负责讲清楚我是怎样设计这套方法的，阶段计划和执行记录则保留 AI 实际施工时发生过的失败、修正与验收证据。
最终源码只能告诉我们“现在是什么样”。这套课程还保留了“为什么这样设计”“原计划哪里判断错了”“AI 怎样根据新证据修正计划”“每个阶段怎样证明已经完成”。这些内容以后也可以迁移到自己的项目中。
课程里会提供哪些工程资料
为了让 AI 在很多次会话之间继续工作，我把不同职责的内容拆开放进仓库。学员可以把课程文章和真实工程资料对照着看。
| 资料 | 主要解决什么问题 |
|---|---|
| AI 长期规则 | 规定每次会话都要遵守的架构边界、权限和收工要求 |
| 改造计划与进度 | 保存总体设计、阶段依赖和唯一的当前阶段 |
| 当前阶段与下一步 | 记录最近一次停止位置，以及新会话应该怎样继续 |
| 阶段计划 | 告诉 AI 当前阶段为什么要做、能改哪里、怎样测试、什么时候结束 |
| 执行记录 | 保存实际命令、测试数量、失败原因、计划偏差和验收结果 |
| 验证规则 | 统一自动测试、运行数据检查和人工验收的判断标准 |
| 最终源码与测试 | 查看设计最后怎样落到 Java、Python、数据库和运行链路中 |
这些资料各管一件事。新会话不需要重新翻完全部聊天记录，只需要按固定入口读取当前阶段需要的内容。历史记录也不会抢走当前状态的解释权。
Harness 会持续告诉 AI 哪些事情
AI 会写代码，大型任务仍然可能失控，因为它拿到的控制信息不完整。我的这套工作流会在每次开工、施工和收工时告诉 AI：
| AI 需要知道的内容 | 解决的问题 |
|---|---|
| 每个新会话先读哪些文件 | 避免只靠聊天摘要恢复上下文 |
| 当前只能进入哪个阶段 | 防止顺手修改相邻模块，导致问题混在一起 |
| 哪些结论已经被代码或数据确认 | 把事实和猜测分开，猜测不能直接推动长期改造 |
| 当前阶段允许和禁止修改什么 | 保护用户已有代码，也控制实际影响范围 |
| 修改前先补什么测试 | 先证明旧实现哪里不满足目标，再开始改生产代码 |
| 测试通过后还要检查哪些运行数据 | 避免单元测试通过，真实进程仍然使用旧代码或旧数据 |
| 什么时候更新状态并停下来 | 阶段完成后及时收口，不在同一会话继续扩张范围 |
| 哪些操作必须交给用户 | 上传、重建、真实聊天等业务操作保持清楚的授权边界 |
| 后续发现问题时回到哪个阶段 | 找到最早责任阶段，修复根因后再恢复原来的进度 |
AI 依然可以自己调查源码、比较方案、写测试和实现功能。它的自主工作有了可靠边界，遇到证据不足、需要人工操作或发现旧结论失效时，也能及时把情况反馈给我。
为什么我没有把工作流绑死在 superpowder 上
我知道 superpowder 也在处理复杂任务拆分、按步骤执行和质量检查这些问题。对于刚开始用 AI 做项目的小伙伴来说，现成插件可以省掉不少准备工作，装好以后就能跟着它的流程往下走。
我在 Nexus Agent Pro 的长期重构中更关心流程能不能跟着项目一起变化。AI 模型一直在升级，过去需要插件分成很多步才能完成的工作，新模型可能已经可以自己处理。固定流程如果没有同步变轻，原来用于帮助模型的步骤就会逐渐显得笨重。
项目本身也会不断产生新的要求。这个阶段需要冻结数据库水位，下一个阶段要等用户重建文档，后面又可能出现阶段重开。通用插件很难提前知道每个项目的业务边界，项目只能再写一层规则去适配插件原有的执行节奏。
所以我把工作流的控制信息放回了项目仓库。哪些步骤需要保留、哪些步骤可以合并、什么时候必须暂停、用什么证据完成验收，都可以根据当前模型和项目情况直接调整。
| 发生的变化 | 固定插件流程可能遇到的问题 | 这套仓库工作流怎样处理 |
|---|---|---|
| AI 模型能力升级 | 仍然执行过去为旧模型准备的全部步骤 | 删除或合并已经多余的步骤 |
| 项目边界变化 | 需要绕过插件默认流程或增加适配规则 | 直接修改当前阶段合同和长期规则 |
| 更换 AI 工具 | 新工具要重新安装并理解插件约定 | 读取同一套仓库文件就可以接手 |
| 需要真实产品操作 | 通用流程很难知道哪些数据必须由用户产生 | 在阶段中明确人工操作、事前水位和只读验收 |
| 后续验收推翻旧结论 | 容易从当前失败位置继续打补丁 | 重开最早责任阶段，修完后恢复原进度 |
这套设计也不会排斥插件。superpowder、Skills、Hooks 和其他 AI 工具中有用的能力都可以继续使用，只是它们不负责解释项目当前进行到哪里，也不拥有最终验收标准。项目需要什么就留下什么，模型已经能自己做的步骤就及时拿掉。
这样一来，AI 升级以后，工作流可以跟着变轻；项目增加新的测试、状态和人工节点时，也能直接补进仓库。我们不需要等待某个插件更新，或者让整个项目长期迁就一套固定流程。
一个阶段怎样交给 AI 执行
总体设计写得再完整，也很难直接作为施工命令。交给 AI 的阶段计划需要回答几个更具体的问题：
- 当前问题怎样稳定复现；
- 哪些结论由源码确认，哪些结论由运行数据确认；
- 这个阶段唯一要关闭的工程问题是什么；
- 可以修改哪些模块，哪些相邻问题先记录下来；
- 修改生产代码前要补哪条失败测试；
- 实现完成后跑哪些定向测试、回归测试和静态检查；
- 是否需要用户上传文档、重建索引或产生新对话；
- 哪些证据齐全后，阶段才可以结束。
AI 开工后先核对当前源码。有时阶段计划中的类名已经变化，有时旧测试固定的恰好是错误行为。AI 需要先把文档与源码的差异写出来，再决定真实修改范围。这样可以避免为了符合一份旧计划，反过来改坏已经正确的代码。
会话压缩以后，下一次怎么接着做
一次大型重构会经历很多轮聊天。上下文压缩可以保留大意，却很难完整保存这些细节：
- 当前代码基于哪个版本；
- 工作区原来就有哪些未提交修改；
- 哪条假设已经被运行数据否定；
- 当前阶段只允许动哪些模块；
- 用户操作前记录了哪些数据水位；
- 哪些测试只是在固定旧行为；
- 下一步需要自动执行，还是应该停下来等用户。
所以我没有把聊天记录当成长期状态。每次收工，AI 都要把当前状态、实际执行结果和下一步写回仓库。新的 AI 工具接手时，也走同一套恢复入口。即使更换模型或开发工具，项目仍然知道自己进行到了哪里。
这套设计对学员很有帮助。小伙伴可以直接比较“阶段原本准备怎么做”和“执行中实际发生了什么”，也能看到新会话怎样在较小的上下文里继续完成任务。
改造出问题以后，怎么回到正确阶段
持续重构最麻烦的情况，是后续验收推翻了前面已经完成的判断。
例如，早期判断认为正确证据在重排阶段丢失，后续运行数据证明它已经进入最终证据选择环节。继续调重排参数只会增加新的补偿逻辑。Harness 会沿数据产生位置、处理过程和最终使用位置重新调查，把问题交给最早拥有根因的阶段。
课程使用六种状态管理这条施工线：
| 状态 | 通俗理解 |
|---|---|
NOT_STARTED | 阶段还没有开工 |
IN_PROGRESS | 已经开始修改测试或实现 |
HUMAN_ACTION_REQUIRED | AI 已完成自动工作，正在等待用户产生真实数据 |
BLOCKED | 外部条件已经复现，当前确实无法继续 |
DONE | 阶段退出条件和证据全部完成 |
REOPENED | 后续证据推翻了一个已经完成的阶段，需要回去返工 |
进入阶段重开后，原来的执行进度会被冻结。责任阶段修好并重新验收后，工作流再恢复到原来的位置。旧执行记录继续保留，因为它能告诉学员当时为什么判断错误、新证据又是怎样推翻它的。
AI 怎样检查自己改得对不对
单元测试通过，只能说明测试环境里的几组输入满足断言。真实项目中还会出现很多“看起来已经通过”的情况：
- 测试里的模拟对象绕开了生产环境实际使用的提示词；
- Java 内存中的稳定标识正确，数据库字段长度却保存不下；
- 源码已经更新，文档、索引和知识图谱仍然是旧版本生成的；
- 历史回答刚好正确，却没有证明新代码走过目标链路；
- 候选数量相同，其中一个真实来源证据已经被其他内容替换。
课程会把验证拆成几层：先固定旧系统目前怎样运行，再补一条能稳定失败的目标测试；实现完成后运行定向测试、受影响回归、全量测试、编译和静态检查；需要真实运行结果时，再由用户产生新文档、新索引或新对话，AI 根据事前记录的数据水位做只读验收。
每一层回答的问题不同。AI 发现失败后，也能沿运行记录定位是召回、融合、排序、最终证据、提示词、引用还是归档出了问题。这样修复会落到真实责任位置，代码质量不会在一轮轮局部补丁中慢慢下滑。
学完以后，面试时可以多讲哪一层
很多项目介绍停在“用了哪些技术”。学完这套内容后，小伙伴还可以讲清楚自己怎样使用 AI 完成一项长期工程任务。
面试时可以结合自己的项目这样回答：
我没有让 AI 靠一条很长的提示词一次改完整个项目。我先根据源码、测试和运行数据建立问题基线，再把总体设计拆成有依赖的阶段。每个新会话只执行一个阶段，修改前先补失败测试，完成后还要跑回归和真实数据验收。阶段状态、执行记录和下一步都放在仓库里，所以经历多次上下文压缩以后仍然可以继续。如果后续证据推翻前面的结论，工作流会重开最早责任阶段，修好后再恢复原来的进度。
这段经历还能继续展开：
- 为什么按业务责任拆阶段，没有按文件数量拆；
- 怎样区分源码事实、运行数据和暂时猜测；
- 怎样处理遗留代码中固化旧错误的测试；
- 为什么自动测试之后还要检查真实数据；
- 哪些操作由 AI 完成，哪些操作要交给用户；
- 后续验收推翻旧结论时，怎样避免重复返工；
- 怎样控制兼容代码，并在阶段结束前删除旧入口。
有了真实计划、执行记录和代码证据，这些内容都能从项目里找到对应材料，面试时也更容易讲出自己的判断过程。
这套内容适合哪些小伙伴
- 已经会使用 AI 写代码，想进一步处理跨模块大任务；
- 手里有项目，但很难讲清楚自己怎样借助 AI 完成设计和重构；
- 经常遇到会话变长、上下文压缩后任务接不上的问题；
- 想让 AI 参与遗留系统改造，同时守住测试、权限和代码质量；
- 准备面试，想把“会用 AI”讲成一段有设计、有执行、有证据的项目经历。
即使还没有完整学习过 Nexus Agent Pro，也可以先从课程文章理解 Harness 的设计思路。文中遇到项目专有词时会先用中文解释，再保留对应的源码名称，方便读完后回到代码中查找。
建议怎样学习
我建议按四轮来读：
- 先读课程文章：理解项目问题怎样变成总体设计，整体计划又怎样拆成阶段。
- 再对照阶段计划：查看 AI 在一个阶段开工前会拿到哪些事实、边界、测试和退出条件。
- 接着读执行记录：观察计划没有预料到的失败、人工接力和阶段重开。
- 最后回到源码和测试：确认这些设计最终落在什么位置，自动验证又保护了哪些合同。
这套阅读方式会把“方法”和“真实施工”连起来。学员既能学习 Nexus Agent Pro 的系统设计，也能学习我怎样让 AI 长时间参与一个复杂项目。
Nexus Agent Pro 项目的申请
Nexus Agent Pro 是我按照真实企业项目的开发思路持续打磨的私有项目。除了项目源码、详细文档和视频，学习内容中还会提供这套 AI Harness 课程、阶段计划和真实执行记录。
还没有加入星球的小伙伴，可以先查看星球提供的项目、技术内容和学习服务：👉 了解星球和加入方式
已经加入星球的小伙伴，可以按照下面的说明申请和学习 Nexus Agent Pro：👉 点击这里学习 Nexus Agent Pro