智能体工程课 walkinglabs/learn-harness-engineering

一门项目制课程，教你搭建环境、管理状态、做验证、加控制机制，让 AI 编程智能体稳定干活。

🌍 本课程提供 15 种语言版本：English、简体中文、繁體中文、日本語、한국어、Español、Français、Русский、Deutsch、العربية、Tiếng Việt、Oʻzbekcha、Türkçe、Portuguese (BR)、Українська。从上方徽章中选择你的语言。

🆕 最新动态 — 2026 年 8 月

前沿 Harness 设计拆解 — 新章节（4 篇拆解）

| 内容 | 详情 |
| 新章节 | 前沿 Harness 设计拆解 — 用课程里的五子系统框架（指令、工具、环境、状态、反馈），逆向拆解四款前沿产品如何搭建真实 harness。 |
| Pi | Pi 如何搭建 harness — 极简内核、可编程扩展，以及「让 Pi 帮你搭」背后的上下文工程。 |
| Claude Code | Claude Code 如何搭建 harness — 四层记忆、五级压缩、钩子，以及子代理隔离。 |
| Codex | Codex 如何搭建 harness — 仓库即事实来源、AGENTS.md 当目录页，以及 worktree 隔离。 |
| DeepSeek | DeepSeek 如何搭建 harness — 「一切皆插件」、能力接缝，以及事件流水线。 |
| 全部 15 种语言 | 所有支持语言均已完整翻译。 |

核心思路： 课程给你一套框架；这些拆解让你看到同样的原则在生产环境的 harness 里究竟怎么落地。

图工程更新 — 1 节新课，1 个新项目

| 内容 | 详情 |
| 第 14 讲 | 从单循环到图工程 — 单循环为什么会生长成图：四层堆叠（提示词 → 上下文 → 循环 → 图），以及 harness 在这套堆叠里的位置；图的四个组成部分（节点、边、共享状态、路由）；为什么循环内的检查点在规模上来后修不了三种结构性失效（古德哈特定律、向上失明、冲突）；一套不绑定框架的六步走法，帮你搭出第一张图；图与工作流之别；锚点；哪些开源「图工程」项目出现在这个名字之前、哪些在之后；编排税；以及什么时候才真值得画一张图。 |
| Project 08 | 把你的工作流画成图 — 三个递进实验：把 maker-checker 循环画成一张显式的图，加一个并行 fan-out/fan-in 节点，再加一条条件回滚边和一个人工审批节点。 |

核心思路： 循环就是只有一个节点的图。当你的任务需要专门化、并行、共享状态、验证和恢复时——它就不再是循环了。它是图。

🆕 新内容 — 2026 年 7 月

Loop Engineering 更新 — 1 节新课，1 个新项目

| 内容 | 详情 |
| Lecture 13 | 为什么你需要停止给智能体写提示词 — 从 /goal 到 loop engineering 的六大原语（automations、worktrees、skills、connectors、sub-agents、external state），generator/evaluator 拆分，四种隐性成本，以及一步步搭建你的第一个循环的指南。 |
| Project 07 | 搭建你的第一个自动化循环 — 三个递进实验：goal loop、timer loop 和 maker-checker loop。对比手动与自动，衡量干预减少量，并学会跳出循环。 |
| 代码模板 | goal-template.md、loop-state-template.md、maker-prompt.md、checker-prompt.md — 拿来即用的模板，帮你立刻搭建循环。 |
| 全部 15 种语言 | 所有支持语言均已完整翻译。 |

核心思路： Harness engineering 造车。Loop engineering 设计车跑的路——而你在车外设计这条路。

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、验证工作流）。

目录

- 🆕 新内容
- ✨ 可视化预览
- Harness Engineering 到底指什么
- 快速上手：今天就改进你的智能体
- 毕业项目：一个真实应用
- 学习路径
- 课程大纲
- 技能
- 其他课程

✨ 视觉预览

🏠 课程主页

完整的课程大纲与核心理念介绍，给你一条清晰的入门路径。

课程主页预览

📖 沉浸式讲解

深入真实痛点与实战项目（比如 Project 01），带来沉浸式学习体验。

课程讲解预览

🗂️ 开箱即用的资源库

模板与参考配置，专为解决多轮 AI 智能体开发中的常见坑而设计，比如上下文丢失、任务提前收尾。

