Harness Engineering 与 Codex 生产实践

核心内容#

这条 archive 卡片记录的是一篇我觉得非常重要的工程实践文章：

OpenAI 官方文章：https://openai.com/zh-Hans-CN/index/harness-engineering/ ↗
Gemini 辅助精读总结：https://gemini.google.com/share/e447cc0560fa ↗

它最有价值的地方，不是“Codex 会写代码”这件事本身，而是：

当团队决定不手写代码，而是让智能体生成几乎全部实现时，软件工程的重点会如何迁移？

文章给出的答案非常清楚：

人类不再主要负责写代码
人类负责设计环境、边界、反馈回路和知识系统
智能体负责执行
软件工程的纪律，从“如何写代码”转移到了“如何设计让智能体可靠工作的系统”

这是我觉得最值得反复记的一点。

要点整理#

1. 核心口号不是 AI 替代人，而是“Humans steer, agents execute”#

这篇文章里最重要的一句话，其实可以概括为：

人类掌舵，智能体执行。

OpenAI 团队做的是一场极端实验：

从空仓库开始
几乎所有代码都由 Codex 生成
包括：
- 应用逻辑
- 测试
- CI 配置
- 文档
- 可观测性定义
- 内部工具
人类不直接写代码，而是通过提示、审核、设计约束和系统建设来驱动产出

文章里提到，三名工程师起步，后来扩展到七名工程师，在大约五个月里做出一个接近 100 万行代码 的真实产品，打开并合并了约 1500 个 PR。

所以这篇文章讨论的已经不是“AI 能不能写个 demo”，而是：

生产级项目
持续部署
故障与修复
真实用户
智能体优先的软件工程组织方式

2. 真正的瓶颈不再是写代码，而是环境设计#

文章一个很强的观察是：

早期进展慢，不是因为 Codex 不会写代码，而是因为：

环境不够明确
工具不够全
结构不够清晰
反馈回路不够直接

换句话说，问题不是模型不会，而是系统没有让模型可靠地会。

所以工程师的新职责变成了：

让目标可分解
让上下文可读
让规则可执行
让结果可验证

一旦项目卡住，解决思路不再是“我手工去补这个功能”，而是：

智能体现在缺的到底是什么能力？这个能力能不能被显式地加入到系统里？

3. 代码仓库必须变成“智能体真正能读取的知识库”#

这是文章里我最认同的一部分。

对智能体来说，仓库之外的知识基本等于不存在：

Slack 讨论
人脑里的隐性经验
Google Docs 里的口头共识

如果没有进入仓库，没有被版本化，没有被结构化地组织出来，它就不会稳定进入智能体的运行情境。

所以他们最后的做法不是维护一个巨大的 AGENTS.md，而是：

用一个简短的 AGENTS.md 当地图
把真正的知识放在结构化的 docs/ 里
让文档成为 record system
通过 lint / CI / doc-gardening agent 持续清理和更新文档

这背后的理念很强：

给智能体的是地图，不是一本 1000 页的说明书。

我觉得这对任何 agent-first repo 都是特别重要的经验。

4. 要为了“智能体可读性”而设计系统#

传统软件工程讲的是 human readability。文章强调的是另一层：

agent readability

也就是：

代码仓库能不能让智能体快速定位知识
UI 能不能被智能体读懂
日志 / metrics / traces 能不能直接进推理闭环
智能体能不能自己复现 bug、验证修复、收集反馈

OpenAI 团队做了几件非常关键的事：

a. 让 Codex 能直接读 UI#

接 Chrome DevTools 协议
能看 DOM 快照
能看截图
能导航和验证 UI

b. 让 Codex 能直接读可观测性#

日志可查询
metrics 可查询
traces 可查询
每个 worktree 对应临时、隔离的可观测性环境

c. 让 Codex 能在 worktree 里自助调试#

每次改动可以起独立实例
复现 bug
验证修复
录制前后对比视频

这一点我觉得特别重要，因为它说明：

智能体真正的能力上限，往往由可观察、可验证、可操控的系统边界决定。

5. 架构边界必须机械化，而不是靠人记住#

文章反复强调：

不能只靠“团队约定”
必须把边界写进 linter、结构测试、CI 规则里

他们采用的是非常强的分层架构：

