Harness Engineering：OpenAI 智能体工程总结

[!abstract] 这篇文章真正讨论的重点，不是“AI 会不会写代码”，而是“怎样搭建一个让智能体持续稳定地产出代码、测试、文档与修复的工程系统”。

[!note] 这是一份基于原文的整理版总结，偏重方法论提炼，不是逐段直译。

标题怎么理解

Harness Engineering 如果直译并不自然。结合全文语境，我更倾向把它理解为：

  • 面向智能体的工程编排
  • 为智能体设计工作环境、约束和反馈回路的工程实践

也就是说，重点已经不只是“让模型写代码”，而是让它在一个可读、可测、可验证、可修复的系统里持续工作。

一句话总结

OpenAI 用一个很小的工程团队，在几个月内做出了一个已经有真实用户使用的内部产品；在这个过程中，人类几乎不直接写代码，而是把主要精力放在搭建代码仓库结构、文档体系、工具链、架构约束、可观测性和自动反馈回路上，让 Codex 能稳定地产生、验证、修复并合并变更。

文章的核心信息

1. 人类从“写代码”转向“设计系统”

文章里最关键的一句话可以概括为：人类掌舵，智能体执行。

工程师的主要职责不再是亲手补实现，而是：

  • 把目标拆成智能体能完成的任务
  • 提供足够清晰的上下文和约束
  • 设计反馈回路，让智能体自己发现问题并修复

当智能体做不好一件事时，重点不是“再提示一次”，而是追问：是不是缺工具、缺文档、缺规则、缺可观察性。

2. AGENTS.md 应该是地图，不该是百科全书

他们早期试过写一个超大的 AGENTS.md，结果失败了。原因很直接：

  • 上下文窗口是稀缺资源
  • 规则太多以后，模型会丢失重点
  • 大而全的说明很快就会过期
  • 单文件很难机械检查和持续维护

所以更好的做法是：

  • 用简短的 AGENTS.md 充当导航地图
  • 把真正的知识沉淀到结构化的 docs/ 中
  • 给设计文档、执行计划、产品规格、架构说明和质量评分做索引

这本质上是在做渐进式披露：先给入口，再按需深入，而不是一次性把所有东西塞给模型。

3. 代码仓库要成为唯一可信的记录系统

对智能体来说，拿不到上下文就等于不存在。

所以那些只存在于聊天记录、口头讨论、Google Docs 或人脑里的决策，实际上都无法被智能体可靠地复用。文章强调，应该把越来越多的重要上下文沉淀回仓库，包括：

  • 架构原则
  • 产品约束
  • 设计决策
  • 执行计划
  • 技术债状态
  • 代码质量标准

这样智能体才能基于版本化的、可检索的材料持续工作。

4. 不只是代码要可读，应用本身也要对智能体可读

他们做了很多“让智能体自己看得见系统状态”的建设，比如：

  • 支持基于 git worktree 启动独立应用实例
  • 把浏览器调试能力接入智能体运行时
  • 提供 DOM 快照、截图、导航等能力
  • 把日志、指标、链路追踪也暴露给智能体查询

这样智能体就不只是“改代码”，还可以：

  • 复现问题
  • 观察 UI 行为
  • 验证修复结果
  • 根据日志和指标判断性能是否达标

这让我觉得很重要的一点是：真正高杠杆的地方，不是让模型会写更多代码，而是让模型能自己闭环验证。

5. 架构约束要靠机械规则强制执行

他们没有靠“大家自觉保持风格一致”，而是尽量把不变量写进工具里：

  • 固定的分层架构
  • 明确的依赖方向
  • 自定义 lint
  • 结构测试
  • 命名约定
  • 文件大小限制
  • 日志和可靠性约束

文章强调的不是“微观管理实现细节”，而是“把边界条件写死”。一旦边界清楚了，智能体在边界内反而可以高效率发挥。

6. 高吞吐量下，合并策略会变化

在一个智能体产能远大于人类注意力的系统里，等待的成本会变得很高，修正错误的成本反而更低。

所以他们会倾向于：

  • 保持 Pull Request 生命周期很短
  • 不让偶发测试失败长期阻塞合并
  • 通过后续重跑或补丁修正问题

这个思路并不适合所有团队，但它说明了一件事：当生产方式改变后，很多以前默认正确的工程习惯也要重新审视。

7. 熵会积累，所以要有“垃圾回收”机制

完全由智能体生成的代码库一样会漂移，也会长出“AI 残渣”。

他们后来的做法是：

  • 把黄金原则写成可执行规则
  • 定期跑后台智能体任务扫描偏差
  • 自动发起清理和重构 PR
  • 持续更新质量评分和技术债状态

这有点像给代码仓库做垃圾回收。与其等问题积累到很痛苦再处理，不如让系统每天都做一点小修小补。

我认为最值得借鉴的几点

如果把这篇文章压缩成几个适合落地的动作，我会记这几条：

  1. AGENTS.md 保持短小，把它当导航页，不要当百科全书。
  2. 重要决策尽量回写到仓库里，不要只停留在聊天记录里。
  3. 给智能体可读的运行环境，而不是只给它源码。
  4. 用 lint、结构测试和脚本固化团队共识，不要只靠口头规范。
  5. 把“清理 AI 生成垃圾”变成持续自动化任务，而不是每周集中人工打扫。

对我自己的一个提醒

这篇文章最有价值的地方，是把“提示词工程”往前推进了一层。

真正决定智能体产出的，不只是单次提示，而是整个执行环境：

  • 仓库结构清不清楚
  • 文档是不是最新
  • 规则能不能自动验证
  • 应用是否可观测
  • 智能体能不能自己复现和验收

如果这些基础设施没有搭起来，再强的模型也只能在混乱环境里碰运气。

相关笔记

  • [[Agent/Agent 开发]]
  • [[Agent/上下文管理]]

原文