万字干货！Harness Engineering如何工程化落地？

Harness Engineering 的概念已经火了有一阵了，全网很多文章基本都是在讲理念，讲为什么今天做 AI 开发，不能只靠一段提示词，也不能把模型当一个“更聪明的代码补全”。但与此同时，一个问题也在持续地发酵：

理念我理解了，可是真正落到工程里，我第一步到底该做什么？

这个问题特别重要。因为 Harness 这个词听上去很大，很像一个抽象的方法论，但它如果不能落到工程、目录、文档、脚本、工作流里，那它最后就只是一句漂亮的话。事实上，不同项目落地出来的 Harness，表面上可能完全不一样。有的项目是 CI 很强，有的项目是规范很强，有的项目是多 Agent 很强，有的项目甚至只是把几个脚本和模板整理得非常扎实。但如果你往下挖，会发现它们解决的其实都是同一个问题：

如何让 AI 在你的项目里，持续、稳定、规范、顺畅地做出你真正想要的结果。

这一篇我就不再谈泛泛而论的“AI 很重要”“工程化很重要”。我只做一件事：拿 JK Launcher 这个真实工程做例子，把我们这一路是怎么一步一步把 Harness 搭出来的，原原本本讲清楚。哪些地方有效，哪些地方踩坑，哪些东西一开始以为够用，后来发现完全不够，都会写出来。你看完以后，不一定要完全照抄，但至少会知道：如果你也想在自己的项目里从 0 开始搭 Harness Engineering，第一步该做什么，后面又该按什么顺序逐步补齐。

我将整个搭建流程细细拆解，每一个步骤都拆散揉碎了，尽可能的将所有内容都明明白白的写出来，本篇我保证一定值得大家反复细读，当然，以下所有论点都是我的一家之言，不一定对，抛出来也是希望大家一起讨论。

为方便大家阅读，在此提前预警一下，本篇文章字数非常多，一共分为12章，要想细读建议留足至少半小时的时间，建议大家时间不够的话可以先收藏。

很多人一上来就开始写 Rule、搞 Agent、接 MCP，最后越做越乱，根本原因不是执行力不够，而是概念没分清楚。下面这些词，在我们这个工程里都会反复出现。如果这几个概念混在一起，后面就很难搭得稳。

先把这几个概念压成一张速览表，会更容易建立整体印象：

   1.1 Rule 是什么

Rule 可以理解成你给 AI 写的一套“工程规矩”。

它不是需求文档，也不是设计方案，更不是脚本。它更像是你在带一个新人开发时，先告诉他的那些基础原则： 什么能做，什么不能做； 什么做完必须验证； 什么约定绝对不能绕过去。

比如在我们工程里，有一类专门约束“改完代码以后必须完成编译、测试和事后验证”的 Rule，本质上就是在告诉 AI：

所以 Rule 的核心作用，不是帮助 AI “变聪明”，而是帮助 AI 少犯一些本来不该反复犯的低级错误。

Rule 更像一个团队的“研发制度”。制度不是拿来创造价值的，制度是拿来减少混乱的。

但这里有个很重要的前提：Rule 只是软约束，不是硬门禁。

什么意思？就是 AI 理论上应该遵守它，但它并不一定真的每次都遵守。尤其当 Rule 越来越多、需求越来越复杂的时候，模型会出现三种典型情况：

1. 它忘了某条 Rule

2. 它觉得某条 Rule 和这次需求“无关”

3. 它知道这条 Rule，但偷懒没做，还给自己找理由

所以 Rule 非常重要，但 Rule 不能解决所有问题。

   1.2 MCP 是什么

MCP（Model Context Protocol）本质上是一种标准方式：把「仓库之外的能力」接进 AI 的工作链路里——既能拉取信息，也能在明确边界内触发外部系统的动作。

你可以把它理解成一层可编排的接口：AI 不再只依赖当前对话和本地代码，还能对接 Wiki、知识库、表格、各类平台 API；在 Unity 工程这类场景里，还可以对接 Unity Editor / 工程宿主里的工具能力（例如编译、场景与资产、日志与状态、受控命令等），把「写出来的代码」和「编辑器里正在发生的事」对齐起来。

这也就解释了，为什么当你想把 Harness 从「开发闭环」推到「工程交付闭环」时，MCP 往往会变得关键：交付链路里大量是 CI、签名、制品、发布、回写状态 等系统能力，它们都不是「只在仓库里多写几行脚本」就能替代的。

先看能力边界。没有 MCP 时，AI 通常仍被锁在：

• 本地代码仓库

• 本地脚本

• 当前对话上下文

它能分析、能改代码、能跑本地验证，但很难安全、结构化、可审计地接入更外层的工程系统。

反过来，如果你要把闭环做完整，迟早会碰到下面这类动作（只列常见的几种）：

• 调用 CI 平台发起构建

• 读取构建日志和构建结果

• 调用签名服务给安装包或可执行文件签名

• 上传制品到制品库或发布平台

• 调用发布系统做灰度、提审、发布

• 回写发布状态、版本号、交付记录

它们的共性是：需要让 AI 在可控边界里调用系统能力，而不是把凭据和即兴命令散落在对话里。MCP 正是这类能力的连接层：把外部系统以 Tool / 资源的形式暴露给 AI，便于被 Rule、Workflow、Scripts 一起约束。

所以在我们的整体拼图里，MCP 不是 Harness 的主体，而是 Harness 的外接能力接口——接什么、接到多细、何时允许接，本身也要被制度与门禁管住。

如果 Rule 像制度，Skill 像操作手册，Scripts 像闸机，那么 MCP 更像把 AI 接进更大工程系统的标准插座。在当前阶段它也许还是辅助；但当你希望 AI 不只改代码，还要稳定参与构建、签名、制品、发布、回写状态时，这一层往往会越来越「决定性」。

   1.3 Skill 是什么

Skill 是我特别推荐所有团队早点引入的东西。

它本质上是在告诉 AI：有些事情你不要临场发挥，不要每次重新理解，也不要自己“猜一个大概的流程”，而是严格按照这套固定步骤执行。

比如编译这件事。你说“你去编译一下”，AI 可能自己拼一条命令。表面看没问题，但实际工程里，编译往往不是一句 dotnet build  那么简单，可能涉及：

这些东西如果每次都让 AI 自由发挥，迟早出问题。

所以我们把编译做成了 Skill，把测试做成了 Skill，把事后验证也做成了 Skill。这样每次 AI 走到这一环，它不是“想办法完成”，而是“按剧本完成”。

它很像给 AI 写的一份标准操作手册。Rule 告诉 AI “这件事必须做”，Skill 告诉 AI “这件事具体应该怎么做”。

   1.4 Sub Agent 是什么

Sub Agent 就是多个“分工明确的 AI 角色”。

很多人一开始用 AI，默认是一个 Agent 干到底：分析需求、设计方案、写代码、审代码、写测试、做总结全都它来。短任务时这没问题，但只要任务一复杂，问题马上就会出现：

这和真实的软件研发其实完全一样。一个人既做产品、又做架构、又做开发、又做 QA，最后质量一定很难收口。

所以我们后来引入了多个 Sub Agent，把不同阶段拆开。每个 Agent 只负责自己那一段，把产出写进文档，然后交给下一个 Agent。

放到真实研发里，Sub Agent 就像项目组里的一组人：

这个思路其实非常朴素，不是什么新发明，但它对 AI 特别有效。

   1.5 Workflow 是什么

Workflow 不是“写了几个 Agent”那么简单。 如果只写了几个 Agent，而没有 Workflow，那其实只是“有几个人在干活”，还谈不上“有一套稳定可复用的协作方式”。

我觉得 Workflow 最形象的理解方式，不是流程图，而是接力赛规则。

接力赛最重要的，不是有四个跑得快的人，而是下面这些事情必须先说清楚：

放到工程里其实一模一样。 你有需求分析、方案设计、开发、测试这些角色，只代表你“有人”。 但只有当你把下面这些东西明确下来，Workflow 才真正成立：

如果没有 Workflow，工程现场通常会变成下面这种状态：

