一门基于项目的课程，教你构建让 AI 编程代理可靠工作的环境、状态管理、验证和控制机制。
Learn Harness Engineering 是一门专注于 AI 编程代理工程化的课程。我们深入研究和综合了业界最先进的 Harness Engineering 理论与实践。我们的核心参考资料包括：
- 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、验证工作流）。
全面的课程大纲和核心理念介绍，为你提供清晰的学习起点。
深入剖析真实痛点，配合动手项目（如项目 01），带来沉浸式学习体验。
专为解决多轮 AI 代理开发中的常见问题而设计的模板和参考配置，例如上下文丢失和过早完成任务。
本仓库包含课程内容的 PDF 构建流水线。
- 运行
npm run pdf:build可在本地生成英文和中文 PDF。 - 输出文件写入
artifacts/pdfs/目录。 - 如果你想刷新 README 预览图片，可运行
npm run screenshots:readme。 - GitHub Actions 工作流
release-course-pdfs.yml可以构建 PDF 并发布到 GitHub Releases。
大多数人都曾付出过惨痛代价才认识到一个残酷的事实：世界上最强大的模型，如果你不为它构建合适的环境，它在真正的工程任务上依然会失败。
你可能亲身经历过。你给 Claude 或 GPT 一个仓库中的任务。开始一切顺利——读文件、写代码、看起来很高效。然后出了问题。它跳过了一个步骤。它破坏了一个测试。它说"完成了"，但实际上什么都不能用。你花在清理上的时间比自己做还多。
这不是模型的问题。这是 Harness 的问题。
证据很明确。Anthropic 做了一个对照实验：同一个模型（Opus 4.5），同一个提示词（"构建一个 2D 复古游戏编辑器"）。没有 Harness 时，它在 20 分钟内花了 9 美元，产出了一个不能用的东西。有了完整的 Harness（规划器 + 生成器 + 评估器），它在 6 小时内花了 200 美元，构建了一个你真的能玩的游戏。模型没有变。变的是 Harness。
OpenAI 在 Codex 上也报告了同样的事情：在一个良好 Harness 的仓库中，同一个模型从"不可靠"变成了"可靠"。这不是边际提升——这是质变。
这门课程教你如何构建那个环境。
HARNESS 模式
=============
你 --> 给出任务 --> 代理读取 harness 文件 --> 代理执行
|
harness 管控每一个步骤：
|
+--> 指令：做什么，按什么顺序
+--> 范围：一次一个功能，不越界
+--> 状态：进度日志、功能列表、git 历史
+--> 验证：测试、lint、类型检查、冒烟测试
+--> 生命周期：开始时初始化，结束时清理状态
|
v
代理只在验证通过时
才会停止
Harness Engineering 是围绕模型构建一个完整的工作环境，使其产生可靠的结果。它不是关于写更好的提示词。它是关于设计模型运行其中的系统。
一个 Harness 有五个子系统：
┌─────────────────────────────────────────────────────────────────┐
│ HARNESS 系统 │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ 指令 │ │ 状态 │ │ 验证 │ │
│ │ │ │ │ │ │ │
│ │ AGENTS.md │ │ progress.md │ │ 测试 + lint │ │
│ │ CLAUDE.md │ │ feature_list │ │ 类型检查 │ │
│ │ feature_list │ │ git log │ │ 冒烟测试 │ │
│ │ docs/ │ │ 会话交接 │ │ 端到端流水线 │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
│ │ 范围 │ │ 会话生命周期 │ │
│ │ │ │ │ │
│ │ 一次一个功能 │ │ 开始时运行 init.sh │ │
│ │ 明确完成的 │ │ 结束时执行清理检查清单 │ │
│ │ 定义 │ │ 为下一次会话留下交接说明 │ │
│ │ │ │ 只在安全可恢复时才提交 │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
模型决定写什么代码。
HARNESS 管控何时、何地以及如何写。
Harness 不会让模型更聪明。
它让模型的输出更可靠。
每个子系统各司其职：
- 指令——告诉代理做什么、按什么顺序、开始前读什么。不是一个巨大的文件，而是一个渐进式披露结构，代理按需导航。
- 状态——追踪已完成的工作、正在进行的工作和下一步。持久化到磁盘，使下一次会话可以准确地从上次离开的地方继续。
- 验证——只有通过的测试套件才算数。代理不能在没有可运行证据的情况下宣布完成。
- 范围——将代理限制在一次只做一个功能。不越界。不同时做三个半成品。不重写功能列表来掩盖未完成的工作。
- 会话生命周期——开始时初始化。结束时清理。为下一次会话留下干净的重启路径。
问题不是"模型能不能写代码？"它们能。问题是：它们能否在没有持续人工监督的情况下，在真实的仓库中、跨多个会话、可靠地完成真正的工程任务？
目前，答案是：没有 Harness 就不行。
没有 HARNESS 有 HARNESS
============== ===========
会话 1：代理写代码 会话 1：代理读取指令
代理破坏了测试 代理运行 init.sh
代理说"完成了" 代理只做一个功能
你手动修复 代理在声明完成前先验证
代理更新进度日志
会话 2：代理从零开始 代理提交干净的状态
代理不记得之前
发生了什么 会话 2：代理读取进度日志
代理重做已完成的工作 代理准确从上次离开处继续
或者做完全不同的事情 代理继续未完成的功能
你再次修复 你是审查者，不是救援者
结果：你花的时间比 结果：代理完成工作，
自己做还多 你验证结果
这门课程真正关心的问题：
- 哪些 Harness 设计能提高任务完成率？
- 哪些设计能减少返工和错误完成？
- 哪些机制能让长时间运行的任务稳步推进？
- 哪些结构能让系统在多次代理运行后仍然可维护？
完整的课程材料，请访问**文档网站**。
课程分为三个部分：
- 讲座：12 个概念单元，讲解 Harness Engineering 背后的理论。
- 项目：6 个动手项目，你将从零构建一个代理工作空间。
- 资源库：可直接使用的模板（
AGENTS.md、feature_list.json、init.sh等），今天就能用在你自己的仓库中。
你不需要先读完所有 12 个讲座才能开始获得价值。如果你已经在真实项目中使用编程代理，以下是如何立刻改善它。
思路很简单：与其只写提示词，不如给你的代理一组结构化文件，定义做什么、已做了什么、以及如何验证工作。这些文件存在于你的仓库中，所以每次会话都从相同的状态开始。
你的项目根目录
├── AGENTS.md <-- 代理的操作手册
├── CLAUDE.md <-- （替代方案，如果你使用 Claude Code）
├── init.sh <-- 运行安装 + 验证 + 启动
├── feature_list.json <-- 哪些功能存在，哪些已完成
├── claude-progress.md <-- 每次会话发生了什么
└── src/ <-- 你的实际代码
从资源库获取入门模板，放入你的项目。就这样。四个文件，你的代理会话就会比仅靠提示词稳定得多。
全部六个课程项目围绕同一个产品展开：一个基于 Electron 的个人知识库桌面应用。
┌─────────────────────────────────────────────────────┐
│ 知识库桌面应用 │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
│ │ 文档列表 │ │ 问答面板 ││
│ │ │ │ ││
│ │ doc-001.md │ │ 问：什么是 Harness Eng？ ││
│ │ doc-002.md │ │ 答：围绕代理模型构建的 ││
│ │ doc-003.md │ │ 环境... ││
│ │ ... │ │ [引用: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
│ │ 状态栏：42 篇文档 | 38 篇已索引 | 上次同步 3 分钟前 ││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
核心功能：
├── 导入本地文档
├── 管理文档库
├── 处理和索引文档
├── 基于导入内容运行 AI 驱动的问答
└── 返回带引用的有据答案
选择这个项目是因为它兼具实用价值、足够的真实产品复杂度，以及一个适合观察 Harness 改进前后对比的良好场景。
每个课程项目的 starter/solution 都是此 Electron 应用在相应进化阶段的完整副本。P(N+1) 的 starter 派生自 P(N) 的 solution——随着你的 Harness 技能增长，应用也在进化。
课程按顺序设计。每个阶段建立在前一个之上。
阶段 1：看到问题 阶段 2：结构化仓库
======================= ==========================
L01 强模型 ≠ 可靠执行 L03 仓库作为唯一的
真实来源
L02 Harness 到底意味着什么
L04 将指令分散到多个文件，
而不是一个巨大文件
|
v |
P01 仅提示词 vs. v
规则优先对比
P02 代理可读的工作空间
阶段 3：连接会话 阶段 4：反馈与范围
========================== =========================
L05 让上下文跨会话保持活跃 L07 划清任务边界
L06 每次代理会话前初始化 L08 功能列表作为 Harness
基本单元
| |
v v
P03 多会话连续性 P04 运行时反馈
纠正代理行为
阶段 5：验证 阶段 6：整合一切
===================== ============================
L09 阻止代理过早 L11 让代理的运行时
宣布完成 可观测
L10 完整流水线运行 = L12 每次会话结束时
真正的验证 干净交接
| |
v v
P05 代理验证自己的工作 P06 构建完整的 Harness
（毕业项目）
如果你是业余时间学习，每个阶段大约需要一周。如果你想加快速度，阶段 1-3 可以在一个长周末完成。
在文档网站上阅读每讲完整文本。
| 讲次 | 问题 | 核心观点 |
|---|---|---|
| L01 | 为什么强模型在真实任务上仍然会失败？ | 基准测试与真实工程之间的能力差距 |
| L02 | "Harness" 到底是什么意思？ | 五个子系统：指令、状态、验证、范围、生命周期 |
| L03 | 为什么仓库必须是唯一的真实来源？ | 如果代理看不到它，它就不存在 |
| L04 | 为什么一个巨大的指令文件会失败？ | 渐进式披露：给一张地图，不是一本百科全书 |
| L05 | 为什么长时间运行的任务会失去连续性？ | 将进度持久化到磁盘；从上次离开处继续 |
| L06 | 为什么初始化需要单独的阶段？ | 在代理开始工作前验证环境是否健康 |
| L07 | 为什么代理会越界和欠完成？ | 一次一个功能；明确的完成定义 |
| L08 | 为什么功能列表是 Harness 基本单元？ | 代理无法忽视的机器可读范围边界 |
| L09 | 为什么代理过早宣布完成？ | 验证缺口：信心 ≠ 正确 |
| L10 | 为什么端到端测试能改变结果？ | 只有完整的流水线运行才算真正的验证 |
| L11 | 为什么可观测性应该属于 Harness？ | 如果你看不到代理做了什么，你就无法修复它破坏的东西 |
| L12 | 为什么每次会话都必须留下干净的状态？ | 下一次会话的成功取决于这一次会话的清理 |
| 项目 | 你要做什么 | Harness 机制 |
|---|---|---|
| P01 | 同一个任务运行两次：仅提示词 vs. 规则优先 | 最小 Harness：AGENTS.md + init.sh + feature_list.json |
| P02 | 重构仓库使代理可读 | 代理可读工作空间 + 持久化状态文件 |
| P03 | 让代理从上次离开处继续 | 进度日志 + 会话交接 + 多会话连续性 |
| P04 | 阻止代理做得太多或太少 | 运行时反馈 + 范围控制 + 增量索引 |
| P05 | 让代理验证自己的工作 | 自验证 + 有据问答 + 基于证据的完成 |
| P06 | 从零构建完整的 Harness（毕业项目） | 完整 Harness：所有机制 + 可观测性 + 消融实验 |
项目演进
=================
P01 仅提示词 vs. 规则优先 你看到问题
|
v
P02 代理可读工作空间 你重构仓库
|
v
P03 多会话连续性 你连接会话
|
v
P04 运行时反馈与范围 你添加反馈循环
|
v
P05 自验证 你让代理检查自己
|
v
P06 完整 Harness（毕业项目） 你构建完整系统
每个项目的 solution 成为下一个项目的 starter。
应用在演进。你的 Harness 技能随之增长。
- English — templates, checklists, and method references
- 简体中文 — 中文模板、清单和方法参考
- 繁體中文 — 繁體中文範本、清單和方法參考
- 日本語 — テンプレート、チェックリスト、方法リファレンス
- 한국어 — 템플릿, 체크리스트, 방법 참고 자료
- 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
- Türkçe — şablonlar, kontrol listeleri ve referanslar
- Português (BR) — modelos, listas de verificação e referências de métodos
这门课程的核心观点之一：代理的会话应该遵循结构化的生命周期，而不是放任自流。 如下所示：
代理会话生命周期
======================
┌──────────────────────────────────────────────────────────────────┐
│ 启动 │
│ │
│ 1. 代理读取 AGENTS.md / CLAUDE.md │
│ 2. 代理运行 init.sh（安装、验证、健康检查） │
│ 3. 代理读取 claude-progress.md（上次发生了什么） │
│ 4. 代理读取 feature_list.json（哪些完成，哪些待做） │
│ 5. 代理检查 git log（最近的变更） │
│ │
│ 选择 │
│ │
│ 6. 代理精确选择一个未完成的功能 │
│ 7. 代理只做那个功能 │
│ │
│ 执行 │
│ │
│ 8. 代理实现功能 │
│ 9. 代理运行验证（测试、lint、类型检查） │
│ 10. 如果验证失败：修复并重新运行 │
│ 11. 如果验证通过：记录证据 │
│ │
│ 收尾 │
│ │
│ 12. 代理更新 claude-progress.md │
│ 13. 代理更新 feature_list.json │
│ 14. 代理记录仍然有问题或未验证的内容 │
│ 15. 代理提交（仅在安全可恢复时） │
│ 16. 代理为下一次会话留下干净的重启路径 │
│ │
└──────────────────────────────────────────────────────────────────┘
Harness 管控这个生命周期中的每一次转换。
模型决定每一步写什么代码。
没有 Harness，第 9 步变成"代理说看起来没问题"。
有了 Harness，第 9 步是"测试通过，lint 干净，类型检查通过"。
本课程适合：
- 已经在使用编程代理、希望获得更好稳定性和质量的工程师
- 希望系统理解 Harness 设计的研究者或构建者
- 需要了解环境设计如何影响代理性能的技术负责人
本课程不适合：
- 寻找零代码 AI 入门的人
- 只关心提示词、不打算构建实际实现的人
- 不准备让代理在真实仓库中工作的学习者
这是一门你需要实际运行编程代理的课程。
你至少需要以下工具之一：
- Claude Code
- Codex
- 其他支持文件编辑、命令执行和多步骤任务的 IDE 或 CLI 编程代理
本课程假设你能够：
- 打开本地仓库
- 允许代理编辑文件
- 允许代理运行命令
- 检查输出并重新运行任务
如果你没有这样的工具，你仍然可以阅读课程内容，但无法按设计完成项目。
本仓库使用 VitePress 作为文档查看器。
npm install
npm run docs:dev # 带热重载的开发服务器
npm run docs:build # 生产构建
npm run docs:preview # 预览构建后的站点然后在浏览器中打开 VitePress 输出的本地 URL。
必需：
- 熟悉终端、git 和本地开发环境
- 能够使用至少一种常见应用技术栈读写代码
- 基本的软件调试经验（阅读日志、测试和运行时行为）
- 足够的时间投入到以实现为核心的课程中
有帮助但非必需：
- 有 Electron、桌面应用或本地优先工具的经验
- 有测试、日志或软件架构方面的背景
- 之前接触过 Codex、Claude Code 或类似的编程代理
主要参考：
- 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 代理技能
│ └── harness-creator/ # Harness Engineering 技能
├── package.json # VitePress + 开发工具
└── CLAUDE.md # 本仓库的 Claude Code 指令
- 每个讲座聚焦一个问题
- 课程包含 6 个项目
- 每个项目都要求代理做真实的工作
- 每个项目都比较弱 Harness 和强 Harness 的结果
- 重要的是可测量的差异，不是写了多少文档
本仓库还包含可复用的 AI 代理技能，你可以直接安装到你的 IDE 或代理工作空间中。
- harness-creator：一个帮助你在几分钟内为自己的项目搭建生产级别 Harness 的技能。
我们的团队还创建了其他课程！欢迎查看：
Hands-on Modern RL：一个开源的动手课程，从基础强化学习概念到 LLM 对齐、RLVR 和高级 Agentic 系统，架起理论与实践的桥梁。
本课程受到 learn-claude-code 的启发并借鉴了其中的理念——那是一份从单循环到隔离自主执行的渐进式代理构建指南。