Seven Mental · 心智七篇
中 EN
← Knowledge Atlas · Source

Harness Engineering: Leveraging Codex in an Agent-First World

OpenAI 零人工编码实验：agent legibility、repo 即知识系统、架构执行、熵管理
源
SOURCE · HARNESS ENGINEERING · OpenAI · 5-month zero-human-coding experiment · 2026

Designing Harnesses for an Agent-First World

Engineers stop writing code — design environments, express intent, build feedback loops

”
Humans steer.
Agents execute.
When the agent gets stuck, don’t “try again” — ask “what capability is missing, and how do we make it legible and executable for the agent?“
1M
lines of code
1500+
PRs
3.5
PRs/person/day
6hr+
single Codex run
Repository as Knowledge
AGENTS.md = table of contents (~100 lines) + structured docs/ + progressive disclosure + linter mechanically verifying freshness
Agent Legibility
Knowledge in Slack/GDocs is invisible to the agent — not reachable at runtime = does not exist
Enforce Invariants
Types→Config→Repo→Service→Runtime→UI — dependency direction enforced mechanically
Entropy Garbage Collection
Encode golden principles + background agents scan for drift + auto-open fix PRs
→ harness-engineering · agent-legibility · long-running-agentsopenai.com/index/harness-engineering

Harness Engineering: Leveraging Codex in an Agent-First World

概述

OpenAI 团队用 5 个月、零人工编码构建了一个内部产品（约百万行代码、1500+ PR）。本文记录了这个过程中关于 harness engineering 的核心经验——当工程师的工作不再是写代码，而是设计环境、表达意图、构建反馈回路时，什么变了。

核心主张

“Humans steer. Agents execute.”

工程师的角色重新定义为：优先级排列、用户反馈转化为验收标准、结果验证。当 agent 卡住时，不是”再试一次”，而是问”缺什么能力，怎么让它对 agent 可读且可执行”。

关键实践

Repository 作为知识系统

“一个大 AGENTS.md”的做法失败了——context 稀缺、过多指导等于无指导、内容迅速腐烂。改为：

  • AGENTS.md 作为目录（~100 行），指向 docs/ 中的深层知识
  • 结构化 docs/：design docs、execution plans、product specs、references
  • 渐进式披露：agent 从小而稳的入口出发，按需深入
  • 机械化验证：专门的 linter + CI 检查知识库的新鲜度、交叉链接、结构正确性

Agent Legibility（Agent 可读性）

传统代码为人类可读性优化；这里为 agent 可读性 优化。核心原则：“agent 在运行时无法访问的信息等于不存在。” Slack 讨论、Google Docs 中的知识对 agent 不可见——必须推入 repo。

架构执行与品味

  • Enforce invariants, not implementations：每个业务域固定分层（Types → Config → Repo → Service → Runtime → UI），依赖方向机械化执行
  • “无聊”技术更适合 agent：可组合、API 稳定、训练数据覆盖好
  • 有时 agent 重新实现功能比依赖不透明的外部库更便宜
  • 自定义 linter 的错误信息嵌入修复指令——直接注入 agent context

熵与垃圾回收

Agent 复制已有模式，包括不好的模式。最初人类每周五手动清理”AI slop”（20% 时间），不可持续。 改为：“golden principles” 编码进 repo + 定期后台 agent 扫描偏差 + 开修复 PR → 技术债的持续小额偿还。

吞吐量改变合并哲学

Agent 吞吐远超人类注意力 → 最少阻塞合并门、短生命周期 PR、修正比等待便宜。在低吞吐环境下不负责任，在这里是正确的权衡。

量化成果

  • 3 名工程师起步，后增至 7 人
  • 平均每人每天 3.5 PR
  • 单次 Codex 运行可持续 6+ 小时
  • 吞吐量随团队增长而提升（非下降）

与其他来源的关系

与 Anthropic 的 harness 系列 形成有趣对比：

  • 共识：harness 的核心是约束 + 反馈回路 + 外部化状态；渐进式披露而非信息倾倒
  • 差异：OpenAI 更强调整个开发流程的 agent 化（review、merge、cleanup 都由 agent 完成），Anthropic 更聚焦于单个 agent 的 session 间协调
  • 共同洞察：agent 的失败是环境不足的信号，而非模型能力的上限

References

  • sources/openai_official/harness-engineering.md