Design for AI, Not AI for Design
副标题：读 OpenAI《Harness Engineering》后的工程笔记
OpenAI 在 2026 年 2 月 11 日发布的《Harness Engineering》，我觉得最值得读的地方，不是“AI 又能写多少代码”，而是它把一个更底层的工程变化说清楚了。文章讲的是一个内部 beta 产品：五个月，从空仓库起步，接近一百万行代码，大约 1500 个 PR，内部已经有日活用户，也有外部 alpha 测试者。更重要的是，它们把约束定得很死: 人不手写代码，所有代码都由 Codex 生成，包括应用逻辑、测试、CI 配置、文档、可观测性配置和内部工具。
这个约束听起来有点极端，但也正因为极端，很多平时能靠人肉补过去的问题都被暴露出来了。原文里有一句话我觉得可以当整篇文章的总纲: Humans steer. Agents execute. 工程师没有消失，只是从“直接写代码”转向了“设计环境、表达意图、搭建反馈回路，让 agent 能稳定工作”。
先说结论：这篇博客真正重要的结论，不是 agent 能替代多少编码劳动，而是当代码生成变便宜之后，真正稀缺的资源会变成人的时间和注意力。谁能把仓库、工具、验证、知识和规则设计得对 agent 更可读，谁就更有可能把吞吐变成可靠性，而不是把混乱放大。
图 1：变化的重点不只是“谁在写代码”，而是工程重心从手写实现转向环境、约束和反馈系统。
Agent环境
原文开头其实已经把实验边界说得很具体了。第一，仓库是空的，第一笔提交发生在 2025 年 8 月下旬。第二，初始脚手架也不是人写的，而是用 Codex CLI 配合 GPT-5，从一小组现成模板生成出来的，包括仓库结构、CI 配置、格式化规则、包管理器设置、应用框架，甚至最初的 AGENTS.md。第三，这不是“为了演示而演示”的代码生成实验，因为这个产品后来真的被几百个内部用户使用，其中包括日常重度用户。
这些细节决定了文章的重点不是“模型会不会写 CRUD”，而是“如果默认执行者是 agent，工程环境应该长什么样”。OpenAI 的经验很明确: 早期进展比预期慢，不是因为 Codex 不会写，而是因为环境定义得不够充分。agent 缺工具，缺抽象，缺内部结构，所以无法朝着高层目标稳定推进。
这也是我读完后最认同的一点。过去我们说“工程环境”，常常是在讲 IDE、包管理、构建系统和部署脚本；但在 agent-first 的开发方式里，环境更像一整套可执行工作条件。它要回答的不是“人能不能舒服地写代码”，而是“agent 能不能自己拿到上下文、自己验证结果、自己知道边界在哪里”。原文把这个变化说得很直白: 团队的主要工作不再是写代码，而是设计环境、指定意图、构建反馈回路。
Agent如何闭环？
原文里“闭环”不是抽象说法，而是很具体的工程能力。随着代码吞吐上升，OpenAI 团队的瓶颈很快从“能不能产出代码”变成了“人类 QA 能不能跟上”。因为真正固定不变的稀缺资源，是人的时间和注意力。
所以他们做的事不是继续优化 prompt，而是把应用本身变得对 Codex 可见。比如，他们让应用支持按 git worktree 启动。这个机制可以理解成“给每次改动分一个独立工作副本”，这样 agent 改代码时能在隔离实例里把应用跑起来，不会互相干扰。又比如，他们把 Chrome 开发者工具协议接进运行环境，再配上处理页面结构、截图和导航的技能。这样 agent 就不只是“改了前端代码”，而是真的能自己点开页面、复现 bug、验证修复、判断界面行为是否符合预期。
同样的思路也被用在可观测性上。原文明确提到，日志、指标和调用链追踪都会通过一套只服务于当前任务的本地观测环境暴露给 Codex，任务结束后再一起销毁。文中提到了几种查询语言，但核心意思并不复杂: agent 不只是能看“报错了没有”，而是能主动查日志、看性能指标、顺着一次请求的调用链找到慢点和错点。这一步很关键，因为它把很多以前只能靠人来判定的要求，变成了 agent 可以自己验证的问题。比如“服务启动必须在 800ms 以内”，或者“这四条关键用户路径上不能有任何一步超过两秒”。
文章里还有一个很有分量的细节：单次 Codex run 经常会在一个任务上连续工作六个小时以上，而且很多时候人已经去睡觉了。这个细节不是在夸模型勤奋，而是在说明一件事: 只有当闭环能力足够完整，长时任务才有意义。否则长时间运行只是在更长时间里持续瞎猜。
图 2：在 agent-first 环境里，反馈回路不是附属品，而是让长时任务成立的前提。
agent如何发现知识
原文在这一节里讲得非常清楚: 给 Codex 一张地图，而不是一本 1000 页说明书。这个说法比“多写文档”准确得多。问题不是文档多不多，而是知识有没有被组织成 agent 能导航、能校验、能持续维护的结构。
OpenAI 试过“大一统 AGENTS.md”的方案，结论是失败，而且失败方式很典型。上下文本来就是稀缺资源，一个巨大的指令文件会把任务本身、代码本身和真正相关的文档一起挤出去。信息一旦太多，就会变成没有信息。更糟的是，这种总纲式文件很容易快速腐烂，而且很难做机械校验，无法检查覆盖度、时效性、负责人和交叉链接，最后就会漂。
所以他们把 AGENTS.md 从“百科全书”降成了“目录”。原文提到，那个文件大约只有 100 行，主要作用是作为注入上下文时的入口索引。真正的知识系统在结构化的 docs/ 目录里，而且它被明确当成仓库内的主记录源，也就是“以仓库里的版本化文档为准”。文中给了一个知识库布局示例，但没必要把名字全背下来。你只要抓住它的分工就够了: 设计文档有单独目录，执行计划有单独目录，产品规格、自动生成的参考资料和一些顶层规则文档都各归其位。
这几个点在我看来特别有价值。第一，设计文档不是堆在一起，而是有索引、有验证状态，也有一组明确原则。第二，计划被当成一等产物。小改动用轻量计划，复杂任务就写成版本化的执行计划，把进度和决策日志一起签进仓库。第三，技术债本身也是版本化知识，不再只是团队脑子里的“以后再说”。
原文还强调了一件很容易被忽略的事: 这些文档不是靠自觉维护，而是靠机械校验维护。专门的 linter 和 CI 任务会检查知识库是否最新、是否交叉链接、结构是否正确；另外还有一个周期性运行的“文档整理 agent”，专门扫描已经过时或与真实代码行为不一致的文档，然后发修复 PR。这个做法很工程化，也很关键，因为 agent 时代过期文档的危害，通常比“没有文档”更大。
图 3：知识系统的重点不是“写很多文档”，而是让知识在仓库里成为可导航、可验证、可维护的系统。
工程品味如何传达给agent
我上次写这一节时，用了“把建议升级成法律”这种说法，意思没错，但还是不够精确。原文这里更强调的其实不是抽象的“风格”，而是那些能被机械执行的约束: 不变量、清晰边界、可预测结构。
OpenAI 的做法不是去微观规定每个实现细节，而是先把不会轻易变的东西钉死。文章举的例子是“在边界处解析数据形状”。意思是，外部数据一旦进入系统，就要先把结构说明白、校验清楚，别让模糊的数据一路流进核心逻辑。他们要求 Codex 守住这条规则，但不规定一定要用哪一个具体库。这种做法很重要，因为它区分了“必须守住的约束”和“可以局部自由发挥的实现”。
真正的骨架是一套很刚性的分层架构。原文明确写了每个业务域里的依赖方向: Types → Config → Repo → Service → Runtime → UI。翻成普通话，大致可以理解成: 类型定义在最前面，配置其次，数据访问再往后，之后是服务逻辑、运行时适配，最后才是界面层。跨领域的公共能力，比如认证、连接器、遥测和功能开关，不允许随意渗透，而是通过一个明确入口进入。除此之外的依赖边，一律不允许。
这些规则不是靠 code review 口头提醒维持的，而是通过自定义 linter 和结构测试机械执行。这里术语要分清: linter 更像一类检查器，用来守住架构边界和依赖方向；lint 则是某一条具体规则，比如结构化日志、类型命名、文件大小限制、平台可靠性要求。原文还提到一个很实用的做法: 因为这些规则是团队自己写的，所以报错信息也能自己定义，直接把修复建议写进错误信息里，让 agent 在失败时知道下一步怎么改。
这一节我觉得最有分量的一句话是: 在 human-first 工作流里，这些规则可能显得有点吹毛求疵；但对 agent 来说，它们是乘数。规则一旦编码，影响就会同时作用在整个仓库，而不是一次次靠人去重复讲。
图 4：对 agent 来说，真正有用的“品味”不是抽象偏好，而是被编码进 linter、lint 和结构测试里的约束。
AGENT工作流程
原文把工程师角色改写得很具体，不只是“人负责高层、agent 负责执行”这么一句话。更接近真实情况的是，工程师先用 prompt 把任务讲清楚，让 agent 去做第一版实现并开 PR。到这里工作其实只完成了一半，后面的流程才是重点。
原文里这条工作流大致是这样跑的。第一步，agent 在本地自审，先自己检查改动是否符合仓库规则。第二步，它会主动拉起额外的 agent review，有的在本地跑，有的在云端跑，相当于再加几层自动审查。第三步，收到反馈后，它要自己回评论、自己继续改，而不是每轮都等人重新接手。第四步，如果构建失败、测试失败或者 review 又提出了新问题，它就继续迭代，直到这轮审查通过。原文甚至把这个过程起了个内部玩笑式名字，但核心并不在名字，而在这是一条“生成 - 自审 - 互审 - 修正 - 再验证”的闭环链路。
这里还有两个很关键的技术细节。第一，Codex 直接使用标准开发工具取上下文，包括 gh、本地脚本和仓库内置技能，而不是等人把外部信息手动复制进命令行。第二，人类可以 review，但不是每次都必须亲自下场；随着流程成熟，他们把越来越多的审查工作推向了 agent 之间互相处理。
这也直接带来了合并策略的变化。原文用了一个很明确的小节标题: 吞吐会改变合并哲学。当 Codex 的吞吐远远超过人的注意力时，很多传统工程规范会开始变得适得其反。它们仓库的做法是尽量减少阻塞式合并门槛，PR 尽量短命，偶发的测试抖动通常通过后续 run 修掉，而不是无限期卡在那儿。背后的逻辑很直接: 在高吞吐环境里，修正很便宜，等待很昂贵。
当然，原文也没有把这件事写成普适真理。它明确说，这种做法放在低吞吐环境里会是不负责任的；在他们这个前提下，才经常是对的 trade-off。这个限定很重要，因为它说明 merge 策略不是孤立方法，而是建立在前面那整套工具、约束和反馈系统上的。
图 5：吞吐变高之后，很多团队真正昂贵的成本会从“修正”转向“等待”。
ai自主性可以到哪一步
原文没有把“自主性”讲成一个模糊口号，而是列出了一组已经能端到端完成的具体动作。随着测试、验证、review、反馈处理和恢复流程越来越多地被编码进系统，仓库最近跨过了一个门槛: 给定一个 prompt，Codex 已经可以验证当前代码状态、复现 bug、录一段失败视频、实现修复、驱动应用验证结果、再录一段修复后视频、打开 PR、响应 agent 和人工反馈、修掉构建失败、只在需要判断时升级给人，最后自己合并。
这份清单很重要，因为它把“agent-generated”这个词从“会写很多代码”扩展成了“能完成开发生命周期里一整串动作”。原文甚至专门有一节解释这个词的边界: 所谓 agent-generated，不只是产品代码和测试，还包括 CI 配置、发布工具、内部开发者工具、文档和设计历史、评测用的验证框架、review 评论与回复、管理仓库本身的脚本，以及生产仪表盘的定义文件。
但原文同样留了刹车。它明确说，这种自主行为高度依赖这一个仓库的结构和工具链，不应假定可以在没有类似投入的团队里自然复现。换句话说，自主性不是模型单方面长出来的，而是工程系统一点点“喂”出来的。
如何控制agent的代码熵？
这一节基本是在回答一个很现实的问题: 如果 agent 会复制仓库里已经存在的模式，那它也会复制坏模式。原文说得很直接，full agent autonomy 会带来新的问题，Codex 会复用库里那些不均匀、次优甚至有点脏的做法，时间一长就会 drift。
OpenAI 一开始是靠人清理的。团队过去每周五都要花一整天，也就是一周 20% 的时间，去收拾所谓的 “AI slop”。这个数字很有说服力，因为它说明问题不是抽象的审美焦虑，而是实打实的产能损耗。后来他们把做法换掉了: 把一组 “golden principles” 编进仓库，再建立一个周期性清理流程。
原文举了两个例子。第一，尽量使用共享工具包，而不是到处手搓 helper，把那些不该变的规则收在中心位置。第二，不允许用“先猜再说”的方式试探数据结构，要么在边界验证，要么依赖带类型的 SDK，避免 agent 在猜出来的结构上继续搭代码。然后，他们再跑一组后台 Codex 任务，定期扫描偏离、更新质量评分、发针对性的重构 PR。这些 PR 大多数能在一分钟内看完，并自动合并。
原文把这套机制类比成 garbage collection，我觉得这个类比非常准确。技术债像高利贷，持续小额偿还，通常比拖到最后一起爆掉更划算。尤其在 agent-first 的代码库里，人的“品味”不能只体现在 review 评论里，而要尽可能被记录一次、执行无数次。
图 6：agent 会放大仓库里已经存在的模式，所以清理机制必须和生成机制一样常态化。
对于个人开发者
对个人开发者来说，这篇文章并不意味着“你也要先砸一整套 OpenAI 级别的平台基础设施”。更有启发的是它的顺序感。先让 agent 看得见，再让 agent 做得快；先把知识放进仓库，再谈让它自主；先把约束编码，再谈提高吞吐。
如果要落到手上能做的事，我觉得至少有四件值得先做。第一，给 agent 一个最小但完整的验证回路，哪怕只是本地可启动、能跑测试、能看日志、能做基础页面检查。第二，不要把 AGENTS.md 写成总手册，把它写成入口目录，然后把规范、计划、架构说明和技术债记录真正沉进仓库。第三，尽早把最关键的不变量写成 linter、具体 lint 规则、结构测试或 CI 规则，不要全靠 review 习惯维持。第四，把清理当成常规任务，而不是“项目后期再收拾”。
我现在更愿意把这篇文章的题目读成一句工程建议，而不是一句口号。Design for AI, not AI for design。重点不是“让 AI 进入设计流程”，而是先把你的工程系统整理成一种 agent 能理解、能验证、能维护的形态。原文真正讨论的，也一直是这个方向。
延伸阅读
部分信息可能已经过时