OpenAI 纯靠 Agent 写出百万行代码的秘密：Harness 工程五大原则

最近”Harness”这个词越来越频繁地出现。OpenAI 发布的一篇博客终于为这个概念下了清晰的定义。在 Agent 时代，工程师到底该做什么？我们来梳理一下。

Harness（线束/工具壳）是让 AI Agent 能够影响现实世界的工具外壳。如果推理模型是大脑，那 Harness 就是手脚。读取文件、修改代码、运行测试、部署上线, , 所有操作都发生在 Harness 内部。

OpenAI 内部团队从 2025 年 8 月底一个空仓库起步，纯靠 Codex Agent 构建了一个百万行的新产品。条件是：不允许人类手写代码。据报告，耗时仅为手工开发的十分之一。他们在此过程中总结出以下五条原则。

Agent 看不到的知识等于不存在

对 Codex 而言，运行时无法访问的信息就等于不存在。Google Docs 里的需求文档、Slack 中达成的架构共识、某个人脑子里的隐性知识, , 全都看不见。这和三个月后入职的新人面临的处境完全一样。

因此团队将所有决策推入仓库中的 Markdown 文档、Schema 和执行计划（ExecPlan）。

• ExecPlan 是在 PLANS.md 中定义的自包含设计文档
• 通过标准：新手读完后能独立完成实现
• 存在 Codex 单次 Prompt 连续工作超过 7 小时的案例
• 将 matklad 的 ARCHITECTURE.md 理念扩展到 Agent 场景

不要说”再努力一点”，要问”缺了什么能力”

早期 Agent 的速度低于预期。原因不在模型能力，而在环境准备不足。每次失败时，团队都会问：“缺少了什么能力？怎样才能让 Agent 可读取、可验证？”

• 用自研的并发 Helper 替代外部库，与 OpenTelemetry 100% 集成
• 业界常说的”无聊技术”反而对 Agent 更有利（API 稳定性高，训练数据表示度高）

机械化强制而非文档来保证代码一致性

仅靠文档无法维持 Agent 生成代码库的一致性。于是团队选择了只机械化强制不变规则、而非事无巨细地指导实现。他们要求在数据边界必须做解析，但把库的选择权留给了 Agent。架构固定为分层领域结构，依赖方向由 Linter 验证。

• 每个业务领域固定层级：Providers → Service → Runtime → UI
• Types、Config、Repo 作为底层共享的横切关注点
• 自定义 Linter 和结构测试在违规时立即中断构建
• Linter 本身也由 Codex 编写

给 Agent 装上眼睛，它能独自工作 6 小时

团队将 Chrome DevTools Protocol 接入 Agent 运行时，为 Codex 提供 DOM 快照、截图和导航能力。结构是：对比任务前后的快照、观察运行时事件、然后在循环中不断修复直到一切正常。

可观测性工具也以相同方式接入。每个 git worktree 会启动一个临时观测栈，工作结束后自动销毁。

• 通过 Victoria Logs（LogQL）和 Victoria Metrics（PromQL），Agent 可直接查询日志和指标
• “让服务启动时间控制在 800ms 以内”这样的 Prompt 变得可执行
• 单次 Codex 运行专注于一个任务超过 6 小时的情况被定期观测到

给地图，别给千页手册

上下文管理决定了 Agent 的效能。一开始团队尝试把所有内容塞进一个巨大的 AGENTS.md，结果失败了。matklad 在 2021 年写的 ARCHITECTURE.md 理念在这里大放异彩。原则是：简短鸟瞰项目整体结构，只收录不常变化的内容。对 Agent 同样适用。

• ARCHITECTURE.md 是代码地图，不是代码图集
• 架构不变规则往往以”某样东西不存在”的形式来表达
• 明确声明边界（boundary），就能约束后续所有实现

尚未解答的问题

即便是 Codex 团队，也有尚未解答的问题。纯靠 Agent 构建的系统能否在数年内保持架构一致性，没有人知道。模型持续进化后，这套体系本身会如何变化，也是未知数。

有一点是明确的：写好代码的时代正在落幕，设计好环境的时代已经开始。