walkinglabs/learn-harness-engineering
Learn Harness Engineering 是一门基于项目的课程，提供12讲和6个动手项目，教授如何为AI编码agent构建环境、状态管理、验证和控制机制。课程核心参考资料包括OpenAI和Anthropic关于harness工程的文章。课程涵盖指令、状态、验证、范围和会话生命周期五个子系统，并通过一个Electron个人知识库桌面应用作为顶点项目。课程支持13种语言，采用MIT许可证。
地球图标 本课程提供 13 种语言：English, 简体中文, 繁體中文, 日本語, 한국어, Español, Français, Русский, Deutsch, العربية, Tiếng Việt, Oʻzbekcha, Türkçe。请从上方徽章中选择您的语言。
Learn Harness Engineering 是一门专注于 AI 编码 agent 工程的课程。我们深入研究并综合了业界最先进的 Harness 工程理论与实践。我们的核心参考资料包括：
- OpenAI: Harness engineering: leveraging Codex in an agent-first world
- Anthropic: Effective harnesses for long-running agents
- Anthropic: Harness design for long-running application development
- Awesome Harness Engineering
想快速上手？
skills/harness-creator/技能可以帮助您在几分钟内为您的项目搭建一个生产级 harness（AGENTS.md、功能列表、init.sh、验证工作流）。
目录
- ✨ 视觉预览
- Harness 工程的实际含义
- 快速上手：立即改进你的 Agent
- 顶点项目：一个真实应用
- 学习路径
- 课程大纲
- 技能
- 其他课程
✨ 视觉预览
🏠 课程主页
全面的课程大纲和核心理念介绍，提供清晰的入门路径。
课程主页预览
📖 沉浸式讲座
深入探讨实际痛点与动手项目（如项目 01），提供沉浸式学习体验。
课程讲座预览
🗂️ 即用型资源库
旨在解决多轮 AI agent 开发中常见问题（如上下文丢失、过早完成任务）的模板和参考配置。
资源库预览
PDF 课程手册
该仓库现在包含课程内容的 PDF 构建管道。
- 运行
npm run pdf:build在本地生成当前配置的 PDF 课程手册。 - 输出文件写入
artifacts/pdfs/目录。 - 如需刷新 README 预览图片，请运行
npm run screenshots:readme。 - GitHub Actions 工作流
release-course-pdfs.yml可以构建 PDF 并将其发布到 GitHub Releases。
模型很聪明，Harness 让它可靠
大多数人都会通过惨痛教训认识到一个残酷的事实：如果你没有围绕它构建一个合适的环境，世界上最强大的模型也会在实际工程任务中失败。
你可能也亲眼见过这种情况。你在仓库里给 Claude 或 GPT 一个任务。它开始得很好——读取文件、编写代码、看起来很高效。然后出问题了。它跳过了某个步骤。它破坏了测试。它说“完成了”，但实际上什么都没用。你花在清理上的时间比自己做还要多。
这不是模型的问题。这是 harness 的问题。
证据很明确。Anthropic 进行了一项对照实验：相同的模型（Opus 4.5），相同的提示（“构建一个 2D 复古游戏编辑器”）。没有 harness，它在 20 分钟内花费了 9 美元，产生了一个无法运行的东西。有了完整的 harness（规划器 + 生成器 + 评估器），它在 6 小时内花费了 200 美元，构建了一个真正可以玩的游戏。模型没有变。变的是 harness。
OpenAI 在 Codex 上也报告了同样的情况：在一个良好 harness 化的仓库中，同一个模型从“不可靠”变成了“可靠”。这不是边际改进——而是质的转变。
本课程教你如何构建那个环境。
HARNESS 模式
============
你 --> 给出任务 --> Agent 读取 harness 文件 --> Agent 执行
|
harness 控制每一步：
|
+--> 指令：做什么，按什么顺序
+--> 范围：一次一个功能，不越界
+--> 状态：进度日志、功能列表、git 历史
+--> 验证：测试、lint、类型检查、冒烟测试
+--> 生命周期：开始时初始化，结束时清理状态
|
v
Agent 仅在验证通过时停止
Harness 工程的实际含义
Harness 工程是关于在模型周围构建一个完整的工作环境，使其产生可靠的结果。这不是关于编写更好的提示。而是关于设计模型在其内部运行的系统。
一个 harness 包含五个子系统：
┌────────────────────────────────────────────────────────────────┐
│ HARNESS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │
│ │ 指令 │ │ 状态 │ │ 验证 │ │
│ │ │ │ │ │ │ │
│ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
│ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
│ │ feature_list │ │ git log │ │ smoke runs │ │
│ │ docs/ │ │ session hand │ │ e2e pipeline │ │
│ └──────────────┘ └──────────────┘ └────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
│ │ 范围 │ │ 会话生命周期 │ │
│ │ │ │ │ │
│ │ 一次一个功能 │ │ 开始时运行 init.sh │ │
│ │ 定义完成标准 │ │ 结束时执行清理状态检查清单 │ │
│ │ │ │ 为下一次会话留下交接记录 │ │
│ │ │ │ 仅在安全恢复时提交 │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────┘
MODEL 决定写什么代码。
HARNESS 控制何时、何地以及如何写代码。
Harness 不会让模型更聪明。
它让模型的输出变得可靠。
每个子系统都有一个任务：
- 指令 — 告诉 agent 做什么、按什么顺序做，以及在开始前要读什么。不是一个巨大的文件；而是一个渐进式披露结构，agent 按需导航。
- 状态 — 跟踪已完成、进行中和下一步要做什么。持久化到磁盘，以便下一次会话能精确地从上次中断的地方继续。
- 验证 — 只有通过的测试套件才算证据。没有可运行的证明，agent 不能宣布胜利。
- 范围 — 将 agent 限制为一次只处理一个功能。不越界。不半途而废三个事情。不重写功能列表来隐藏未完成的工作。
- 会话生命周期 — 开始时初始化。结束时清理。为下一次会话留下一个干净的重新启动路径。
为什么这门课程存在
问题不在于“模型能写代码吗？”它们能。问题是：它们能否在真实仓库中、跨多个会话、在没有持续人工监督的情况下，可靠地完成真实的工程任务？
目前，答案是：没有 harness 就不行。
没有 HARNESS 有 HARNESS
============== ============
会话 1: agent 写代码 会话 1: agent 读取指令
agent 破坏测试 agent 运行 init.sh
agent 说“完成了” agent 处理一个功能
你手动修复 agent 在声称完成前验证
agent 更新进度日志
会话 2: agent 从头开始 agent 提交干净状态
agent 没有记忆
之前发生了什么 会话 2: agent 读取进度日志
agent 重做工作 agent 精确地从上次中断处继续
或者完全做别的事情 agent 继续未完成的功能
你再次修复 你审查，而不是救援
结果：你花在清理上的时间 结果：agent 完成工作，
比自己做还要多 你验证结果
这门课程真正关心的问题：
- 哪些 harness 设计能提高任务完成率？
- 哪些设计能减少返工和不正确的完成？
- 哪些机制能让长时间运行的任务稳步推进？
- 哪些结构能在多次 agent 运行后保持系统的可维护性？
课程大纲与文档
如需完整的课程资料，请访问 文档网站。
课程分为三个部分：
- 讲座：12 个概念单元，解释 harness 工程背后的理论。
- 项目：6 个动手项目，从零开始构建一个 agent 工作空间。
- 资源库：可直接复制的模板（
AGENTS.md、feature_list.json、init.sh等），可立即用于你自己的仓库。
快速上手：立即改进你的 Agent
你不需要读完所有 12 讲才能开始获得价值。如果你已经在实际项目中使用编码 agent，以下是如何立即改进它的方法。
思路很简单：与其只写提示，不如给 agent 一组结构化文件，定义要做什么、已经做了什么以及如何验证工作。这些文件存放在你的仓库中，因此每次会话都从相同的状态开始。
你的项目根目录
├── AGENTS.md <-- agent 的操作手册
├── CLAUDE.md <-- (替代方案，如果使用 Claude Code)
├── init.sh <-- 运行安装 + 验证 + 启动
├── feature_list.json <-- 存在哪些功能，哪些已完成
├── claude-progress.md <-- 每次会话发生了什么
└── src/ <-- 你的实际代码
从资源库获取入门模板，然后放入你的项目。就这样。四个文件，你的 agent 会话将比仅靠提示运行稳定得多。
顶点项目：一个真实应用
所有六个课程项目都围绕同一个产品：一个基于 Electron 的个人知识库桌面应用。
┌──────────────────────────────────────────────────────┐
│ 知识库桌面应用 │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐ │
│ │ 文档列表 │ │ 问答面板 │ │
│ │ │ │ │ │
│ │ doc-001.md │ │ 问：什么是 harness 工程？ │ │
│ │ doc-002.md │ │ 答：围绕 agent 模型构建的 │ │
│ │ doc-003.md │ │ 环境... │ │
│ │ ... │ │ [引用: doc-002.md] │ │
│ └──────────────┘ └──────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 状态栏：42 个文档 | 38 个已索引 | 上次同步 3 分钟 │ │
│ └─────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
核心功能：
├── 导入本地文档
├── 管理文档库
├── 处理和索引文档
├── 对导入内容运行 AI 驱动的问答
└── 返回带有引用的有依据答案
选择这个项目是因为它结合了强大的实用价值、足够的真实产品复杂性，以及观察 harness 改进前后对比的良好场景。
每个课程项目的起点/解决方案都是这个 Electron 应用在该演化阶段的完整副本。P(N+1) 的起点源自 P(N) 的解决方案——随着你的 harness 技能增长，应用也随之演化。
学习路径
本课程设计为按顺序学习。每个阶段都建立在前一个阶段之上。
阶段 1：看到问题 阶段 2：结构化仓库
======================== ==========================
L01 强模型 ≠ 可靠执行 L03 仓库作为单一
事实来源
L02 Harness 的实际含义
L04 将指令拆分到多个
| 文件中，而非一个巨大文件
v
P01 纯提示 vs. |
规则优先对比 v
P02 Agent 可读的工作空间
阶段 3：连接会话 阶段 4：反馈与范围
========================== =========================
L05 跨会话保持上下文活跃 L07 划定清晰的任务边界
L06 每次 agent 会话前 L08 功能列表作为 harness
进行初始化 原语
|
| v
v P04 运行时反馈以纠正
P03 多会话连续性 agent 行为
阶段 5：验证 阶段 6：整合所有内容
===================== ============================
L09 阻止 agent 过早 L11 使 agent 的运行时
宣布胜利 可观察
L10 完整管道运行 = L12 每次会话结束时
真正的验证 进行干净的交接
| |
v v
P05 Agent 验证自己的工作 P06 构建一个完整的 harness
(顶点项目)
如果兼职学习，每个阶段大约需要一周。如果你想更快，阶段 1-3 可以在一个长周末内完成。
课程大纲
讲座 — 12 个概念单元，每个回答一个核心问题
在文档网站上阅读每讲的全文。
| 会话 | 问题 | 核心思想 |
|---|---|---|
| L01 | 为什么强模型仍然在实际任务中失败？ | 基准测试与实际工程之间的能力差距 |
| L02 | “Harness”到底是什么意思？ | 五个子系统：指令、状态、验证、范围、生命周期 |
| L03 | 为什么仓库必须是单一事实来源？ | 如果 agent 看不到，它就不存在 |
| L04 | 为什么一个巨大的指令文件会失败？ | 渐进式披露：给一张地图，而不是一本百科全书 |
| L05 | 为什么长时间运行的任务会失去连续性？ | 将进度持久化到磁盘；从上次中断处继续 |
| L06 | 为什么初始化需要自己的阶段？ | 在 agent 开始工作前验证环境是否健康 |
| L07 | 为什么 agent 会越界且完成不足？ | 一次一个功能；明确的完成定义 |
| L08 | 为什么功能列表是 harness 原语？ | 机器可读的范围边界，agent 无法忽略 |
| L09 | 为什么 agent 会过早宣布胜利？ | 验证差距：信心 ≠ 正确性 |
| L10 | 为什么端到端测试会改变结果？ | 只有完整管道运行才算真正的验证 |
| L11 | 为什么可观测性属于 harness 内部？ | 如果你看不到 agent 做了什么，你就无法修复它破坏的东西 |
| L12 | 为什么每次会话都必须留下干净状态？ | 下一次会话的成功取决于本次会话的清理 |
项目 — 6 个动手项目，将讲座方法应用于同一个 Electron 应用
| 项目 | 你做什么 | Harness 机制 |
|---|---|---|
| P01 | 对同一任务运行两次：纯提示 vs. 规则优先 | 最小 harness：AGENTS.md + init.sh + feature_list.json |
| P02 | 重构仓库，使 agent 可以读取它 | Agent 可读的工作空间 + 持久化状态文件 |
| P03 | 让 agent 从上次中断处继续 | 进度日志 + 会话交接 + 多会话连续性 |
| P04 | 阻止 agent 做得太多或太少 | 运行时反馈 + 范围控制 + 增量索引 |
| P05 | 让 agent 验证自己的工作 | 自我验证 + 有依据的问答 + 基于证据的完成 |
| P06 | 从零开始构建一个完整的 harness（顶点项目） | 完整 harness：所有机制 + 可观测性 + 消融研究 |
项目演化
=================
P01 纯提示 vs. 规则优先 你看到问题
|
v
P02 Agent 可读的工作空间 你重构仓库
|
v
P03 多会话连续性 你连接会话
|
v
P04 运行时反馈与范围 你添加反馈循环
|
v
P05 自我验证 你让 agent 检查自己
|
v
P06 完整 harness（顶点项目） 你构建完整系统
每个项目的解决方案成为下一个项目的起点。
应用在演化。你的 harness 技能随之增长。
资源库
- English — 模板、检查清单和方法参考
- 简体中文 — 中文模板、清单和方法参考
- 繁體中文 — 繁體中文範本、清單和方法參考
- 日本語 — テンプレート、チェックリスト、方法リファレンス
- 한국어 — 템플릿, 체크리스트, 방법 참고 자료
- Español — plantillas, listas de verificación y referencias
- Français — modèles, listes de contrôle et références
- Русский — шаблоны, чек-листы и справочники
- Deutsch — Vorlagen, Checklisten und Referenzen
- العربية — قوالب، قوائم تحقق ومراجع
- Tiếng Việt — mẫu, danh sách kiểm tra và tài liệu tham khảo
- Oʻzbekcha — andozalar, tekshiruv roʻyxatlari va maʼlumotnomalar
Agent 会话生命周期
本课程的核心思想之一：agent 的会话应遵循结构化的生命周期，而不是自由放任。 以下是它的样子：
AGENT 会话生命周期
======================
┌──────────────────────────────────────────────────────────────────┐
│ 开始 │
│ │
│ 1. Agent 读取 AGENTS.md / CLAUDE.md │
│ 2. Agent 运行 init.sh (安装、验证、健康检查) │
│ 3. Agent 读取 claude-progress.md (上次发生了什么) │
│ 4. Agent 读取 feature_list.json (已完成什么，下一步做什么) │
│ 5. Agent 检查 git log (最近的更改) │
│ │
│ 选择 │
│ │
│ 6. Agent 精确选择一个未完成的功能 │
│ 7. Agent 只处理那个功能 │
│ │
│ 执行 │
│ │
│ 8. Agent 实现该功能 │
│ 9. Agent 运行验证 (测试、lint、类型检查) │
│ 10. 如果验证失败：修复并重新运行 │
│ 11. 如果验证通过：记录证据 │
│ │
│ 收尾 │
│ │
│ 12. Agent 更新 claude-progress.md │
│ 13. Agent 更新 feature_list.json │
│ 14. Agent 记录仍然损坏或未验证的内容 │
│ 15. Agent 提交 (仅在安全恢复时) │
│ 16. Agent 为下一次会话留下干净的重新启动路径 │
│ │
└──────────────────────────────────────────────────────────────────┘
Harness 控制此生命周期中的每一次转换。
Model 决定在每个步骤写什么代码。
没有 harness，步骤 9 变成“agent 说看起来没问题。”
有了 harness，步骤 9 是“测试通过，lint 干净，类型检查通过。”
适用人群
本课程适用于：
- 已经在使用编码 agent 并希望获得更好稳定性和质量的工程师
- 希望系统理解 harness 设计的研究人员或构建者
- 需要了解环境设计如何影响 agent 性能的技术负责人
本课程不适用于：
- 寻找零代码 AI 入门的人
- 只关心提示而不打算构建实际实现的人
- 不准备让 agent 在真实仓库中工作的学习者
要求
这是一门你实际运行编码 agent 的课程。
你至少需要以下工具之一：
- Claude Code
- Codex
- 另一个支持文件编辑、命令执行和多步骤任务的 IDE 或 CLI 编码 agent
本课程假设你可以：
- 打开本地仓库
- 允许 agent 编辑文件
- 允许 agent 运行命令
- 检查输出并重新运行任务
如果你没有这样的工具，你仍然可以阅读课程内容，但无法按预期完成项目。
本地预览
此仓库使用 VitePress 作为文档查看器。
npm install
npm run docs:dev # 带热重载的开发服务器
npm run docs:build # 生产构建
npm run docs:preview # 预览构建的站点
然后在浏览器中打开 VitePress 输出的本地 URL。
先决条件
必需：
- 熟悉终端、git 和本地开发环境
- 能够至少用一种常见的应用栈读写代码
- 基本的软件调试经验（阅读日志、测试和运行时行为）
- 有足够的时间投入到以实现为重点的课程作业中
有帮助但不是必需的：
- 有 Electron、桌面应用或本地优先工具的经验
- 有测试、日志记录或软件架构的背景
- 之前接触过 Codex、Claude Code 或类似的编码 agent
核心参考资料
主要：
- OpenAI: Harness engineering: leveraging Codex in an agent-first world
- Anthropic: Effective harnesses for long-running agents
- Anthropic: Harness design for long-running application development
- OpenAI: Unrolling the Codex agent loop
- Anthropic: Demystifying evals for AI agents
- LangChain: Improving Deep Agents with harness engineering
- Thoughtworks / Martin Fowler: Harness engineering for coding agent users
- Cursor: Continually improving our agent harness
请参阅 docs/en/resources/reference/ 中的完整分层参考列表。
仓库结构
learn-harness-engineering/
├── docs/ # VitePress 文档站点
│ ├── lectures/ # 12 讲 (index.md + code/ 示例)
│ │ ├── lecture-01-*/
│ │ ├── lecture-02-*/
│ │ └── ... (共 12 个)
│ ├── projects/ # 6 个项目描述
│ │ ├── project-01-*/
│ │ └── ... (共 6 个)
│ └── resources/ # 多语言模板和参考资料
│ ├── en/ # 英文模板、检查清单、指南
│ ├── zh/ # 中文模板、检查清单、指南
│ ├── ru/ # 俄文模板、检查清单、指南
│ └── vi/ # 越南文模板、检查清单、指南
├── projects/
│ ├── shared/ # 共享的 Electron + TypeScript + React 基础
│ └── project-NN/ # 每个项目的 starter/ 和 solution/ 目录
├── skills/ # 可复用的 AI agent 技能
│ └── harness-creator/ # Harness 工程技能
├── package.json # VitePress + 开发工具
└── CLAUDE.md # 此仓库的 Claude Code 指令
课程组织方式
- 每讲聚焦于一个问题
- 课程包含 6 个项目
- 每个项目要求 agent 做实际工作
- 每个项目比较弱 harness 与强 harness 的结果
- 重要的是测量到的差异，而不是写了多少文档
技能
此仓库还包含可复用的 AI agent 技能，你可以直接安装到你的 IDE 或 agent 工作空间中。
- harness-creator: 一个技能，帮助你在几分钟内为你的项目搭建一个生产级 harness。
其他课程
我们的团队还创建了其他课程！来看看：
Hands-on Modern RL: 一个开源的动手课程，弥合从基础 RL 概念到 LLM 对齐、RLVR 和高级 Agentic 系统之间的差距。
Star 历史
致谢
本课程的灵感来源于 learn-claude-code 并借鉴了其思想——这是一份从零开始构建 agent 的渐进式指南，从单个循环到隔离的自主执行。