资源库预览

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（planner + generator + evaluator），它 6 小时烧掉 $200，做出来的游戏你真能玩。模型没变，变的是 harness。

OpenAI 用 Codex 报告了同样的结论：在一个 harness 搭得好的仓库里，同一个模型从「不可靠」变成「可靠」。这不是小幅提升，是质的转变。

这门课教你怎么搭出那个环境。

文字版

THE HARNESS PATTERN

你 --> 下达任务 --> 智能体读取 harness 文件 --> 智能体执行
harness 管控每一步：
+--> 指令：做什么，按什么顺序做
+--> 范围：一次只做一个功能，不越界
+--> 状态：进度日志、功能清单、git 历史
+--> 验证：测试、lint、类型检查、冒烟运行
+--> 生命周期：开始时初始化，结束时清理状态
v
智能体只在验证通过后才停下

Harness 工程到底指什么

Harness 工程指的是围绕模型搭建一套完整的工作环境，让它产出可靠的结果。重点不在写出更好的提示词，而在设计模型运行所处的这套系统。

一套 harness 包含五个子系统：

文本版

┌────────────────────────────────────────────────────────────────┐
│ THE HARNESS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │
│ │ Instructions │ │ State │ │ Verification │ │
│ │ │ │ │ │ │ │
│ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
│ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
│ │ feature_list │ │ git log │ │ smoke runs │ │
│ │ docs/ │ │ session hand │ │ e2e pipeline │ │
│ └──────────────┘ └──────────────┘ └────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
│ │ Scope │ │ Session Lifecycle │ │
│ │ │ │ │ │
│ │ one feature │ │ init.sh at start │ │
│ │ at a time │ │ clean-state checklist at end │ │
│ │ definition │ │ handoff note for next session │ │
│ │ of done │ │ commit only when safe to resume │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────┘

模型决定写什么代码。
框架决定何时写、在哪写、怎么写。
框架不会让模型变聪明。
它让模型的输出变得可靠。

每个子系统只负责一件事：

- 指令 —— 告诉智能体做什么、按什么顺序做、动手前先读什么。不是一个大文件，而是一套渐进式披露结构，智能体按需自行查阅。
- 状态 —— 记录已完成什么、正在进行什么、下一步是什么。持久化到磁盘，下一个会话就能从上次中断的地方精确接续。
- 验证 —— 只有测试套件通过才算证据。没有可运行的证明，智能体不能宣布胜利。
- 范围 —— 约束智能体一次只做一个功能。不越界。不同时做三件事却都做一半。不重写功能列表来掩盖未完成的工作。
- 会话生命周期 —— 开始时初始化。结束时清理。给下一个会话留一条干净的重启路径。

为什么会有这门课

问题不是「模型能不能写代码？」它们能。问题是：它们能不能在真实仓库里，跨多个会话，在没有人时刻盯着的情况下，可靠地完成真实的工程任务？

目前答案是：没有框架就不行。

没有框架 有框架

会话 1：智能体写代码 会话 1：智能体读指令智能体弄坏测试 智能体运行 init.sh 智能体说「完成了」 智能体只做一个功能你手动修好 智能体先验证再宣布完成智能体更新进度日志会话 2：智能体从零开始 智能体提交干净状态智能体不记得之前发生了什么 会话 2：智能体读进度日志智能体重做工作 智能体从上次中断处精确接续或者干脆做了别的事 智能体继续未完成的功能你又修一遍 你负责审查，不是救火

结果：你花在收拾残局上的时间 结果：智能体干活，比自己动手还多 你验证结果

这门课真正关心的问题：

- 哪些框架设计能提高任务完成率？
- 哪些设计能减少返工和错误完成？
- 哪些机制能让长时间运行的任务稳步推进？
- 哪些结构能让系统在多次智能体运行后仍然可维护？

课程大纲与文档

完整课程材料请访问 文档网站。

课程分为三部分：

1. 讲座：13 个概念单元，讲解 harness engineering 背后的理论。
2. 项目：7 个动手项目，从零搭建智能体工作区。
3. 资源库：可直接复制的模板（AGENTS.md、feature_list.json、init.sh 等），今天就能用在你自己的仓库里。

快速上手：今天就改进你的智能体