所以 Workflow 的核心不是“有一张图”，而是让每一次前进、暂停、打回、重跑都有明确依据。

在我们工程里，这套 Workflow 最后被拆成了三层：

• 一层写给人看，告诉大家这条研发链路整体怎么走

• 一层写给系统看，把阶段和迁移边固定下来
• 一层写给具体角色看，明确每个角色接棒时该读什么、交棒时该写什么

这三层合起来，才构成一个真正能长期维护的 Workflow。 否则你以为你搭的是流程，实际上搭出来的往往只是几段漂亮的提示词。

和「接力」配套的还有一条上下文纪律：每一棒只给当前该看的那一份材料。不是要瞒信息，而是避免一上来把规则、地图、任务历史全堆给 AI——上下文越长，重点反而越散。所以我们会有意让 Rule 慢慢长、让 dev-map 与任务看板等「项目级视野」晚一点再上；这和 Workflow 拆阶段、Sub Agent 各看一截文档，其实是同一条思路。

   1.6 Scripts 是什么

Scripts 是整个 Harness 里最“硬”的东西。

如果说 Rule 只是告诉 AI 应该怎么做，Skill 只是给 AI 标准步骤，那 Scripts 就是在说： 你说你做完了没用，得跑过我这关才算。

这也是为什么我越来越觉得，真正成熟的 Harness，最后一定会越来越依赖脚本，而不是越来越依赖提示词。

在我们工程里，就有一个典型的“总门禁脚本”。它把很多原本散落在 Rule 里的东西，真正落到了可执行的检查上。比如：

当这些东西被做成脚本以后，AI 就很难再拿“我觉得没问题”来糊弄过去了。

   1.7 先把前面的几个概念串起来

前面这一章其实已经把后面会反复出现的几个核心零件都讲完了。 如果你是第一次接触这套东西，先不要急着往下看，最好先在脑子里把它们快速过一遍：

这几个东西不是互相替代的，而是逐层叠加的。

你也可以这样理解：

也就是说，到这里为止，你看到的还只是 Harness 的一堆“零件”。 而接下来要讲的，才是最关键的一步：

这些零件为什么拼在一起以后，会变成一整套 Harness Engineering。

   1.8 什么是 Harness Engineering，以及它在我们工程里的全貌

如果前面那些概念你都看完了，这里其实就可以把它们串起来了。

我自己现在对 Harness Engineering 的理解很简单：

它不是某一个工具，也不是某一条提示词技巧，而是一整套让 AI 在工程里稳定产出正确结果的工程系统。

注意这里有三个关键词：

所以在我看来，Harness Engineering 真正解决的不是“怎么让 AI 更聪明”，而是下面这件事：

怎么把 AI 从一个会临场发挥的模型，变成一个在工程里可约束、可协作、可校验、可持续维护的执行系统。

如果把我们当前工程里的 Harness 全貌摊开来看，它大致已经长成了下面这样：

如果非要打个比方，我会说：

Harness Engineering 就像是在给 AI 搭一整套“工程作战系统”。 规格设计文档（SPEC）是作战目标，Rule 是纪律，Skill 是标准动作，Sub Agent 是兵种分工，Workflow 是指挥链，Scripts 是验收和反馈闭环，开发导航地图（dev-map） 和任务看板则提供地图和战场态势（这两个概念将会在第九章进行详细的阐述）。

这些东西单独看都不稀奇，真正有价值的是：它们组合起来以后，AI 才第一次像是在一个真实工程里工作，而不是只是在聊天窗口里表现得很聪明。

在真正讲“第一步怎么搭 Harness”之前，我觉得有必要先把 JK Launcher 这个项目本身说清楚。因为如果读者连这个项目是什么、解决什么问题、复杂度大概在哪个层级都不知道，后面就很容易把我们的方法误解成一套“只有大工程才需要”的复杂仪式。

   2.1 工程画像：JK Launcher 在做什么

下面三张截屏来自真实运行中的 JK Launcher V3（小白模式），便于把「工具体长什么样、日常在管什么」落到可视层面。

项目工程：主工作台 — 快速入门与状态条、SVN/路径与平台配置、更新与打开 Unity 等主操作、底部日志区。

工程修复工具箱：按修复项展示风险等级，支持预检与执行修复，右侧为检测日志 —— 对应冲突扫描、工作副本、误改恢复等工程维护场景。（特别补充一点，这个功能是我使用完整版Harness一次就直接完成的，完成度相当高，大家也可以通过这个功能了解到本篇文章中构建的Harness究竟最终的效果是怎么样的）

设置：可开启小白模式（隐藏高级功能），以及智能建议、悬停详细说明、操作结果摘要等显示相关选项。

JK Launcher 本质上是一个面向 Unity 项目研发流程的桌面启动器工具。它不是一个单一功能的小工具，而是一整套围绕日常研发高频动作搭起来的工作台，核心在于把那些原本零散、容易出错、依赖经验的操作，统一收进一个稳定的桌面端入口里。它要处理的事情并不简单，比如：

• 工程更新
• 打开和关闭 Unity
• SVN 环境检测与权限检查
• 冲突检测与冲突修复
• 定时更新和批量更新
• 更新失败后的诊断与恢复
• 多语言界面
• 日志、遥测、状态反馈

如果你看它最近几个月的演进，会发现它已经不是“一个带按钮的启动器”这么简单了，而是一个不断往研发真实场景贴近的工程工具：有修复工具箱，有环境自检，有消息中心，有定时任务，有 Library 预热，有更细的错误分类和更完整的引导体验。这种项目特别适合作为 Harness 的样本，因为它同时具备几个特征：

• 功能持续迭代

• 既有 UI，又有服务和状态逻辑

• 既要工程正确性，也要用户体验

• 既要能改代码，也要能长期维护

技术上，它的主体是一套典型的 Windows 桌面应用技术栈：以 WPF 为界面基础，以 .NET Framework 为主要运行时，围绕本地工程管理、SVN 协作、配置、状态、更新、日志、多语言等能力不断扩展。也正因为它既有前端交互、又有工程逻辑、又有环境和流程问题，所以它特别适合拿来验证一套 Harness 到底能不能撑住复杂项目。

   2.2 人搭 Harness，AI 写代码

还有一点，我觉得必须提前告诉读者： 这个工具在持续演进的过程中，真正的代码实现工作是完全由 AI 去完成的，人没有亲手写过一行代码。

人做的事情是什么？不是下场补代码，也不是在 AI 后面当“高级打字员”，而是一步一步把 Harness Engineering 搭起来：

• 先把需求和设计说透

• 再补上规则

• 再把固定流程做成 Skill

• 再拆出多 Agent

• 再补上脚本门禁和事后验证

• 再补项目地图、任务看板和流程定义文件

也就是说，这个项目不是先有一个成熟团队在写代码，再把 AI 当辅助工具接进来；恰恰相反，我们是在搭建 Harness 的过程中，逐渐让 AI 从能做小任务，走到能做复杂任务，再走到能持续维护整个项目。

   2.3 从设计规格文档（SPEC）开始

所以这一章真正想回答的问题，不是“我们为什么要写设计规格文档”，而是：

当你面对的是一个真实、持续迭代、并且完全交给 AI 去实现和维护的工程时，你应该先从哪一步开始搭这个系统。

很多人一听到 Harness，就想先写 Rule、先拆 Agent、先上脚本。但如果你一开始连“这个工程到底想怎么开发、最终想交付什么样的东西”都没有说清楚，那后面所有约束都会变成无源之水。

所以我们真正的第一步，不是写 Rule，而是先把一个比较完整的设计规格文档和 AI 反复磨透。

在 JK Launcher 这个工程里，我们最早就是先磨出了一份比较完整的版本设计规格文档，它承担的就是这个作用。

这类文档的意义，不是为了“文档看起来专业”，而是为了在项目一开始就把下面这些问题谈清楚：

• 这个版本到底要解决什么问题

• 哪些问题是核心目标，哪些只是顺手优化

• 改动会影响哪些模块

• 哪些行为必须保持兼容

• 最终什么样才算做完

