# Technical Documentation: deusyu/harness-engineering

> ℹ️ **Provenance:** Hybrid Fusion: `deusyu/harness-engineering` (README + 2 In-Tree Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/deusyu/harness-engineering) · Recency: Active (< 180 days)

## 1. Project Overview & Quickstart (deusyu/harness-engineering)

中文 | [English](README.en.md)





# Harness Engineering 学习指南

> 一个从概念理解到独立实践的 Harness Engineering 深度学习档案

[](works/harness-engineering-intro-deck/)



## 前言

这是一个不断生长的学习项目。**Harness Engineering**（驭缰工程）是 OpenAI 在 2026 年 2 月提出的工程范式：工程师不再写代码，而是设计环境、明确意图、构建反馈回路，让 AI 智能体可靠地完成工作。

> **人类掌舵，智能体执行。**

本仓库记录了从阅读原文、拆解概念、形成思考、动手实践到输出作品的完整学习过程。希望对同样关注 AI 工程化的朋友有所帮助。

来源：[OpenAI — Harness Engineering: Harnessing Codex in an Agent-First World](https://openai.com/zh-Hans-CN/index/harness-engineering/)

> **注意：** 以下经验分享并非普遍适用，请在具体实践中结合场景，辩证采纳。

## ⚡ 一句话理解

```
传统工程：人类写代码 → 机器执行代码
Harness Engineering：人类设计约束 → 智能体写代码 → 机器执行代码
```

核心转变：**工程师的产出从代码变成了约束系统**——AGENTS.md、架构规则、自定义 linter、反馈回路。

## 🧭 六大核心概念


**1. 仓库即记录系统** — 不在仓库里的东西，对智能体不存在

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

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



**2. 地图而非手册** — AGENTS.md 是目录页，不是百科全书

~100 行的入口文件，指向更深层的文档。渐进式披露：智能体从小入口点开始，被指导下一步该看什么。巨型指令文件的三个死因：挤占上下文、无法维护、无法机械验证。

→ 详见 [concepts/00-overview.md](concepts/00-overview.md)



**3. 机械化执行** — 文档会腐烂，lint 规则不会

自定义 linter + 结构测试 = 不变量的守护者。lint 错误信息里内嵌修复指令，智能体可以自我纠正。在中央层面强制执行边界，在本地层面允许自主权。

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



**4. 智能体可读性** — 优先为智能体的推理能力优化

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

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



**5. 吞吐量改变合并理念** — 纠错成本低，等待成本高

PR 生命周期很短。测试偶发失败通过后续重跑解决。在智能体吞吐量远超人类注意力的系统中，这通常是正确的选择。

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



**6. 熵管理 = 垃圾回收** — 技术债是高息贷款

智能体会复现仓库中已有的模式——包括坏模式。将"黄金规则"编码进仓库，定期后台任务扫描偏差、更新质量评分、发起重构 PR。

→ 详见 [concepts/03-entropy-and-garbage-collection.md](concepts/03-entropy-and-garbage-collection.md)


## 🔑 关键数据点

| 指标 | 数据 |
|------|------|
| 团队规模 | 3 人 → 7 人 |
| 时间跨度 | 5 个月 |
| 代码量 | ~100 万行 |
| PR 数量 | ~1,500 个 |
| 人均日 PR | 3.5 个（扩展后仍在增长） |
| 单次运行时长 | 6+ 小时（通常在人类睡眠时间） |
| 效率估算 | 手工编写的 ~1/10 时间 |

## 📂 仓库结构

```
harness-engineering/
├── README.md              ← 你在这里
├── AGENTS.md              ← 仓库导航入口（给智能体看的）
│
├── concepts/              # Phase 1：概念笔记（8 篇）
│   ├── 00-overview.md     #   六大核心概念总览
│   ├── 01-repo-as-...     #   仓库即记录系统
│   ├── 02-mechanical-...  #   机械化执行
│   ├── 03-entropy-...     #   熵管理与垃圾回收
│   ├── 04-agent-...       #   智能体可读性
│   ├── 05-throughput-...  #   吞吐量改变合并理念
│   ├── 06-harness-...     #   Harness 精确定义（Fowler 控制论扩展）
│   └── 07-spec-as-product.md #   约束即产品（Symphony 延伸）
│
├── thinking/              # Phase 2：独立思考与质疑（11 篇）
├── practice/              # Phase 3：小项目实验（1 个 Ralph Demo）
├── feedback/              # Phase 4：踩坑与迭代心得（1 篇）
├── works/                 # Phase 5：可展示的作品（34 篇翻译 + 1 篇原创 + 2 篇外部中文收录）
├── tools/                 # 工具具像化：降低 6 维复杂度的杠杆库
├── prompts/               # 验证有效的提示词积累
└── references/            # 外部资源索引（74 篇文章深度摘要）
```

每个子目录都有自己的 `AGENTS.md`，说明该目录的用途和写作约定。这本身就是原文「渐进式披露」的实践。

## 🚀 学习路线

- [x] **Phase 1：理解核心概念** — 8 篇概念笔记，覆盖 OpenAI 六大概念 + Fowler 控制论扩展 + Symphony 约束即产品
- [x] **Phase 2：形成自己的观点** — 11 篇独立思考（持续中）
- [x] **Phase 3：选一个小项目实践** — Ralph Demo 完成（321 秒，$0.31）
- [x] **Phase 4：记录反馈迭代** — 1 篇（持续中）
- [x] **Phase 5：输出可展示的作品** — 34 篇专业翻译 + 1 篇原创综合分析 + 2 篇外部中文收录

## 📚 研究资料库

跨三条知识脉络 74 篇文章 + 2 篇延伸阅读：

| 脉络 | 覆盖 | 核心视角 |
|------|------|---------|
| AI 时代的 Harness Engineering | 70 篇 | OpenAI → Fowler → Anthropic → LangChain → Stanford → Claude Code 逆向与源码实锤 → Subagent runtime → 传感器/SPDD/ADLC → 越界·安全审计·质量复盘 → 评测三部曲 → 动态工作流 → 起源考据（Ralph / Hashimoto）与学科汇流 → Codex harness 解剖 → Loop Engineering 三部曲 → 自演化 harness 与 RSI → 形式化验证 → 多智能体并行规模化（Cursor / C compiler）→ 遏制与评测官方方法论 → 行为地图 / DSL / 本地模型 / 外环问责 → 工业级机械移植（Bun）与 harness-模型共演化（HarnessX）→ 长时 harness 奠基与评测环境混杂（Anthropic 存量）→ harness 运维度量与奖励作弊（Cursor 存量）→ 工具 schema 不中立 → 软件工厂之争（Dex Horthy / Osmani）→ 智能体蜂群成本经济学 → 删掉 80% 系统提示词 → 代码评审传感器基准（ReviewBench） |
| 云原生 Harness.io | 2 篇 | CI/CD 平台架构（同名不同义的参照） |
| 效率悖论与能力进化 | 2 篇 | YDD 系统性拆解 + METR 实验后续（测量方法论危机） |
| 延伸阅读 | 2 篇 | Context Engineering、人机协作 |

详见 [references/articles.md](references/articles.md) — 每篇文章含核心论点、关键数据、跨文章关联的深度摘要。

## 📖 翻译作品


**34 篇核心文章的中文翻译**（点击展开）

| 作品 | 原作者 | 来源 |
|------|--------|------|
| ⭐ [渴望了八年，用 AI 三个月造出来](works/maganti-eight-years-building-ai-translation.md) | Lalit Maganti | 个人博客 |
| [用 ReviewBench 评测代码评审智能体](works/langchain-reviewbench-translation.md) | Nick Hollon | LangChain |
| [Claude 5 世代模型的上下文工程新规则](works/anthropic-context-engineering-claude5-translation.md) | Thariq Shihipar | Anthropic / Claude |
| [更好的模型：更差的工具](works/ronacher-better-models-worse-tools-translation.md) | Armin Ronacher | 个人博客 |
| [用 Rust 重写 Bun](works/bun-in-rust-translation.md) | Jarred Sumner | Bun Blog |
| [用一支并行 Claude 团队构建 C 编译器](works/anthropic-c-compiler-translation.md) | Nicholas Carlini | Anthropic |
| [规模化长时自主编码](works/cursor-scaling-agents-translation.md) | Wilson Lin | Cursor |
| [我们如何在各产品中遏制 Claude](works/anthropic-how-we-contain-translation.md) | Max McGuinness 等 | Anthropic |
| [面向自我改进的 Harness Engineering](works/weng-harness-self-improvement-translation.md) | Lilian Weng | Lil'Log |
| [循环工程（Loop Engineering）](works/osmani-loop-engineering-translation.md) | Addy Osmani | 个人博客 |
| [正在到来的循环（The Coming Loop）](works/ronacher-coming-loop-translation.md) | Armin Ronacher | 个人博客 |
| [为每个任务配一套 harness：动态工作流](works/anthropic-dynamic-workflows-translation.md) | Thariq Shihipar 等 | Anthropic / Claude |
| [METR：我们正在更改生产力实验设计](works/metr-uplift-update-translation.md) | Joel Becker 等 | METR |
| [Inside the Scaffold 论文](works/inside-the-scaffold-paper-translation.md) | Benjamin Rombaut | Huawei / arXiv |
| [Meta-Harness 论文](works/meta-harness-paper-translation.md) | Yoonho Lee 等 | Stanford / arXiv |
| [Harness Engineering 正式版](works/fowler-harness-engineering-full-translation.md) | Birgitta Böckeler | Martin Fowler |
| [Harness Engineering 备忘录](works/fowler-harness-engineering-memo-translation.md) | Birgitta Böckeler | Martin Fowler |
| [Encoding Team Standards](works/fowler-encoding-team-standards-translation.md) | Rahul Garg | Martin Fowler |
| [Feedback Flywheel](works/fowler-feedback-flywheel-translation.md) | Rahul Garg | Martin Fowler |
| [Scaling Managed Agents](works/anthropic-managed-agents-translation.md) | Lance Martin 等 | Anthropic |
| [Agent Evaluation Checklist](works/langchain-agent-evaluation-checklist-translation.md) | LangChain 团队 | LangChain |
| [Agent-driven Development](works/github-agent-driven-development-translation.md) | Tyler McGoffin | GitHub |
| [Continual Learning](works/langchain-continual-learning-translation.md) | Harrison Chase | LangChain |
| [Codex 编排开源规范 Symphony](works/openai-codex-symphony-translation.md) | Kotliarskyi 等 | OpenAI |
| [Claude Code 架构（逆向工程版）](works/claude-code-architecture-reverse-translation.md) | Vikash Rungta | Substack |
| [面向编码智能体的可维护性传感器](works/fowler-sensors-translation.md) | Birgitta Böckeler | Martin Fowler |
| [结构化提示驱动开发 SPDD](works/fowler-spdd-translation.md) | Wei Zhang 等 | Martin Fowler |
| [智能体开发生命周期 ADLC](works/langchain-adlc-translation.md) | Harrison Chase | LangChain |
| [Deep Agents 中的解释器](works/deep-agents-interpreter-translation.md) | Hunter Lovell | LangChain |
| [Claude Code 质量回归复盘](works/anthropic-postmortem-translation.md) | Anthropic 工程团队 | Anthropic |
| [Agentic Harness Engineering 论文](works/arxiv-agentic-harness-engineering-translation.md) | Jiahang Lin 等 | 复旦 / arXiv |
| [过度积极的编码智能体 论文](works/arxiv-overeager-coding-agents-translation.md) | Yubin Qu 等 | arXiv |
| [我是如何用 AI 写代码的](works/chris-ai-code-translation.md) | Chris Parsons | 个人博客 |
| [我们如何构建 LangSmith Engine](works/langsmith-engine-translation.md) | Palash Shah | LangChain |



## 🔗 相关项目与资源

### 原始来源

| 资源 | 说明 |
|------|------|
| [OpenAI 原文（中文）](https://openai.com/zh-Hans-CN/index/harness-engineering/) | Harness Engineering 的完整阐述 |

### Ralph 系列 — Harness Engineering 的实战框架

「Ralph Wiggum 循环」是 Harness Engineering 的核心实现模式：让智能体在循环中自主工作直到任务完成。

| 项目 | Stars | 说明 |
|------|-------|------|
| [snarktank/ralph](https://github.com/snarktank/ralph) | 13.6k | 原版 Ralph：bash 脚本反复启动 AI，每次迭代清空上下文，直到 PRD 全部完成。6 条核心信条（Fresh Context、Backpressure、Plan Is Disposable 等） |
| [ralph-orchestrator](https://mikeyobrien.github.io/ralph-orchestrator/) | 2.3k | Rust 进化版：Hat 角色系统 + 事件驱动协调 + 多后端（Claude/Kiro/Gemini/Codex）+ 背压门控 + 持久化记忆 |
| [bmad-ralph](https://github.com/qianxiaofeng/bmad-ralph) | 2 | BMAD 方法论 + Ralph：并行 Claude Code worktree + 三层自愈（retry → restart → diagnose）+ SQLite 状态机 |

### Ralph 六条信条（与 Harness Engineering 的映射）

| 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](https://github.com/tukuaiai/vibe-coding-cn) | 中文 Vibe Coding 社区指南 |
| [Mitchell Hashimoto: Engineer the Harness](https://mitchellh.com/writing/my-ai-adoption-journey#step-5-engineer-the-harness) | "harness engineering" 命名出处（已收录为文章 #29，深度摘要见 references/articles.md） |

## 🛠️ 开发须知

仓库自带一致性检查脚本 `scripts/check-consistency.sh`，守护数量与保真类漂移，覆盖十三层校验：

- **C1-C2** — `references/articles.md` 文章数 + 下游 4 处引用（README × 2 badges、`prompts/deep-research-tracker.md` 头部、`references/AGENTS.md` 概览）
- **C3** — `concepts/` / `thinking/` / `feedback/` 三个目录的 `*.md` 实际数与 README "X 篇" 声明一致
- **C4** — `works/*-translation.md` 文件数与各处翻译计数声明一致（badges、表格摘要、Phase 5 注释、AGENTS 快照、表格行数）
- **C5** — README 结构树的 `concepts/` 子树列出每一个 `concepts/*.md` 文件
- **C6** — `references/articles.md` 末尾"不计入 N 篇"的 N 与 C1 权威值一致
- **C7** — 三脉络（脉络一/二/三）的 per-track 计数在 4 处下游声明（READMEs 资料库表 × 2、`references/AGENTS.md` 三脉络小标题、`prompts/deep-research-tracker.md` 三脉络明细）保持一致
- **C8** — 翻译流水线本地守卫：当 `translate/<...>/sources/<slug>/source-full.md` 已抓取，对应 `01-analysis.md` 不得再声称"仅摘要页 / 建议补抓全文"。`translate/` 已 gitignore，故 CI 与干净 clone 上自动 SKIP，仅在本地有过程稿时触发
- **C9** — `concepts/` / `thinking/` / `feedback/` 正文不得把文库计数（"N 篇文章 / N 篇翻译 / N 大概念"）当活事实裸写——这类数字在 C2/C7 声明位之外会悄悄腐烂。历史性提法必须带"写作时点 / 当时 / 此前 / 首批 / 首轮 / 截至 / 快照"限定词，否则去掉数字、改链 `references/articles.md`
- **C10** — 图片保真（纯本地、零网络）：每篇译文 frontmatter 必须声明 `sourceFigureCount`，正文嵌图数须 ≥ 声明数，且本地嵌图路径必须真实存在（`null` = 原文不可得、未审计 → SKIP）
- **C11** — markdown 表格形状：受检文件里每行表格的单元格数须与表头一致
- **C12** — `references/articles.md` 每个编号条目必须带 **作者：** 与 **日期：** 字段
- **C13** — 零插图声明须留痕。C10 只能证伪"多报"，`sourceFigureCount: 0` 在本地永远无法被证伪——2026-07-27 就是这个洞放行了一个假 0（原文实有 4 张图）。因此声明 0 的译文必须同时带 `sourceFigureAudit`，值里要有 `YYYY-MM-DD` 核对日期，写清怎么核对、结论是什么

**首次 clone 后启用 pre-commit hook：**

```bash
git config core.hooksPath .githooks
```

启用后，每次 commit 涉及 README、`AGENTS.md`、`references/articles.md`、`references/AGENTS.md`、`prompts/deep-research-tracker.md`、或 `concepts/` / `thinking/` / `feedback/` / `works/` 中的 `*.md` 时会自动跑检查；不涉及则不打扰。

**手动跑：** `bash scripts/check-consistency.sh`

**CI 兜底：** 即使本地未启用 hook，GitHub Actions（`.github/workflows/consistency.yml`）会在每次 push / PR 时跑同一脚本（不做路径过滤，保证分支保护的必需检查总能得到上报）。本地 hook 是开发期反馈，CI 才是真正的合并门。

详情见根 `AGENTS.md` 的"机械化检查"段。

## 🪞 仓库即 harness（自我指涉）

> 这个仓库开始策展自己了。
>
> 收录外部调研不再靠手感——它走一条固化成 skill 的流水线 [`curate-research`](.claude/skills/curate-research/SKILL.md)：评审由并行 agent 自动完成（反馈回路），`scripts/check-consistency.sh` 的 C1–C13 守着计数与保真不漂移（机械护栏），而"收不收进来"始终是一道人类闸门（人类掌舵、智能体执行）。
>
> 于是约束本身成了产品——正是本仓库 [concepts/07-spec-as-product.md](concepts/07-spec-as-product.md) 讲的东西，只不过这次的实验对象是仓库自己。

## 🤝 参与贡献

欢迎通过 Issue 和 PR 参与：
- 补充概念笔记（`concepts/` 中还有待补充的概念）
- 分享你的独立思考（`thinking/`）
- 贡献实践案例（`practice/`）
- 推荐相关资源（`references/`）

## 📞 联系方式

| 渠道 | 链接 |
|------|------|
| GitHub | [@deusyu](https://github.com/deusyu) |
| X (Twitter) | [@0xdeusyu](https://x.com/0xdeusyu) |
| Telegram | [@DeusThink](https://t.me/DeusThink) |
| Telegram 交流群 | [@talkdeusyu](https://t.me/talkdeusyu) |
| Telegram 频道 | [@lovedesuyu](https://t.me/lovedesuyu) |
| Email | [rainman.deus@gmail.com](mailto:rainman.deus@gmail.com) |

## Star History

如果这个项目对您有帮助，请考虑为其点亮一颗 Star ⭐！

[](https://star-history.com/#deusyu/harness-engineering&Date)

## 💛 赞助支持

如果这份学习档案为你节省了时间，欢迎[赞助我的开源工作](https://github.com/sponsors/deusyu)——你的支持让它持续更新、保持免费与开放。

[](https://github.com/sponsors/deusyu)

## 📄 License

MIT

## 2. In-Tree Documentation Chapters (deusyu/harness-engineering)

## File: README.md

中文 | [English](README.en.md)





# Harness Engineering 学习指南

> 一个从概念理解到独立实践的 Harness Engineering 深度学习档案

[](works/harness-engineering-intro-deck/)



## 前言

这是一个不断生长的学习项目。**Harness Engineering**（驭缰工程）是 OpenAI 在 2026 年 2 月提出的工程范式：工程师不再写代码，而是设计环境、明确意图、构建反馈回路，让 AI 智能体可靠地完成工作。

> **人类掌舵，智能体执行。**

本仓库记录了从阅读原文、拆解概念、形成思考、动手实践到输出作品的完整学习过程。希望对同样关注 AI 工程化的朋友有所帮助。

来源：[OpenAI — Harness Engineering: Harnessing Codex in an Agent-First World](https://openai.com/zh-Hans-CN/index/harness-engineering/)

> **注意：** 以下经验分享并非普遍适用，请在具体实践中结合场景，辩证采纳。

## ⚡ 一句话理解

```
传统工程：人类写代码 → 机器执行代码
Harness Engineering：人类设计约束 → 智能体写代码 → 机器执行代码
```

核心转变：**工程师的产出从代码变成了约束系统**——AGENTS.md、架构规则、自定义 linter、反馈回路。

## 🧭 六大核心概念


**1. 仓库即记录系统** — 不在仓库里的东西，对智能体不存在

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

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



**2. 地图而非手册** — AGENTS.md 是目录页，不是百科全书

~100 行的入口文件，指向更深层的文档。渐进式披露：智能体从小入口点开始，被指导下一步该看什么。巨型指令文件的三个死因：挤占上下文、无法维护、无法机械验证。

→ 详见 [concepts/00-overview.md](concepts/00-overview.md)



**3. 机械化执行** — 文档会腐烂，lint 规则不会

自定义 linter + 结构测试 = 不变量的守护者。lint 错误信息里内嵌修复指令，智能体可以自我纠正。在中央层面强制执行边界，在本地层面允许自主权。

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



**4. 智能体可读性** — 优先为智能体的推理能力优化

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

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



**5. 吞吐量改变合并理念** — 纠错成本低，等待成本高

PR 生命周期很短。测试偶发失败通过后续重跑解决。在智能体吞吐量远超人类注意力的系统中，这通常是正确的选择。

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



**6. 熵管理 = 垃圾回收** — 技术债是高息贷款

智能体会复现仓库中已有的模式——包括坏模式。将"黄金规则"编码进仓库，定期后台任务扫描偏差、更新质量评分、发起重构 PR。

→ 详见 [concepts/03-entropy-and-garbage-collection.md](concepts/03-entropy-and-garbage-collection.md)


## 🔑 关键数据点

| 指标 | 数据 |
|------|------|
| 团队规模 | 3 人 → 7 人 |
| 时间跨度 | 5 个月 |
| 代码量 | ~100 万行 |
| PR 数量 | ~1,500 个 |
| 人均日 PR | 3.5 个（扩展后仍在增长） |
| 单次运行时长 | 6+ 小时（通常在人类睡眠时间） |
| 效率估算 | 手工编写的 ~1/10 时间 |

## 📂 仓库结构

```
harness-engineering/
├── README.md              ← 你在这里
├── AGENTS.md              ← 仓库导航入口（给智能体看的）
│
├── concepts/              # Phase 1：概念笔记（8 篇）
│   ├── 00-overview.md     #   六大核心概念总览
│   ├── 01-repo-as-...     #   仓库即记录系统
│   ├── 02-mechanical-...  #   机械化执行
│   ├── 03-entropy-...     #   熵管理与垃圾回收
│   ├── 04-agent-...       #   智能体可读性
│   ├── 05-throughput-...  #   吞吐量改变合并理念
│   ├── 06-harness-...     #   Harness 精确定义（Fowler 控制论扩展）
│   └── 07-spec-as-product.md #   约束即产品（Symphony 延伸）
│
├── thinking/              # Phase 2：独立思考与质疑（11 篇）
├── practice/              # Phase 3：小项目实验（1 个 Ralph Demo）
├── feedback/              # Phase 4：踩坑与迭代心得（1 篇）
├── works/                 # Phase 5：可展示的作品（34 篇翻译 + 1 篇原创 + 2 篇外部中文收录）
├── tools/                 # 工具具像化：降低 6 维复杂度的杠杆库
├── prompts/               # 验证有效的提示词积累
└── references/            # 外部资源索引（74 篇文章深度摘要）
```

每个子目录都有自己的 `AGENTS.md`，说明该目录的用途和写作约定。这本身就是原文「渐进式披露」的实践。

## 🚀 学习路线

- [x] **Phase 1：理解核心概念** — 8 篇概念笔记，覆盖 OpenAI 六大概念 + Fowler 控制论扩展 + Symphony 约束即产品
- [x] **Phase 2：形成自己的观点** — 11 篇独立思考（持续中）
- [x] **Phase 3：选一个小项目实践** — Ralph Demo 完成（321 秒，$0.31）
- [x] **Phase 4：记录反馈迭代** — 1 篇（持续中）
- [x] **Phase 5：输出可展示的作品** — 34 篇专业翻译 + 1 篇原创综合分析 + 2 篇外部中文收录

## 📚 研究资料库

跨三条知识脉络 74 篇文章 + 2 篇延伸阅读：

| 脉络 | 覆盖 | 核心视角 |
|------|------|---------|
| AI 时代的 Harness Engineering | 70 篇 | OpenAI → Fowler → Anthropic → LangChain → Stanford → Claude Code 逆向与源码实锤 → Subagent runtime → 传感器/SPDD/ADLC → 越界·安全审计·质量复盘 → 评测三部曲 → 动态工作流 → 起源考据（Ralph / Hashimoto）与学科汇流 → Codex harness 解剖 → Loop Engineering 三部曲 → 自演化 harness 与 RSI → 形式化验证 → 多智能体并行规模化（Cursor / C compiler）→ 遏制与评测官方方法论 → 行为地图 / DSL / 本地模型 / 外环问责 → 工业级机械移植（Bun）与 harness-模型共演化（HarnessX）→ 长时 harness 奠基与评测环境混杂（Anthropic 存量）→ harness 运维度量与奖励作弊（Cursor 存量）→ 工具 schema 不中立 → 软件工厂之争（Dex Horthy / Osmani）→ 智能体蜂群成本经济学 → 删掉 80% 系统提示词 → 代码评审传感器基准（ReviewBench） |
| 云原生 Harness.io | 2 篇 | CI/CD 平台架构（同名不同义的参照） |
| 效率悖论与能力进化 | 2 篇 | YDD 系统性拆解 + METR 实验后续（测量方法论危机） |
| 延伸阅读 | 2 篇 | Context Engineering、人机协作 |

详见 [references/articles.md](references/articles.md) — 每篇文章含核心论点、关键数据、跨文章关联的深度摘要。

## 📖 翻译作品


**34 篇核心文章的中文翻译**（点击展开）

| 作品 | 原作者 | 来源 |
|------|--------|------|
| ⭐ [渴望了八年，用 AI 三个月造出来](works/maganti-eight-years-building-ai-translation.md) | Lalit Maganti | 个人博客 |
| [用 ReviewBench 评测代码评审智能体](works/langchain-reviewbench-translation.md) | Nick Hollon | LangChain |
| [Claude 5 世代模型的上下文工程新规则](works/anthropic-context-engineering-claude5-translation.md) | Thariq Shihipar | Anthropic / Claude |
| [更好的模型：更差的工具](works/ronacher-better-models-worse-tools-translation.md) | Armin Ronacher | 个人博客 |
| [用 Rust 重写 Bun](works/bun-in-rust-translation.md) | Jarred Sumner | Bun Blog |
| [用一支并行 Claude 团队构建 C 编译器](works/anthropic-c-compiler-translation.md) | Nicholas Carlini | Anthropic |
| [规模化长时自主编码](works/cursor-scaling-agents-translation.md) | Wilson Lin | Cursor |
| [我们如何在各产品中遏制 Claude](works/anthropic-how-we-contain-translation.md) | Max McGuinness 等 | Anthropic |
| [面向自我改进的 Harness Engineering](works/weng-harness-self-improvement-translation.md) | Lilian Weng | Lil'Log |
| [循环工程（Loop Engineering）](works/osmani-loop-engineering-translation.md) | Addy Osmani | 个人博客 |
| [正在到来的循环（The Coming Loop）](works/ronacher-coming-loop-translation.md) | Armin Ronacher | 个人博客 |
| [为每个任务配一套 harness：动态工作流](works/anthropic-dynamic-workflows-translation.md) | Thariq Shihipar 等 | Anthropic / Claude |
| [METR：我们正在更改生产力实验设计](works/metr-uplift-update-translation.md) | Joel Becker 等 | METR |
| [Inside the Scaffold 论文](works/inside-the-scaffold-paper-translation.md) | Benjamin Rombaut | Huawei / arXiv |
| [Meta-Harness 论文](works/meta-harness-paper-translation.md) | Yoonho Lee 等 | Stanford / arXiv |
| [Harness Engineering 正式版](works/fowler-harness-engineering-full-translation.md) | Birgitta Böckeler | Martin Fowler |
| [Harness Engineering 备忘录](works/fowler-harness-engineering-memo-translation.md) | Birgitta Böckeler | Martin Fowler |
| [Encoding Team Standards](works/fowler-encoding-team-standards-translation.md) | Rahul Garg | Martin Fowler |
| [Feedback Flywheel](works/fowler-feedback-flywheel-translation.md) | Rahul Garg | Martin Fowler |
| [Scaling Managed Agents](works/anthropic-managed-agents-translation.md) | Lance Martin 等 | Anthropic |
| [Agent Evaluation Checklist](works/langchain-agent-evaluation-checklist-translation.md) | LangChain 团队 | LangChain |
| [Agent-driven Development](works/github-agent-driven-development-translation.md) | Tyler McGoffin | GitHub |
| [Continual Learning](works/langchain-continual-learning-translation.md) | Harrison Chase | LangChain |
| [Codex 编排开源规范 Symphony](works/openai-codex-symphony-translation.md) | Kotliarskyi 等 | OpenAI |
| [Claude Code 架构（逆向工程版）](works/claude-code-architecture-reverse-translation.md) | Vikash Rungta | Substack |
| [面向编码智能体的可维护性传感器](works/fowler-sensors-translation.md) | Birgitta Böckeler | Martin Fowler |
| [结构化提示驱动开发 SPDD](works/fowler-spdd-translation.md) | Wei Zhang 等 | Martin Fowler |
| [智能体开发生命周期 ADLC](works/langchain-adlc-translation.md) | Harrison Chase | LangChain |
| [Deep Agents 中的解释器](works/deep-agents-interpreter-translation.md) | Hunter Lovell | LangChain |
| [Claude Code 质量回归复盘](works/anthropic-postmortem-translation.md) | Anthropic 工程团队 | Anthropic |
| [Agentic Harness Engineering 论文](works/arxiv-agentic-harness-engineering-translation.md) | Jiahang Lin 等 | 复旦 / arXiv |
| [过度积极的编码智能体 论文](works/arxiv-overeager-coding-agents-translation.md) | Yubin Qu 等 | arXiv |
| [我是如何用 AI 写代码的](works/chris-ai-code-translation.md) | Chris Parsons | 个人博客 |
| [我们如何构建 LangSmith Engine](works/langsmith-engine-translation.md) | Palash Shah | LangChain |



## 🔗 相关项目与资源

### 原始来源

| 资源 | 说明 |
|------|------|
| [OpenAI 原文（中文）](https://openai.com/zh-Hans-CN/index/harness-engineering/) | Harness Engineering 的完整阐述 |

### Ralph 系列 — Harness Engineering 的实战框架

「Ralph Wiggum 循环」是 Harness Engineering 的核心实现模式：让智能体在循环中自主工作直到任务完成。

| 项目 | Stars | 说明 |
|------|-------|------|
| [snarktank/ralph](https://github.com/snarktank/ralph) | 13.6k | 原版 Ralph：bash 脚本反复启动 AI，每次迭代清空上下文，直到 PRD 全部完成。6 条核心信条（Fresh Context、Backpressure、Plan Is Disposable 等） |
| [ralph-orchestrator](https://mikeyobrien.github.io/ralph-orchestrator/) | 2.3k | Rust 进化版：Hat 角色系统 + 事件驱动协调 + 多后端（Claude/Kiro/Gemini/Codex）+ 背压门控 + 持久化记忆 |
| [bmad-ralph](https://github.com/qianxiaofeng/bmad-ralph) | 2 | BMAD 方法论 + Ralph：并行 Claude Code worktree + 三层自愈（retry → restart → diagnose）+ SQLite 状态机 |

### Ralph 六条信条（与 Harness Engineering 的映射）

| 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](https://github.com/tukuaiai/vibe-coding-cn) | 中文 Vibe Coding 社区指南 |
| [Mitchell Hashimoto: Engineer the Harness](https://mitchellh.com/writing/my-ai-adoption-journey#step-5-engineer-the-harness) | "harness engineering" 命名出处（已收录为文章 #29，深度摘要见 references/articles.md） |

## 🛠️ 开发须知

仓库自带一致性检查脚本 `scripts/check-consistency.sh`，守护数量与保真类漂移，覆盖十三层校验：

- **C1-C2** — `references/articles.md` 文章数 + 下游 4 处引用（README × 2 badges、`prompts/deep-research-tracker.md` 头部、`references/AGENTS.md` 概览）
- **C3** — `concepts/` / `thinking/` / `feedback/` 三个目录的 `*.md` 实际数与 README "X 篇" 声明一致
- **C4** — `works/*-translation.md` 文件数与各处翻译计数声明一致（badges、表格摘要、Phase 5 注释、AGENTS 快照、表格行数）
- **C5** — README 结构树的 `concepts/` 子树列出每一个 `concepts/*.md` 文件
- **C6** — `references/articles.md` 末尾"不计入 N 篇"的 N 与 C1 权威值一致
- **C7** — 三脉络（脉络一/二/三）的 per-track 计数在 4 处下游声明（READMEs 资料库表 × 2、`references/AGENTS.md` 三脉络小标题、`prompts/deep-research-tracker.md` 三脉络明细）保持一致
- **C8** — 翻译流水线本地守卫：当 `translate/<...>/sources/<slug>/source-full.md` 已抓取，对应 `01-analysis.md` 不得再声称"仅摘要页 / 建议补抓全文"。`translate/` 已 gitignore，故 CI 与干净 clone 上自动 SKIP，仅在本地有过程稿时触发
- **C9** — `concepts/` / `thinking/` / `feedback/` 正文不得把文库计数（"N 篇文章 / N 篇翻译 / N 大概念"）当活事实裸写——这类数字在 C2/C7 声明位之外会悄悄腐烂。历史性提法必须带"写作时点 / 当时 / 此前 / 首批 / 首轮 / 截至 / 快照"限定词，否则去掉数字、改链 `references/articles.md`
- **C10** — 图片保真（纯本地、零网络）：每篇译文 frontmatter 必须声明 `sourceFigureCount`，正文嵌图数须 ≥ 声明数，且本地嵌图路径必须真实存在（`null` = 原文不可得、未审计 → SKIP）
- **C11** — markdown 表格形状：受检文件里每行表格的单元格数须与表头一致
- **C12** — `references/articles.md` 每个编号条目必须带 **作者：** 与 **日期：** 字段
- **C13** — 零插图声明须留痕。C10 只能证伪"多报"，`sourceFigureCount: 0` 在本地永远无法被证伪——2026-07-27 就是这个洞放行了一个假 0（原文实有 4 张图）。因此声明 0 的译文必须同时带 `sourceFigureAudit`，值里要有 `YYYY-MM-DD` 核对日期，写清怎么核对、结论是什么

**首次 clone 后启用 pre-commit hook：**

```bash
git config core.hooksPath .githooks
```

启用后，每次 commit 涉及 README、`AGENTS.md`、`references/articles.md`、`references/AGENTS.md`、`prompts/deep-research-tracker.md`、或 `concepts/` / `thinking/` / `feedback/` / `works/` 中的 `*.md` 时会自动跑检查；不涉及则不打扰。

**手动跑：** `bash scripts/check-consistency.sh`

**CI 兜底：** 即使本地未启用 hook，GitHub Actions（`.github/workflows/consistency.yml`）会在每次 push / PR 时跑同一脚本（不做路径过滤，保证分支保护的必需检查总能得到上报）。本地 hook 是开发期反馈，CI 才是真正的合并门。

详情见根 `AGENTS.md` 的"机械化检查"段。

## 🪞 仓库即 harness（自我指涉）

> 这个仓库开始策展自己了。
>
> 收录外部调研不再靠手感——它走一条固化成 skill 的流水线 [`curate-research`](.claude/skills/curate-research/SKILL.md)：评审由并行 agent 自动完成（反馈回路），`scripts/check-consistency.sh` 的 C1–C13 守着计数与保真不漂移（机械护栏），而"收不收进来"始终是一道人类闸门（人类掌舵、智能体执行）。
>
> 于是约束本身成了产品——正是本仓库 [concepts/07-spec-as-product.md](concepts/07-spec-as-product.md) 讲的东西，只不过这次的实验对象是仓库自己。

## 🤝 参与贡献

欢迎通过 Issue 和 PR 参与：
- 补充概念笔记（`concepts/` 中还有待补充的概念）
- 分享你的独立思考（`thinking/`）
- 贡献实践案例（`practice/`）
- 推荐相关资源（`references/`）

## 📞 联系方式

| 渠道 | 链接 |
|------|------|
| GitHub | [@deusyu](https://github.com/deusyu) |
| X (Twitter) | [@0xdeusyu](https://x.com/0xdeusyu) |
| Telegram | [@DeusThink](https://t.me/DeusThink) |
| Telegram 交流群 | [@talkdeusyu](https://t.me/talkdeusyu) |
| Telegram 频道 | [@lovedesuyu](https://t.me/lovedesuyu) |
| Email | [rainman.deus@gmail.com](mailto:rainman.deus@gmail.com) |

## Star History

如果这个项目对您有帮助，请考虑为其点亮一颗 Star ⭐！

[](https://star-history.com/#deusyu/harness-engineering&Date)

## 💛 赞助支持

如果这份学习档案为你节省了时间，欢迎[赞助我的开源工作](https://github.com/sponsors/deusyu)——你的支持让它持续更新、保持免费与开放。

[](https://github.com/sponsors/deusyu)

## 📄 License

MIT

---

## File: practice/01-ralph-demo/README.md

# 实验 01：用 Ralph Orchestrator 跑一个完整的编排循环

> 验证概念：帽子系统、背压门控、迭代循环、持久记忆
> 日期：2026-03-31
> 耗时：321 秒 | 费用：$0.31 | 迭代：4 次

## 目标

用 Ralph Orchestrator（Harness Engineering 的开源实现）从零完成一个编码任务，观察编排循环的实际运行过程。

## 环境

- Ralph Orchestrator v2.8.1（`npm install @ralph-orchestrator/ralph-cli`）
- 后端：Claude Code（claude-opus-4-6）
- Hat collection：`builtin:code-assist`

## 步骤

### 1. 安装 Ralph

```bash
npm install @ralph-orchestrator/ralph-cli
```

### 2. 初始化项目

```bash
mkdir -p /tmp/ralph-demo && cd /tmp/ralph-demo
ralph init --backend claude
```

生成 `ralph.yml`，核心配置：

```yaml
cli:
  backend: "claude"
event_loop:
  prompt_file: "PROMPT.md"
  completion_promise: "LOOP_COMPLETE"
  max_iterations: 100
```

### 3. 编写任务描述

人类唯一的产出——`PROMPT.md`：

```markdown
# Task: Build a CLI word counter

Create a simple Python CLI tool called `wc.py` that:
1. Accepts a filename as argument
2. Counts lines, words, and characters
3. Prints the result in a formatted table

Include a test file `test_wc.py` using pytest.

When all tests pass, output LOOP_COMPLETE.
```

### 4. 启动编排循环

```bash
ralph run -c ralph.yml -H builtin:code-assist
```

## 循环过程

Ralph 自动完成了 4 轮迭代，每轮戴不同的"帽子"：

| 迭代 | 帽子 | 做了什么 |
|------|------|---------|
| 1 | **Planner** | 分析 PROMPT.md → 拆解任务 → 创建 task → 写入 scratchpad → 交给 Builder |
| 2 | **Builder** | 先写 `test_wc.py`（7 个测试，全红）→ 写 `wc.py` 实现 → 修 char count bug → 7/7 全绿 |
| 3 | **Critic** | 独立重跑 pytest → 手动验证 5 种 CLI 路径（正常/无参数/文件缺失/空文件/无换行符） |
| 4 | **Finalizer** | 确认无遗留任务 → 更新 scratchpad → emit `LOOP_COMPLETE` → 循环终止 |

## 产出

### wc.py（49 行）

```python
#!/usr/bin/env python3
"""CLI word counter — counts lines, words, and characters in a file."""

import sys

def count(text: str) -> tuple[int, int, int]:
    lines = text.count("\n")
    words = len(text.split())
    chars = len(text)
    return lines, words, chars

def format_table(filename: str, lines: int, words: int, chars: int) -> str:
    col_w = max(len(str(v)) for v in (lines, words, chars, "Lines", "Words", "Chars"))
    sep = "+" + "-" * (col_w + 2) + "+" + "-" * (col_w + 2) + "+"
    row = lambda label, val: f"| {label:<{col_w}} | {val:>{col_w}} |"
    return "\n".join([
        f"File: {filename}",
        sep,
        row("Lines", lines),
        row("Words", words),
        row("Chars", chars),
        sep,
    ])

def main() -> int:
    if len(sys.argv) < 2:
        print("Usage: wc.py <filename>", file=sys.stderr)
        return 1
    filename = sys.argv[1]
    try:
        with open(filename) as f:
            text = f.read()
    except FileNotFoundError:
        print(f"Error: file not found: {filename}", file=sys.stderr)
        return 1
    lines, words, chars = count(text)
    print(format_table(filename, lines, words, chars))
    return 0

if __name__ == "__main__":
    sys.exit(main())
```

### test_wc.py（7 个测试）

| 测试类 | 测试 | 验证 |
|--------|------|------|
| TestNormalFile | counts_lines_words_chars | 计数正确性 |
| TestNormalFile | output_is_formatted_table | 输出格式 |
| TestEmptyFile | empty_file_all_zeros | 边界：空文件 |
| TestMissingFile | missing_file_exits_nonzero | 错误退出码 |
| TestMissingFile | missing_file_prints_error | 错误信息 |
| TestNoArgs | no_args_exits_nonzero | 无参数退出码 |
| TestNoArgs | no_args_prints_usage | 使用说明 |

### CLI 运行效果

```
$ python3 wc.py wc.py
File: wc.py
+-------+-------+
| Lines |    49 |
| Words |   166 |
| Chars |  1339 |
+-------+-------+
```

## scratchpad.md（跨迭代的持久记忆）

Ralph 在 `.ralph/agent/scratchpad.md` 中记录了每轮迭代的决策和结果，供后续迭代读取：

```
## Iteration 1 — Planner: Initial Decomposition
Objective: Build CLI word counter (wc.py + test_wc.py).
Plan: 2 steps. Step 1 covers both implementation and tests. Step 2 is manual verification.

## Iteration 2 — Builder: Implement wc.py + test_wc.py
- Wrote test_wc.py first (TDD)
- Fixed test char count (24 not 23)
- All 7 tests pass. Emitting review.ready.

## Iteration 3 — Critic: Fresh-Eyes Review
- 7/7 pytest tests pass (re-verified independently)
- All CLI paths verified
- Verdict: PASSED

## Iteration 4 — Finalizer: Whole-Prompt Gate
- All objective requirements met
- Verdict: LOOP_COMPLETE
```

## 映射到 Harness Engineering 核心概念

| 观察到的行为 | 对应概念 |
|-------------|---------|
| PROMPT.md 是唯一的人类输入 | **仓库即记录系统** — 任务描述必须在文件中，不在脑子里 |
| Planner/Builder/Critic/Finalizer 角色分离 | **帽子系统** — 每个角色有独立职责，不越界 |
| Builder 写完代码 → 必须测试通过才能继续 | **背压门控** — 不规定怎么做，但拒绝坏结果 |
| Critic 独立重跑测试 + 手动验证 CLI | **机械化执行** — 自动化验证，不靠自我评估 |
| scratchpad.md 跨迭代传递上下文 | **持久记忆** — 磁盘是状态，Git 是记忆 |
| `LOOP_COMPLETE` 触发循环终止 | **完成信号** — 明确的退出条件，不靠猜测 |
| Builder 在第 2 轮自己发现并修了 char count bug | **迭代自愈** — 测试失败 → 自动修复 → 重新验证 |

## 归档文件

实验原始运行在 `/tmp/ralph-demo`（ephemeral 路径）。为践行"仓库即记录系统"，产物已落盘到本目录：[PROMPT.md](PROMPT.md)、[ralph.yml](ralph.yml)、[wc.py](wc.py)、[test_wc.py](test_wc.py)（复原件）。各文件来源与复验方式见 [AGENTS.md](AGENTS.md)；工具本身的主张与失效场景见 [tools/harnesses/ralph-orchestrator.md](../../tools/harnesses/ralph-orchestrator.md)。

--- METRICS ---
- Files Extracted: 3
- Estimated Token Budget: ~7442 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/deusyu/harness-engineering