主题

很多人第一次用 AI 写代码都会经历同一条曲线：一开始惊艳，几周后挫败。模型本身没变笨，问题出在你让它干的事越来越复杂了——从”补一个函数”变成”改一个模块”再变成”在一个持续演进的工程里做一整个需求”。

当任务跨越多个文件、多个阶段、多次迭代，仅靠提示词和个人记忆已经接不住。这时候需要的不是更强的模型，而是一套让 AI 稳定、可约束、可校验地干活的工程系统——这就是 Harness Engineering。

本文面向刚开始做 AI Coding、已经感到”单纯聊天不够用”的开发者，讲清三件事：

  1. Harness 到底在解决什么问题
  2. 它由哪些零件组成、为什么是这几件
  3. 从零开始应该按什么顺序搭，不要一次搭齐
不讨论具体 IDE 或某家 Agent 产品的操作，这里讲的是方法论。

核心内容

一、Harness 在解决什么问题

把大语言模型想成一个聪明但健忘、擅长临场发挥的新同事。他一次对话内表现很好，但有三件事他做不好：
  • 记不住项目长期约定——上周你定的命名规则，这周可能又违反了
  • 没有稳定的完成标准——他说”做完了”不等于真的做完
  • 面对复杂任务会自己给自己打分——既当运动员又当裁判
单靠聊天，每次遇到问题就补一句”注意不要 XXX”，你会发现规则越堆越多，AI 却越来越不听。原因是：自然语言约束本质上是”软约束”，模型可以忽略、绕过、或做解释性执行。

Harness Engineering 的核心论点是：

不要试图把 AI 变聪明，而要给它搭一个不允许偷懒的工作环境。把能判定的规则变成脚本，把复杂任务拆成固定角色，把流程沉淀成可维护的工程资产。
一句话总结——Harness 不让 AI 更聪明，而是让 AI 更可靠。

二、六个核心零件

Harness 由六个零件拼成。它们不是互相替代，而是逐层叠加，每一层解决上一层解决不了的问题。
零件 回答什么问题 工程角色 约束类型
SPEC 要做什么 设计规格文档 起点
Rule 什么事绝对不能乱来 底线 / 红线 软约束
Skill 固定动作具体怎么做 标准操作手册 软约束
Sub Agent 复杂任务由谁分工 专业角色 结构约束
Workflow 角色按什么顺序接力 流程规则 结构约束
Scripts 到底做没做好 统一门禁 硬约束
MCP 怎么接外部系统 外接能力 延伸
下面逐个说清楚它们为什么必要。

SPEC：所有约束的起点

SPEC 是项目的设计规格文档，回答”AI 到底要做什么、边界在哪、怎么算验收”。

新手最容易跳过的一步，却是最该认真花时间的一步。如果连”要做什么”都是模糊的，后续所有 Rule、Skill、Scripts 都是无源之水——你甚至无法判断 AI 做得对不对。

SPEC 的三条写作建议：

  • 禁用”建议 / 可选 / 推荐 / 尽量”这类模糊词，改成明确的”必须 / 禁止 / 验收条件”
  • 可以把初稿丢给 AI 反问，让它帮你挖出被你默认但没写出来的假设
  • SPEC 不是一次写完的圣经，随着项目演进同步更新

Rule：写死底线，但别指望它解决所有问题

Rule 是项目的红线清单：命名规范、禁用 API、日志格式、文件组织等。

Rule 的边界很重要：它只能做”原则性约束”，不能做”流程执行”。因为 Rule 本质还是自然语言，模型在复杂上下文里一定会出现：

  • 遗忘——上下文太长，规则被挤出去
  • 绕过——找字面解释的缝隙
  • 解释性执行——”这条规则的精神是……所以我这样做也算合规”
所以 Rule 应该只写最关键、最反复出错的那几条底线。贪多反而让每一条都变得无效。能下沉成脚本的规则，就不要停留在 Rule。

Skill：固定动作不靠临场发挥

Skill 是把高频固定动作写成标准操作手册。典型场景：如何跑编译、如何跑测试、如何生成 changelog、如何提交代码。

没有 Skill 的时候，AI 每次做这些事都会自己想一套步骤，偶尔出错。把这些动作抽成 Skill 之后，好处很明确：

  • Rule 变轻——不用再在 Rule 里反复提醒
  • 执行更稳——同一件事每次同一种做法
  • 维护成本低——改一处，所有调用都生效
