Skip to content
Back to search

learn-harness-engineering

Harness engineering beginner tutorial, from 0 to 1

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/walkinglabs/learn-harness-engineering with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/walkinglabs/learn-harness-engineering'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/walkinglabs-learn-harness-engineering/badge.svg)](/listings/walkinglabs-learn-harness-engineering)

HTML

<a href="/listings/walkinglabs-learn-harness-engineering"><img src="/api/listings/walkinglabs-learn-harness-engineering/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You don't need to read all 14 lectures before you start getting value. If you're already using a coding agent on a real project, here's how to improve it right now.

The idea is simple: instead of just writing prompts, give your agent a set of structured files that define what to do, what's been done, and how to verify the work. These files live inside your repo, so every session starts from the same state.

    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

Grab the starter templates from the [Resource Library](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) and drop them into your project. That's it. Four files, and your agent sessions will already be significantly more stable than running on prompts alone.

`claude-progress.md` is a generic, repository-local session progress log; the name is retained for compatibility with the course examples. It is not tied to Claude Code and is not updated automatically by any agent. Codex, OpenHands, Antigravity, and other coding agents can use the same file when their root instructions tell them to read it at startup and update it before handoff.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 752 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark) and (max-width: 600px)" srcset="assets/readme/harness-wordmark-compact-dark.svg">
  4. <source media="(max-width: 600px)" srcset="assets/readme/harness-wordmark-compact.svg">
  5. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/harness-wordmark-dark.svg">
  6. <img src="assets/readme/harness-wordmark.svg" alt="Learn Harness Engineering" width="880">
  7. </picture>
  8. </h1>
  9. <p align="center">
  10. <a href="README.md"><img alt="English" src="https://img.shields.io/badge/EN-English-blue?style=flat-square"></a>
  11. <a href="docs-readme/zh-CN/README.md"><img alt="简体中文" src="https://img.shields.io/badge/ZH-简体中文-red?style=flat-square"></a>
  12. <a href="docs-readme/zh-TW/README.md"><img alt="繁體中文" src="https://img.shields.io/badge/ZH--TW-繁體中文-orange?style=flat-square"></a>
  13. <a href="docs-readme/ja-JP/README.md"><img alt="日本語" src="https://img.shields.io/badge/JA-日本語-green?style=flat-square"></a>
  14. <a href="docs-readme/ko-KR/README.md"><img alt="한국어" src="https://img.shields.io/badge/KO-한국어-blueviolet?style=flat-square"></a>
  15. <a href="docs-readme/es-ES/README.md"><img alt="Español" src="https://img.shields.io/badge/ES-Español-yellow?style=flat-square"></a>
  16. <a href="docs-readme/fr-FR/README.md"><img alt="Français" src="https://img.shields.io/badge/FR-Français-007EC6?style=flat-square"></a>
  17. <a href="docs-readme/ru-RU/README.md"><img alt="Русский" src="https://img.shields.io/badge/RU-Русский-informational?style=flat-square"></a>
  18. <a href="docs-readme/de-DE/README.md"><img alt="Deutsch" src="https://img.shields.io/badge/DE-Deutsch-2EA043?style=flat-square"></a>
  19. <a href="docs-readme/ar-SA/README.md"><img alt="العربية" src="https://img.shields.io/badge/AR-العربية-success?style=flat-square"></a>
  20. <a href="docs-readme/vi-VN/README.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/VI-Tiếng_Việt-cc6699?style=flat-square"></a>
  21. <a href="docs-readme/uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
  22. <a href="docs-readme/tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
  23. <a href="docs-readme/pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
  24. <a href="docs-readme/uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
  25. </p>
  26. <p align="center"><strong>A project-based course on building the environment, state management, verification, and control mechanisms that make AI coding agents work reliably.</strong></p>
  27. <p align="center">
  28. <img src="https://img.shields.io/badge/Lectures-14-blue?style=flat-square" alt="14 Lectures">
  29. <img src="https://img.shields.io/badge/Projects-8-green?style=flat-square" alt="8 Projects">
  30. <img src="https://img.shields.io/badge/Languages-15-yellow?style=flat-square" alt="15 Languages">
  31. <img src="https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square" alt="MIT License">
  32. <a href="https://github.com/walkinglabs"><img src="https://img.shields.io/badge/Discord-Join_Community-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Join the Discord community"></a>
  33. </p>
  34. > 🌍 This course is available in **15 languages**: English, 简体中文, 繁體中文, 日本語, 한국어, Español, Français, Русский, Deutsch, العربية, Tiếng Việt, Oʻzbekcha, Türkçe, Portuguese (BR), Українська. Choose your language from the badges above.
  35. ## 🆕 What's New — August 2026
  36. **Frontier Harness Design Breakdowns — new section (4 breakdowns)**
  37. | What | Details |
  38. |------|---------|
  39. | **New section** | [Frontier Harness Design Breakdowns](docs/en/harness-designs/index.md) — Apply the course's five-subsystem framework (instructions, tools, environment, state, feedback) to reverse-engineer how four frontier products build real harnesses. |
  40. | **Pi** | [How Pi builds its harness](docs/en/harness-designs/pi/index.md) — a minimal kernel, programmable expansion, and context engineering behind "ask Pi to build what you want." |
  41. | **Claude Code** | [How Claude Code builds its harness](docs/en/harness-designs/claude-code/index.md) — four-layer memory, five-level compaction, hooks, and sub-agent isolation. |
  42. | **Codex** | [How Codex builds its harness](docs/en/harness-designs/codex/index.md) — the repository as source of truth, AGENTS.md as a directory page, and worktree isolation. |
  43. | **DeepSeek** | [How DeepSeek builds its harness](docs/en/harness-designs/deepseek/index.md) — "everything is a plugin," capability seams, and an event pipeline. |
  44. | **All 15 languages** | Full translation coverage across all supported languages. |
  45. **Key idea:** The course gives you a framework; these breakdowns show you how the same principles actually play out in production harnesses.
  46. ---
  47. **Graph Engineering Update — 1 new lecture, 1 new project**
  48. | What | Details |
  49. |------|---------|
  50. | **Lecture 14** | [From Single Loops to Graph Engineering](docs/en/lectures/lecture-14-graph-engineering/index.md) — Why a single loop grows into a graph: the four stacked layers (prompt → context → loop → graph) and where harness sits in that stack, the four parts of a graph (nodes, edges, shared state, routing), why in-loop checkpoints can't fix the three structural failures at scale (Goodhart, blindness upward, conflict), a framework-agnostic six-step walkthrough for building your first graph, graph vs. workflow, anchors, which open-source "graph engineering" projects existed before the name vs. after it, the orchestration tax, and when a graph is actually worth drawing. |
  51. | **Project 08** | [Draw Your Workflow as a Graph](docs/en/projects/project-08-graph-engineering-first-graph/index.md) — Three progressive experiments: draw your maker-checker loop as an explicit graph, add a parallel fan-out/fan-in node, then add a conditional rollback edge and a human-approval node. |
  52. **Key idea:** A loop is a graph with one node. When your task needs specialization, parallelism, shared state, verification, and recovery — it has stopped being a loop. It's a graph.
  53. ---
  54. ## 🆕 What's New — July 2026
  55. **Loop Engineering Update — 1 new lecture, 1 new project**
  56. | What | Details |
  57. |------|---------|
  58. | **Lecture 13** | [Why You Need to Stop Prompting Your Agent](docs/en/lectures/lecture-13-loop-engineering/index.md) — From `/goal` to the six primitives of loop engineering (automations, worktrees, skills, connectors, sub-agents, external state), the generator/evaluator split, four silent costs, and a step-by-step guide to building your first loop. |
  59. | **Project 07** | [Build Your First Automated Loop](docs/en/projects/project-07-loop-engineering-first-loop/index.md) — Three progressive experiments: goal loop, timer loop, and maker-checker loop. Compare manual vs. automated, measure intervention reduction, and learn to step outside the loop. |
  60. | **Code templates** | `goal-template.md`, `loop-state-template.md`, `maker-prompt.md`, `checker-prompt.md` — drop-in templates for building loops immediately. |
  61. | **All 15 languages** | Full translation coverage across all supported languages. |
  62. **Key idea:** Harness engineering builds the vehicle. Loop engineering designs the road it drives on — and you design the road from outside the car.
  63. ---
  64. Learn Harness Engineering is a course dedicated to the engineering of AI coding agents. We have deeply studied and synthesized the most advanced Harness Engineering theories and practices in the industry. Our core references include:
  65. - [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
  66. - [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
  67. - [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
  68. - [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)
  69. > **Quick start?** The [`skills/harness-creator/`](./skills/harness-creator/) skill can help you scaffold a production-grade harness (AGENTS.md, feature lists, init.sh, verification workflows) for your own project in minutes.
  70. ---
  71. ## Table of Contents
  72. - [🆕 What's New](#-whats-new--august-2026)
  73. - [✨ Visual Preview](#-visual-preview)
  74. - [What Harness Engineering Actually Means](#what-harness-engineering-actually-means)
  75. - [Quick Start: Improve Your Agent Today](#quick-start-improve-your-agent-today)
  76. - [Capstone Project: A Real App](#capstone-project-a-real-app)
  77. - [Learning Path](#learning-path)
  78. - [Syllabus](#syllabus)
  79. - [Skills](#skills)
  80. - [Other Courses](#other-courses)
  81. ---
  82. ## ✨ Visual Preview
  83. ### 🏠 Course Homepage
  84. > A comprehensive course outline and introduction to core philosophies, providing a clear path to get started.
  85. ![Course homepage preview](./docs/public/screenshots/readme/en-home.png)
  86. ### 📖 Immersive Lectures
  87. > Deep dives into real-world pain points and hands-on projects (like Project 01) for an immersive learning experience.
  88. ![Course lecture preview](./docs/public/screenshots/readme/en-lecture-01.png)
  89. ### 🗂️ Ready-to-Use Resource Library
  90. > Templates and reference configurations designed to solve common pitfalls in multi-turn AI agent development, such as context loss and premature task completion.
  91. ![Resource library preview](./docs/public/screenshots/readme/en-resources.png)
  92. ## PDF Coursebooks
  93. The repository now includes a PDF build pipeline for the course content.
  94. - Run `npm run pdf:build` to generate the currently configured PDF coursebooks locally.
  95. - Output files are written to `artifacts/pdfs/`.
  96. - Run `npm run screenshots:readme` if you want to refresh the README preview images.
  97. - GitHub Actions workflow [`release-course-pdfs.yml`](./.github/workflows/release-course-pdfs.yml) can build the PDFs and publish them to GitHub Releases.
  98. ---
  99. ## The Model Is Smart, The Harness Makes It Reliable
  100. There's a hard truth most people learn the hard way: **the strongest model in the world will still fail on real engineering tasks if you don't build a proper environment around it.**
  101. You've probably seen this yourself. You give Claude or GPT a task in your repo. It starts well — reads files, writes code, looks productive. Then something goes wrong. It skips a step. It breaks a test. It says "done" but nothing actually works. You spend more time cleaning up than if you'd done it yourself.
  102. This isn't a model problem. It's a harness problem.
  103. The evidence is clear. Anthropic ran a controlled experiment: same model (Opus 4.5), same prompt ("build a 2D retro game editor"). Without a harness, it spent $9 in 20 minutes and produced something that didn't work. With a full harness (planner + generator + evaluator), it spent $200 in 6 hours and built a game you could actually play. The model didn't change. The harness did.
  104. OpenAI reported the same thing with Codex: in a well-harnessed repository, the same model goes from "unreliable" to "reliable." Not a marginal improvement — a qualitative shift.
  105. **This course teaches you how to build that environment.**
  106. <p align="center">
  107. <a href="assets/readme/harness-pattern.svg">
  108. <picture>
  109. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/harness-pattern-dark.svg">
  110. <img src="assets/readme/harness-pattern.png" alt="Harness pattern: give a task, read harness files, execute, and stop after verification passes." width="920">
  111. </picture>
  112. </a>
  113. </p>
  114. <details>
  115. <summary>Text version</summary>
  116. ```text
  117. THE HARNESS PATTERN
  118. ====================
  119. You --> give task --> Agent reads harness files --> Agent executes
  120. |
  121. harness governs every step:
  122. |
  123. +--> Instructions: what to do, in what order
  124. +--> Scope: one feature at a time, no overreach
  125. +--> State: progress log, feature list, git history
  126. +--> Verification: tests, lint, type-check, smoke runs
  127. +--> Lifecycle: init at start, clean state at end
  128. |
  129. v
  130. Agent stops only when
  131. verification passes
  132. ```
  133. </details>
  134. ---
  135. ## What Harness Engineering Actually Means
  136. Harness engineering is about building a complete working environment around the model so it produces reliable results. It's not about writing better prompts. It's about designing the system the model operates inside.
  137. A harness has five subsystems:
  138. <p align="center">
  139. <a href="assets/readme/harness-subsystems.svg">
  140. <picture>
  141. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/harness-subsystems-dark.svg">
  142. <img src="assets/readme/harness-subsystems.png" alt="Five harness subsystems: instructions, state, verification, scope, and session lifecycle." width="920">
  143. </picture>
  144. </a>
  145. </p>
  146. <details>
  147. <summary>Text version</summary>
  148. ```text
  149. ┌────────────────────────────────────────────────────────────────┐
  150. │ THE HARNESS │
  151. │ │
  152. │ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │
  153. │ │ Instructions │ │ State │ │ Verification │ │
  154. │ │ │ │ │ │ │ │
  155. │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
  156. │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
  157. │ │ feature_list │ │ git log │ │ smoke runs │ │
  158. │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
  159. │ └──────────────┘ └──────────────┘ └────────────────────┘ │
  160. │ │
  161. │ ┌──────────────┐ ┌──────────────────────────────────────┐ │
  162. │ │ Scope │ │ Session Lifecycle │ │
  163. │ │ │ │ │ │
  164. │ │ one feature │ │ init.sh at start │ │
  165. │ │ at a time │ │ clean-state checklist at end │ │
  166. │ │ definition │ │ handoff note for next session │ │
  167. │ │ of done │ │ commit only when safe to resume │ │
  168. │ └──────────────┘ └──────────────────────────────────────┘ │
  169. │ │
  170. └────────────────────────────────────────────────────────────────┘
  171. The MODEL decides what code to write.
  172. The HARNESS governs when, where, and how it writes it.
  173. The harness doesn't make the model smarter.
  174. It makes the model's output reliable.
  175. ```
  176. </details>
  177. Each subsystem has one job:
  178. - **Instructions** — Tell the agent what to do, in what order, and what to read before starting. Not one giant file; a progressive disclosure structure the agent navigates on demand.
  179. - **State** — Track what's been done, what's in progress, and what's next. Persisted to disk so the next session picks up exactly where the last one left off.
  180. - **Verification** — Only a passing test suite counts as evidence. The agent cannot declare victory without runnable proof.
  181. - **Scope** — Constrain the agent to one feature at a time. No overreach. No half-finishing three things. No rewriting the feature list to hide unfinished work.
  182. - **Session Lifecycle** — Initialize at the start. Clean up at the end. Leave a clean restart path for the next session.
  183. ---
  184. ## Why This Course Exists
  185. The question isn't "can models write code?" They can. The question is: **can they reliably complete real engineering tasks inside real repositories, over multiple sessions, without constant human supervision?**
  186. Right now, the answer is: not without a harness.
  187. ```text
  188. WITHOUT HARNESS WITH HARNESS
  189. ============== ============
  190. Session 1: agent writes code Session 1: agent reads instructions
  191. agent breaks tests agent runs init.sh
  192. agent says "done" agent works on one feature
  193. you fix it manually agent verifies before claiming done
  194. agent updates progress log
  195. Session 2: agent starts fresh agent commits clean state
  196. agent has no memory
  197. of what happened before Session 2: agent reads progress log
  198. agent re-does work agent picks up exactly where it left off
  199. or does something else entirely agent continues the unfinished feature
  200. you fix it again you review, not rescue
  201. Result: you spend more time Result: agent does the work,
  202. cleaning up than if you you verify the result
  203. did it yourself
  204. ```
  205. The questions this course actually cares about:
  206. - Which harness designs improve task completion rates?
  207. - Which designs reduce rework and incorrect completions?
  208. - Which mechanisms keep long-running tasks progressing steadily?
  209. - Which structures keep the system maintainable after multiple agent runs?
  210. ---
  211. ## Course Curriculum & Documentation
  212. For the full course materials, please visit the **[Documentation Website](https://walkinglabs.github.io/learn-harness-engineering/)**.
  213. The curriculum is divided into three parts:
  214. 1. **Lectures**: 13 conceptual units explaining the theory behind harness engineering.
  215. 2. **Projects**: 7 hands-on projects where you build an agentic workspace from scratch.
  216. 3. **Resource Library**: Copy-ready templates (`AGENTS.md`, `feature_list.json`, `init.sh`, etc.) to use in your own repositories today.
  217. ---
  218. ## Quick Start: Improve Your Agent Today
  219. You don't need to read all 14 lectures before you start getting value. If you're already using a coding agent on a real project, here's how to improve it right now.
  220. The idea is simple: instead of just writing prompts, give your agent a set of structured files that define what to do, what's been done, and how to verify the work. These files live inside your repo, so every session starts from the same state.
  221. ```text
  222. YOUR PROJECT ROOT
  223. ├── AGENTS.md <-- the agent's operating manual
  224. ├── CLAUDE.md <-- (alternative, if using Claude Code)
  225. ├── init.sh <-- runs install + verify + start
  226. ├── feature_list.json <-- what features exist, which are done
  227. ├── claude-progress.md <-- session progress (historical filename; agent-agnostic)
  228. └── src/ <-- your actual code
  229. ```
  230. Grab the starter templates from the [Resource Library](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) and drop them into your project. That's it. Four files, and your agent sessions will already be significantly more stable than running on prompts alone.
  231. `claude-progress.md` is a generic, repository-local session progress log; the
  232. name is retained for compatibility with the course examples. It is not tied to
  233. Claude Code and is not updated automatically by any agent. Codex, OpenHands,
  234. Antigravity, and other coding agents can use the same file when their root
  235. instructions tell them to read it at startup and update it before handoff.
  236. ---
  237. ## Capstone Project: A Real App
  238. All six course projects revolve around the same product: **an Electron-based personal knowledge base desktop app**.
  239. ```text
  240. ┌──────────────────────────────────────────────────────┐
  241. │ Knowledge Base Desktop App │
  242. │ │
  243. │ ┌──────────────┐ ┌──────────────────────────────┐ │
  244. │ │ Document List│ │ Q&A Panel │ │
  245. │ │ │ │ │ │
  246. │ │ doc-001.md │ │ Q: What is harness eng? │ │
  247. │ │ doc-002.md │ │ A: The environment built │ │
  248. │ │ doc-003.md │ │ around an agent model... │ │
  249. │ │ ... │ │ [citation: doc-002.md] │ │
  250. │ └──────────────┘ └──────────────────────────────┘ │
  251. │ │
  252. │ ┌─────────────────────────────────────────────────┐ │
  253. │ │ Status Bar: 42 docs | 38 indexed | last sync 3m │ │
  254. │ └─────────────────────────────────────────────────┘ │
  255. └──────────────────────────────────────────────────────┘
  256. Core features:
  257. ├── Import local documents
  258. ├── Manage a document library
  259. ├── Process and index documents
  260. ├── Run AI-powered Q&A over imported content
  261. └── Return grounded answers with citations
  262. ```
  263. This project was chosen because it combines strong practical value, enough real-world product complexity, and a good setting for observing before/after harness improvements.
  264. Each course project's starter/solution is a complete copy of this Electron app at that evolutionary stage. P(N+1)'s starter is derived from P(N)'s solution — the app evolves as your harness skills grow.
  265. ---
  266. ## Learning Path
  267. The course is designed to be done in order. Each phase builds on the last.
  268. <p align="center">
  269. <a href="assets/readme/harness-learning-path.svg">
  270. <picture>
  271. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/harness-learning-path-dark.svg">
  272. <img src="assets/readme/harness-learning-path.png" alt="Eight learning phases connecting lectures L01–L14 with projects P01–P08." width="920">
  273. </picture>
  274. </a>
  275. </p>
  276. <details>
  277. <summary>Text version</summary>
  278. ```text
  279. Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
  280. ======================== ==========================
  281. L01 Strong models ≠ reliable L03 Repository as single
  282. execution source of truth
  283. L02 What harness actually means
  284. L04 Split instructions across
  285. | files, not one giant file
  286. v
  287. P01 Prompt-only vs. |
  288. rules-first comparison v
  289. P02 Agent-readable workspace
  290. Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
  291. ========================== =========================
  292. L05 Keep context alive L07 Draw clear task boundaries
  293. across sessions
  294. L08 Feature lists as harness
  295. L06 Initialize before every primitives
  296. agent session
  297. |
  298. | v
  299. v P04 Runtime feedback to
  300. P03 Multi-session continuity correct agent behavior
  301. Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
  302. ===================== ============================
  303. L09 Stop agents from L11 Make agent's runtime
  304. declaring victory early observable
  305. L10 Full-pipeline run = L12 Clean handoff at end of
  306. real verification every session
  307. | |
  308. v v
  309. P05 Agent verifies its own work P06 Build a complete harness
  310. (capstone project)
  311. Phase 7: AUTOMATE THE LOOP
  312. ==========================
  313. L13 Stop prompting your agent —
  314. design loops instead
  315. |
  316. v
  317. P07 Build your first automated loop
  318. (goal loop, timer loop, maker-checker)
  319. Phase 8: STRUCTURE THE SYSTEM
  320. =============================
  321. L14 Draw the system as a graph —
  322. nodes, edges, shared state, routing
  323. |
  324. v
  325. P08 Draw your workflow as a graph
  326. (explicit graph, parallel fan-out/fan-in,
  327. rollback edges, human-in-the-loop)
  328. ```
  329. </details>
  330. Each phase takes about a week if you're going part-time. If you want to go faster, phases 1–3 can be done in a long weekend.
  331. ---
  332. ## Syllabus
  333. ### Lectures — 14 conceptual units, each answering one core question
  334. *Read the full text for each lecture on the [Documentation Website](https://walkinglabs.github.io/learn-harness-engineering/).*
  335. | Session | Question | Core Idea |
  336. |---------|----------|-----------|
  337. | [L01](./docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Why do strong models still fail on real tasks? | The capability gap between benchmarks and real engineering |
  338. | [L02](./docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | What does "harness" actually mean? | Five subsystems: instructions, state, verification, scope, lifecycle |
  339. | [L03](./docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Why must the repo be the single source of truth? | If the agent can't see it, it doesn't exist |
  340. | [L04](./docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Why does one giant instruction file fail? | Progressive disclosure: give a map, not an encyclopedia |
  341. | [L05](./docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Why do long-running tasks lose continuity? | Persist progress to disk; pick up where you left off |
  342. | [L06](./docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Why does initialization need its own phase? | Verify the environment is healthy before the agent starts work |
  343. | [L07](./docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Why do agents overreach and under-finish? | One feature at a time; explicit definition of done |
  344. | [L08](./docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Why are feature lists harness primitives? | Machine-readable scope boundaries the agent can't ignore |
  345. | [L09](./docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Why do agents declare victory too early? | Verification gaps: confidence ≠ correctness |
  346. | [L10](./docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Why does end-to-end testing change results? | Only a full-pipeline run counts as real verification |
  347. | [L11](./docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Why does observability belong inside the harness? | If you can't see what the agent did, you can't fix what it broke |
  348. | [L12](./docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Why must every session leave a clean state? | The next session's success depends on this session's cleanup |
  349. | [L13](./docs/en/lectures/lecture-13-loop-engineering/index.md) | Why do you need to stop prompting your agent? | From manual driving to automated loops — goal loops, timer loops, and maker-checker separation |
  350. | [L14](./docs/en/lectures/lecture-14-graph-engineering/index.md) | Why does a single loop grow into a graph? | From single loops to graph engineering — nodes, edges, shared state, routing, and when a graph is actually worth drawing |
  351. ### Projects — 8 hands-on projects applying lecture methods to the same Electron app
  352. | Project | What You Do | Harness Mechanism |
  353. |---------|------------|-------------------|
  354. | [P01](./docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | Run the same task twice: prompt-only vs. rules-first | Minimal harness: AGENTS.md + init.sh + feature_list.json |
  355. | [P02](./docs/en/projects/project-02-agent-readable-workspace/index.md) | Restructure the repo so the agent can read it | Agent-readable workspace + persistent state files |
  356. | [P03](./docs/en/projects/project-03-multi-session-continuity/index.md) | Make the agent pick up from where it left off | Progress log + session handoff + multi-session continuity |
  357. | [P04](./docs/en/projects/project-04-incremental-indexing/index.md) | Stop the agent from doing too much or too little | Runtime feedback + scope control + incremental indexing |
  358. | [P05](./docs/en/projects/project-05-grounded-qa-verification/index.md) | Make the agent verify its own work | Self-verification + grounded Q&A + evidence-based completion |
  359. | [P06](./docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | Build a complete harness from scratch (capstone) | Full harness: all mechanisms + observability + ablation study |
  360. | [P07](./docs/en/projects/project-07-loop-engineering-first-loop/index.md) | Build your first automated loop | Goal loops, timer loops, maker-checker separation, loop state management |
  361. | [P08](./docs/en/projects/project-08-graph-engineering-first-graph/index.md) | Draw your workflow as a graph | Explicit nodes/edges/state/routing, parallel fan-out/fan-in, rollback edges, human-in-the-loop approval |
  362. ```text
  363. PROJECT EVOLUTION
  364. =================
  365. P01 Prompt-only vs. rules-first You see the problem
  366. |
  367. v
  368. P02 Agent-readable workspace You restructure the repo
  369. |
  370. v
  371. P03 Multi-session continuity You connect sessions
  372. |
  373. v
  374. P04 Runtime feedback & scope You add feedback loops
  375. |
  376. v
  377. P05 Self-verification You make the agent check itself
  378. |
  379. v
  380. P06 Complete harness (capstone) You build the full system
  381. |
  382. v
  383. P07 Your first automated loop You step outside the loop
  384. |
  385. v
  386. P08 Draw your workflow as a graph You draw the system as a graph
  387. Each project's solution becomes the next project's starter.
  388. The app evolves. Your harness skills grow with it.
  389. ```
  390. ### Resource Library
  391. - [English](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — templates, checklists, and method references
  392. - [简体中文](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考
  393. - [繁體中文](https://walkinglabs.github.io/learn-harness-engineering/zh-TW/resources/) — 繁體中文範本、清單和方法參考
  394. - [日本語](https://walkinglabs.github.io/learn-harness-engineering/ja/resources/) — テンプレート、チェックリスト、方法リファレンス
  395. - [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/resources/) — 템플릿, 체크리스트, 방법 참고 자료
  396. - [Español](https://walkinglabs.github.io/learn-harness-engineering/es/resources/) — plantillas, listas de verificación y referencias
  397. - [Français](https://walkinglabs.github.io/learn-harness-engineering/fr/resources/) — modèles, listes de contrôle et références
  398. - [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/resources/) — шаблоны, чек-листы и справочники
  399. - [Deutsch](https://walkinglabs.github.io/learn-harness-engineering/de/resources/) — Vorlagen, Checklisten und Referenzen
  400. - [العربية](https://walkinglabs.github.io/learn-harness-engineering/ar/resources/) — قوالب، قوائم تحقق ومراجع
  401. - [Tiếng Việt](https://walkinglabs.github.io/learn-harness-engineering/vi/resources/) — mẫu, danh sách kiểm tra và tài liệu tham khảo
  402. - [Oʻzbekcha](https://walkinglabs.github.io/learn-harness-engineering/uz/resources/) — andozalar, tekshiruv roʻyxatlari va maʼlumotnomalar
  403. - [Türkçe](https://walkinglabs.github.io/learn-harness-engineering/tr/resources/) — şablonlar, kontrol listeleri ve referanslar
  404. - [Português (BR)](https://walkinglabs.github.io/learn-harness-engineering/pt-BR/resources/) — modelos, listas de verificação e referências de métodos
  405. ---
  406. ## The Agent Session Lifecycle
  407. 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:
  408. <p align="center">
  409. <a href="assets/readme/harness-session-lifecycle.svg">
  410. <picture>
  411. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/harness-session-lifecycle-dark.svg">
  412. <img src="assets/readme/harness-session-lifecycle.png" alt="Start, select one feature, execute and verify with a fix-and-rerun loop, then wrap up with persistent state." width="920">
  413. </picture>
  414. </a>
  415. </p>
  416. <details>
  417. <summary>Text version</summary>
  418. ```text
  419. AGENT SESSION LIFECYCLE
  420. ======================
  421. ┌──────────────────────────────────────────────────────────────────┐
  422. │ START │
  423. │ │
  424. │ 1. Agent reads AGENTS.md / CLAUDE.md │
  425. │ 2. Agent runs init.sh (install, verify, health check) │
  426. │ 3. Agent reads claude-progress.md (what happened last time) │
  427. │ 4. Agent reads feature_list.json (what's done, what's next) │
  428. │ 5. Agent checks git log (recent changes) │
  429. │ │
  430. │ SELECT │
  431. │ │
  432. │ 6. Agent picks exactly ONE unfinished feature │
  433. │ 7. Agent works only on that feature │
  434. │ │
  435. │ EXECUTE │
  436. │ │
  437. │ 8. Agent implements the feature │
  438. │ 9. Agent runs verification (tests, lint, type-check) │
  439. │ 10. If verification fails: fix and re-run │
  440. │ 11. If verification passes: record evidence │
  441. │ │
  442. │ WRAP UP │
  443. │ │
  444. │ 12. Agent updates claude-progress.md │
  445. │ 13. Agent updates feature_list.json │
  446. │ 14. Agent records what's still broken or unverified │
  447. │ 15. Agent commits (only when safe to resume) │
  448. │ 16. Agent leaves clean restart path for next session │
  449. │ │
  450. └──────────────────────────────────────────────────────────────────┘
  451. The harness governs every transition in this lifecycle.
  452. The model decides what code to write at each step.
  453. Without the harness, step 9 becomes "agent says it looks fine."
  454. With the harness, step 9 is "tests pass, lint is clean, types check."
  455. ```
  456. </details>
  457. ---
  458. ## Who This Is For
  459. This course is for:
  460. - Engineers already using coding agents who want better stability and quality
  461. - Researchers or builders who want a systematic understanding of harness design
  462. - Tech leads who need to understand how environment design affects agent performance
  463. This course is not for:
  464. - People looking for a zero-code AI introduction
  465. - People who only care about prompts and don't plan to build real implementations
  466. - Learners not prepared to let agents work inside real repositories
  467. ---
  468. ## Requirements
  469. This is a course where you actually run coding agents.
  470. You need at least one of these tools:
  471. - Claude Code
  472. - Codex
  473. - Another IDE or CLI coding agent that supports file editing, command execution, and multi-step tasks
  474. The course assumes you can:
  475. - Open a local repository
  476. - Allow the agent to edit files
  477. - Allow the agent to run commands
  478. - Inspect output and re-run tasks
  479. 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.
  480. ---
  481. ## Local Preview
  482. This repository uses VitePress as a documentation viewer.
  483. ```sh
  484. npm install
  485. npm run docs:dev # Dev server with hot reload
  486. npm run docs:build # Production build
  487. npm run docs:preview # Preview built site
  488. ```
  489. Then open the local URL that VitePress outputs in your browser.
  490. ---
  491. ## Prerequisites
  492. Required:
  493. - Familiarity with the terminal, git, and local development environments
  494. - Ability to read and write code in at least one common application stack
  495. - Basic software debugging experience (reading logs, tests, and runtime behavior)
  496. - Enough time to commit to implementation-focused coursework
  497. Helpful but not required:
  498. - Experience with Electron, desktop apps, or local-first tools
  499. - Background in testing, logging, or software architecture
  500. - Prior exposure to Codex, Claude Code, or similar coding agents
  501. ---
  502. ## Core References
  503. Primary:
  504. - [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
  505. - [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
  506. - [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
  507. - [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/)
  508. - [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)
  509. - [LangChain: Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering)
  510. - [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
  511. - [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
  512. See the full layered reference list in [`docs/en/resources/reference/`](./docs/en/resources/reference/index.md).
  513. ---
  514. ## Repository Structure
  515. ```text
  516. learn-harness-engineering/
  517. ├── docs/ # VitePress documentation site
  518. │ ├── lectures/ # 14 lectures (index.md + code/ examples)
  519. │ │ ├── lecture-01-*/
  520. │ │ └── ... (14 total)
  521. │ ├── projects/ # 8 project descriptions
  522. │ │ ├── project-01-*/
  523. │ │ └── ... (8 total)
  524. │ └── resources/ # Multilingual templates & references (14 languages)
  525. │ ├── en/
  526. │ └── ... (14 total)
  527. ├── projects/
  528. │ ├── shared/ # Shared Electron + TypeScript + React foundation
  529. │ └── project-NN/ # Per-project starter/ and solution/ directories
  530. ├── skills/ # Reusable AI agent skills
  531. │ └── harness-creator/ # Harness engineering skill
  532. ├── tools/ # Zero-dependency shell utilities
  533. │ └── audit-harness.sh # Shell-based harness audit (L03–L12, no Node.js needed)
  534. ├── package.json # VitePress + dev tooling
  535. └── CLAUDE.md # Claude Code instructions for this repo
  536. ```
  537. ---
  538. ## How the Course Is Organized
  539. - Each lecture focuses on one question
  540. - The course includes 8 projects
  541. - Every project requires the agent to do real work
  542. - Every project compares weak vs. strong harness results
  543. - What matters is the measured difference, not how many docs were written
  544. ---
  545. ## Skills
  546. This repository also includes reusable AI agent skills that you can install directly into your IDE or agent workspace.
  547. - [**harness-creator**](./skills/harness-creator/): A skill that helps you scaffold a production-grade harness for your own project in minutes.
  548. ## Tools
  549. Zero-dependency utilities you can run without installing Node.js.
  550. - [**audit-harness.sh**](./tools/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`.
  551. ```bash
  552. # Run directly on any repo
  553. curl -fsSL https://raw.githubusercontent.com/walkinglabs/learn-harness-engineering/main/tools/audit-harness.sh | bash -s -- /path/to/your/repo
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 728 on GitHub
  554. # Or after cloning
  555. bash tools/audit-harness.sh /path/to/your/repo
  556. ```
  557. ---
  558. ## Other Courses
  559. Our team has also created other courses! Check them out:
  560. [![Hands-on Modern RL](https://img.shields.io/badge/HANDS--ON_MODERN_RL-0052cc?style=for-the-badge)](https://github.com/walkinglabs/hands-on-modern-rl)
  561. **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.
  562. [![Modern LLM Notebook](https://img.shields.io/badge/MODERN_LLM_NOTEBOOK-0052cc?style=for-the-badge)](https://github.com/walkinglabs/modern-llm-notebook)
  563. **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.
  564. ---
  565. ## Acknowledgments
  566. This course was inspired by and draws ideas from [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) — a progressive guide to building an agent from scratch, from a single loop to isolated autonomous execution.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.