我自己在这一步通常会和 AI 来回聊很多轮，甚至聊到有点烦。因为这一轮你偷懒，后面会用十倍时间还回来。

这些来回不只是在改文档措辞，也是我们和 AI 共同加深对需求本身的理解的过程。有时一开始连自己都不确定想要什么，不妨把 AI 拉进需求讨论里，让它帮着追问、掰开选项——真正的需求常常就是在这样的来回里被挖出来的，而不是第一版就写死在纸上。

最终的SPEC长什么样？它必须清晰的写明你的所有需求，指明必要的边界条件（后面的需求分析agent会帮你补充 剩下的边界条件），必须没有任何不确定的词语，例如：建议，可以，推荐，可选等字样。

但很快我就发现，只靠这份文档，AI 还是会出问题。

问题不在于它看不懂文档，而在于：

1. 它不会百分之百按文档执行

2. 它做完以后，你很难知道它现在到底做到哪了

3. 很多错误它会反复犯

比如它会：

• 按自己理解跳过一些看起来“没那么重要”的细节

• 做完之后告诉你“都完成了”，但你仔细一看其实漏了
• 某个以前犯过的错，下一次又犯一遍

到这里我才真正意识到： 仅有规格设计文档（SPEC），只能解决“知道做什么”的问题，解决不了“如何稳定地做到位”的问题。

于是我们才进入下一步：给 AI 上 Rule。

当时我的直觉很简单：既然 AI 经常忘事，那我就把容易忘、容易错的事情写成 Rule。

于是，像“改完必须完成编译、测试和事后验证”这一类规则就出来了。它本质上是在告诉 AI：

这一步非常有用。因为 AI 最爱偷懒的地方，恰恰就是那些“看起来像收尾，其实是底线”的动作。比如很多时候它会觉得：

• “我改的是文档，不用编译”

• “我只是小改，不用跑测试”

• “这次失败看起来是历史问题，不算我引入的”

Rule 一上去，这些最粗糙的问题会立刻少很多。

但如果你真的在复杂项目里跑过一段时间，你会很快发现 Rule 的天花板。

Rule 多了以后，会出现两个非常典型的问题。

   3.1 AI 会忽略 Rule

不是完全不看，而是会在复杂任务下“局部遗忘”。尤其当你的需求很长、上下文很重、同时加载了很多别的内容以后，一些 Rule 在实际执行时会被稀释掉。

   3.2 AI 会绕过 Rule

这个比忽略更麻烦。因为它不是不知道规则，而是会开始给你找理由。

比如：

• 这次不通过不是我引入的，是之前遗留的

• 这个 Rule 说的是常规需求，这次是特殊情况

• 我已经做了等价验证，不需要完全照规则来

这其实是我做 Harness 过程中非常关键的一个认知转折：

Rule 不是没用，而是 Rule 只能做“原则约束”，不能做“流程执行”。

当我意识到这件事以后，我就开始做下一步：把固定流程从 Rule 里拆出去，做成 Skill。

如果你认真观察，你会发现工程里有一类事情非常适合做成 Skill：

编译、单元测试、事后验证，就是这一类事情。

所以我们把这几个流程单独做成了 Skill，比如编译 Skill、测试 Skill、事后验证 Skill。

这样一来，Rule 里就不需要再写一堆细碎的命令和注意事项了。Rule 只要保留一句话：

“你必须做这件事。”

而 Skill 则负责把“这件事具体怎么做”写清楚。

这样做的好处特别直接：

1. Rule 变轻了

以前 Rule 既讲原则又讲流程，越写越长。现在 Rule 可以只保留真正的红线，复杂的执行步骤都交给 Skill。

2. AI 的执行稳定性变高了

以前 AI 需要临场理解“编译应该怎么编、测试应该怎么测”。现在它不是理解，而是调用一套现成的方法。

3. 维护成本更低了

比如你后来修改编译流程，只需要改编译 Skill 本身，不需要去全项目搜索每条 Rule 里是不是都写了旧命令。

这一步做完以后，我们整套系统的健壮性明显提升了一截。 但新的问题很快又出现了：

单个 Agent 在复杂需求下，还是不够稳定。

前面在规格设计文档（SPEC）、Rule、Skill 这几层补齐以后，我们已经明显感觉到系统比最早稳了很多。 至少 AI 不再是“拿到一句话就直接开写”的状态，它开始知道目标、知道约束、知道固定流程。

但当需求继续变复杂以后，一个新的问题开始越来越明显：

单个 Agent 很难在长时间、复杂链路的开发里，同时把需求理解、方案设计、风险判断、编码实现、代码自审、测试验证都做好。

这件事不是因为模型不够聪明，而是因为我们在强迫它一次性扮演太多角色。

一个 Agent 如果既负责理解需求，又负责设计方案，还负责判断可行性，再负责写代码，最后还要自己审自己、测自己，它一定会出现下面这些问题：

走到这里时，我其实面对的是一次很典型的技术选型问题。 不是“要不要上多 Agent”这么简单，而是：到底应该选哪种多 Agent 形态。

   5.1 第一种做法：继续强化单 Agent

这是最容易想到的路线。 既然一个 Agent 不够稳，那就继续给它补：

这条路我们其实已经走过一段，而且不能说完全没用。 SPEC、Rule、Skill 这几层，恰恰就是这样一步一步补出来的。

但问题在于，这条路越往后走，越像是在把越来越多的责任塞进一个“大而全”的角色里。 它可以让单个 Agent 变得更谨慎，却很难解决“角色冲突”本身。

说得更直接一点：

• 需求分析和代码审查，本来就不是同一种工作

• 方案设计和测试验证，本来就不是同一种思考方式

• 让一个 Agent 同时扮演所有角色，本质上还是在赌它一次性全都做好

这在简单任务上能凑合，在复杂工程里就会越来越吃力。

   5.2 第二种做法：去中心化协作

网上很常见的另一条路，是让多个 Agent 平起平坐，通过对话和协商动态达成共识。 这类模式看起来很高级，也很像“一个 AI 团队在开会”。AutoGen 的 GroupChat 一类思路，就是这种方向的典型代表。

它的优点确实很诱人：

• 足够灵活

• 现场应变能力强

• 不需要一开始就把流程定义得很死

但它的缺点，在真实工程里会越来越大：

如果你的目标是做一个很聪明的演示，或者探索一个开放式问题，这种模式很有魅力。 但如果你的目标是长期维护一个真实项目，它就会逐渐暴露出一个致命问题：

好看，但难维护。

   5.3 第三种做法：结构化调度

还有一条路，就是把多 Agent 做成一条有明确角色分工、有明确流转规则的结构化流程。

这种模式的典型特征是：

它的优点也非常明确：

它的缺点也不是没有：

• 前期设计成本更高

• 灵活性会比自由协商差一些

• 产物更多，token 消耗更大

但我们最后还是坚定地选了它。 因为到了真实工程阶段，你会越来越清楚一件事：

真正贵的不是 token，真正贵的是失控。

我们需要的，不只是“AI 把代码写出来”，我们还需要：

这些东西不是形式主义，而是为了让后续任何一个人、任何一个 AI，在几天后、几周后、几个月后，都还能看懂：

所以从项目可维护性、流程规范性、角色可替换性来看，结构化调度几乎是我们能找到的最适合这类工程的方案。

三条路线压缩成一张表会更清楚：

   5.4 结构化调度里，我们也做过一次内部 PK

即便确定了走结构化调度，这里面其实也还有两种常见做法。

做法 A：固定角色、固定流程

也就是先把有哪些 Agent、每个 Agent 干什么、什么阶段找谁，尽量定义清楚。 项目经理只负责按流程调度。

优点是：

做法 B：只固定 PM 和开发经理，具体 Agent 动态生成

这种模式会让上层保留项目经理和开发经理，具体研发时由开发经理动态“招聘”或生成不同的 Agent 去做事。

它的好处是：

• 灵活性更强

• 面对非常多样化的问题时，理论上更容易按需适配

但问题也很明显：

