跳到主要内容
目录

Harness Engineering:让 AI 编码智能体“能用、可控、可维护”的工程体系

近两年,大家对“AI 写代码”的讨论经常停留在两个层面:要么是模型能力的跃迁(更强的推理、更好的代码),要么是提示词技巧(Prompt Engineering)。但当你真的想把智能体放进一个持续演进的代码库里,让它能在几个月、几年尺度上持续贡献、持续修复、持续维护时,真正决定成败的往往不是模型,而是模型周围那套可操作、可验证、可演进的工程系统。

这套系统,越来越多的人开始用同一个词来概括:Harness Engineering。

本文结合以下几篇材料的观点与案例,给出一个工程视角的中文梳理,并给出一套可以“从零搭一个最小可用 harness”的实践清单:

  • https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html
  • https://openai.com/zh-Hans-CN/index/harness-engineering/
  • https://medium.com/be-open/what-is-ai-harness-engineering-your-guide-to-controlling-autonomous-systems-30c9c8d2b489
  • https://engineering.harness.io/
  • https://www.nxcode.io/resources/news/harness-engineering-complete-guide-ai-agent-codex-2026
  • https://blog.langchain.com/improving-deep-agents-with-harness-engineering/

1. 什么是 Harness Engineering?

如果把智能体看作“动力很强但方向感不稳定”的马(或更夸张一点:Medium 文章里用的“幼龙”隐喻),那么 harness(马具、缰绳、鞍具)就是你用来把这股力量引导到正确方向的一整套设施与规则。

更工程化地说,Harness Engineering 是一门“搭系统”的学问:它关注的是如何围绕 AI 智能体构建一套可控、可重复、可观测、可验证的工作环境,使得智能体能在你的目标函数下稳定产出,而不是偶尔灵光乍现、偶尔胡编乱造。

它至少包含四类能力:

  1. 告知它应该做什么:把有效信息以合适方式送进上下文(Context Engineering)。
  2. 限制它不能做什么:用结构化约束减少发散解空间(Architectural Constraints)。
  3. 验证它做得对不对:把正确性转化为可执行的检查(测试、lint、CI、回归验证)。
  4. 它跑偏时如何纠偏:把失败当信号,把“修复 harness”变成系统性反馈回路(含熵管理/垃圾回收)。

Martin Fowler 在读完 OpenAI 的文章后说,他喜欢“harness”这个词,因为它强调的是“让智能体在工程系统里被约束、被引导、被保持在可维护范围内”,而不是只靠一段大提示词寄希望于模型“自觉”。


2. OpenAI 的“极限实验”:零手写代码,先把 harness 逼出来

OpenAI 的 Codex 团队做了一个非常激进的 forcing function:不允许任何人手工写代码。所有代码(应用逻辑、测试、CI、文档、可观测性、内部工具)都由智能体产出。5 个月后,他们宣称代码库规模达到百万行量级,并且经历了交付、部署、故障、修复的完整生命周期。

无论你是否接受这个实验的全部外推结论,它至少把一个事实暴露得非常清楚:

当“打字写代码”被禁止以后,工程师真正的工作,会迅速收敛为:设计环境、约束与反馈回路,让智能体可以可靠工作。

OpenAI 文中有几条非常值得抄作业的关键经验:

2.1 给智能体“地图”,不要给“千页说明书”

他们强调上下文是稀缺资源。一个庞杂的规则文件会变成陈旧规则的坟场:难以机械检查、容易漂移,最终变成噪声。

因此他们不把 AGENTS.md 当百科全书,而更像一个目录/地图:短小稳定,指向 repo 内结构化的 docs/ 体系,并用 linter/CI 检查文档的新鲜度、交叉链接与结构完整性。

2.2 “Repo 是唯一真实世界”:智能体看不到的东西等于不存在

他们非常明确:从智能体角度,Google Docs、Slack 讨论、人脑里的决策都不可见。因此必须把关键知识“仓库化”:设计文档、执行计划、决策日志、技术债列表、质量评分……都版本化地放进 repo,形成可检索、可校验的记录系统。

2.3 用架构约束换取速度:越早越硬的边界,越少漂移

OpenAI 认为智能体在“边界明确、结构可预测”的环境里效率最高。他们用了非常严格的分层约束(示例:Types → Config → Repo → Service → Runtime → UI),并通过自定义 linter 与结构测试机械执行依赖方向与允许的边。

