OpenAI Codex Harness Engineering: Agent-First 软件开发实验

OpenAI 团队在 5 个月内用 0 行手写代码构建了一个百万行级别的内部产品，3 名工程师驱动 Codex 完成约 1,500 个 PR（3.5 PR/人/天）。这个实验揭示了当 agent 成为主要的代码生产者时，工程工作的本质如何从"写代码"转变为"设计环境、制定意图和构建反馈循环"。

来源: OpenAI Engineering Blog — Ryan Lopopolo, 2026-02-11

Compiled Truth (可重写)

核心数据

关键设计决策

1. AGENTS.md 作为目录，而非百科全书

“一个巨大的 AGENTS.md” 方案失败了，原因：

• 上下文是稀缺资源：巨大的指令文件挤占了任务、代码和文档的空间
• 太多指导等于无指导：当一切都是"重要"的，agent 开始局部模式匹配
• 立即腐烂：单体手册变成过时规则的墓地
• 难以验证：单个 blob 不支持机械检查

替代方案：短 AGENTS.md（~100 行）作为目录，结构化 docs/ 目录作为知识库。

2. 渐进式披露（Progressive Disclosure）

AGENTS.md          ← 入口，地图
ARCHITECTURE.md    ← 顶层架构
docs/
├── design-docs/   ← 设计文档 + 核心信念
├── exec-plans/    ← 活跃/已完成计划 + 技术债追踪
├── generated/     ← 自动生成的文档（如 db-schema）
├── product-specs/ ← 产品规格
├── references/    ← 外部库的 llms.txt
├── DESIGN.md / FRONTEND.md / QUALITY_SCORE.md / ...

用 CI 和 linter 机械地验证知识库的时效性、交叉链接和结构正确性。一个"文档园艺"agent 定期扫描过时文档并开修复 PR。

3. Agent 可读性优先

“Agent 看不到的东西，对它来说就不存在。”

• Google Docs、Slack 讨论、人类头脑中的隐性知识 — 对 agent 来说不可见
• 所有知识必须编码进代码库（markdown、schema、可执行计划）
• 类比：就像给新入职的工程师做 onboarding

技术选择偏向"无聊"的技术 — 组合性好、API 稳定、训练集中有充分表示。有时让 agent 重新实现子集功能比处理不透明的上游库更便宜。

4. 机械执行架构约束

Types → Config → Repo → Service → Runtime → UI
          ↑
      Providers（跨切面关注点的唯一入口）

• 每个业务域按固定分层，依赖方向严格验证
• 自定义 linter（Codex 自己写的！）和结构测试执行约束
• Lint 错误信息中注入修复指令到 agent 上下文
• 中心化执行边界，本地化允许自主

5. 垃圾回收（Garbage Collection）

Agent 会复制代码库中已有的模式——包括不理想的。解决方案：

• 编码"黄金原则"（如：共享工具包 > 手写帮助函数）
• 定期后台 Codex 任务扫描偏差、更新质量评级、开重构 PR
• 大多数重构 PR 可在 1 分钟内审阅并自动合并
• 技术债像高利贷：持续小额偿还远优于累积后大规模清理

6. 全栈 Agent 可观测性

• App 可按 git worktree 启动，每个变更一个隔离实例
• Chrome DevTools Protocol 集成：DOM 快照、截图、导航
• 本地可观测栈（LogQL/PromQL/TraceQL），随 worktree 创建/销毁
• Agent 可以验证"服务启动 < 800ms"、“关键路径无 span > 2s”

完全自主的端到端流程

单条 prompt 即可驱动 agent 完成：

1. 验证代码库状态 → 2. 复现 bug → 3. 录制失败视频 → 4. 实现修复 → 5. 驱动 app 验证修复 → 6. 录制修复视频 → 7. 开 PR → 8. 响应审阅 → 9. 处理构建失败 → 10. 仅在需判断时升级给人 → 11. 合并

工程师角色转变

Timeline (只追加)

• 2025-08: 项目启动，空 git 仓库的第一个 commit
• 2026-02-11: OpenAI 发布博客文章
• 2026-04-13: 整理进 KB，创建 wiki 页面