我们最终还是选了第一种。 原因并不复杂：我们的实际开发工作流，虽然需求内容会变，但大的阶段结构其实相对固定。

比如：

• 一个标准需求开发，通常就是需求分析、方案设计、评估、开发、代码审查、测试、交付

• 一个 Bug 修复，也可以落到相对固定的裁剪版流程

既然工作流本身并不是完全开放式的，那就没必要为了“理论上的灵活性”牺牲掉稳定性和可维护性。

往前看，这几次 PK 其实都在做同一类取舍：灵活性和稳定性之间，我们最后都更偏向后者。因为对一个要长期维护的工程来说，可控、可追踪、可复用，比“理论上更灵活”重要得多。

   5.5 这一章最重要的结论

所以第五章真正想讲清楚的是：

我们不是因为“多 Agent 很酷”才去做多 Agent。 我们是因为：

• 单 Agent 到复杂需求阶段开始失稳

• 自由协商式多 Agent 不适合长期维护

• 动态招聘式结构化多 Agent 对当前项目来说过于漂移

在一轮轮技术选型和对比之后，最后才落到了今天这条路上：

用结构化调度，把研发流程拆成一组固定角色和固定阶段，让 AI 不再是一个人在乱拳打死老师傅，而是进入一个被制度化管理的研发体系。

结构化调度确定下来以后，下一个问题就是： 到底要拆成几个 Agent，怎么拆。

这一步如果做得不好，多 Agent 不会让系统更稳，只会让系统更乱。 所以我们当时并不是一上来就拍板“就七个”。相反，我们是随着问题暴露，一层一层把角色拆出来的。

   6.1 第一步，先拆需求分析、方案设计、开发实现

最早我们碰到的核心问题，是“模糊需求直接流进代码”。 用户说一句想法，AI 很快就能写出点东西，看起来很有执行力，但往往会有三个问题：

• 需求边界不清

• 技术方案是边做边想的

• 做完以后很难说清这是按什么思路做的

所以最先拆出来的，其实是三层最基础的角色：

1. 需求分析 负责把模糊想法变成结构化需求。

2. 方案设计 负责把需求翻译成真正能落地的技术方案。

3. 开发实现 负责按照前面的约束去写代码，而不是边写边定义需求。

为什么这三层必须先拆？

因为如果这三层不拆开，后面所有事情都会混成一团。 需求和方案混在一起，方案和实现混在一起，最后出了问题你根本不知道该补哪一层。

所以可以说，需求分析、方案设计、开发实现 是整套多 Agent 体系最早的骨架。

   6.2 第二步，再补上闸门总控

但只拆这三层，很快又不够用了。

原因是： 需求写出来了，方案也写出来了，并不代表它真的已经具备进入开发的条件。

我们在实际跑的时候，很快就遇到很多这种情况：

这时候我就意识到，流程里必须有一个专门的角色，站在“开发之前的最后一道门”上。 于是我们补出了第四个关键角色：

闸门总控（可行性分析）

它的必要性就在于，它不负责重新写需求，也不负责重新写方案，而是专门判断：

如果没有闸门，很多问题都会在开发阶段才爆炸。 而开发阶段是最贵的阶段之一，因为这时候已经开始写代码了，返工成本会迅速变大。

所以闸门总控本质上是在帮我们做一件事： 把很多本该更早暴露的问题，提前暴露。

需求分析、方案设计以及闸门总控实际上是我将之前反复和AI讨论需求文档中，必经的步骤都提炼出来，让AI形成固定工作流。

   6.3 第三步，再把代码审查和测试独立成最后收口

接着我们又碰到一个特别现实的问题：

开发说自己做完了，不等于真的做对了。

如果只有需求、方案、闸门、开发这几层，流程还是缺最后的收口。 因为“实现完成”这个动作，本身不能证明：

于是我们又把下游收口拆成了两层：

1. 代码审查

2. 测试验证

这两个角色为什么不能合在一起？

因为它们解决的根本不是同一个问题。

代码审查的必要性

代码审查不是看格式好不好看这么简单。 它负责的是从实现层回头看：

它更像是“技术落地质量”的最后一道收口。

测试验证的必要性

测试验证则是从行为层再看一遍：

它更像是“实际结果质量”的最后一道收口。

如果没有代码审查，开发很容易“代码能跑就算完成”。 如果没有测试验证，系统又很容易停留在“看起来写对了”。

所以代码审查和测试，必须是两道独立的关。 这也是为什么我们后来越来越觉得：下游角色不是附属品，而是整套流程的真正收口。

   6.4 第四步，再补一个只做路由的 PM

到这里，角色已经不少了。 新的问题又来了：

谁来决定现在该找谁？

如果让每个 Agent 自己判断下一个该找谁，那流程很快又会滑回自由协商。 于是我们最后把项目经理这个角色放到了中央。

但这里有一个特别重要的点：

我们需要的不是一个“最懂研发的 PM”，而是一个“最守流程边界的 PM”。

它的职责只有这些：

它不负责：

这一点非常关键。 因为 PM 一旦越界，就会把整个多 Agent 系统重新拉回到“一个中央大脑说了算”的旧路上去。

   6.5 为什么最后会稳定成这七个 Agent

所以最后，这套系统自然收敛成了我们现在的七个 Agent：

这里最重要的不是“正好七个”，而是这七个角色各自解决了一个前一个角色解决不了的问题。

这就是它们各自的必要性。 不是为了把流程搞复杂，而是为了把一个原本混在一起的大任务，拆回到可以被管理、被交接、被替换、被回退的几个模块。

   6.6 角色拆完以后，我们还做了一件很实际的事：给不同 Agent 配不同档位的模型

这一点其实很工程化。

很多人一提多 Agent，会下意识觉得既然都拆角色了，那是不是所有 Agent 都应该上同样强的模型。 但我们实际跑下来发现，这样做既没必要，也很浪费。

原因很简单：不同 Agent 的工作性质，决定了它们对模型能力的要求并不一样。

比如 PM 这个角色，本质上只负责流程流转、阶段判断、交接记录和任务推进。 它最重要的是守流程、读文档、做路由，而不是输出特别复杂的专业结论。 所以对 PM 来说，用一个相对简单、但更节约 Token、性价比更高的模型，往往就已经足够了。

而像需求分析、方案设计、代码审查、测试这类角色，承担的专业判断明显更重，对理解能力、推理深度、细节覆盖度的要求也会更高。 这时候就更适合给它们配更强一点的模型，把算力花在真正需要的地方。

这件事带来的好处非常现实：

不是每个岗位都配同一把最贵的锤子，而是让不同岗位用最合适、最有性价比的工具。

多 Agent 真正落地以后，很多设计都不再只是“AI 玩法”，而会越来越像真实团队的资源配置问题。

顺便提一句，这套“给不同 Agent 分配不同模型”的实践，我目前主要是在 Cursor 上完成的。 在我上个月体验 CodeBuddy 时，它还不支持为各 Sub Agent 自定义所用模型；但很快 CodeBuddy 就补上了这一能力——在这里要为 CodeBuddy 的迭代速度点个赞。 这类能力一旦具备，多 Agent 会从“能跑”进一步走向“跑得更合理、更省成本”。

当你真的进入多角色、多阶段、长期迭代的工程开发以后，模型分层配置本身就会变成 Harness Engineering 里非常重要的一部分。

做到这里，七个 Agent 的骨架其实已经搭起来了。 而且老实说，跑起来以后效果确实和我们预期差不多。

复杂需求终于不再是一个 Agent 一路硬闯，而是开始形成一条标准的文档链。 像我们后来一些比较完整的需求，已经能够沉淀出标准的阶段文档，整条链也更清晰了。

但这并不意味着系统就成熟了。 恰恰相反，真正把这套东西跑起来以后，新的问题才开始一轮一轮冒出来。

这一章我想讲的，就是这些真实的曲折过程。 因为 Harness Engineering 从来不是“一次设计到位”，而是跑一段、撞墙、补洞、再跑一段、再升级。

   7.1 第一轮问题：下游开始自己修改上游文档

多个 Agent 真正协作起来以后，第一个很快暴露出来的问题是：