判断一件事该不该做成 Skill 的标准：这件事有没有”正确的唯一做法”？ 有，就写成 Skill；没有，交给 AI 临场发挥反而合理。

Sub Agent：拆掉单 Agent 的角色冲突

当任务复杂度上来，单个 Agent 会出现典型症状：
  • 需求刚说了一半就开始写代码，写完又说发现需求不对
  • 自己写的代码自己审，当然都觉得没问题
  • 上下文越滚越长，早期约定被挤掉
根本原因：一个 Agent 同时扮演多个角色，必然产生利益冲突。解决方案是拆成多个专门 Agent，每个只负责一段，角色之间有明确的输入输出边界。

多 Agent 有三种主流路线，结论是只有第三种能真正长期用：

路线 特点 问题 建议
强化单 Agent 改动小 角色冲突无解 早期过渡，不是终局
自由协商（群聊式） 灵活 路径不稳、责任不清、难审计 不推荐用于工程
结构化调度（固定角色 + 固定流程） 清晰、可审计、可维护 前期设计成本高 推荐
真正贵的不是 token，真正贵的是失控。
典型的结构化角色集合可以拆成七个：项目经理、需求分析、方案设计、可行性闸门、开发、代码审查、测试验证。每个角色解决前一个解决不了的问题。

这里有一个反直觉的关键点：项目经理（PM）应该是”最守流程边界的 PM”，而不是”最懂研发的 PM”。PM 一旦开始给专业意见，多 Agent 就塌回”中央大脑说了算”的老路。让 PM 只做路由、交接和打回，专业判断交给对应的专业 Agent。

一个容易被忽略的工程化细节：不同角色配不同档位的模型。PM 做路由用轻量模型够了，需求分析和代码审查这类专业判断重的才上强模型。像真实团队配置资源，而不是所有岗位都塞最贵的人。

Workflow：让协作有规矩

有了多个角色，还要规定他们怎么接力：
  • 前进——什么条件下进入下一阶段
  • 暂停——什么情况停下等输入
  • 打回——下游觉得上游有问题，怎么回退（注意：下游不能擅自改上游产物，只能提阻塞，由 PM 打回）
  • 重跑——什么时候整段重来
Workflow 不是一张漂亮的流程图就完事。它需要三份可维护的工程资产：
  1. 流程定义文件——阶段、负责人、前进路径、回退条件
  2. 角色契约——每个 Agent 的输入输出边界（读什么、写什么、什么时候阻塞）
  3. 流程校验脚本——自动校验定义文件和契约是否自洽
这样流程本身才从”靠人记住”变成”可拆分、可维护、可校验”。

Scripts：Harness 的质变点

到这里为止，所有约束都还是自然语言的。Scripts 的出现是 Harness 从”软约束系统”升级成”有反馈闭环的工程系统”的分水岭。

核心思想：完成的定义，不能由 AI 自己说了算，必须由脚本判定。

总验证脚本通常覆盖三类检查：

  • 静态规范：代码风格、禁用 API、命名、日志格式等可静态扫描的规则
  • 交付门槛：编译通过、测试全过、测试数量不异常减少
  • 工程一致性：配置文件多处同步、新文件纳入构建等跨文件一致性
完成的定义从”我觉得我做完了”，变成”脚本判定你过了，才算做完”。
有了 Scripts，整个闭环才真正闭合：做事 → 校验结果 → 发现问题 → 回退修复 → 再校验。

还有一个细节——基线对比。AI 经常用”这是历史遗留问题”糊弄，对治方法是：改动前后各跑一遍总验证脚本，按差量认账。你改之前没出这个错，改之后出了，就是你的锅，解释权不在 AI 手里。

MCP：把闭环向外延伸

MCP（Model Context Protocol）负责把 Harness 对接到仓库之外——构建系统、制品仓库、CI/CD、发布平台、监控系统等。

初学者一开始不用考虑 MCP。等你的开发闭环在仓库内已经跑顺了，想把”完成”的定义从”代码 merge”推到”可交付、可发布、可回滚”时，再引入 MCP。

三、从零搭建：推荐顺序

最重要的原则：不要第一天就把最终形态全画出来。

