14 KiB
title, source, author, published, last_updated, tags, raw_sources
| title | source | author | published | last_updated | tags | raw_sources | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Harness 工程完整指南 | https://www.nxcode.io/resources/news/harness-engineering-complete-guide-ai-agent-codex-2026 | NxCode Team | 2026-03-01 | 2026-04-11 |
|
|
Harness 工程完整指南
如果说 2025 年是 AI 智能体证明它们可以编写代码的一年，那么 2026 年就是我们认识到智能体不是难点——Harness 才是的一年。
OpenAI 的 Codex 团队刚刚构建了一个生产应用程序，超过 100 万行代码，其中零行是由人工手写的。工程师没有编写代码。他们设计了让 AI 可靠编写代码的系统。那个系统——约束、反馈循环、文档、linter 和生命周期管理——就是行业现在所称的 Harness。
Harness 工程是设计这些系统的新学科。它正在改变软件工程师的含义。
什么是 Harness 工程？
马的隐喻
"Harness" 一词来自马具——缰绳、马鞍、衔铁——用于将强大但不可预测的动物引导到正确方向的完整设备集。这个隐喻是有意的：
- 马是 AI 模型——强大、快速，但它自己不知道去哪里
- Harness是基础设施——约束、护栏、反馈循环，以富有成效地引导模型的力量
- 骑手是人类工程师——提供方向，而不是亲自奔跑
没有 Harness，AI 智能体就像开放领域中的纯种马。快速、令人印象深刻，但完全无法完成任何有用的事情。
正式定义
Harness 工程是设计和实现以下系统的学科：
- 约束 AI 智能体可以做什么（架构边界、依赖规则）
- 告知 智能体应该做什么（上下文工程、文档）
- 验证 智能体正确完成了工作（测试、linting、CI 验证）
- 纠正 智能体出错时的问题（反馈循环、自我修复机制）
Martin Fowler 将其描述为*"我们可以用来控制 AI 智能体的工具和实践"*——但这不仅仅是安全。一个好的 Harness 使智能体更有能力，而不仅仅是更受控制。
为什么 Harness 工程现在很重要
模型是商品，Harness 是护城河
AI 行业正在面对的令人不安的事实是：底层模型的重要性不如其周围的系统。
LangChain 明确证明了这一点。他们的编码智能体在 Terminal Bench 2.0 上从 52.8% 提升到 66.5%——从 前 30 名跃升至前 5 名——通过只改变 Harness，模型本身没有任何变化：
| 更改 | 他们做了什么 | 影响 |
|---|---|---|
| 自我验证循环 | 添加完成前检查清单中间件 | 在提交前捕获错误 |
| 上下文工程 | 启动时映射目录结构 | 智能体从一开始就理解代码库 |
| 循环检测 | 跟踪重复的文件编辑 | 防止"末日循环" |
| 推理三明治 | 规划/验证使用高推理，实现使用中推理 | 在时间预算内提高质量 |
相同的模型。不同的 Harness。显著更好的结果。
OpenAI 的 100 万行代码证明点
OpenAI 的实验是迄今为止最引人注目的证据：
- 5 个月的开发
- 最终产品中超过 100 万行代码
- 零手动编写的行——每一行都是由 Codex 智能体生成的
- 以人类所需时间的约 1/10 构建
- 产品有内部日常用户和外部 alpha 测试者
- 它交付、部署、崩溃并得到修复——所有这些都由 Harness 内的智能体完成
工程师的工作？设计 Harness。指定意图。提供反馈。不编写代码。
Harness 工程的三大支柱
OpenAI 的框架将 Harness 工程组织为三个核心类别：
1. 上下文工程
上下文工程是关于确保智能体在正确的时间拥有正确的信息。
静态上下文：
- 存储库本地文档（架构规范、API 契约、风格指南）
- 编码项目特定规则的
AGENTS.md或CLAUDE.md文件 - 由 linter 验证的交叉链接设计文档
动态上下文：
- 智能体可访问的可观测性数据（日志、指标、追踪）
- 智能体启动时的目录结构映射
- CI/CD 管道状态和测试结果
关键规则：从智能体的角度来看，它无法在上下文中访问的任何内容都不存在。Google Docs、Slack 线程或人们头脑中的知识对系统是不可见的。存储库必须是唯一的真实来源。
2. 架构约束
这是 Harness 工程与传统 AI 提示最显著不同的地方。与其告诉智能体"编写好的代码"，不如机械地强制执行好代码的样子。
依赖分层：
Types → Config → Repo → Service → Runtime → UI
每一层只能从其左侧的层导入。这不是建议——它由结构测试和 CI 验证强制执行。
约束强制执行工具：
- 确定性 linter——自动标记违规的自定义规则
- 基于 LLM 的审计器——审查其他智能体代码的架构合规性的智能体
- 结构测试——像 ArchUnit，但用于 AI 生成的代码
- 预提交钩子——任何代码提交前的自动检查
为什么约束可以改善输出：矛盾的是，约束解决方案空间使智能体更有生产力，而不是更少。当智能体可以生成任何东西时，它会浪费 token 探索死胡同。当 Harness 定义清晰的边界时，智能体会更快地收敛到正确的解决方案。
3. 熵管理（"垃圾收集"）
这是最被低估的组件。随着时间的推移，AI 生成的代码库会积累熵——文档与现实脱节、命名约定发散、死代码积累。
Harness 工程通过定期清理智能体来解决这个问题：
- 文档一致性智能体——验证文档与当前代码匹配
- 约束违规扫描器——找到通过早期检查的代码
- 模式强制执行智能体——识别并修复与既定模式的偏差
- 依赖审计器——跟踪并解决循环或不必要的依赖
这些智能体按计划运行——每天、每周或由特定事件触发——保持代码库对人类审查者和未来 AI 智能体都健康。
Harness 工程实践：团队实际如何做
OpenAI 方法：零人工代码
OpenAI 的 Harness 工程团队结构：
| 角色 | 传统 | Harness 工程 |
|---|---|---|
| 编写代码 | 主要工作 | 从不 |
| 设计架构 | 工作的一部分 | 主要工作 |
| 编写文档 | 事后考虑 | 关键基础设施 |
| 审查 PR | 代码审查 | 审查智能体输出 + Harness 有效性 |
| 调试 | 阅读代码 | 分析智能体行为模式 |
| 测试 | 编写测试 | 设计智能体执行的测试策略 |
Stripe 方法：规模化的 Minions
Stripe 的内部编码智能体，称为 Minions，现在每周产生超过 1,000 个合并的拉取请求：
- 开发者在 Slack 中发布任务
- Minion 编写代码
- Minion 通过 CI
- Minion 打开 PR
- 人类审查并合并
第 1 步和第 5 步之间没有开发者交互。Harness 处理一切——测试执行、CI 验证、风格合规和文档更新。
LangChain 方法：中间件优先
LangChain 将他们的 Harness 构建为可组合的中间件层：
Agent Request
→ LocalContextMiddleware (映射代码库)
→ LoopDetectionMiddleware (防止重复)
→ ReasoningSandwichMiddleware (优化计算)
→ PreCompletionChecklistMiddleware (强制执行验证)
→ Agent Response
每个中间件层都添加特定功能，而不修改核心智能体逻辑。这种模块化方法使 Harness 可测试且可演进。
构建你的第一个 Harness：实用框架
级别 1：基础 Harness（单个开发者）
如果你正在使用 Claude Code、Cursor 或 Codex 进行个人项目：
需要设置什么：
- 带有项目约定的
CLAUDE.md或.cursorrules文件 - 用于 linting 和格式化的预提交钩子
- 智能体可以运行以自我验证的测试套件
- 具有一致命名的清晰目录结构
设置时间：1-2 小时 影响：防止最常见的智能体错误
级别 2：团队 Harness（小团队）
对于 3-10 个共享代码库的开发者团队：
添加到级别 1：
- 带有团队范围约定的
AGENTS.md - 由 CI 强制执行的架构约束
- 常见任务的共享提示模板
- 由 linter 验证的文档即代码
- 专门针对智能体生成 PR 的代码审查检查清单
设置时间：1-2 天 影响：跨团队一致的智能体行为
级别 3：生产 Harness（工程组织）
对于运行数十个并发智能体的组织：
添加到级别 2：
- 自定义中间件层（循环检测、推理优化）
- 可观测性集成（智能体读取日志和指标）
- 计划运行的熵管理智能体
- Harness 版本控制和 A/B 测试
- 智能体性能监控仪表板
- 智能体卡住时的升级策略
设置时间：1-2 周 影响：智能体作为自主贡献者运作
常见的 Harness 工程错误
1. 过度工程化控制流
"如果你过度工程化控制流，下一次模型更新会破坏你的系统。"
模型改进迅速。2024 年需要复杂管道的能力现在由单个上下文窗口提示处理。构建你的 Harness 以可剥离——当模型变得足够智能不需要时，你应该能够删除"智能"逻辑。
2. 将 Harness 视为静态的
Harness 需要与模型一起演进。当新模型版本改进推理时，你的推理优化中间件可能会适得其反。每次重大模型更新时审查和更新 Harness 组件。
3. 忽略文档层
最有影响力的 Harness 改进通常是最简单的：更好的文档。如果你的 AGENTS.md 含糊不清，你的智能体输出也会含糊不清。投资于精确、机器可读的文档，作为智能体的基础事实。
4. 没有反馈循环
没有反馈的 Harness 是一个笼子，而不是指南。智能体需要知道它何时成功何时失败。内置：
- 任务完成前的自我验证步骤
- 作为智能体工作流一部分的测试执行
- 按任务类型划分的智能体成功率指标
5. 只有人类的文档
如果你的架构决策存在于人们的头脑中或智能体无法访问的 Confluence 页面中，Harness 就有差距。智能体需要的一切都必须在存储库中。
Harness 工程与相关概念
| 概念 | 范围 | 焦点 |
|---|---|---|
| 提示工程 | 单次交互 | 制作有效的提示 |
| 上下文工程 | 模型上下文窗口 | 模型看到什么信息 |
| Harness 工程 | 整个智能体系统 | 环境、约束、反馈、生命周期 |
| 智能体工程 | 智能体架构 | 内部智能体设计和路由 |
| 平台工程 | 基础设施 | 部署、扩展、运营 |
Harness 工程包括上下文工程并借鉴提示工程，但它在更高层次上运作——它是关于使智能体可靠的完整系统，而不仅仅是单次交互的输入。
这对软件工程师意味着什么
工作正在改变
Harness 工程代表了软件工程师工作的真正演变：
| 之前 | 之后 |
|---|---|
| 编写代码 | 设计 AI 编写代码的环境 |
| 调试代码 | 调试智能体行为 |
| 审查代码 | 审查智能体输出 + Harness 有效性 |
| 编写测试 | 设计测试策略 |
| 维护文档 | 构建文档作为机器可读基础设施 |
这并不意味着工程师变得不那么技术。如果说有什么不同的话，Harness 工程需要更深的架构思考——你正在设计必须在没有你持续干预的情况下工作的系统。
重要的技能
基于在 NxCode 构建 AI 驱动产品的所见：
- 系统思维——理解约束、反馈循环和文档如何交互
- 架构设计——定义可强制执行且富有成效的边界
- 规范编写——足够精确地表达意图，让智能体可以执行
- 可观测性——构建揭示智能体行为模式的监控
- 迭代速度——快速测试和完善 Harness 配置
实践经验：什么有效
使用多个智能体系统（Claude Code、Codex、Cursor）构建 AI 驱动的 Web 应用程序。产生最大差异的模式：
- 存储库优先文档：每个架构决策、命名约定和部署过程都在 repo 中。没有任何东西存在于 Slack 或 Google Docs 中。
- 增量约束构建：从基本 linting 开始，随着模式出现添加架构约束，不要尝试预先设计完美的 Harness。
- 智能体特定审查检查清单：AI 生成的代码与人类代码有不同的失败模式。审查过程考虑常见的智能体模式（过度抽象、不必要的错误处理、文档漂移）。
- 多提供商 Harness 设计：Harness 适用于 Claude、GPT 和 Gemini 模型。提供商无关设计意味着可以切换模型而无需重建整个系统。
关键要点
- Harness 工程是新学科——设计使 AI 智能体可靠的系统——约束、反馈循环、文档和生命周期管理
- 模型是商品；Harness 是护城河——LangChain 通过只改变 Harness 从基准前 30 名跃升至前 5 名
- OpenAI 用零人工代码构建了 100 万+行——证明 Harness 工程在生产规模上有效
- 三大支柱：上下文工程、架构约束和熵管理
- 简单开始：一个好的
AGENTS.md和预提交钩子比复杂中间件更有影响力 - 工程师的工作正在演变——从编写代码到设计 AI 编写代码的环境
- 构建可剥离的 Harness——当模型改进时，过度工程化会破裂；保持适应性