Harness Engineering 概念总览

来源：OpenAI 2026-02-11，作者 Ryan Lopopolo 背景：3人团队用 Codex 从空仓库到100万行代码，5个月，零手写代码

一句话定义

Harness Engineering = 工程师不再写代码，而是设计环境、明确意图、构建反馈回路，让 AI 智能体可靠地完成工作。

六大核心概念

概念编号以本总览与 README 为准（两处一致）；concepts/ 的文件名编号是阅读顺序，不是概念编号。对照表见 AGENTS.md。

1. 仓库即记录系统（Repo as System of Record）

• 不在仓库里的东西，对智能体来说不存在
• Slack 讨论、Google Docs、脑子里的知识 = 对智能体不可见
• 一切决策、规范、计划都必须以版本化工件提交到仓库

→ 详见 01-repo-as-source-of-truth.md

2. 地图而非手册（Map, Not Manual）

• AGENTS.md ≈ 目录页（~100行），不是百科全书
• 渐进式披露：从小入口点开始，指向更深层的文档
• 巨型指令文件的三个死因：挤占上下文、无法维护、无法机械验证

（本节即该概念的主文，无独立文件；跨仓库延伸见 07-spec-as-product.md）

3. 机械化执行（Mechanical Enforcement）

• 文档会腐烂，lint 规则不会
• 自定义 linter + 结构测试 = 不变量的守护者
• lint 错误信息里内嵌修复指令，智能体可以自我纠正

→ 详见 02-mechanical-enforcement.md

4. 智能体可读性（Agent Readability）

• 优先选择"无聊"技术（API 稳定、训练集覆盖好）
• 有时重新实现子集比包装不透明的上游行为更划算
• 让应用可以按 git worktree 启动，智能体可以启动隔离实例

→ 详见 04-agent-readability.md

5. 吞吐量改变合并理念（Throughput Changes Merge Philosophy）

• 纠错成本低，等待成本高：PR 生命周期很短
• 测试偶发失败通过后续重跑解决，而不是阻塞合并
• 在智能体吞吐量远超人类注意力的系统中，这通常是正确的选择

→ 详见 05-throughput-changes-merge.md

6. 熵管理 = 垃圾回收（Entropy & Garbage Collection）

• 智能体会复现仓库中已有的模式——包括坏模式
• "黄金规则"编码进仓库，定期后台任务扫描偏差
• 技术债 = 高息贷款，小额持续偿还

→ 详见 03-entropy-and-garbage-collection.md

总纲：人类掌舵，智能体执行（Humans Steer, Agents Execute）

六大概念之上的总原则，也是本仓库 README 开篇的那句口号：

• 人类时间是最稀缺的资源
• 出问题时，答案不是"更努力"，而是"缺什么上下文/工具/约束"
• 工程师的新角色：设计环境 → 拆解任务 → 提示智能体 → 验证结果

架构模型

每个业务域内的固定分层：
Types → Config → Repo → Service → Runtime → UI

横切关注点通过 Providers 进入（auth, telemetry, feature flags）
依赖只能向前流动，由 linter 强制执行

关键数据点

• 3人团队 → 5个月 → ~100万行代码 → ~1500个 PR
• 人均每天 3.5 个 PR，扩展到 7 人后吞吐量还在增长
• 单次 Codex 运行可持续 6+ 小时（通常在人类睡眠时间）
• 估算：约为手工编写的 1/10 时间