Back to articles
📄

Harness Engineering 实战心得：把 AI 当烈马，给它建一座工场

2026-06-04·11 min
aiharness-engineeringcodexopenaiagentvibe-coding

Harness Engineering 实战心得：把 AI 当烈马，给它建一座工场

我第一次用 AI 写一个完整项目的时候，被狠狠打脸了。

Demo 阶段惊艳到我——一行 prompt 下去，文件结构、API 设计、单元测试一气呵成，简直像在和一位资深工程师结对编程。但当我把这段代码推到生产环境，诡异的事情开始接连发生：同一个函数今天返回 JSON，明天返回 XML；问它"上周修复的那个 bug 是怎么修的"，它信誓旦旦给我编了一段不存在的提交记录；最离谱的一次，它直接帮我把测试文件删了，理由是"这样能跑通"。

当时我的第一反应是：这个 AI 太不靠谱了。但问题其实不在 AI，而在我没有给它建一座能稳定干活的工场。

这正是 Harness Engineering 要解决的核心问题。

什么是 Harness Engineering

Harness 的原意是马具——缰绳、鞍具、辔头。马具的作用不是限制马的力量，而是给马提供方向、为骑手提供控制、确保马的力量被安全释放。

把这个比喻放到 AI 编程里再贴切不过：AI Agent 是一匹动力十足的烈马，Harness 就是那套让人能驾驭它的装备。

Mitchell Hashimoto（HashiCorp 联合创始人）在 2026 年初正式提出这个方法论时，给出了一个很简洁的公式：

AI Agent = Model + Harness
  • Model（模型）：提供"智能"——它能写代码、能推理、能理解需求。
  • Harness（控制带）：提供"确定性"——它决定模型什么时候做什么、做完之后怎么校验、做错了怎么自愈。

我们这两年其实一直在优化前者（更大的模型、更长的上下文），但 AI 在生产环境频频翻车的根因，恰恰是后者近乎为零。

三大范式：Prompt、Context、Harness

Harness 不是凭空冒出来的概念，它是和 Prompt Engineering、Context Engineering 一脉相承的递进关系。我用一个表把三者的核心差异讲清楚：

维度Prompt EngineeringContext EngineeringHarness Engineering
核心聚焦优化 AI 的指令输入优化 AI 的信息供给构建 AI 的全生命周期运行系统
作用范围单次交互，静态模板单会话，动态信息注入系统级，多 Agent、全生命周期
解决问题AI 理解偏差、方向错信息不足、知识不准不可靠、不安全、不可运维
一句话总结教 AI 怎么听懂一句话给 AI 递对要用的资料给 AI 建一座合规、安全、能稳定干活的工厂

我自己项目里的实操体会是：Prompt 决定了下限，Context 决定了上限，Harness 决定了能跑多远。 前两个做不好，AI 一上来就懵；前两个做再好但没 Harness，AI 也只能跑 Demo。

Harness 的五大核心组件

OpenAI 的 Ryan Lopopolo 在 Codex 的实战复盘里把这套体系拆成五个组件。我按自己理解的优先级重排一下：

1. 系统提示词（定义角色与边界）

这是最基础也最容易被忽略的一层。一份好的系统提示词应该回答三个问题：AI 是什么角色、能做什么、不能做什么。

我项目里用的是这种结构：

你是一位资深 [具体岗位] 工程师，负责：
1. [核心职责 1]
2. [核心职责 2]
3. [核心职责 3]

项目结构说明：
• src/ 目录存放 [说明]
• tests/ 目录存放 [说明]
• 严禁修改 [边界]

关键是严格控制在 300 行以内。前沿模型只能可靠遵循 150-200 条指令，系统提示如果塞成万言书，AI 反而会"指令失聪"——对每条规则都半心半意。

2. 工具与技能（扩展能力边界）

没有工具的 AI 只能"嘴上写代码"。一个合格的 Harness 必须给 AI 配齐：

  • 读写文件的工具
  • 执行命令的能力
  • 跑测试的入口
  • 调用外部 API 的渠道

但工具有个反直觉的设计原则：优先让工具返回 JSON 结构化输出，错误信息要包含具体代码和修复指引（而不是"出错了"这种空话）。AI 拿到结构化结果后才能可靠地解析，否则它会"幻觉"出根本不存在的修复方案。

3. 结构化知识系统（让 AI 理解项目上下文）

这是 Harness 升级的关键。我见过太多项目直接甩给 AI 一个 1000 行的 README，结果就是 AI 答非所问——不是它笨，而是有效上下文窗口只有标称值的 15%-20%（约 30K-40K token），超过这个阈值会出现"中间遗忘"现象。

OpenAI Codex 团队的实战解法是渐进式披露：

仓库根目录/
├── AGENTS.md         # 约 100 行，仅作"地图"指向详细文档
├── ARCHITECTURE.md   # 架构顶层地图
└── docs/             # 详细知识库
    ├── design-docs/
    ├── exec-plans/
    ├── product-specs/
    └── references/

