# Harness Engineering 概念总览

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

## 一句话定义

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

## 六大核心概念

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

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

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

→ 详见 [01-repo-as-source-of-truth.md](01-repo-as-source-of-truth.md)

<a id="map-not-manual"></a>

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

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

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

### 3. 机械化执行（Mechanical Enforcement）

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

→ 详见 [02-mechanical-enforcement.md](02-mechanical-enforcement.md)

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

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

→ 详见 [04-agent-readability.md](04-agent-readability.md)

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

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

→ 详见 [05-throughput-changes-merge.md](05-throughput-changes-merge.md)

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

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

→ 详见 [03-entropy-and-garbage-collection.md](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 时间