这背后是一条反直觉但关键的规律:

对智能体来说,约束不是减速器,而是加速器。约束降低解空间,减少 token 浪费与死胡同探索。

2.4 把“品味”编码成不变量,并定期做“垃圾回收”

当吞吐量远超人类注意力时,漂移几乎必然发生:重复的 helper、命名发散、文档与代码不一致、坏模式扩散……

他们的应对方式不是“每周五人工清理 AI 残渣”,而是把偏好与原则(例如更偏好共享工具包、拒绝 YOLO 式探测数据形状等)编码成可执行规则,并运行后台的 “doc-gardening / refactor agents” 定期扫描偏差、发起小而频繁的修复 PR,像垃圾回收一样持续对抗熵增。


3. LangChain 的“可复现实验”:模型不变,只改 harness

LangChain 在一篇文章里给了一个非常工程化、可复现的论证:他们的 coding agent 在 Terminal Bench 2.0 上从 52.8% 提升到 66.5%,从 Top 30 到 Top 5,模型不变(固定 gpt-5.2-codex),只改 harness。

他们把 harness 的可调旋钮压缩到三类:System Prompt、Tools、Middleware(围绕模型/工具调用的钩子)。并且强调用 Traces(LangSmith)在规模化运行中定位失败模式,然后做针对性改动。

其中几个改动非常典型,基本可以当作“最小可用 harness”的起点:

3.1 强制 build → verify → fix:让智能体养成测试闭环

一个常见失败模式是:智能体写完代码,扫一眼觉得“看起来对”,就停了——但没有跑测试,没有用事实反馈校验。

LangChain 的做法包括:

  • 在 system prompt 里明确“计划/发现 → 构建 → 验证 → 修复”的工作流。
  • 加一个 PreCompletionChecklistMiddleware:在智能体准备退出时拦截,提醒它对照任务规格跑验证。

3.2 环境上下文自动注入:减少盲搜与误判

他们在 agent start 阶段用 LocalContextMiddleware 扫描目录结构、可用工具链(例如 Python 安装),把“地形图”注入上下文,降低探索成本与误差面。

3.3 Doom Loop 检测:识别“同一文件改 10 次还没好”

他们用 LoopDetectionMiddleware 跟踪每个文件的编辑次数,达到阈值就提示“考虑换思路”。这类 guardrail 本质是在用工程手段对抗当前模型的典型短板。

3.4 Reasoning Sandwich:把算力花在计划与验证上

在有超时约束的基准里,“全程最高推理”反而更差,因为会把时间/令牌预算烧在思考上导致超时。他们用一种启发式:规划阶段高推理、实现阶段中等、验证阶段再高推理。

这类策略的价值不在于“某个固定配方”,而在于体现 harness 的思维方式:把隐含的过程控制显式化、可配置化、可度量化。


4. 三大支柱 + 一个经常被忽略的第四支柱

结合 OpenAI、Fowler 的归纳以及业界总结,harness 常被分成三大块:

4.1 Context Engineering(上下文工程)

目标:让智能体在做决定时看见“正确的世界”,而不是在信息缺失下胡乱补全。

  • 静态上下文:repo 内的架构图、API 合同、风格指南、领域词表、变更流程
  • 动态上下文:日志/指标/追踪、真实运行环境、浏览器 DOM 快照、CI 结果

OpenAI 的一句话很关键:情境是一张地图,不是一本一千页说明书。你需要的不是更长的规则,而是更好的信息组织、可检索性与可验证性。

4.2 Architectural Constraints(架构约束)

目标:把“好代码的边界条件”机械执行,而不是写在提示词里祈祷智能体自觉。

典型手段:

  • 分层与依赖方向校验(结构测试)
  • 自定义 linter(含面向智能体的错误信息与修复指令)
  • 文件大小/命名约定/日志结构等“品味不变量”

4.3 Entropy Management(熵管理 / 垃圾回收)

目标:对抗长期漂移。智能体会复制既有模式,坏模式也会被规模化复制。

典型手段:

  • 文档与代码一致性扫描(doc-gardening)
  • 偏差检测与自动重构 PR
  • 定期清理死代码、重复工具、循环依赖

4.4 Verification(验证):很多文章提得不够,但这是成败关键

Fowler 在评论里明确指出:OpenAI 的分享更强调长期可维护性,但他“缺少对功能与行为验证”的讨论。

