Harness Engineering 在 Agent Coding 里的项目组织方法

OpenAI 这篇工程文章真正补上了什么

如果只从个人实践去理解 Harness Engineering，这套方法很容易被写成“怎么和模型聊天更有效”。OpenAI 在 2026 年 2 月 11 日那篇工程文章里给了一个更完整的口径。他们讲的重点不是提示词技巧，而是当一个项目从零开始、主要代码都交给 Codex 产出以后，工程团队到底要把精力放在哪里。

文章里最醒目的信息，是他们真的用一支很小的团队，把一个从空 Git 仓库起步的内部产品一路做到了百万行代码规模，而且坚持不手写代码。人类仍然在掌舵，但主要工作已经从“直接写实现”转向“设计环境、写清意图、补工具、建反馈回路”。如果把这件事翻译成更容易执行的话，Harness Engineering 处理的其实不是某一轮问答，而是整个项目如何为 Agent 准备工作环境。

代码仓库要变成记录系统

这篇官方文章里最值得吸收的一点，是 OpenAI 不再把 AGENTS.md 当成一本塞满规则的大手册，而是把它压到很短，只保留目录和入口作用。真正的知识放进仓库里的 docs/、架构文档、执行计划、产品规格、技术债追踪和生成出来的 schema 文档里，全部走版本控制。这样一来，Agent 拿到的不是一坨超长说明书，而是一张清楚的地图，知道自己下一步该去哪找信息。

这个思路很适合改写到普通项目里。很多团队现在的问题不是没有信息，而是信息散在聊天记录、Google Docs、飞书文档和人脑里。人能靠经验补齐，Agent 不能。对 Agent 来说，运行时拿不到的内容就等于不存在。把关键信息压回代码仓库，效果比继续往系统提示里塞更多限制更直接。

短 AGENTS，长文档，按层往下找

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 才更像是在一个被设计过的环境里工作，而不是每次都从零猜起。