Harness 工程：构建 AI 智能体可靠运行的系统指南

OpenAI 的实验是迄今为止最有力的证据：

• 5 个月 的开发周期
• 最终产品包含 100 万 + 行代码
• 零人工编写代码 —— 每一行都由 Codex 智能体生成
• 构建时间约为人工的 1/10
• 该产品拥有 内部日常用户和外部 Alpha 测试者
• 它能 发布、部署、崩溃并被修复 —— 全部由 Harness 内的智能体完成

工程师的工作是什么？设计 Harness。指定意图。提供反馈。而不是写代码。

Harness 工程的三大支柱

OpenAI 的框架将 Harness 工程分为三个核心类别：

1. 上下文工程 (Context Engineering)

上下文工程旨在确保智能体在正确的时间获得正确的信息。

静态上下文：

• 本地代码库文档（架构规范、API 契约、风格指南）
• 编码项目特定规则的 AGENTS.md 或 CLAUDE.md 文件
• 由 Linter 验证的交叉链接设计文档

动态上下文：

• 智能体可访问的可观测性数据（日志、指标、追踪）
• 智能体启动时的目录结构映射
• CI/CD 流水线状态和测试结果

关键原则： 从智能体的角度来看，任何它无法在上下文中访问的内容都不存在。存在于 Google Docs、Slack 频道或人们头脑中的知识对系统是不可见的。代码库必须是唯一的真理来源。

2. 架构约束 (Architectural Constraints)

这是 Harness 工程与传统 AI 提示词（Prompting）区别最大的地方。你不是告诉智能体'写出好的代码'，而是通过机械手段强制规定好代码的模样。

依赖分层：

Types → Config → Repo → Service → Runtime → UI 

每一层只能从其左侧的层导入。这不仅是一个建议——它是由结构化测试和 CI 校验强制执行的。

约束执行工具：

• 确定性 Linter —— 自动标记违规行为的自定义规则
• 基于 LLM 的审计员 —— 审查其他智能体代码是否符合架构合规性的智能体
• 结构测试 —— 类似于 ArchUnit，但针对 AI 生成的代码
• Pre-commit 钩子 —— 在任何代码提交前进行自动检查

为什么约束能提高产出： 矛盾的是，限制解决方案空间会让智能体生产力更高，而不是更低。当智能体可以生成任何东西时，它会浪费 Token 去探索死路。当 Harness 定义了清晰的边界时，智能体能更快地收敛到正确的解决方案。

3. 熵管理 (Entropy Management / "垃圾回收")

这是最容易被忽视的组件。随着时间的推移，AI 生成的代码库会积累熵——文档与现实脱节、命名约定发生偏离、死代码堆积。

Harness 工程通过定期清理智能体来解决这个问题：

• 文档一致性智能体 —— 验证文档是否与当前代码匹配
• 约束违规扫描器 —— 寻找溜过早期检查的代码
• 模式强化智能体 —— 识别并修复偏离既定模式的情况
• 依赖审计员 —— 追踪并解决循环依赖或不必要的依赖

这些智能体按计划运行（每天、每周或由特定事件触发），保持代码库对人类审查者和未来的 AI 智能体都是健康的。

Harness 工程实践：团队如何落地

OpenAI 模式：零人工代码

OpenAI 用于 Harness 工程的团队结构：

Stripe 模式：大规模 Minions

Stripe 的内部编程智能体（被称为 Minions）现在每周产生超过 1,000 个合并的 Pull Request：

1. 开发人员在 Slack 中发布任务
2. Minion 编写代码
3. Minion 通过 CI
4. Minion 开启 PR
5. 人类评审并合并

在步骤 1 和步骤 5 之间没有开发人员交互。Harness 处理了一切——测试执行、CI 校验、风格合规性以及文档更新。

LangChain 模式：中间件优先

LangChain 将其 Harness 结构化为可组合的中间件层：

智能体请求 → LocalContextMiddleware (映射代码库) → LoopDetectionMiddleware (防止重复) → ReasoningSandwichMiddleware (优化计算) → PreCompletionChecklistMiddleware (执行校验) → 智能体响应 

每个中间件层增加了一项特定能力，而无需修改核心智能体逻辑。这种模块化方法使得 Harness 可测试且可进化。