不必读完 14 讲才能获得价值。如果你已经在真实项目里使用编码智能体，下面就是立刻改进它的方法。

思路很简单：不要只写提示词，而是给智能体一组结构化文件，定义要做什么、已经做了什么、如何验证工作。这些文件放在仓库里，所以每次会话都从同一状态开始。

YOUR PROJECT ROOT
├── AGENTS.md <-- the agent's operating manual
├── CLAUDE.md <-- (alternative, if using Claude Code)
├── init.sh <-- runs install + verify + start
├── feature_list.json <-- what features exist, which are done
├── claude-progress.md <-- session progress (historical filename; agent-agnostic)
└── src/ <-- your actual code

从资源库取来入门模板，放进你的项目即可。就这样。四个文件，你的智能体会话就会比只靠提示词稳定得多。

claude-progress.md 是通用的、仓库本地的会话进度日志；保留这个名字是为了兼容课程示例。它不绑定 Claude Code，也不会被任何智能体自动更新。Codex、OpenHands、Antigravity 以及其他编码智能体都能使用同一个文件，只要它们的根指令要求启动时读取、交接前更新即可。

毕业项目：一个真实应用

六个课程项目都围绕同一个产品：基于 Electron 的个人知识库桌面应用。

┌──────────────────────────────────────────────────────┐
│ Knowledge Base Desktop App │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐ │
│ │ Document List│ │ Q&A Panel │ │
│ │ │ │ │ │
│ │ doc-001.md │ │ Q: What is harness eng? │ │
│ │ doc-002.md │ │ A: The environment built │ │
│ │ doc-003.md │ │ 围绕智能体模型…… │ │ │ │ ... │ │ [citation: doc-002.md] │ │ │ └──────────────┘ └──────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ Status Bar: 42 docs | 38 indexed | last sync 3m │ │ │ └─────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────┘

核心功能： ├── 导入本地文档 ├── 管理文档库 ├── 处理并索引文档 ├── 对导入内容运行 AI 问答 └── 返回带引用的有据回答

选这个项目，是因为它实用价值高、产品复杂度够真实，也适合观察接入 harness 前后的变化。

每个课程项目的 starter/solution 都是这个 Electron 应用在对应演进阶段的完整副本。P(N+1) 的 starter 来自 P(N) 的 solution——你的 harness 技能成长，应用也跟着演进。

学习路径

课程按顺序推进，每个阶段都建立在上一个阶段之上。

文字版 text Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO

L01 Strong models ≠ reliable L03 Repository as single
execution source of truth
L02 What harness actually means
L04 Split instructions across
| files, not one giant file
v
P01 Prompt-only vs. |
rules-first comparison v
P02 Agent-readable workspace

Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE

L05 Keep context alive L07 Draw clear task boundaries
across sessions
L08 Feature lists as harness
L06 Initialize before every primitives
agent session

| v
v P04 Runtime feedback to
P03 Multi-session continuity correct agent behavior

Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER

L09 别让智能体提前宣布胜利 L11 让智能体的运行时可观测

L10 全流程运行 = L12 每次会话结束都干净真实验证 交接

v v
P05 智能体验证自己的产出 P06 搭建完整 harness （毕业项目）

Phase 7：自动化循环

L13 别再给智能体写提示词——去设计循环

v
P07 搭出你的第一个自动化循环（目标循环、定时循环、maker-checker）

Phase 8：给系统搭结构

L14 把系统画成图——节点、边、共享状态、路由

v
P08 把你的工作流画成图（显式图、并行 fan-out/fan-in、回滚边、human-in-the-loop）

如果你利用业余时间学，每个阶段大约要一周。想快一点的话，阶段 1–3 可以放在一个长周末里完成。

课程大纲

讲座 —— 14 个概念单元，每个回答一个核心问题

每讲的完整正文都在文档网站上。

