中文 | English
一个从概念理解到独立实践的 Harness Engineering 深度学习档案
这是一个不断生长的学习项目。Harness Engineering（驭缰工程）是 OpenAI 在 2026 年 2 月提出的工程范式：工程师不再写代码，而是设计环境、明确意图、构建反馈回路，让 AI 智能体可靠地完成工作。
人类掌舵，智能体执行。
本仓库记录了从阅读原文、拆解概念、形成思考、动手实践到输出作品的完整学习过程。希望对同样关注 AI 工程化的朋友有所帮助。
来源：OpenAI — Harness Engineering: Harnessing Codex in an Agent-First World
注意： 以下经验分享并非普遍适用，请在具体实践中结合场景，辩证采纳。
传统工程：人类写代码 → 机器执行代码
Harness Engineering：人类设计约束 → 智能体写代码 → 机器执行代码
核心转变：工程师的产出从代码变成了约束系统——AGENTS.md、架构规则、自定义 linter、反馈回路。
1. 仓库即记录系统 — 不在仓库里的东西，对智能体不存在
Slack 讨论、Google Docs、脑子里的知识 = 对智能体不可见。一切决策、规范、计划都必须以版本化工件提交到仓库。
2. 地图而非手册 — AGENTS.md 是目录页，不是百科全书
~100 行的入口文件，指向更深层的文档。渐进式披露：智能体从小入口点开始，被指导下一步该看什么。巨型指令文件的三个死因：挤占上下文、无法维护、无法机械验证。
3. 机械化执行 — 文档会腐烂，lint 规则不会
自定义 linter + 结构测试 = 不变量的守护者。lint 错误信息里内嵌修复指令，智能体可以自我纠正。在中央层面强制执行边界，在本地层面允许自主权。
4. 智能体可读性 — 优先为智能体的推理能力优化
选"无聊"技术（API 稳定、训练集覆盖好）。有时重新实现子集比包装不透明的上游行为更划算。让应用可以按 git worktree 启动。
5. 吞吐量改变合并理念 — 纠错成本低，等待成本高
PR 生命周期很短。测试偶发失败通过后续重跑解决。在智能体吞吐量远超人类注意力的系统中，这通常是正确的选择。
6. 熵管理 = 垃圾回收 — 技术债是高息贷款
智能体会复现仓库中已有的模式——包括坏模式。将"黄金规则"编码进仓库，定期后台任务扫描偏差、更新质量评分、发起重构 PR。
| 指标 | 数据 |
|---|---|
| 团队规模 | 3 人 → 7 人 |
| 时间跨度 | 5 个月 |
| 代码量 | ~100 万行 |
| PR 数量 | ~1,500 个 |
| 人均日 PR | 3.5 个（扩展后仍在增长） |
| 单次运行时长 | 6+ 小时（通常在人类睡眠时间） |
| 效率估算 | 手工编写的 ~1/10 时间 |
harness-engineering/
├── README.md ← 你在这里
├── AGENTS.md ← 仓库导航入口（给智能体看的）
│
├── concepts/ # Phase 1：概念笔记（7 篇）
│ ├── 00-overview.md # 六大核心概念总览
│ ├── 01-repo-as-... # 仓库即记录系统
│ ├── 02-mechanical-... # 机械化执行
│ ├── 03-entropy-... # 熵管理与垃圾回收
│ ├── 04-agent-... # 智能体可读性
│ ├── 05-throughput-... # 吞吐量改变合并理念
│ └── 06-harness-... # Harness 精确定义（Fowler 控制论扩展）
│
├── thinking/ # Phase 2：独立思考与质疑（6 篇）
├── practice/ # Phase 3：小项目实验（1 个 Ralph Demo）
├── feedback/ # Phase 4：踩坑与迭代心得（1 篇）
├── works/ # Phase 5：可展示的作品（11 篇翻译 + 1 篇原创）
├── prompts/ # 验证有效的提示词积累
└── references/ # 外部资源索引（18 篇文章深度摘要）
每个子目录都有自己的 AGENTS.md，说明该目录的用途和写作约定。这本身就是原文「渐进式披露」的实践。
- Phase 1：理解核心概念 — 7 篇概念笔记，覆盖 OpenAI 六大概念 + Fowler 控制论扩展
- Phase 2：形成自己的观点 — 6 篇独立思考（持续中）
- Phase 3：选一个小项目实践 — Ralph Demo 完成（321 秒，$0.31）
- Phase 4：记录反馈迭代 — 1 篇（持续中）
- Phase 5：输出可展示的作品 — 11 篇专业翻译 + 1 篇原创综合分析
跨 15 篇核心文章 + 3 篇延伸阅读，构建三条知识脉络：
| 脉络 | 覆盖 | 核心视角 |
|---|---|---|
| AI 时代的 Harness Engineering | 15 篇 | OpenAI → Fowler → Anthropic → LangChain → Stanford |
| 云原生 Harness.io | 3 篇 | CI/CD 平台架构（同名不同义的参照） |
| 延伸阅读 | 3 篇 | Mitchell Hashimoto、Context Engineering、人机协作 |
详见 references/articles.md — 每篇文章含核心论点、关键数据、跨文章关联的深度摘要。
11 篇核心文章的中文翻译（点击展开）
| 作品 | 原作者 | 来源 |
|---|---|---|
| ⭐ 渴望了八年，用 AI 三个月造出来 | Lalit Maganti | 个人博客 |
| Inside the Scaffold 论文 | Benjamin Rombaut | Huawei / arXiv |
| Meta-Harness 论文 | Yoonho Lee 等 | Stanford / arXiv |
| Harness Engineering 正式版 | Birgitta Böckeler | Martin Fowler |
| Harness Engineering 备忘录 | Birgitta Böckeler | Martin Fowler |
| Encoding Team Standards | Rahul Garg | Martin Fowler |
| Feedback Flywheel | Rahul Garg | Martin Fowler |
| Scaling Managed Agents | Lance Martin 等 | Anthropic |
| Agent Evaluation Checklist | LangChain 团队 | LangChain |
| Agent-driven Development | Tyler McGoffin | GitHub |
| Continual Learning | Harrison Chase | LangChain |
| 资源 | 说明 |
|---|---|
| OpenAI 原文（中文） | Harness Engineering 的完整阐述 |
「Ralph Wiggum 循环」是 Harness Engineering 的核心实现模式：让智能体在循环中自主工作直到任务完成。
| 项目 | Stars | 说明 |
|---|---|---|
| snarktank/ralph | 13.6k | 原版 Ralph：bash 脚本反复启动 AI，每次迭代清空上下文，直到 PRD 全部完成。6 条核心信条（Fresh Context、Backpressure、Plan Is Disposable 等） |
| ralph-orchestrator | 2.3k | Rust 进化版：Hat 角色系统 + 事件驱动协调 + 多后端（Claude/Kiro/Gemini/Codex）+ 背压门控 + 持久化记忆 |
| bmad-ralph | 2 | BMAD 方法论 + Ralph：并行 Claude Code worktree + 三层自愈（retry → restart → diagnose）+ SQLite 状态机 |
| Ralph 信条 | Harness Engineering 对应概念 |
|---|---|
| Fresh Context Is Reliability | 智能体可读性 — 每次迭代重新读取 |
| Backpressure Over Prescription | 机械化执行 — 不规定怎么做，但门控拒绝坏结果 |
| The Plan Is Disposable | 熵管理 — 重新生成的成本只是一次 planning loop |
| Disk Is State, Git Is Memory | 仓库即记录系统 — 文件是交接机制 |
| Steer With Signals, Not Scripts | 人类掌舵 — 加路标，不加脚本 |
| Let Ralph Ralph | 智能体执行 — 坐在循环上，不坐在循环里 |
| 资源 | 说明 |
|---|---|
| vibe-coding-cn | 中文 Vibe Coding 社区指南 |
| Mitchell Hashimoto: Engineer the Harness | "Harness" 概念的另一个起源 |
仓库自带一致性检查脚本 scripts/check-consistency.sh，守护数量类漂移：references/articles.md 文章数、其下游 4 处引用（README × 2 badges、prompts/deep-research-tracker.md 头部、references/AGENTS.md 概览），以及 concepts/ / thinking/ / feedback/ 三个目录的篇数。works/ 目前不在覆盖范围（结构仍在演化）。
首次 clone 后启用 pre-commit hook：
git config core.hooksPath .githooks启用后，每次 commit 涉及 README、references/articles.md、references/AGENTS.md、prompts/deep-research-tracker.md、或 concepts/ / thinking/ / feedback/ 中的 *.md 时会自动跑检查；不涉及则不打扰。
手动跑： bash scripts/check-consistency.sh
CI 兜底： 即使本地未启用 hook，GitHub Actions（.github/workflows/consistency.yml）会在每次 push / PR 触及受控文件时跑同一脚本。本地 hook 是开发期反馈，CI 才是真正的合并门。
详情见根 AGENTS.md 的"机械化检查"段。
欢迎通过 Issue 和 PR 参与：
- 补充概念笔记（
concepts/中还有待补充的概念） - 分享你的独立思考（
thinking/） - 贡献实践案例（
practice/） - 推荐相关资源（
references/）
| 渠道 | 链接 |
|---|---|
| GitHub | @deusyu |
| X (Twitter) | @0xdeusyu |
| Telegram | @DeusThink |
| Telegram 交流群 | @talkdeusyu |
| Telegram 频道 | @lovedesuyu |
| [email protected] |
如果这个项目对您有帮助，请考虑为其点亮一颗 Star ⭐！
MIT