把 AI 协作做成一套 Agent Harness

最近我越来越强烈地感觉到一件事：

AI 的上限，不只取决于模型有多聪明，也取决于你把它放进什么样的工作系统里。

以前我用 AI，更多是把它当成一个很强的个人助手。给它一个需求，它理解、规划、执行、自查，最后告诉我完成了。

这个模式当然有用，但它也有一个很明显的问题：同一个 Agent 从头做到尾，最后还要自己判断自己做得好不好。

这就像让一个人写方案、做执行、当评委、再给自己打分。它不是不会发现问题，而是天然容易放过自己。

尤其在复杂任务里，问题会更明显：需求一开始没展开，执行中范围漂移，自评时又过于乐观。最后结果看起来完整，但真正一用，核心流程可能是坏的。

所以我开始思考：我们是不是不应该只追求一个更强的 Agent，而是应该给 Agent 设计一套更好的协作结构？

这就是我整理 Agent Harness 这套方法的原因。不是召唤更多 Agent，而是建立制衡关系

很多人一听多 Agent，第一反应是：那是不是开三个 Agent，让它们一起想方案？

但我觉得这不是重点。

如果三个 Agent 都在写答案，那它们只是三个写手。你最后可能得到三份相似但互相冲突的结果，还要自己来合并。

真正有价值的不是“人数变多”，而是“角色变清楚”。

在我的设计里，有三个核心角色：

Planner，规划者。

Generator，生成者。

Evaluator，评估者。

还有一个隐藏角色：Coordinator，协调者。

Coordinator 不算在三个 Agent 里面，它更像项目经理，负责保存用户意图、分配任务、组织文件交接、控制边界，以及决定什么时候继续迭代，什么时候结束。

这套结构的关键不是并行，而是制衡。

Planner 不负责写。

Generator 不负责最终验收。

Evaluator 不负责生产。

每个角色只做自己该做的事。Planner 只定义“要什么”，不要急着规定“怎么做”

我以前很容易犯一个错误：让 AI 一开始就把方案拆得很细，甚至让它提前决定技术实现。

后来我发现，上游规划太细反而危险。

因为如果 Planner 一开始做了一个错误的技术判断，这个错误会一路传导到后面。Generator 会按错的方向实现，Evaluator 也可能沿着错的框架验收。

所以 Planner 应该克制。

它要做的是把一句模糊需求展开成高层规格：目标是什么，用户是谁，范围是什么，什么不做，有哪些约束，什么情况算完成。

但它不要抢着写实现方案。

好的规划不是把路径定死，而是把方向说清楚。Generator 不能直接开干，它要先签合同

这套方法里，我最喜欢的机制是 iteration contract，也就是迭代合同。

很多 AI 任务失败，并不是因为模型不会做，而是因为“完成”的定义太模糊。

用户觉得完成是核心流程可用。

Generator 觉得完成是页面写完、代码跑起来。

Evaluator 如果没有标准，也只能凭感觉判断。

所以在每一轮真正生成之前，Generator 和 Evaluator 要先协商一份合同。

这份合同要写清楚：

本轮做什么。

交付物是什么。

验收标准是什么。

怎么验证。

哪些东西本轮不做。

如果失败，怎么进入下一轮。

默认一轮只做一个功能、一个用户流程，或者一个可验收的 vertical slice。

这一步看起来慢，但它其实是在避免后面更大的浪费。

不要等做完之后才发现，大家对“做好了”的理解完全不同。Evaluator 是整套系统里最重要的角色

我现在越来越觉得，评估器比生成器更重要。

因为生成能力会越来越强，但判断质量的能力，不一定会自然变强。

尤其是 AI 生成的东西，经常有一种迷惑性：表面很完整，语言很流畅，结构也好看，但细看会发现核心判断不稳，功能没有真跑，设计很模板，或者证据不可靠。

所以 Evaluator 必须独立，而且必须严格。

它不能只听 Generator 说“我已经检查过了”。它要自己看，自己跑，自己点，自己验证。

如果是代码，就跑测试、看 diff、查日志。

如果是前端，就打开页面、点流程、看截图。

如果是文档，就检查结构、事实、引用和一致性。

Evaluator 的输出也不能只是“不错”或“有待优化”。它要 findings first，先列问题，再给结论。

我给它保留了四个默认维度：

设计质量。