| 课次 | 问题 | 核心观点 |
| L01 | 模型这么强，为什么在真实任务上还是失败？ | 基准测试与真实工程之间的能力鸿沟 |
| L02 | 「harness」到底指什么？ | 五个子系统：指令、状态、验证、范围、生命周期 |
| L03 | 为什么仓库必须是唯一事实来源？ | 智能体看不到的东西，就等于不存在 |
| L04 | 为什么一个巨大的指令文件会失败？ | 渐进式披露：给一张地图，而不是一本百科全书 |
| L05 | 为什么长时间运行的任务会失去连续性？ | 把进度持久化到磁盘；从上次停下的地方接着做 |
| L06 | 为什么初始化需要独立阶段？ | 智能体开工前先确认环境健康 |
| L07 | 为什么智能体会做过头、又收不了尾？ | 一次只做一个功能；明确定义「完成」 |
| L08 | 为什么功能清单是 harness 原语？ | 机器可读的范围边界，智能体无法忽略 |
| L09 | 为什么智能体过早宣布胜利？ | 验证缺口：自信 ≠ 正确 |
| L10 | 为什么端到端测试会改变结果？ | 只有跑完整条流水线才算真正验证 |
| L11 | 为什么可观测性属于 harness 内部？ | 看不见智能体做了什么，就修不好它弄坏的东西 |
| L12 | 为什么每个会话都必须留下干净状态？ | 下个会话能否成功，取决于本次会话的清理 |
| L13 | 为什么你需要停止手动给智能体写提示词？ | 从手动驾驶到自动循环 —— 目标循环、定时循环，以及 maker-checker 分离 |
| L14 | 为什么单个循环会长成一张图？ | 从单循环到图工程 —— 节点、边、共享状态、路由，以及什么时候才真值得画一张图 |

Projects — 8 个动手项目，把课程方法用到同一个 Electron 应用上

| Project | 你要做什么 | Harness 机制 |
| P01 | 同一个任务跑两遍：只写提示词 vs. 规则优先 | 最小 harness：AGENTS.md + init.sh + feature_list.json |
| P02 | 重构仓库，让智能体能读懂它 | 智能体可读的工作区 + 持久化状态文件 |
| P03 | 让智能体从上次停下的地方接着干 | 进度日志 + 会话交接 + 多会话连续性 |
| P04 | 别让智能体做太多，也别做太少 | 运行时反馈 + 范围控制 + 增量索引 |
| P05 | 让智能体验证自己的产出 | 自我验证 + 有据可依的问答 + 基于证据的完成 |
| P06 | 从零搭一套完整 harness（综合项目） | 完整 harness：所有机制 + 可观测性 + 消融实验 |
| P07 | 搭出你的第一个自动循环 | 目标循环、定时循环、maker-checker 分离、循环状态管理 |
| P08 | 把工作流画成图 | 显式的节点/边/状态/路由，并行扇出/扇入，回滚边，人在环中审批 |
text
PROJECT EVOLUTION

P01 Prompt-only vs. rules-first 你看到问题

v
P02 Agent-readable workspace 你重构仓库

v
P03 Multi-session continuity 你连接会话

v
P04 Runtime feedback & scope 你加入反馈回路

v
P05 Self-verification 你让智能体检查自己

v

P06 Complete harness (capstone) You build the full system
v
P07 Your first automated loop You step outside the loop
v
P08 Draw your workflow as a graph You draw the system as a graph

Each project's solution becomes the next project's starter.
The app evolves. Your harness skills grow with it.

Resource Library

- 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

The Agent Session Lifecycle

One of the core ideas in this course: the agent's session should follow a structured lifecycle, not a free-for-all. Here's what that looks like:

Text version

AGENT SESSION LIFECYCLE

┌──────────────────────────────────────────────────────────────────┐
│ START │
│ │
│ 1. Agent reads AGENTS.md / CLAUDE.md │
│ 2. Agent runs init.sh (install, verify, health check) │
│ 3. Agent reads claude-progress.md (what happened last time) │
│ 4. Agent reads feature_list.json (what's done, what's next) │
│ 5. Agent checks git log (recent changes) │
│ │
│ SELECT │
│ │
│ 6. Agent picks exactly ONE unfinished feature │
│ 7. Agent works only on that feature │
│ │
│ EXECUTE │
│ │
│ 8. Agent implements the feature │
│ 9. Agent runs verification (tests, lint, type-check) │
│ 10. If verification fails: fix and re-run │
│ 11. If verification passes: record evidence │
│ │
│ WRAP UP │
│ │
│ 12. Agent updates claude-progress.md │
│ 13. Agent updates feature_list.json │
│ 14. Agent records what's still broken or unverified │
│ 15. Agent commits (only when safe to resume) │
│ 16. Agent leaves clean restart path for next session │
│ │
└──────────────────────────────────────────────────────────────────┘