Harness 应该是”撞墙 → 补洞 → 升级 → 再撞墙”演进出来的，不是一次设计到位的。按下面的顺序补，每一步都对应一个你真实遇到的痛点，才不会搭一堆没人用的东西。

  1. 磨一份能指导开发的 SPEC——目标、边界、验收标准说清楚
  2. 补最关键的几条 Rule——只盯最反复出错、最容易偷懒的底线，不贪多
  3. 把高频固定动作下沉成 Skill——编译 / 测试 / 提交 / 部署这类最适合
  4. 单 Agent 失稳时再拆多 Agent——没感到角色冲突就不要拆
  5. 多 Agent 变复杂时再补流程定义文件和角色契约
  6. 进入持续迭代后再补项目级索引——开发导航图（代码落点、影响面）+ 任务看板（当前任务、阶段、文档入口）
  7. 想把闭环推到交付发布时再接 MCP
中间关于第 6 点的一个重要原则——谁动代码谁改地图，谁管需求谁改看板。不要指望有人专门维护一份”永远没人更新的漂亮文档”。让更新动作落在每次改动的自然路径上，才可持续。

四、一个常见误区：Memory vs 仓库

很多初学者的第一反应是：让 AI 把经验都记在 Memory 里不就好了？

在个人项目里这样做没问题，省事。但在团队项目里，Memory 应该靠边站。原因：

  • 不同人的 Memory 互相矛盾
  • 交接、审计、CI 都看不见 Memory
  • 个人偏好会变成隐性规范，破坏标准化
一个有用的类比：事实像档案、例子像故事、规矩像手册。手册应该进仓库（以 Rule、Scripts、SPEC 的形式），而不是只躺在某个人的对话记忆里。

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

五、Harness 的四块拼图

当你搭到后期，可以用这四块拼图自检是否完整：
拼图 管什么 对应零件
约束与流程 AI 按什么节奏、什么纪律推进 Rule / Skill / Sub Agent / Workflow
反馈 做完以后系统能不能对结果有说法 Scripts
知识索引 项目从哪读起、改动影响到哪 开发导航图 / 任务看板
进化 规范往哪沉淀、人退到哪一层 仓库资产主场 + 人做系统设计者
缺任何一块的典型症状：
  • 只有流程没反馈——完成幻觉，看起来很忙但不知道做对没
  • 只有反馈没流程——闸机有了，上游仍一团即兴
  • 没有索引——同一类功能反复被重写，同一类坑反复踩
  • 没有进化——前三块冻在某一版，脚本和规则跟不上结构变化

六、人与 AI 的关系，会重新划分

最后一个观念转换。很多宣传把 AI 说成”你的助手”，这在简单任务里没错，但在复杂工程里太轻也太不准确。

一个更准的类比是：AI 是一支执行力极强、但必须被制度化管理的团队。你要给它边界、分工、门禁、反馈闭环。

随之而来的变化是——Harness 越强，人越重要，但人的职责上移了：

  • 从执行者 → 系统设计者 + 最后责任人
  • 从”自己写代码” → “设计让 AI 把代码写对的系统”
  • 从”盯每一行” → “定义边界、设计门禁、审视漏洞、在流程卡住时做最终判断”
不是人退场，而是人往上走一层。

要点总结

  • Harness 不让 AI 更聪明，而是让 AI 更可靠——它不是提示词技巧，是一整套让 AI 稳定产出正确结果的工程系统
  • 六个核心零件逐层叠加：SPEC 定起点、Rule 定底线、Skill 标准化动作、Sub Agent 拆角色、Workflow 串接力、Scripts 做硬门禁、MCP 向外延伸
  • 自然语言约束是软约束，脚本判定才是硬约束——能判定的规则一律下沉成脚本；”完成”的定义必须由脚本说了算
  • 多 Agent 首选结构化调度，避免自由协商；PM 只做路由，不做专业判断；不同角色配不同档位的模型
  • 不要一次搭齐，按 SPEC → Rule → Skill → 多 Agent → Workflow → 项目级索引 → MCP 的顺序，每一步对应一个真实痛点再补
  • 团队项目以仓库资产 + 门禁为主干，Memory 不适合当团队主场
  • Harness 越强，人越重要——职责从执行者上移到系统设计者和最后责任人