Types -> Config -> Repo -> Service -> Runtime -> UI

再加上统一的 Providers 入口来处理横切关注点，比如：

auth
telemetry
connectors
feature flags

关键点在于：

允许智能体在局部实现上自由发挥
但在边界和依赖方向上零容忍

这其实很像：

对系统结构极端严格，对具体表达方式适度放权。

我觉得这就是 agent-first 时代很合理的工程纪律。

6. Lint / 规则 / “黄金原则”在智能体时代价值更大#

在人类主导开发时，很多规范会显得有点繁琐。
但在智能体主导开发时，这些规范反而变成倍增器。

因为：

一旦规则明确
智能体就能持续、规模化地遵守
并且可以在所有 PR 中一致执行

文中提到他们会把很多“品味判断”机械化，比如：

命名规范
文件大小限制
结构化日志规则
边界验证原则
避免 YOLO 式探测数据

这些被他们总结成一类更主观但可执行的“黄金原则”。

我非常认同这一点，因为这其实是在做：

把人的品味沉淀成机器可持续执行的系统约束。

7. 在高吞吐量智能体环境里，“等待”比“犯错”更贵#

这篇文章里还有一个很反直觉但很真实的观点：

在智能体吞吐量非常高时：

出错后修复的成本变低
等待人工阻塞的成本反而更高

所以他们减少了很多传统的人为阻塞合并门槛。
短生命周期 PR、快速修补、持续 refactor，可能比过度追求一次合并零缺陷更合理。

这不是说质量不重要，而是说：

在 agent-heavy workflow 里，质量控制应该更多通过自动化反馈回路来做，而不是靠人肉 gatekeeping 卡死流速。

8. “AI 残渣”是真问题，必须持续垃圾回收#

这个表达我觉得特别形象：

完全让智能体写代码，会不断产生模式漂移和“AI sludge”
如果不处理，代码库会慢慢熵增

他们最开始每周五花 20% 时间手工清理，这显然不可扩展。
于是他们把这件事也系统化：

定期跑后台 Codex 任务
扫描偏差
更新质量等级
自动发小型重构 PR

这像垃圾回收一样持续运作。

这个思路很值得记：

技术债不是等到最后统一还，而是像缴高息贷款一样，持续小额偿还。

当前理解 / 结论#

我对这篇文章的核心判断是：

它不是一篇“AI 编程更快”的宣传文#

它真正讨论的是：

agent-first repo 应该长什么样
未来工程师的杠杆点在哪
软件工程的纪律应该被放到哪里

最重要的迁移是：从 code craftsmanship 转向 systems craftsmanship#

过去强调：

怎样手写更好的代码

现在更重要的是：

怎样设计更好的环境
怎样让上下文对智能体可读
怎样让反馈闭环自动化
怎样把边界和品味变成可执行系统

对我最有启发的三个关键词#

Map, not manual
- 给智能体的是地图，不是冗长手册
Agent readability
- 一切都要考虑智能体是否能直接推理和验证
Harness engineering
- 工程重点从写实现，转到搭建支撑智能体高效工作的 harness

对实际工作的启发#

如果把这篇文章转成更实际的工作建议，我觉得最有用的是：

1. 仓库要变成真实知识系统#

关键共识必须入仓库
文档要结构化
AGENTS.md 要短、稳、像地图

2. 让智能体直接看到 UI 和 observability#

截图
DOM
日志
指标
traces

这些不是“高级加分项”，而是 agent workflow 的核心基础设施。

3. 把边界和品味写成代码#

lint
CI
structural tests
golden rules

能自动化的，就不要靠人脑记。

4. 持续做 doc gardening 和 AI sludge cleanup#

文档会腐烂
模式会漂移
必须持续清理

5. 人类最稀缺的资源变成注意力#

文章里一个底层逻辑非常对：

未来最稀缺的不是代码产能，而是人类的时间、注意力和判断力。

待补充#

后面值得继续补的方向：

如何把这种工作流迁移到更小团队 / 个人项目
执行计划（exec plans）在 agent 工作流里的具体写法
doc gardening / repo linting / quality drift 的自动化设计
PR 生命周期缩短后，质量体系如何重新设计
这种模式对前端项目、全栈项目、基础设施项目分别意味着什么