Harness工程

参考openai工程博客：《Harness engineering: leveraging Codex in an agent-first world》（Ryan Lopopolo，2026-02-11）

OpenAI 团队做了一个极端实验：5 个月、0 人工手写业务代码，完全用 Codex Agent 从零造出一个真实可用、百万行级、有日活的产品，效率是传统开发的 10 倍。他们把这套让 AI 稳定、规模化、可持续写代码的工程方法论，叫做：Harness 工程（让 Agent 稳定，可控，可复现的干活，而不是靠玄学Prompt）。

当工作从写代码变成由agent驱动开发构建产品时，我们的时间和注意力应该放到哪里 ？

人不再负责写代码，只负责掌舵、设计环境、搭反馈回路。工程工作的中心从“实现”转向“系统设计，脚手架建设和杠杆构建”。

• 把一个大目标拆成可组合的构件（设计、编码、评审、测试等），让 Agent 逐块完成，再组合成更复杂能力。

任务失败时，修复方式从修改prompt变成分析系统到底缺了什么能力，怎样把它变成 Agent 可读、可执行、可验证的机制。

• 给 Agent 提供工具包括代码执行、搜索、文件读写、API、浏览器。同时提供上下文：文档、规范、示例、历史记忆。

• 格式校验，结果检查，风险操作拦截，自动重试 / 回滚，不让 Agent 乱输出、乱执行、把项目搞崩。

完整工作流：Prompt → Agent → PR → 自动合并:工程师只用 prompt 描述任务,Codex 自动写代码、提 PR,做本地自审。也可以启动多 Agent 评审（本地 + 云端），根据反馈自动迭代修改，直到满足合并条件，自动合入。

---

Agent-First 研发模式下的文档系统

放弃传统的 “大而全” 文档思维，转而采用工程化、自动化、可验证的文档架构，确保 Agent 能拿到准确、实时、可用的信息。

作者团队试过“一个超大 AGENTS.md”方案，问题也很明显：

• 上下文预算是稀缺资源： 巨大说明文件会挤占任务、代码和关键文档的上下文空间，Agent 容易漏掉真正重要的约束。
• 指导过量会变成无指导： 当所有信息都“很重要”时，实际上就没有优先级，Agent 只能做局部模式匹配。
• 它会快速腐烂。：单体手册很快变成过时规则堆，Agent 很难判断哪些还有效，人类也会逐渐放弃维护。
• 难以机械校验。：覆盖率、时效性、所有权、交叉链接都难自动验证，漂移几乎不可避免。

所以团队把 AGENTS.md 从“百科全书”降级为“目录页”。

真正的知识库放在结构化的 docs/ 目录，并作为系统事实来源。注入上下文的是一份约 100 行的短 AGENTS.md，主要负责导航，把 Agent 引导到更深层的真源文档。

AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/
│   ├── index.md
│   ├── core-beliefs.md
│   └── ...
├── exec-plans/
│   ├── active/
│   ├── completed/
│   └── tech-debt-tracker.md
├── generated/
│   └── db-schema.md
├── product-specs/
│   ├── index.md
│   ├── new-user-onboarding.md
│   └── ...
├── references/
│   ├── design-system-reference-llms.txt
│   ├── nixpacks-llms.txt
│   ├── uv-llms.txt
│   └── ...
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md

所有设计文档必须有统一的索引目录（如 docs/index.md），Agent 只需看这张 “地图”，就能知道系统有哪些模块、每个模块对应哪份文档，从而实现导航式阅读。

将复杂的开发任务（如重构、大版本功能）不是写成流水账，而是写成可执行的计划文件。到哪一步了？为什么这么做？（记录历史决策依据，方便后续回溯）。跟代码一样做 Git 管理，可追溯、可回滚。让 Agent 明白 “复杂任务” 的全貌，而不仅仅是执行单个指令。

作者团队还配置专门的代码检查器（linter）和 CI 流水线。检查文档是否最新？内部链接是否坏掉？文档结构是否符合规范？

定期扫描仓库：检查是否有代码改了但文档没改（过期文档）、文档描述与代码逻辑不符的情况，一旦发现不一致，Agent 自动生成修复 PR（Fix PR）。把过期文档更新成最新内容。

架构&规范变成可执行约束

Agent 只会模仿仓库里已有的代码模式，不管是好的实践，还是坏的、过时的写法，它都会原样复制。同时，Agent 缺乏全局架构审美，写出来的代码往往局部能跑、功能可用，但放到整个系统里，风格碎片化、结构混乱、依赖杂乱。

早期openai 团队应对方式非常朴素：每周五投入一整天，人工清理这些由 AI 产生的劣质代码。但很快发现，人力清理的速度，完全追不上 Agent 生成代码的速度。代码腐化只会越来越严重，人工兜底根本无法规模化。

基于此，他们建立了两套防御体系，从根源上约束AI编码，同时自动化维持长期一致性：

1. 不再靠口头规范、文档、Code Review 去约束 Agent，而是直接定下不可突破的架构规则：

• 按业务领域对系统做垂直拆分
• 每个业务域内部，代码强制分为固定层级：数据类型 → 配置 → 数据库访问 → 业务逻辑 → 运行时 → 界面
• 严格规定依赖方向：只允许上层依赖下层，绝对不允许反向依赖

这些规则不是写在文档里，而是通过 linter 等自动化工具强制执行：一旦违反，代码根本无法提交。

2. 自动化 “清洁工”，每日小额偿还技术债

解决了架构底线，还要解决代码风格、重复实现、劣质模式扩散的问题。

启用了一组后台自动化 Agent：

• 定时全量扫描代码库
• 自动识别不符合规范的代码
• 直接生成修复 PR，自动提交

这类修复大多非常轻量：比如把到处手写的工具函数，统一替换成共享工具库的标准实现；修正命名、文件结构、日志格式等。这类 PR 评审成本极低，通常几十秒就能完成，很多可以直接自动合并。

它的价值在于：从 “攒一个月做一次大扫除”，变成 “每天日常打扫”。技术债就像高利息贷款，持续小额偿还，远比集中爆发式重构成本更低、更可持续。

自主等级持续提升

随着测试、验证、评审、反馈处理和失败恢复逐步编码进系统，仓库最近跨过了一个关键阈值：Codex 已可以端到端驱动新特性交付。

给定一个 prompt，它现在可以：

• 校验代码库当前状态
• 复现已报告 bug
• 录制问题复现视频
• 实施修复
• 驱动应用验证修复
• 录制修复成功视频
• 打开 PR
• 响应 Agent 与人类反馈
• 识别并修复构建失败
• 仅在需要判断时升级给人类
• 合并改动

作者也明确强调：这种能力高度依赖该仓库特定结构和持续投入，不应在缺乏同等建设的情况下直接外推。

还不清楚的事

到目前为止，这套策略在 OpenAI 内部上线与采用阶段效果不错。为真实用户交付真实产品，帮助我们把投入锚定在现实约束和长期可维护性上。

但仍有关键未知：

• 全 Agent 生成系统能否在多年尺度上维持架构一致性？
• 人类判断在哪些环节杠杆最大，如何把这些判断编码成可复用机制？
• 随着模型能力继续提升，现有控制系统会如何演化？

当前最清晰的结论是：软件工程纪律没有消失，它只是从“写代码技巧”迁移到了“环境设计、反馈回路与控制系统设计”。

真正决定上限的，不是一次生成是否惊艳，而是你是否建立了能长期自稳、可持续复利的 harness。