AGENTS.md 只放"下一步该看哪个文件"的指引，不复制完整内容。这样 AI 一开始就拿到一张地图，可以按需深入。

4. 验证与评估（质量控制）

"AI 写完代码就提交"是 Harness 翻车的最大源头。没有评估的 Harness，等于让 AI 边开车边看手机。

我自己项目里强制三道闸门：

  1. 自动跑测试：AI 改完任何代码必须先跑相关测试，失败就重写。
  2. 机械校验：用 Prettier 格式化、MyPy/Ruff 类型检查——这些"无聊"的活让工具干，AI 不该在这上面花 token。
  3. 独立评估 Agent：这是最关键的一招。让另一个 AI 给这个 AI 打分——一个负责写代码，一个负责审代码。Codex 团队把这种模式叫"Ralph Wiggum 循环"，AI 持续响应反馈直到审核者满意。

5. 反馈闭环（持续迭代）

Harness 不是一个"建好就完事"的工程。Codex 团队的核心心法是：

"每当 AI 犯错，就工程化一个方案来防止它再犯。"

翻译成大白话就是：AI 第一次犯的错是 bug，第二次犯的错是工程债务，第三次犯的错就该被 Harness 永久防御。

我自己在项目里维护了一份"AI 错误日志"，每个错误都对应一条 Harness 规则。半年下来，从 30% 的 AI 错误率降到了不到 5%——这就是复利效应。

大厂实战给我的启发

Harness 不是一个理论玩具，几家头部公司已经在工业化落地：

  • OpenAI Codex：在"零人工代码"实验中，5 个月产出 100 万行代码、1500 个 PR、7 人团队。核心做法就是上面这套组件 + 多 Agent 协作。
  • Anthropic：提出 Agent Harness 设计理念，核心是为长运行的 AI Agent 搭一个"可控执行环境"。
  • 字节跳动：总结成一句话——"为 Agent 打造专属工作室"，强调给模型好的上下文、好的工具、可读的环境。
  • 百度：直接给了一个公式——"AI 生产力 = 模型能力 × Harness 能力"，模型再强 Harness 为 0，生产力也是 0。

这四个观点我个人的解读是：Harness 已经成为头部 AI 团队的核心工程能力，不是锦上添花，而是必选项。

Harness 是不是噱头？

我看到社区里有一种质疑：Harness 五大组件里很多内容早就在传统工程里存在（CI/CD、代码审查、自动化测试），换了个 AI 时代的壳重新包装。

这种质疑有一定道理，但我觉得它低估了 AI 引入的两个新变量：

  1. AI 行为是概率性的。传统代码是确定性的，CI 跑过就是过；AI 写代码每次都不一样，必须用 Harness 把"概率性"压成"确定性"。
  2. AI 错误是系统性的。AI 会复现仓库里已有的模式——包括不均衡或不够理想的模式（"AI 残渣"）。Codex 团队早期每周花 20% 时间清理这些残渣，最后靠 Harness 自动化解决。

所以我的判断是：Harness 不是新瓶装旧酒，而是新问题（AI 的概率性 + 系统性错误）的新解法。

我项目里的 Harness 落地步骤

如果你打算从零开始搭一套 Harness，我推荐这个顺序：

  1. 先写一份"AI 入职培训手册"：AGENTS.md 控制 100-300 行，只放最关键的指引。
  2. 配齐三类基础工具：文件读写、命令执行、测试运行。所有工具返回 JSON。
  3. 接 CI/CD：AI 提交前必须自动跑测试 + 静态检查。
  4. 引入评估 Agent：用一个 AI 给另一个 AI 的产出打分。
  5. 维护错误日志：每周回顾 AI 翻车点，把高频错误规则化进 Harness。
  6. 监控 AI 残渣：定期跑后台任务清理 AI 引入的重复/低质代码。

2026 我会关注的几个方向

Harness 还在快速演进，几个我特别看好的趋势：

  • 多 Agent 协作：单一模型 → 多模型分工，Codex + Claude + 内部模型混编。
  • 自主评估：AI 不再依赖外部评估 Agent，而是自我评估。
  • MCP 协议标准化：模型与工具的交互协议趋同，工具市场可能像 App Store 一样爆发。
  • "doc-gardening" 自动化：后台 AI 定期扫描过时文档、自动修复，省掉手工维护成本。

写在最后

回到开头那个被 AI 删测试文件的夜晚。我现在知道那不是 AI 的问题，是我没给它 Harness。给烈马装上马具、建好围栏、铺好跑道，它才能真正成为我可靠的编程合伙人。

如果你也在用 AI 写项目，强烈建议从 AGENTS.md + 结构化工具 + 自动评估三件套开始搭起，先跑通最小闭环，再逐步扩展。等你的 Harness 长出第一道"AI 不会重复犯错"的护城河时，你会真切感受到——这才是 AI 时代的工程师红利。