下游觉得上游做得不够好，就顺手自己改了。

最典型的，就是方案设计看完需求分析写的文档以后，觉得某些地方不严谨，于是没有选择打回，而是自己按照理解把需求补掉了。

这件事听起来很“聪明”，甚至一开始你会觉得它像是在帮你提高效率。 但跑久了你会发现，这是非常危险的：

• 需求到底是谁负责，开始变得模糊

• 方案到底是基于原需求，还是基于方案设计私自修过的需求，也开始模糊

• 真出了问题以后，你根本不知道该追责给哪一层

所以我们后来明确加了一条非常重的规则：

下游不能直接改上游文档。 当下游认为上游产出不合格时，只能提出阻塞项，由 PM 把流程正式打回给上游。

这一条一落地，整个系统第一次真正有了“谁负责哪份产物”的边界感。

   7.2 第二轮问题：PM 太容易越界

流程继续往下跑以后，很快又冒出第二个问题：

PM 很容易从流程管理者，滑成一个到处给意见的人。

这其实很好理解。 PM 站在流程中心，天然知道所有阶段发生了什么。一旦需求不清、方案有争议、开发遇到卡点，它就特别容易顺手说：

• “这个需求我觉得可以这么补”

• “这个方案不如改成那样”

• “这个问题别退了，开发顺手修一下就行”

但我们后来越跑越清楚地认识到： PM 给出的这类意见，往往并不专业，甚至特别容易把整个流程带偏。

所以我们后来对 PM 的职责做了严格收缩：

这一轮调整以后，PM 的定位才真正清晰下来：

它不是流程中央的“总专家”，而是流程中央的“总路由器”。

   7.3 第三轮问题：各个 Agent 的专业性都还不够，这里以代码审查和测试这两个 Agent 举例

接着我们又踩到了第三个坑。

跑了一段时间以后我们逐渐发现，问题并不只是某一个 Agent 做得不够好，而是整套多 Agent 在早期都还存在专业性不够深的问题。

需求分析会有需求边界挖得不够透的时候，方案设计会有方案覆盖不够全的时候，闸门总控也会有风险识别不够狠的时候。 这里我选择以代码审查和测试这两个 Agent 来举例，是因为它们在整条链里处在非常典型的收口位置，更容易把前面累积的问题看得更清楚。

因为前面角色如果专业性稍微差一点，问题不一定立刻炸；但一旦到了收口阶段，很多前面遗漏的问题会一下子集中暴露。

所以这里我还是拿代码审查和测试举例，不是因为只有它们不专业，而是因为它们最能代表“整套系统的专业性不足，最后会在哪里爆出来”。

虽然前面几层已经拆开了，但到了下游，我们一开始的代码审查和测试，确实也都还比较“常规”。

最初的代码审查，更像是普通的代码审查：

• 看有没有明显逻辑 bug

• 看有没有违反 Rule

• 看实现有没有一些基础问题

最初的测试，也更像常规验证：

• 看功能大面上能不能跑

• 看是否有明显异常

这些当然有用，但远远不够。 因为到了这个阶段，代码审查和测试实际上已经不是一般角色，而是整条链的最终收口。

它们如果只看“本层有没有问题”，就会漏掉很多真正重要的东西：

所以后来我们专门加强了这两个角色的专业性要求。

代码审查不再只是给代码意见，而是必须对照需求和方案，确认“做的是不是对的、是不是完整的”。 测试也不再只是走一遍流程，而是要站在真正收口的位置，去看功能、边界、回归、稳定性和基础性能诉求。

我展示一下我现在的需求分析agent，大家也可以作为参考：

这一步很重要。 因为从这里开始，多 Agent 才不只是“流程拆得很细”，而是真的开始具备质量闭环能力。

   7.4 第四轮问题：Rule 约束开始不够用了

流程问题补得差不多以后，我们一度以为系统已经比较稳了。 但很快又发现一个新的老毛病：

很多已经写进 Rule 的基础约束，Agent 还是会时不时不遵守。

比如它会说：

• “这个不通过不是我引入的，是之前遗留的问题”

• “这条 Rule 这次场景特殊，可以先不管”

• “我已经做了主要工作，这一步可以先跳过”

走到这里我才真正意识到一件事：

Rule 再多，本质上还是自然语言约束。

自然语言约束可以管住很多基础行为，但当需求越来越复杂时，它一定会被忽略、被绕过，或者被“解释性执行”。

所以我们后来又往前走了一步： 把很多能判定的约束，尽量落地成脚本。

也就是：

• 编译要过，不是口头说“应该没问题”

• 测试要过，不是口头说“理论上没影响”

• 规则扫描要过，不是口头说“这次特殊”

只有脚本通过，才算真正开发完成。

这也是为什么后来总验证脚本变得越来越重要。 因为它不是又多了一份工具，而是把“是否完成”这件事，从 Agent 的主观汇报，变成了一个可检查的客观结果。这个话题将在第八章展开细聊。

   7.5 第五轮问题：Agent 会偷懒，于是又补了基线对比

脚本上来以后，本来以为事情就结束了。 但 AI 很快又展示了新的“聪明”。

它会告诉你：

• “这次不通过不是我造成的”

• “这个错误本来就存在”

• “这个 Warning 是历史遗留”

这时候如果你没有额外机制，真的很容易被它糊过去。 于是我们又顺手补了一层：

开发前先跑一次，开发后再跑一次，做基线对比。

做法上一般是：改代码前先跑一遍总验证（或同一套测试与静态检查），把输出或报告留作基线；改完再跑一遍，对两次结果做对比（看新增失败、告警或违规项）。

如果开发后新增了错误、失败、Warning 增量，就必须修。 这样一来，“是不是你这次引入的”就不再靠嘴解释，而是靠前后报告对比。

这一点很像给 AI 又加了一层紧箍咒。 但它也恰恰说明了一件事：

Harness 不是只靠相信 AI，而是靠不断补机制，让它没有太多偷懒空间。

   7.6 第六轮问题：流程本身也开始难维护了

当需求一轮一轮跑下来，系统越来越成熟时，我们又遇到了一个更后期的问题：

流程本身开始越来越难维护。

最开始，很多流程规则都写在 PM 的长文里。 一开始这样是够用的，但到后面，阶段多了、回退边多了、角色边界多了，你会越来越痛苦：

这时候我才意识到，前面那几轮补洞主要都在解决“让流程能跑起来”，而这一轮要解决的，是让流程本身也变成可维护资产。

所以我们后来又做了一次专门的升级，这次升级不是再多加几个 Agent，也不是再补几条 Rule，而是把原来散落在长文和默契里的流程要素，正式抽出来。

我们大概补了三层东西。

第一层：把流程结构单独抽成流程定义文件

以前流程主要写在 PM 的长篇说明里。 这种写法的好处是人读起来顺，但坏处也很明显：当阶段、迁移边、回退边越来越多时，流程结构就会被埋在大段描述里。

于是我们后来把下面这些东西单独抽出来：

这样一来，如果以后再回答“这条流程到底怎么走”，就不需要先去翻一大篇散文，而是先看这份流程定义文件。

它的价值在于，流程结构第一次从“写在说明里的知识”，变成了“可以单独维护、单独校验的资产”。

第二层：把每个 Agent 的输入输出抽成角色契约

光有流程定义文件还不够。 因为就算你知道现在该轮到哪个 Agent，如果没有进一步说清楚“它到底该读什么、写什么、什么情况下算阻塞”，角色边界还是会慢慢漂。

所以我们后来又给每个 Agent 都补了一份角色契约。 它其实就是每个角色的接口说明。

里面重点固定几件事：

这样做以后，Agent 就不再只是“一篇很长的人设提示词”，而更像一个有输入输出边界的稳定模块。

这对长期维护特别重要。 因为后面即使你换模型、换提示词，甚至换维护人，只要契约还在，角色边界就不至于轻易漂掉。

第三层：再补一个流程校验脚本

流程定义文件和角色契约都抽出来以后，还差最后一步：

怎么保证这些流程资产本身是齐的、是一致的。