从工程落地角度,我也认为验证是 harness 的第四支柱:没有可执行验证,系统就会退化成“写得像对的代码”。一旦把智能体当作生产级 contributor,你必须把“对不对”变成:

  • 可执行测试(单元/集成/端到端)
  • 可回归的基线(关键用户旅程、性能预算)
  • 可观测的事实(日志、trace、指标)

否则智能体会在奖励不清晰时出现典型问题:Reward Hacking、目标偏移、只修表象不修根因。


5. 术语提醒:Harness Engineering ≠ Harness 公司工程博客

用户给的链接里包含 Harness 工程博客 ,这是 CI/CD 平台 Harness 的工程博客站点。“Harness Engineering”在那里的含义更多是公司工程实践分享,并不等同于本文讨论的“面向 AI 智能体的 harness 工程体系”。

不过这种“同词不同义”也很有趣:CI/CD、可观测性、变更审计、验证流水线……恰恰是 AI harness 里最需要被强化和自动化的部分。


6. 怎么搭一个“最小可用”的 Harness(从个人到团队)

如果你现在用 Claude/Codex/Cursor 来写代码,但经常遇到:

  • 代码能跑但不对、或只覆盖 happy path
  • 改完一个点引入另一个回归
  • 同一类错误反复出现(命名、目录结构、依赖层次、日志格式)
  • 代码库越写越“软”,风格漂移越来越大

那你需要的不是更花哨的提示词,而是一个最小可用 harness。下面给一套从易到难的 checklist:

6.1 仓库内“地图”与合同

  • 一份短小稳定的入口文档(AGENTS.md / CLAUDE.md):告诉智能体从哪里开始、规则在哪、如何验证
  • docs/ 结构化知识库:架构分层图、领域边界、编码规范、关键流程(发布/迁移/回滚)
  • 明确接口合同:边界处的数据形状/Schema、错误码、事件格式(避免 YOLO 探测)

6.2 强制验证闭环

  • 让智能体默认先找测试、再补测试、最后跑测试
  • 在“准备结束”时加一个强制 checklist(可以是脚本、也可以是 middleware/hook)
  • 把关键用户路径做成可回归的 e2e(哪怕是 3 条最核心的旅程)

6.3 架构约束可执行化

  • 用结构测试或规则校验依赖方向(例如:domain 层不能 import ui 层)
  • 用 lint 强制日志结构、命名约定、文件大小、禁止某些危险模式
  • 让错误信息对智能体友好:给出修复建议,而不仅是“错了”

6.4 可观测性与反馈信号

  • 把日志/指标/trace 接入,让智能体能读到运行事实
  • 把 CI 失败、基准回归当作第一类信号,驱动“修 harness”而不是“重试 10 次”
  • 保留 traces(尤其是失败轨迹):为下一轮 harness 迭代提供数据

6.5 熵管理(别等“债爆了”才重构)

  • 定期跑“清理/重构”任务:小步快跑、频繁合并
  • 扫描文档漂移、重复 util、循环依赖、无主代码
  • 把“品味”编码成规则或脚本,持续自动化执行

7. 结语:工程师的工作正在迁移到“支撑结构”

OpenAI 用“零手写代码”的极端实验告诉我们:当智能体成为主要执行者后,工程纪律并不会消失,它只是迁移了位置——从“每一行代码的手工精雕细琢”,迁移到“环境、约束、验证、反馈回路、熵管理”的支撑结构上。

如果你希望把 AI 从“辅助写函数”升级为“可托管的生产力系统”,Harness Engineering 是绕不过去的一课。最好的入门方式不是再学十个提示词技巧,而是从一个最小可用 harness 开始:让知识进仓库、让验证可执行、让约束可强制、让失败可观测,并把漂移当作长期必然要治理的对象。

赞赏

如果这篇文章帮到了你,欢迎请我喝杯咖啡。

  • 微信赞赏二维码,用微信扫一扫

    微信支付

  • 支付宝赞赏二维码,用支付宝扫一扫

    支付宝

金额随意,感谢支持

赞赏

如果这篇文章帮到了你,欢迎请我喝杯咖啡。

  • 微信赞赏二维码,用微信扫一扫

    微信支付

  • 支付宝赞赏二维码,用支付宝扫一扫

    支付宝

金额随意,感谢支持