构建你的第一个 Harness：实用框架

1 级：基础 Harness（个人开发者）

如果你在个人项目中使用 Claude Code、Cursor 或 Codex：

设置内容：

• 包含项目约定的 CLAUDE.md 或 .cursorrules 文件
• 用于 Linting 和格式化的 Pre-commit 钩子
• 智能体可以运行以进行自验证的测试套件
• 具有一致命名的清晰目录结构

设置时间： 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 时要保持 可剥离性（Rippable） —— 当模型变得足够聪明而不再需要时，你应该能够移除那些'聪明'的逻辑。

2. 将 Harness 视为静态的

Harness 需要随模型一起进化。当新模型版本提高了推理能力时，你的推理优化中间件可能会适得其反。每次重大模型更新后，都要检查并更新 Harness 组件。

3. 忽视文档层

最具影响力的 Harness 改进往往是最简单的：更好的文档。如果你的 AGENTS.md 模糊不清，智能体的产出也会模糊不清。投入精力编写精确的、机器可读的文档，将其作为智能体的真理来源。

4. 缺乏反馈回路

没有反馈的 Harness 是笼子，而不是引导。智能体需要知道它什么时候成功，什么时候失败。内置：

• 任务完成前的自验证步骤
• 作为智能体工作流一部分的测试执行
• 按任务类型统计的智能体成功率指标

5. 仅限人类阅读的文档

如果你的架构决策只存在于人们的头脑中，或者存在于智能体无法访问的 Confluence 页面上，那么 Harness 就会出现缺口。智能体需要的一切都必须在代码库中。

Harness 工程 vs 相关概念

Harness 工程包含上下文工程，并借鉴了提示工程，但它运行在更高的维度——它关乎使智能体可靠的完整系统，而不仅仅是单次交互的输入。

这对软件工程师意味着什么

工作内容正在改变

Harness 工程代表了软件工程师职责的一次真正演变：

这并不意味着工程师的技术含量降低了。如果说有什么不同的话，那就是 Harness 工程需要更深层次的架构思考——你正在设计即使没有你持续干预也必须运行的系统。

核心技能

根据我们在构建 AI 驱动产品时的观察：

1. 系统思维 —— 理解约束、反馈回路和文档如何相互作用
2. 架构设计 —— 定义可执行且高效的边界
3. 规范编写 —— 精确表达意图，以便智能体执行
4. 可观测性 —— 构建能揭示智能体行为模式的监控
5. 迭代速度 —— 快速测试和改进 Harness 配置

我们的经验：什么在实践中奏效

我们一直在使用多种智能体系统（Claude Code、Codex、Cursor）构建 AI 驱动的 Web 应用程序。对我们影响最大的模式包括：

• 代码库优先的文档：每个架构决策、命名约定和部署流程都在代码库中。Slack 或 Google Docs 中不留存任何信息。
• 增量式约束构建：从基础 Linting 开始，随着模式的出现增加架构约束，不要试图预先设计完美的 Harness。
• 智能体特定的评审清单：AI 生成的代码与人工代码有不同的失败模式。我们的评审流程考虑了常见的智能体模式（过度抽象、不必要的错误处理、文档漂移）。
• 多供应商 Harness 设计：我们的 Harness 兼容 Claude、GPT 和 Gemini 模型。供应商无关的设计意味着我们可以切换模型而无需重建整个系统。

核心要点

1. Harness 工程是一门新学科，旨在设计使 AI 智能体可靠的系统——包含约束、反馈回路、文档和生命周期管理。
2. 模型是商品；Harness 是护城河 —— LangChain 仅通过改变 Harness 就让基准测试排名从前 30 跃升至前 5。
3. OpenAI 在零人工代码的情况下构建了 100 万行代码 —— 证明了 Harness 工程在生产规模下是可行的。
4. 三大支柱：上下文工程、架构约束和熵管理。
5. 从简单开始：一个好的 AGENTS.md 和 Pre-commit 钩子比复杂的中间件更有影响力。
6. 工程师的角色正在演变 —— 从编写代码转变为设计 AI 编写代码的环境。
7. 构建可剥离的 Harness —— 过度工程化会在模型改进时失效；保持其适应性。