The harness governs every transition in this lifecycle.
The model decides what code to write at each step.
Without the harness, step 9 becomes "agent says it looks fine."
With the harness, step 9 is "tests pass, lint is clean, types check."

Who This Is For

This course is for:

- Engineers already using coding agents who want better stability and quality
- Researchers or builders who want a systematic understanding of harness design
- Tech leads who need to understand how environment design affects agent performance

This course is not for:

- People looking for a zero-code AI introduction
- People who only care about prompts and don't plan to build real implementations
- Learners not prepared to let agents work inside real repositories

Requirements

This is a course where you actually run coding agents.

You need at least one of these tools:

- Claude Code
- Codex
- Another IDE or CLI coding agent that supports file editing, command execution, and multi-step tasks

The course assumes you can:

- Open a local repository
- Allow the agent to edit files
- Allow the agent to run commands
- Inspect output and re-run tasks

If you don't have such a tool, you can still read the course content, but you won't be able to complete the projects as intended.

Local Preview

This repository uses VitePress as a documentation viewer.

npm install
npm run docs:dev # Dev server with hot reload
npm run docs:build # Production build
npm run docs:preview # Preview built site

Then open the local URL that VitePress outputs in your browser.

Prerequisites

Required:

- Familiarity with the terminal, git, and local development environments
- Ability to read and write code in at least one common application stack
- Basic software debugging experience (reading logs, tests, and runtime behavior)
- Enough time to commit to implementation-focused coursework

Helpful but not required:

- Experience with Electron, desktop apps, or local-first tools
- Background in testing, logging, or software architecture
- Prior exposure to Codex, Claude Code, or similar coding agents

Core References

Primary:

- 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

See the full layered reference list in docs/en/resources/reference/.

Repository Structure

learn-harness-engineering/
├── docs/ # VitePress documentation site
│ ├── lectures/ # 14 lectures (index.md + code/ examples)
│ │ ├── lecture-01-/
│ │ └── ... (14 total)
│ ├── projects/ # 8 project descriptions
│ │ ├── project-01-/
│ │ └── ... (8 total)
│ └── resources/ # Multilingual templates & references (14 languages)
│ ├── en/
│ └── ... (14 total)
├── projects/
│ ├── shared/ # Shared Electron + TypeScript + React foundation
│ └── project-NN/ # Per-project starter/ and solution/ directories
├── skills/ # Reusable AI agent skills
│ └── harness-creator/ # Harness engineering skill
├── tools/ # Zero-dependency shell utilities
│ └── audit-harness.sh # Shell-based harness audit (L03–L12, no Node.js needed)
├── package.json # VitePress + dev tooling
└── CLAUDE.md # Claude Code instructions for this repo

How the Course Is Organized

- Each lecture focuses on one question
- The course includes 8 projects
- Every project requires the agent to do real work
- Every project compares weak vs. strong harness results
- What matters is the measured difference, not how many docs were written

Skills

This repository also includes reusable AI agent skills that you can install directly into your IDE or agent workspace.

- harness-creator: A skill that helps you scaffold a production-grade harness for your own project in minutes.

Tools

Zero-dependency utilities you can run without installing Node.js.

- audit-harness.sh: A shell-based audit script that checks an existing repo against all five harness subsystems (L03–L12). Exits 0 when all CRITICAL items pass. No Node.js required — complements harness-creator's validate-harness.mjs.

Run directly on any repo
curl -fsSL https://raw.githubusercontent.com/walkinglabs/learn-harness-engineering/main/tools/audit-harness.sh | bash -s -- /path/to/your/repo

Or after cloning
bash tools/audit-harness.sh /path/to/your/repo

Other Courses

Our team has also created other courses! Check them out:

Hands-on Modern RL: An open-source, hands-on curriculum bridging the gap from basic RL concepts to LLM alignment, RLVR, and advanced Agentic systems.

Modern LLM Notebook: A hands-on course for building modern LLMs from scratch in PyTorch, with 23 runnable Jupyter Notebooks covering tokenizers, attention, MoE, RLHF, inference, evaluation, and distillation.

Acknowledgments

This course was inspired by and draws ideas from learn-claude-code — a progressive guide to building an agent from scratch, from a single loop to isolated autonomous execution.