于是我们后来又补了一个流程校验脚本，专门去检查最基础的几类问题，比如：

• 流程定义文件是不是存在
• 每个 Agent 对应的契约文件是不是齐全
• 流程里提到的角色，能不能在契约里找到

它现在还不是一个特别复杂的“流程编译器”，但已经足够把很多最容易出现的低级问题拦在前面。

比如以前很容易出现这样的情况：

这些问题单看都不大，但一旦累积起来，整个多 Agent 流程就会越来越难维护。

所以这一轮升级的本质，其实非常明确：

不是让流程更复杂，而是让流程本身也从“靠人记住”升级成“可以被拆分、被维护、被校验”的工程资产。

   7.7 回头看，这一整段曲折过程说明了什么

第五章到第七章连起来看，其实是在回答同一件事：

• 第五章在解决“为什么选这条路线”
• 第六章在解决“这条路线上的角色怎么拆”
• 第七章在解决“拆完以后，系统怎么继续补稳”

也就是说，Harness Engineering 在真实项目里的成长路径，根本不是：

这也是我特别想让读者看到的一点。 如果你要在自己的项目里搭 Harness，不要以为第一天就得把最终形态全画出来。 更现实、更正确的做法，往往是：

这才是它真正落地的样子。

   7.8 如果你想在自己的项目里从 0 开始，我建议按这个最小顺序搭

前面讲的是完整演化过程，这里把它收成一个最小起步路径。

如果你今天手上也有一个项目，想把 AI 慢慢带进工程里，我建议不要一上来就把所有东西一次搭齐，而是按下面这个顺序来：

先让 AI 知道该做什么，再让它知道必须怎么做，再让它在复杂任务里学会分工，最后再让整套流程本身变成可维护的工程资产。

实际跑起来时的界面

上一节收的是「从零开始按什么顺序搭」。这里贴一张 Cursor 长截屏：同一条线拿去解一个具体需求时，PM Agent（Orchestrator，总调度） 按 workflow 依次调用各子 Agent，从分析、方案、开发、审查一直到测试和收尾。左侧是这一路的时间线——谁被点到、何时跑完、审查打回再跑也留在上面；右侧是同一段里我跟 PM 的对话，和左边各步大体对得上。

前面在第七章里，其实已经讲到一件事： 当 Rule 开始管不住、Agent 开始会解释性执行、甚至会拿“历史遗留问题”给自己找理由时，很多约束最后一定会继续下沉到脚本。

所以第八章我不再重复那段演化过程，而是只把这件事本身讲透：

为什么总验证脚本会逐渐变成整套 Harness 里最关键的基础设施之一。

在我们工程里，这个角色就是一份总验证脚本。 它不再是“建议你验证一下”，而是在客观上决定：这次开发到底算不算完成。

   8.1 总验证脚本到底做了什么

它不是一个单一检查，而是一套“研发后验证总入口”。

它更像一个统一裁判：

它覆盖了很多本来散落在 Rule 里的内容。最典型的几类包括：

A 类：静态规范问题

B 类：基础交付门槛

C 类：工程一致性

这些检查项单看每一条都不复杂，但它们合在一起，才真正构成了一个“这次开发到底合不合格”的门槛。

更重要的是，事后验证本身就是 Harness 极其关键的一环。

因为前面的 SPEC、Rule、Skill、多 Agent，本质上都还在解决“怎样让 AI 去做事”的问题；但如果没有事后验证，你其实始终不知道它这次做出来的结果，到底是正确的、错误的，还是只是看起来像完成了。

这一点是我们后来越做越深以后，感受特别强的一件事。 很多团队把 AI 开发做成了“能自动往前推进任务”，但它们缺少一个扎实的反馈回路。结果就是：

但系统本身并没有真正感知： 这次产出到底是对还是错。

而事后验证的意义，恰恰就在这里。它不是为了让流程看起来完整，而是为了让这套 Harness 第一次具备“结果感知能力”。 也正是从这一步开始，我们的系统才不再只是“能推动事情继续发生”，而是开始有能力判断：这次事情到底做得对不对。

   8.2 为什么这一步对 Harness 特别关键

因为从这一刻开始，AI 的完成定义不再是：

“我觉得我做完了。”

而变成：

“脚本判定你通过了，你才算做完。”

这一步是一个非常大的质变。

   8.3 为什么它最后会变成统一入口

总验证脚本真正厉害的地方，不只是“多了一个检查工具”，而是它把很多原本分散的事情收成了一个统一入口。

以前这些动作可能分散在：

但当它们被统一收进一份总验证脚本以后，开发完成的定义就第一次真正被收紧了：

• 不是你主观说做完了就算
• 不是你局部通过了某一项就算
• 而是要经过同一个统一入口的检查

这对 Harness 很重要。 因为只有当“完成”也被统一定义以后，整套系统才开始从“很多零散约束”变成“一个真正有门禁的工程流程”。

如果让我从整个 Harness 里挑一个最容易被低估、但实际价值极高的模块，我会选事后验证。

因为它补上的不是一个步骤，而是一整个反馈闭环。

在没有这套闭环之前，我们其实经常停留在一种“任务完成幻觉”里： AI 把代码改了，文档写了，流程往下推进了，于是我们会下意识觉得这次开发完成了。 但完成不等于正确，推进不等于收口，做了事情不等于把事情做好了。

而当这类事后验证真正成为流程硬门槛以后，整套 Harness 的性质就变了：

• 它不再只是一个会驱动 AI 往前跑的系统
• 它开始具备对结果做判断的能力
• 它开始形成“做事 -> 校验结果 -> 发现问题 -> 回退修复 -> 再次验证”的完整回路

这才是我理解里真正开始成熟的 Harness。

做到这里，我们的 Harness 已经能独立完成相当复杂的需求了。 但如果任务进入持续迭代阶段，还会遇到一个非常现实的问题：

PM 和各个 Agent 缺乏整个项目的全局视野。

这时候如果还只是单看当前需求，很容易发生两种惨案：

1. 新方案把旧方案冲掉

2. AI 重复造轮子，根本不知道项目里已经有现成实现

这一章要补的，可以粗粗理解成：给 AI 配一份跟着仓库走的项目级知识库。 但这里说的知识库，不是把整仓说明书塞进上下文那种「百科全书」，而是一套够准的索引——先告诉它该从哪几条线、哪几份文档进门，再让它自己去翻代码、对细节。

维护上，我们尽量让流程里的 AI 自己改、自己闭环（谁动代码谁改地图，谁管需求谁改看板），减少「写一份永远没人更新的漂亮文档」那种尴尬。

具体落到我们工程里，是 dev-map 和 任务看板 这两块；它们和第一章 Workflow 末尾那条纪律也对得上：项目还小的时候，没必要一上来就把整仓库地图和全部任务历史塞给 AI。 时机会变：持续迭代起来以后，这一层才变得划算。

• 前面几章更多是在补「流程上下文」

• 到这一章，补的是「项目上下文」——写进仓库、大家能看见、能接着改的那一层

   9.1 「项目级索引」常见有哪些搭法

同一件事，不同团队会选不同材料；下面只是几种常见路子，互不排斥，也经常混着用。 本章后面写的 dev-map 和任务看板，只是我们仓库里实际在跑的组合，不是唯一答案。

• 人工整理的导航文档：按功能、服务、配置把「该看哪、别碰哪、惯例怎么写」写清楚，改结构时跟着改文档（我们 dev-map 属于这一类）。

• 任务 / 需求总览：一张表或一页索引，记当前在做什么、做到哪一阶段、文档落在哪个目录、上一轮结论是什么（任务看板属于这一类）。

• 工具自动吐出来的「地图」：依赖图、模块清单、接口列表、测试报告之类，由脚本或 CI 定期生成，给人和 AI 当第二参照。

• 编辑器 / 语言服务能提供的跳转：符号定义、引用查找——负责的是「这一行代码在哪」，和「这一坨业务该从哪进门」往往是两回事，可以互补。

• 检索进上下文：对文档或代码块做全文搜、关键词搜，或接上向量检索，按问题临时捞片段；适合兜底，通常代替不了一张维护得好的索引表。