原创性。

工艺。

功能性。

这四个维度特别适合评估那些“看起来不错但可能很 AI”的结果。

比如一个页面用了漂亮渐变、白色卡片、很多圆角，看起来很完整，但如果它和业务无关、没有真正的视觉判断，那就不应该得高分。

AI 最容易产出的是“精致的通用答案”。Evaluator 的任务，就是把这种表面完整性拆穿。评估器也需要训练，不是写一句 prompt 就够了

一个独立 Evaluator 并不会天然严格。

它也可能过于礼貌，也可能被表面完成度骗过去，也可能漏掉真正重要的问题。

所以 Evaluator 本身也要被校准。

我的做法是给它示例、反例、评分维度和惩罚项。然后看它的评估日志，找出它和人类判断不一致的地方，再修改 rubric 和 prompt，再重跑。

这个过程很像训练一个 QA 同事。

你不能只说“你要严格一点”。你要告诉它，什么叫好，什么叫勉强可以，什么叫失败，哪些问题是阻塞项，哪些只是 polish。

只有评估信号稳定，Generator 才有明确的改进方向。文件交接比长聊天更可靠

另一个重要设计是：角色之间尽量通过文件交接，而不是一直聊天。

比如：

10-product-spec.md

20-evaluation-rubric.md

25-iteration-contract.md

30-generation-report.md

40-evaluation-report.md

50-final-summary.md

文件的好处是清楚、短、可追踪。

Planner 写规格，Generator 读规格。

Generator 写生成报告，Evaluator 读报告但不盲信。

Evaluator 写评估报告，Coordinator 决定下一轮。

这比一个长长的共享聊天记录稳定得多。

长聊天很容易污染角色边界，也很难复盘到底是哪一步出了问题。文件则让每一步都留下证据。上下文不够时，不只是压缩，而是重置

长任务里还有一个很常见的问题：模型工作到后面，会开始丢状态，甚至提前收尾。

很多人的直觉是做上下文压缩，把前面的内容总结一下继续给它。

但我更喜欢另一种方式：上下文重置。

也就是启动一个新的 Generator，用一份结构化交接文档告诉它：当前目标是什么，已经做了什么，改了哪些文件，当前合同是什么，哪些检查失败，下一步要做什么。

这相当于给模型一块干净的白板。

不是让它背着越来越重的历史继续跑，而是让它接手一个清晰的工作状态。Harness 也不能迷信，组件要能拆

我不认为这套系统应该永远保持复杂。

每个组件都代表一个假设：

Planner 存在，是因为模型可能低估需求。

Evaluator 存在，是因为生成者自评不可靠。

迭代合同存在，是因为任务边界容易漂移。

上下文重置存在，是因为长任务里模型可能失去状态。

但模型会进步。今天必要的脚手架，明天可能变成负担。

所以 harness 也要定期做消融：一次只移除或简化一个组件，然后比较结果有没有变差。

如果模型已经能连续稳定工作很久，也许不需要每个小功能都做一轮合同。可以保留 Planner，提前冻结最终验收合同，让 Generator 连续完成更大范围任务，最后由 Evaluator 做一次严格总评。

但底线不能变：生成和评估必须分离。我真正想复用的是一套工作协议

我把这套方法整理成 skill，不是为了绑定某一个工具。

它可以在 Claude 用，也可以在 Codex 用，甚至可以在任何支持角色提示词、文件交接、子 Agent 或顺序角色模拟的环境里用。

对我来说，它真正有价值的地方，是把 AI 协作从“一个模型努力完成任务”，变成“一个系统稳定地产出结果”。

这也是我最近对 AI 工具最大的认知变化：

不要只问模型能不能做。

要问你给它搭了什么工作系统。

单个 Agent 很强，但它仍然会自信、会偷懒、会误判、会提前结束。

一个好的 harness，不是让 AI 更像人，而是让 AI 更像一个有流程、有质检、有交接、有复盘的团队。

这才是我认为 Agent 工作流真正值得探索的地方。

我也把这套方法整理成了一个开源 skill，放在 GitHub 上，包含中英双语 README、可安装的 SKILL.md、中文阅读版和文章稿。

GitHub 地址：

https://github.com/samwang0041-star/agent-harness-skill

欢迎直接安装、改造，或者把它迁移到你自己的 AI 工作流里。