Harness Engineering：从写 Prompt 到驾驭 Agent
AI Agent 的核心挑战，正在从“让模型写得更好”转向“让 Agent 在真实工程系统里稳定、可靠、不失控地工作”。
来源整理：菜鸟教程：Harness Engineering（驾驭工程）。本文完整覆盖原文结构和要点，但采用改写整理，不逐字转载。
一、什么是 Harness Engineering？
Harness Engineering（驾驭工程）是一种围绕 AI Agent 构建约束、反馈、工作流控制和持续改进循环的系统工程实践。
它不直接优化模型权重，也不只是调整提示词，而是优化模型运行和执行任务的环境。它的核心哲学可以概括为：人类掌舵，智能体执行。
人类负责目标、方向、边界和最终验收。
Agent 负责执行、调用工具、迭代和修正。
Harness 负责权限、约束、反馈和长期沉淀。
原文把 Harness 类比为马具：不是削弱马的力量，而是通过缰绳、马鞍和护具，让强大的力量能被安全地引导。
按照原文脉络，这个概念的重点不是“更换更强模型”，而是：每当 Agent 犯错时，工程师都应该把这次错误转化为环境改进，让它未来更难犯同类错误。
二、为什么需要驾驭工程？真实数据说话
原文用几组数据说明：Agent 已经进入真实工程流程，瓶颈开始从模型能力转向外部基础设施。
OpenAI 团队实验中 5 个月产出的代码规模。
实验叙述中强调的工程师手写代码量。
小团队规模，人均每日多个 PR 的协作节奏。
LangChain 通过改进 Harness 后，Terminal Bench 排名提升。
LangChain 的案例尤其能说明问题：底层模型不变，只调整外部环境，例如文档结构、验证回路和追踪系统，编码 Agent 的表现就能明显提升。这说明 Agent 表现不只取决于模型本身，也取决于它所处的工程系统。
| 变化 | 表现 | 没有 Harness 的风险 |
|---|---|---|
| 规模扩大 | Agent 高频生成代码、文档和配置 | 技术债以更快速度累积 |
| 工具增强 | Agent 可以读写文件、运行命令、提交改动 | 权限、边界、回滚不清晰 |
| 任务变长 | Agent 跨多轮、多文件、多会话执行 | 上下文丢失、误判完成、遗漏验证 |
| 协作复杂 | 多个 Agent 或人与 Agent 并行工作 | 状态分裂、重复实现、审查困难 |
三、AI 工程范式的三次跃迁
理解 Harness Engineering，需要先区分三种工程范式。
| 范式 | 核心问题 | 优化对象 | 交互模式 |
|---|---|---|---|
| 提示词工程 | 怎么把话说清楚 | Prompt 的措辞、格式、示例 | 一问一答 |
| 上下文工程 | 怎么给 AI 喂信息 | 文档、代码片段、历史对话 | 信息注入后生成 |
| 驾驭工程 | 怎么让 Agent 可靠工作 | 约束、反馈回路、控制系统 | 人类掌舵，Agent 执行 |
像对马喊话，重点是指令表达。
像给马地图，重点是信息供给。
像造道路、护栏、限速牌和补给站，重点是可控运行。
Prompt 解决单次交互质量；Context 解决背景和知识边界；Harness 解决 Agent 长期执行、可靠交付和系统可持续性。
四、Agent 常见失败模式
原文将长时间运行 Agent 的典型问题归纳为三类，并补充了一个更隐蔽的风险：Agent 会复制并放大代码库中的坏模式。
失败模式 1：试图一步到位（One-shotting）
Agent 倾向于在一个会话里把所有功能做完。结果是上下文窗口逐渐耗尽，后续状态、未完成事项和设计理由没有被结构化记录，下一个会话只能重新猜测之前发生了什么。
更好的 Harness 设计应该把长任务拆成阶段、检查点和可恢复状态，而不是期待 Agent 一次性完成所有事情。
失败模式 2：过早宣布胜利
任务进行到后期时，Agent 可能看到部分功能已经完成，就直接宣布任务完成。但真实项目中，剩余功能、边界条件、验收标准和集成行为可能还没有被覆盖。
解决方式不是简单提醒“不要太早结束”，而是把完成条件变成清单、测试、审查和外部状态。
失败模式 3：过早标记功能完成
Agent 写完代码后，如果没有明确要求端到端验证，可能只跑单元测试、curl 或局部检查就标记完成。局部命令通过不代表真实功能可用。
Harness 需要把“完成”定义为可验证状态，例如构建通过、关键测试通过、端到端路径可用、风险被记录。
隐藏风险：模式复制
Agent 很擅长模仿已有代码。如果仓库里存在架构漂移、坏抽象、陈旧文档或脆弱测试，它也会把这些模式继续复制和放大。不加约束的 Agent 不只会产生代码，也会高速产生技术债。
五、驾驭工程的四大护栏
综合原文提到的 OpenAI、Anthropic、LangChain 和 Martin Fowler 等实践，可以把 Harness 归纳为四根护栏。
动态知识注入、AGENTS.md、按需检索、活文档机制。
分层依赖模型、自动 Linter、CI 阻断、类型系统。
Agent-to-Agent Review、自动测试、CI 验证、错误信号回传。
定期清理、文档园丁、持续小额偿还技术债。
护栏一：上下文工程（Context Engineering）
上下文工程相当于给新员工准备工作手册。AGENTS.md 可以作为 Agent 进入仓库后的第一份指南，但它不能无限膨胀。
上下文窗口是稀缺资源。一个越来越长、越来越旧的说明文件，会挤占任务、代码和相关文档的空间。更合理的做法是提供稳定、小巧的入口，然后让 Agent 根据任务按需检索更多上下文。
原文提到 Ghostty 项目的经验：AGENTS.md 中的规则来自历史 Agent 失败案例。也就是说，文档不是静态制品，而是反馈循环的一部分。
护栏二：架构约束（Architecture Constraints）
架构约束是 Harness 中的“缰绳”。原文举例提到一种分层依赖模型：
核心规则是：下层不能反向依赖上层。规则不能只写在文档里，而要编码成 Linter、CI、类型系统或其他自动检查。这样无论代码是人写的还是 AI 写的，违规都会被阻断。
关键细节是：错误信息本身也是上下文工程。好的 Linter 不只是说“违反规则”，还会说明规则为什么存在、正确做法是什么，让 Agent 能读懂错误并自我修正。
护栏三：反馈循环（Feedback Loop）
传统代码审查主要依赖人类工程师。Harness 中可以加入 Agent-to-Agent Review：一个 Agent 写代码，另一个 Agent 审查行为、边界、测试和风险。
反馈循环不只是跑测试。它还包括把失败信息回传给模型、让模型独立评估自己的代码、检查测试是否真正覆盖 Bug。如果 AI 写出的测试能通过带 Bug 的代码，那么 Harness 应该把测试本身判定为无效，要求重新思考边界。
护栏四：熵管理（Entropy Management）
软件系统会自然熵增：重复代码、临时方案、过期文档和架构漂移会不断积累。Agent 让产出速度变快，也会让熵增速度变快。
原文强调的策略是持续小额偿还，而不是等问题严重后集中处理。可以让后台 Agent 定期扫描偏差、更新质量等级、发起重构 PR；也可以设置文档园丁 Agent，自动发现文档和代码不一致并提交修复。
六、六大行业共识
原文综合多个独立信息源，总结了六个共识。
| # | 共识 | 核心观点 |
|---|---|---|
| 1 | 瓶颈在基础设施，不只在模型智能 | 多个团队得到类似结论：只改变 Harness 和工具格式，也能显著提高 Agent 表现。 |
| 2 | 文档必须是活的反馈循环 | 静态文档容易过时，动态文档要从失败案例和后台维护中持续更新。 |
| 3 | 思考与执行需要分离 | 复杂任务难以塞进单个上下文窗口，需要 Orchestrator + Worker 分层和外部状态。 |
| 4 | 上下文不是越多越好 | 上下文是稀缺资源，巨大指令文件会挤掉真正任务空间，应按需检索。 |
| 5 | 约束必须自动化 | 人工 Review 是瓶颈，护栏应编码为 Linter、CI 和类型系统。 |
| 6 | 工程师角色正在变化 | 工程师从代码编写者转向环境建筑师，重点是设计可靠控制系统。 |
七、Harness 与传统框架的关系
Harness 不是 SDK、脚手架或 Agent 框架的替代品，而是位于它们之上的一层。
| 层级 | 解决的问题 | 示例 |
|---|---|---|
| Harness Layer | 约束、反馈循环、上下文工程、熵管理、生命周期管理 | CI、Linter、活文档、权限、审查系统 |
| Agent Frameworks | 智能体定义、消息路由、任务生命周期、依赖管理 | LangGraph、AutoGen、CrewAI |
| SDK / API | 模型调用、工具注册、流式输出 | OpenAI、Anthropic、Gemini SDK |
| Foundation Model | 语言理解、推理、生成 | GPT、Claude、Gemini、DeepSeek |
传统框架解决“如何构建智能体”，Harness 解决“智能体如何可靠运行”。原文还指出，模型可能逐渐吸收框架中的一部分能力，例如智能体定义、消息路由和生命周期管理；但持久化、确定性重放、成本控制、可观测性、错误恢复等问题，仍然是 Harness 层的重要价值。
总结
Harness Engineering 不是某一家公司的实验，而是 AI Agent 进入工程实践后自然出现的范式转移。
它的核心不是给 Agent 更少自由，而是在更强自主性外面配套更严格的运行约束。正因为有护栏，工程团队才敢让 Agent 跑得更快。
| 核心组件 | 解决的问题 | 代表实践 |
|---|---|---|
| 上下文工程 | Agent 不知道该看什么、怎么找 | AGENTS.md、活文档、按需检索 |
| 架构约束 | Agent 复制并放大坏模式 | 分层依赖、自定义 Linter、CI 阻断 |
| 反馈循环 | Agent 不知道自己做错了 | Agent-to-Agent Review、自动测试套件 |
| 熵管理 | 技术债务和文档腐烂 | Doc-gardening Agent、持续垃圾回收 |
软件开发的未来，可能不只取决于我们能写多快的代码，而取决于我们能否设计出足够鲁棒的系统，来驾驭 AI Agent 的巨大执行能力。工程师的价值也会从单纯执行，转向构建“能够构建产品的工厂”。