• 仓库里的轻量约定：顶层 README、各模块 README、CODEOWNERS、贡献指南——篇幅短，但能把「从哪读起」说死。

• 单独的知识库或 Wiki：和代码分仓管理时常见；要记得和仓库里的真相对齐，否则容易各说各话。

看清这些选项以后，第九章想强调的其实就两句：别把「项目级上下文」理解成堆字数；它首先该是一套索引。 至于索引具体长什么样，完全可以按团队习惯换材料——我们接下来只展开自己用的那两样。

它们在我们这边的分工，可以先压成一张表：

   9.2 dev-map：开发侧那本导航

主工程下面有一套开发导航地图，规则写得很直白：改代码之前，先查 dev-map。 动刀之前先把功能落点、影响范围从地图里对一遍。

很多人第一次听到 dev-map，会以为它只是「文件列表」。 它的用处其实更大一些：更像这座工程的开发导航图，说的是——

核心就一条：先搞清这里已经长成了什么样，再下手。 AI 容易「重新发明一遍轮子」；地图的作用，是让它早点看见这座城市不是空地。

这套东西由 开发 Agent 在干活的过程中维护，而不是 PM 单维护。 谁改地貌，谁最有资格改地图——这和前面说的「AI 闭环更新知识库」是同一套逻辑。

仓库很大的时候

文件多到一定程度，一张表想写全所有文件，表本身会先变成负担，也很难长期和仓库对齐。更常见的折中是：前面留几页总览——从哪进门、几大块各管什么；扎进某一块开发，再翻那一块自己的说明。具体某个类、某个路径，交给搜索、跳转或后面的检索去办；dev-map 这边，主要还是结构和习惯用法。大地图可以拆成好几本薄一点的册子，每本封面写清管哪一片，往往比硬撑一本厚目录要现实。

   9.3 任务看板：需求侧那张总览

另一个关键是项目任务看板，由 PM 维护。 它不是普通待办，而是项目级的任务总览，一般会记：

新的需求分析 Agent 进来时，不必从零猜和历史有没有关系——先看一眼看板，往往能回答：是不是旧需求的延续、有没有类似任务做过、文档在哪、上一轮设计怎么定的。 「新需求把旧设计冲掉」的概率会小很多。

dev-map 偏代码与模块结构从哪进门；任务看板偏需求和任务历史从哪进门。两个入口都写在仓库里，AI 在流程里各改各的，这一层才算转得起来。

所以这一章收束时想留的，不是「两个工具的名字」，而是一层能力：

AI 已经会把当前任务做完以后，还能在仓库里找到「整个项目从哪读起」的那几把钥匙。

有了 dev-map 和任务看板以后，我们忽然发现，前文几乎没单独提一件很多人挂在嘴上的东西：Memory。

第九章补的是「项目级上下文」——写进仓库的索引：开发导航（dev-map）和任务总览（任务看板），大家能看见、流程里也会接着改。业界和产品里常说的 Memory，多半是另一类东西：藏在会话或产品里的、帮模型「记着点啥」。二者听起来都在解决「别丢上下文」，解决的却不是同一个问题。把这件事说清楚，这一章就值得单独占一节。

在标准化的、多人协作的、项目级 Harness Engineering 里，我的观点依旧很明确：Memory 可以不在主干上——不是说它「邪恶」，而是说团队该对齐的真相与规矩，不该指望靠「记忆层」当权威来源。

   10.1 先把 Memory 拆成两类：都在存什么

大家说的 Memory，大致两种：

一类是偏「这一轮」的。

也就是当前对话里攒下的上下文：刚讨论过的结论、临时贴进去的说明、甚至有人把「错题、反例」先堆在聊天里。作用很简单：这一场别断片。

一类是偏「跨很多轮」的。

隔几天再来，产品或系统仍帮你记着的东西：个人偏好（例如「回答用中文」）、操作习惯（例如「用 PowerShell 跑命令」）、「别这么写」的口头规矩、或者几条成功/失败案例的片段。作用也很直接：少重复交代。

但是我认为：凡是最后会变成「团队都要遵守」或「交付要对齐」的东西，都不该长期停在这一层。

   10.2 档案、故事、手册——该进仓库的，别只靠聊天记忆

我喜欢用三句话压住分工：

事实像档案，例子像故事，规矩像手册——手册应进仓库，别只靠聊天记忆。

对照到这套 Harness 里，可以这样理解：

所谓「错题集」，若真重要，就该晋升级：进 Rule 或进 Scripts，而不是长期当对话里的私有笔记。

   10.3 个人偏好与 Memory：可以用，但要和「团队标准」划界

纯个人偏好——回答语言、常用 shell、你喜欢的排版说明——用 Memory 减少摩擦，无可厚非。

但在团队里要克制，原因很现实：

• 同一件事，不同人的 Memory 可能悄悄矛盾；
• 交接、审计、CI 看不见 Memory；
• 「个人风格」容易变成隐性规范，损害标准化。

团队级 Harness 的目标，是不依赖某个具体的人也能把事做对。所以：偏好要么小到不影响契约，要么应写进团队共识（Rule、贡献指南、统一脚本入口），而不是留在私人记忆里。

   10.4 个人工具与团队项目：Memory 何时作用大、何时尽量少用

个人项目、或 OpenClaw 等偏「一人一把工具」的形态（OpenClaw 可理解为个人向 AI 工具栈的一种代表，主战场在「顺手」而非团队仓库对齐），目标常常是「更顺手、更懂我」——Memory 性价比很高，省重复话、省摩擦。

多人、标准、要长期维护的工程，目标是可交接、可审计、可对齐——主干必须是仓库里的资产 + 门禁。Memory 顶多是润滑剂，不能当规范源。

这不是否定 Memory 这种能力，而是分清主场：团队 Harness 的主场在 SPEC / Rule / Skill / Scripts / dev-map / 任务看板 / 流程与契约。

   10.5 实践上可以多问自己的几句话

• 这是「个人习惯」还是「团队要对齐」？后者 → 进仓库。

• 错题有没有可执行判定？有 → Scripts；只能先文字约束 → Rule，并争取以后脚本化。

• 成功/失败样例能不能变成测试或样例数据？能 → 别只存在聊天记录里。

• solo 时可以用 Memory 提速；合并进团队流程前，把该沉淀的沉淀掉。

写到这里，其实已经能看到一个很清晰的演进过程了。

一开始，我们只是希望 AI 能帮我们完成一个小任务。 后来，我们希望它能稳定地完成一个完整需求。 再后来，我们希望它不是一次性地帮我们写代码，而是能参与项目的持续维护。

随着目标越来越大，Harness 的作用也越来越明显。

   11.1 在这个过程中，人到底在做什么

很多人会误以为，Harness 搭起来以后，人是不是就退场了。

恰恰相反。 Harness 越强，人越重要。

只是人的职责发生了变化。

以前，人更多是在直接写代码、直接改需求、直接盯每一个细节。 现在，人更像是在做下面几件事：

也就是说，人从“执行者”逐步上移成了“系统设计者”和“最后责任人”。

   11.2 今后人和 AI 应该是什么关系

我现在越来越不认同一种说法： “AI 是你的助手。”

这个说法太轻了，也太不准确。

在复杂工程里，AI 不是助手，AI 更像是一支执行力极强但必须被制度化管理的团队。 你不能指望它天生懂规矩，也不能指望它自己长出流程意识。 你要给它边界、给它分工、给它门禁、给它反馈闭环。

所以未来人和 AI 更合理的关系，我觉得是：

• 人负责设计系统

• AI 负责在系统里高强度执行

• 人对最终结果负责

   11.3 后续怎样做更专业的 Harness Engineering

如果继续往前走，我认为还有几个方向特别值得做。

第一，更多规则继续脚本化

只要是能判定的，就尽量不要停留在 Rule 层，而应该下沉成脚本。 因为只要还是自然语言，就永远存在解释空间。

