从玩具到生产力：用真实项目讲透 AI Agent 的 Harness Engineering
一句话概括
以真实项目为例，讲解如何将 AI Agent 从原型玩具提升为可投产的工程系统，重点探讨 Harness Engineering（约束与编排工程）在其中的核心作用。
实践内容
Harness 的定义与边界
Harness 是一整套把大模型纳入工程体系的控制面，管理的核心问题是：传统软件工程管的是「确定性」，Harness Engineering 管的是「非确定性」。传统软件工程是为人类设计的防呆系统，而大模型是概率引擎，同样的输入可能产生不同结果。
AI Agent 架构模式边界矩阵
用两个坐标轴界定 Harness Engineering 的边界：
- X轴（执行流路由）：静态预设 vs. 动态自主——下一步干什么，是代码写死的，还是大模型决定的？
- Y轴（状态与上下文）：隐式内部 vs. 显式外部——系统的记忆是塞在 Prompt 窗口里维持，还是由外部数据库/状态机接管？
四个象限：
- 象限三：无状态链 — 单次 API 调用，把 LLM 当纯函数，适合一次性翻译或海量情感分类
- 象限二：提示词驱动 — AutoGPT、原生 ReAct，模型自主性高，中间步骤全堆在 Prompt 里
- 象限四：传统管道 — LangChain 顺序链，外部状态管理严谨，模型只是被动调用的”处理节点”
- 象限一：Harness Engineering — 模型提供意图，外部 Harness 负责状态隔离与沙盒校验
识别”伪 Harness”与”劣质 Harness”
伪 Harness（根本不是 Harness）：
- “软约束”陷阱：在 Prompt 里写 5000 字 DO NOT，只是”口头嘱咐”，长链路中容易被遗忘
- “军火库”陷阱：一股脑给 Agent 塞 20 个 API 让它自己挑，没有边界约束
劣质 Harness（是 Harness 但质量差）：
- “盲打”陷阱：外层套执行器，一报错就把 Error 塞回模型让它继续试，容易陷入死胡同
- “官僚主义”陷阱：强制模型先输出万字设计文档才能写代码，浪费 Token 且难以维护
好的 Harness 的三个特征
- 前置验证（Evaluator 沙盒）：单测失败时，把日志抓给 Agent，在沙盒里基于证据触发 Retry
- 最小真相源（Spec is Truth）：维护一份轻量的状态机文档，任务跨天时能无损恢复上下文
- 物理门禁（Checkpoint Before Execute）：用系统级审批节点作为刹车，模型破坏现有环境前必须拿到授权
Aegis 项目的五阶段实践
- 起步阶段：先收敛目标，不急着编码 — 第一条指令是”阅读架构设计文档，了解我想做什么，然后向我复述需求并讨论”
- 连续开发阶段：用 Spec 和 Handoff 对抗上下文腐烂 — 每轮对话开场白都是”请阅读 Handoff 文件恢复任务上下文”
- 执行阶段：将 Prompt 溶解进 Capability 框架 — 一个 Capability = 一小段专属 Prompt + 一段确定的 Python 脚本 + 一个 Validator
- 运行阶段：跨越”能聊”与”能跑”的分水岭 — 接入真实环境后处理 Chat 接口静默退出、504 超时、403 拦截
- 交付阶段：让测试与回归前置化 — 测试不再是收尾动作，而是工作轨道本身
sdd-riper-one-light 的四个控制点
用契约式设计（Design by Contract）把非确定性引擎夹在确定性管道里：
- 前置断言（Pre-conditions）：强制 Checkpoint 与 Restate First，执行高危代码前模型必须复述核心目标
- 后置断言（Post-conditions）：闭环回写，必须通过测试与日志等外部证据交叉验证
- 不变式（Invariants）：维护最小真相源（Spec is Truth），外部 Spec 是不容篡改的”不变式”
8 阶段 SOP
| 阶段 | 我给模型的输入 | 先要求它返回什么 | 我的控制动作 |
|---|---|---|---|
| 目标收敛 | 先读文档，不准上来写代码 | 需求复述、主线判断、疑问边界 | 先纠偏，再放行 |
| 状态恢复 | 先读 Spec/Handoff | 已完成项、未完成项、接续建议 | 用外部真相源恢复状态 |
| 上下文装配 | 不整包投喂，只给索引 | 最小上下文清单 | 按需补充，避免爆 Context |
| 任务分块 | 这一轮只做一个小段 | 1-3 个动作、风险、验证方式 | 只批准当前轮次 |
| 链路设计 | 先判断该走什么模式 | 执行模式和装配方案 | 先定路线，不盲改 Prompt |
| 执行前校准 | 先别改代码，先 Checkpoint | 当前理解、下一步、风险、验证方案 | 对齐后再 Approval |
| 外部验证 | 不接受”我觉得好了” | 基于日志、测试、回包的事实判断 | 用证据而不是主观感觉决策 |
| 回写交接 | 暂停前必须回写 | 完成项、偏差、残留问题、下一步 | 给下一轮留下干净恢复点 |
摘录
Harness 不是某条提示词、某个工具，也不是多写几份文档。它是一整套把大模型纳入工程体系的控制面：如何提供唯一的真相源？如何约束执行边界？如何接入业务能力（Capability）？如何观测、调试运行状态？如何让产出可验证、可回归，让其他工程师能接手？
传统软件工程管的是「确定性」，Harness Engineering 管的是「非确定性」。传统软件工程是为人类设计的防呆系统——我们有常识，但容易手滑敲错代码。但大模型是概率引擎，同样的输入，它可能直接返回结果，可能调一个不相干的 Tool，也可能因为前文的某句话”幻觉”暴走。
大模型时代，工程师的核心价值正在从”亲手写出每一行代码”，逐步迁移到”定义目标、卡住边界、掌控节奏、验收结果”。
Harness 的价值不是”让 Agent 更自由”，而是让人类始终握着方向盘，把非确定性执行压缩成可验证、可回退、可交接的小闭环。
在每一个阶段只给模型一个带边界的输入；它必须先交付中间产物；我用 Harness 控制点核对无误后，才允许进入下一步。
你不能让模型一路黑盒干到底。每一轮都要先拿到一个中间产物，再决定是否放行。
想释放大模型的生产力，第一步是先建好约束和轨道。
涉及实体
- Claude-Code —— Claude Code 是 Harness Engineering 的典型实现
- Harness-Engineering —— 本文的核心主题