近两年,大家对“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 智能体构建一套可控、可重复、可观测、可验证的工作环境,使得智能体能在你的目标函数下稳定产出,而不是偶尔灵光乍现、偶尔胡编乱造。
它至少包含四类能力:
- 告知它应该做什么:把有效信息以合适方式送进上下文(Context Engineering)。
- 限制它不能做什么:用结构化约束减少发散解空间(Architectural Constraints)。
- 验证它做得对不对:把正确性转化为可执行的检查(测试、lint、CI、回归验证)。
- 它跑偏时如何纠偏:把失败当信号,把“修复 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 开始:让知识进仓库、让验证可执行、让约束可强制、让失败可观测,并把漂移当作长期必然要治理的对象。