把 Harness Engineering 放进 Agent Coding 场景后,需求文档、任务拆解、确定性校验和交接模板会一起影响项目推进方式。这篇按项目阶段整理一套更容易复用的组织方法。
如果只从个人实践去理解 Harness Engineering,这套方法很容易被写成“怎么和模型聊天更有效”。OpenAI 在 2026 年 2 月 11 日那篇工程文章里给了一个更完整的口径。他们讲的重点不是提示词技巧,而是当一个项目从零开始、主要代码都交给 Codex 产出以后,工程团队到底要把精力放在哪里。
文章里最醒目的信息,是他们真的用一支很小的团队,把一个从空 Git 仓库起步的内部产品一路做到了百万行代码规模,而且坚持不手写代码。人类仍然在掌舵,但主要工作已经从“直接写实现”转向“设计环境、写清意图、补工具、建反馈回路”。如果把这件事翻译成更容易执行的话,Harness Engineering 处理的其实不是某一轮问答,而是整个项目如何为 Agent 准备工作环境。
这篇官方文章里最值得吸收的一点,是 OpenAI 不再把 AGENTS.md 当成一本塞满规则的大手册,而是把它压到很短,只保留目录和入口作用。真正的知识放进仓库里的 docs/、架构文档、执行计划、产品规格、技术债追踪和生成出来的 schema 文档里,全部走版本控制。这样一来,Agent 拿到的不是一坨超长说明书,而是一张清楚的地图,知道自己下一步该去哪找信息。
这个思路很适合改写到普通项目里。很多团队现在的问题不是没有信息,而是信息散在聊天记录、Google Docs、飞书文档和人脑里。人能靠经验补齐,Agent 不能。对 Agent 来说,运行时拿不到的内容就等于不存在。把关键信息压回代码仓库,效果比继续往系统提示里塞更多限制更直接。
OpenAI 在文中明确写到,大而全的 AGENTS.md 会很快失效。内容太长会挤掉任务和代码上下文,也会让“所有规则都重要”这件事最后变成“没有规则真正重要”。他们后面的做法更接近渐进式披露:先给一个小而稳定的入口,再让 Agent 顺着链接继续读更深的内容。
这套做法比“把所有约束放在一个文件里”更稳。项目越往后走,产品规格、架构说明、执行计划、参考文档和临时技术债本来就不该是同一层信息。入口文档适合讲项目结构、关键约定、开发命令和文档索引;更细的设计判断、分层规则、产品背景和任务进度,留给对应文档去承载。这样不仅对 Agent 更友好,对后来接手的人也一样。
这篇文章还有个很重要的角度,就是他们把“代码仓库可读性”重新定义了一遍。过去我们讲可读性,默认是给新同事看;到了智能体优先的工作方式里,可读性的对象还包括 Agent。它能不能直接从代码、文档、schema、计划和日志里推理出业务领域,决定了后面很多任务是顺着做,还是每次都要重新猜。
OpenAI 在文中提到,他们后面越来越倾向于把更多情境直接推回仓库。一次架构讨论、某条产品原则、某种团队偏好,如果只是留在 Slack 或口头约定里,三个月后的 Agent 读不到,效果就和新成员错过背景没有区别。写到仓库里的信息,才是真正能持续复用的上下文。
这一点和你原来的整理是对得上的,只是官方文章把它写得更彻底。OpenAI 没有把一致性寄托在“工程师多提醒几次”上,而是把很多规则直接写进自定义 lint、结构测试和 CI 里。比如分层依赖方向、命名规则、结构化日志、文件大小限制、可靠性要求,这些都不靠 session 里反复强调,而是交给自动化去拦。
这背后的原因也很简单。只要规则还是自然语言,Agent 就总有解释空间;一旦规则进入 lint 或测试,它就成了即时反馈。OpenAI 的做法不是微观规定每个实现细节,而是先把边界和不变量写死,在边界里面再给智能体保留足够的实现自由。对小团队来说,这比要求每一轮代码都“写得像某个资深工程师”更现实。
文中另一处很有参考价值的地方,是他们把严格分层当成了前提条件,而不是规模上来以后再做的事。OpenAI 给出的例子是固定的依赖方向和明确的跨域入口,像 Types → Config → Repo → Service → Runtime → UI 这样的结构,不允许随手跨层调用,横切关注点只通过明确接口进入。对人类团队来说,这种架构有时会被嫌麻烦;对 Agent 来说,它反而能明显减少漂移。
因为 Agent 的强项不是靠直觉维护一个隐性体系,而是在边界清楚、路径稳定的环境里快速迭代。越是希望吞吐量上去,越要早点把结构立住。否则一开始也许很快,后面每次改动都会把依赖关系越拉越乱,最终又得回头手工收拾。
你原文里把规划和执行分别交给不同模型,这个思路可以保留,不过放到教程里更适合写成中性的工作分配。更适合规划的模型,可以放在 PRD、架构、任务拆解和影响评估这些阶段,用来做信息归纳、方案比较和边界梳理;更适合执行的模型,可以放在改文件、跑命令、看报错和回修这类阶段。这样安排不是为了追模型标签,而是为了把高成本推理放在更高杠杆的位置。
如果手头只有一个模型,也不等于这套方法失效。真正要守住的还是阶段切换和上下文卫生。规划阶段结束以后,带着文档产出进入下一段,不把探索过程一起拖过去,往往已经能减少很多来回发散。
OpenAI 这篇文章还提到一个很容易被忽略的变化。Agent 的吞吐量一旦高过人的 review 能力,传统的很多工程习惯都会变。Pull Request 生命周期会变短,等待的代价会变高,一些能快速重跑、快速纠错的问题,不再值得长期卡在队列里。放在人类低吞吐协作里,这样做可能太冒进;放在 Agent 密集产出的环境里,等待本身反而可能是更大的浪费。
这个判断不适合直接照搬到所有团队,但它提醒了一件事:如果后面真的把大量执行交给 Agent,工程流程也要一起重排。任务拆得更细、验证更自动、交付更频繁、回修更快,这些事情本来就是连在一起的。
官方文章后半段讲得最现实的一部分,是他们承认完全由 Agent 生成的代码库会不断复制已有模式,其中也包括不均衡和不理想的模式。OpenAI 早期一度靠工程师每周花固定时间清理“AI 残渣”,后来发现这件事不能长期靠人工扛,于是开始把黄金原则写进代码仓库,再用后台任务持续扫描偏差、更新质量评分,并发起针对性的重构 PR。
这件事放到普通项目里,可以理解成一种更主动的垃圾回收。规则不是写完就结束,而是要持续发现哪些地方已经偏了、哪些文档过时了、哪些工具约束还不够。项目规模越大,这一步越不能省。否则前面辛苦建立的结构,后面还是会被日常小改动一点点磨掉。
如果不准备一上来就照着 OpenAI 的规模做,这套方法也完全可以缩小使用。先把入口文档收短,只保留地图作用;再把真正有用的设计、计划、架构和交接信息写回仓库;然后把任务拆成能单独验收的卡片,把分层和命名这类高频约束变成 lint 或脚本;最后再补一个固定格式的交接文档和变更前影响评估。做到这一步,项目就已经从“和模型反复解释需求”往“让环境本身帮助模型执行”走了一大截。
如果把 Harness Engineering 只理解成 prompt 技巧,它会很快撞到上限。把它理解成项目组织方法,很多后续动作就会更清楚:文档怎么放,规则写在哪,任务怎么拆,什么时候重开新对话,哪些地方必须交给机器检查,哪些信息必须留在代码仓库里。到了这个层面,Agent 才更像是在一个被设计过的环境里工作,而不是每次都从零猜起。