而且这件事背后还有一个更长远的方向：让反馈闭环越来越完整。 我们现在的事后验证，已经能在很多静态规则、编译、测试层面给出明确判断；但这还不是终点。后面我们持续在探索的，是把这一层再往前推进：

如果这些能力继续补齐，Harness 的反馈回路就会从“你写完以后我来扫一遍”，升级成“你写完以后，系统能尽可能接近真实使用场景地验证这次结果到底对不对”。 那时候它就不再只是一个开发约束系统，而更像一个真正有自我校验能力的工程执行系统。

但如果要再往前走一步，真正把这个反馈闭环从“开发完成”延伸到“可交付、可发布、可回滚”，光靠本地脚本其实还不够，这时候 MCP 的价值就会真正体现出来。

因为完整的工程闭环通常至少还包含下面这些环节：

这一整串动作，如果全部让 AI 直接自由发挥，其实风险很高；但如果这些外部系统都能通过 MCP 提供受控、结构化、可审计的能力接口，那么 AI 就能在明确边界里完成：

这时候，你的 Harness 就不再只是一个“开发过程管控系统”，而会开始长成一个真正意义上的工程执行闭环系统。

第二，把流程进一步产品化

现在我们的 Workflow 已经有了流程定义文件和契约，后面完全可以继续往更强的状态机、更强的自动校验上发展。 这时候再考虑 LangGraph 这类流程 / 状态图编排框架，就会更顺手，因为你的流程已经先被整理清楚了。

而如果未来 MCP 这一层也补上，流程产品化就不只是“文档阶段怎么走”，还会进一步升级成“每个阶段对哪些外部系统有权操作、操作成功以后如何自动推进下一步”。 这其实就是很多团队最终想做但一开始做不到的事情：让 AI 不只是懂研发流程，还能在受控前提下参与真实工程交付。

第三，做项目类型模板

不同项目的 Harness 形态会不同。 WPF 工程、Unity 工程、后端服务、工具脚本仓库，它们需要的门禁和工作流一定不一样。 但你完全可以沉淀出每类项目的“最小可用 Harness 模板”。

第四，把“知识”沉淀进项目，而不是沉淀进人

这也是我一直特别强调的一点。 真正专业的 Harness，不应该越来越像“我和我的 AI 的默契”，而应该越来越像“任何一个人拿到这个工程，都能顺着这套系统做对事情”。

这才是工程化。

第十一章聊的是人和 AI 往后的关系。 在收束全文之前，我想把前面几十页里已经长出来的东西，压成一张总图： 约束与流程、反馈、知识库、进化——四块拼图，彼此勾着走。

这一章只做对照复盘：你在第三～七章里看到的是「怎么让 AI 在规矩里干活」；第八章是「干完以后谁来判卷」；第九章是「这座工程从哪读起」。第十、十一章则把问题收束到「人、项目与 AI 各自站在哪一层」。

   12.1 四块拼图与章节大致落点

这不是唯一一种拆法，但可以用来对照我们这篇长文的叙事。

   12.2 第一块：约束与流程（第三～七章）

从 Rule、Skill 讲起，到多 Agent、流程定义文件和角色契约，再到第七章里一轮轮「撞墙、补洞」——这一条线，本质上都在回答：AI 在工程里按什么节奏、什么纪律推进。

没有这一层，模型再强也只是在对话里即兴发挥；有了这一层，复杂需求才能拆成可重复的接力，每一棒才有明确的输入输出。第七章补的那些漏洞（文档边界、回退、维护方式），其实也是流程本身的硬化：不让协作在「口头默契」里塌掉。

   12.3 第二块：反馈（第八章）

约束告诉 AI「应该怎样做」；反馈回答的是「这次做出来的，算不算过关」。第八章把总验证脚本推到台前，就是在补第一章里已经埋过的伏笔：Rule 会软、会忘、会解释性执行，最后总要有一个机器能拍板的入口。

反馈一旦接上，Harness 才第一次具备结果感知：不是流程走完了就完事，而是同一套门槛对每次交付说话。后面第十一章里提到的「规则继续脚本化」「反馈闭环往外推」，都是这一块在往厚里长。

   12.4 第三块：知识库（第九章）

第九章把「项目级上下文」说透了：不是给 AI 一本读不完的百科全书，而是给一套够准的索引——开发从 dev-map 进门，需求与任务史从任务看板进门；谁在流程里动刀，谁在流程里顺手改地图。这样 AI 才少在已经长出来的城市里重复铺路。

这一块和「约束与流程」的关系很实在：流程规定什么时候该读地图；地图降低在错误的地方动手的概率；反馈则能在地图过期或漏改时，用失败结果把维护压力打回来。

   12.5 第四块：进化（第十～十一章）

第十章讨论 Memory，其实是在划主场：团队要对齐的东西，最终应落在仓库里能看见、能审计、能交接的资产上，而不是长期停在会话记忆。第十一章讨论人和 AI，其实是在划责任上移：人越来越像系统设计者和最后责任人，AI 在制度里高强度执行——Harness 本身会随着项目变难、团队变大而继续改结构、加门禁、加长链条。

所以「进化」不是玄学，而是：前三块搭起来以后，由人与 AI 在各自边界里协作推动的持续改版——人定方向与闸门，AI 在规矩里高密度落地；哪条规矩该进脚本、哪张地图该拆薄、哪段流程该接到 MCP，落成可审计的仓库变更，并会回过头拉升流程、反馈与知识库。

   12.6 四块怎么咬在一起

四块是相辅相成的，缺一块，典型症状也很直观：

• 只有流程没有反馈：容易变成「看起来很忙、但不知道做对没有」的完成幻觉。

• 只有反馈没有流程：闸机有了，但上游仍是一团即兴，失败日志很难收敛成可维护的改法。

• 没有知识库（索引）：同一类功能反复被重写、同一类坑反复踩，流程再细也扛不住噪音。

• 没有进化：前三块容易冻在某一版：脚本与规则没人按新标准收紧，地图与真实结构脱节，改法长期堆在会话里落不回仓库。缺的是人划边界与验收、AI 在规矩内动手这一棒接力——没有它，谈不上对约束、反馈与知识库的持续反哺。

这里把进化再说透一点：它不是泛泛的「项目要写文档」，而是人与 AI 共同驱动 Harness 自身改版的那股力——人决定改成什么样算过关、哪些可以自动化、何时收束进仓库；AI在已定流程与契约里高密度落地（改 Rule、补验证脚本、拆 dev-map、顺任务看板等）。这些变更回过头去拉升前三块：约束与流程会更贴现状，反馈门槛会更准或覆盖面更大，知识库会与最新结构对齐。缺了这一层，常见结局是只靠少数人能记着为什么这样定，或每轮靠聊天临时指挥，前三块得不到结构性的往上推。

把它们放在一起看，Harness 的核心图景就是：

用流程和约束把动作摆进轨道，用反馈让轨道尽头有人判卷，用知识库让 AI 别在城里瞎撞；进化则是人与 AI 合力，把实践与门禁里长出来的结论持续灌回流程和约束、反馈与知识库，让规矩、闸机与地图跟得上结构变化——整套东西才真正跟项目活下去。

   12.7 收束到这篇长文本身

JK Launcher 这一路，并不是按「理论四章」一次性设计出来的，而是哪痛补哪、补着补着，四块才逐渐齐全。你若在自己的工程里动手，也大可以从四块里最缺的那一角下刀——不必和我同一顺序，但心里有这样一张总图，后面加 Skill、加脚本时，不容易加偏、也不容易加重复。

让 AI 在工程里受控地工作

第十二章已经把全貌收过一遍；这里只留几句送给要动手的人的话。

Harness Engineering 不是为了让 AI 看起来更聪明，而是为了让 AI 在复杂工程里更可控、更可靠、更可维护。真正跑起来以后，多一分能判对错的反馈，就多一分踏实。

这件事不会一次搭齐。你愿意从最痛、最反复的那一个问题开始，把规矩、技能、脚本和流程一点点沉进仓库，四块拼图就会自己长全。

不要贪大，不要一步到位，先从你最反复、最痛的那个问题开始。

   文中关键模块速览