中文 | English

Harness Engineering 学习指南

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

封面取自仓库自产的项目介绍 PPT + 海报——open-kimi-ppt skill 生成，PPTD 源同仓可编辑

前言

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

人类掌舵，智能体执行。

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

来源：OpenAI — Harness Engineering: Harnessing Codex in an Agent-First World

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

⚡ 一句话理解

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

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

🧭 六大核心概念

🔑 关键数据点

📂 仓库结构

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：可展示的作品（40 篇翻译 + 1 篇原创 + 2 篇外部中文收录）
├── tools/                 # 工具具像化：降低 6 维复杂度的杠杆库
├── prompts/               # 验证有效的提示词积累
└── references/            # 外部资源索引（79 篇文章深度摘要）

每个子目录都有自己的 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：输出可展示的作品 — 40 篇专业翻译 + 1 篇原创综合分析 + 2 篇外部中文收录

📚 研究资料库

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

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

📖 翻译作品

🔗 相关项目与资源

原始来源

Ralph 系列 — Harness Engineering 的实战框架

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

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

社区与延伸

🛠️ 开发须知

仓库自带一致性检查脚本 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//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 核对日期，写清怎么核对、结论是什么
• C14 — 文档站驭缰完整性：站点侧边栏与所有展示计数必须由 .vitepress/sidebar.mjs 构建时从文件系统派生，站点源码（index.md、.vitepress/**）不得手写计数；node .vitepress/sidebar.mjs --verify 断言每个一等内容页在生成的侧边栏中恰好出现一次，并拒绝仓库内出现任何 symlink（软链会把仓库外文件带进公开产物）。构建产物侧另有 scripts/verify-dist.mjs 断言发布页面与 .md 副本一一对应、副本内相对链接与图片可达、dist 无 symlink

首次 clone 后启用 pre-commit hook：

git config core.hooksPath .githooks

启用后，每次 commit 涉及 README、AGENTS.md、references/articles.md、references/AGENTS.md、index.md、.vitepress/、scripts/check-consistency.sh、或 concepts/ / thinking/ / feedback/ / works/ / practice/ / tools/ / prompts/ 下（含嵌套目录）的 *.md 时会自动跑检查；此外任何路径下 stage 了 symlink 会被直接拒绝提交（C14 全仓禁令，按暂存区状态判定）。不涉及则不打扰。

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

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

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

🪞 仓库即 harness（自我指涉）

这个仓库开始策展自己了。

收录外部调研不再靠手感——它走一条固化成 skill 的流水线 curate-research：评审由并行 agent 自动完成（反馈回路），scripts/check-consistency.sh 的 C1–C14 守着计数与保真不漂移（机械护栏），而"收不收进来"始终是一道人类闸门（人类掌舵、智能体执行）。

于是约束本身成了产品——正是本仓库 concepts/07-spec-as-product.md 讲的东西，只不过这次的实验对象是仓库自己。

🤝 参与贡献

欢迎通过 Issue 和 PR 参与：

• 补充概念笔记（concepts/ 中还有待补充的概念）
• 分享你的独立思考（thinking/）
• 贡献实践案例（practice/）
• 推荐相关资源（references/）

📞 联系方式

内容勘误、补充或资源推荐，请按上一节提 Issue 或 PR。交流讨论或其他事情，可以通过下面这些方式找到我：

频道「婴宁」记录我的见闻，以及和 AI 碰撞出的思考；交流群是它的讨论区，也欢迎来聊 Harness Engineering。

Star History

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

💛 赞助支持

如果这份学习档案为你节省了时间，欢迎赞助我的开源工作——你的支持让它持续更新、保持免费与开放。

📄 License

MIT