Skip to content

Harness engineering beginner tutorial, from 0 to 1

Polish READMEs with ASCII diagrams, detailed structure, and acknowledgments

sanbuphyd96cb507dedd
diff --git a/README-CN.md b/README-CN.md
index d6375dd..1598652 100644
--- a/README-CN.md
+++ b/README-CN.md
@@ -2,45 +2,145 @@
> 这是一门项目制课程:系统学习如何通过环境、状态、验证与控制机制,让 Codex 和 Claude Code 更可靠地工作。
+本课程仍在持续建设中,内容后续可能会调整。
+
[英文版](./README.md)
-本课程仍在持续建设中,内容后续可能会调整。
+---
+
+## 模型很强,但 Harness 让它靠谱
+
+有一个很多人交过学费才明白的事实:**世界上最强的模型,如果没有一个合适的工作环境,依然会在真实工程任务中翻车。**
+
+你多半见过这种情况。你给 Claude 或 GPT 一个任务,它看起来干得不错——读文件、写代码、很努力。然后出问题了。它跳过了一个步骤。它搞坏了一个测试。它说"完成了"但实际上什么都没跑通。你花在收拾烂摊子上的时间比自己做还多。
+
+这不是模型的问题,这是 harness 的问题。
+
+证据很明确。Anthropic 做过一组对照实验:同一个模型(Opus 4.5),同一段提示词("做一个 2D 复古游戏编辑器")。没有 harness 的情况下,20 分钟花了 $9,结果游戏核心功能跑不起来。加上完整 harness(planner + generator + evaluator 三 agent 架构),6 小时花了 $200,做出来的游戏可以正常游玩。模型没换,换的是 harness。
+
+OpenAI 用 Codex 也得出了同样结论:在一个 harness 搭得好的仓库里,同一个模型从"不可靠"变成"可靠"——不是"好了一点",是质变。
+
+**这门课教你怎么搭建那个环境。**
+
+```text
+ THE HARNESS PATTERN
+ ====================
+
+ You --> give task --> Agent reads harness files --> Agent executes
+ |
+ harness governs every step:
+ |
+ +--> Instructions: what to do, in what order
+ +--> Scope: one feature at a time, no overreach
+ +--> State: progress log, feature list, git history
+ +--> Verification: tests, lint, type-check, smoke runs
+ +--> Boundaries: what counts as "done," what counts as "broken"
+ |
+ v
+ Agent stops only when
+ verification passes
+```
+
+---
+
+## Harness Engineering 到底是什么
+
+Harness engineering 是围绕模型搭建一整套工作环境,让它产出可靠的结果。不只是写更好的提示词,而是设计模型运行所在的系统。
+
+一个 harness 包含五个子系统:
+
+```text
+ ┌─────────────────────────────────────────────────────────────────┐
+ │ 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 │ │
+ │ └──────────────┘ └──────────────────────────────────────┘ │
+ │ │
+ └─────────────────────────────────────────────────────────────────┘
+
+ The MODEL decides what code to write.
+ The HARNESS governs when, where, and how it writes it.
+ The harness doesn't make the model smarter.
+ It makes the model's output reliable.
+```
+
+每个子系统各司其职:
-## 课程概览
+- **Instructions(指令)** — 告诉 agent 做什么、按什么顺序、开工前先读什么。不是一个巨大的文件,而是渐进式展开的结构,agent 按需导航。
+- **State(状态)** — 跟踪做了什么、正在做什么、下一步是什么。持久化到磁盘,下次会话从上次停下的地方继续。
+- **Verification(验证)** — 只有通过的测试套件才算数。agent 不能没有可运行的证据就说"做完了"。
+- **Scope(范围)** — 约束 agent 一次只做一个功能。不多做,不少做,不偷偷改功能清单掩盖未完成的工作。
+- **Session Lifecycle(会话生命周期)** — 开始时初始化,结束时清理,给下次会话留一条干净的重启路径。
-Harness engineering 指的是:围绕模型搭建一整套工作环境,让它干活更靠谱。这不只是写提示词,还包括:
+---
-- 代码放哪、怎么组织
-- 什么能干、什么干不了
-- 任务做到哪了、下次怎么接上
-- 做完怎么验证对不对
-- 出了问题怎么排查
-- 哪些规矩必须遵守
-- 怎么保持干净、不留烂摊子
+## 为什么要有这门课
-这门课是**强实践导向**的。我们不会只停留在“概念解释”,而是会让 Codex 或 Claude Code 在同一个不断演化的 Electron 应用上反复工作,并比较弱 harness 与强 harness 的差异。
+问题不是"模型能不能写代码"。能写。问题是:**能不能在真实的仓库里,跨越多次会话,不需要人一直盯着,就可靠地完成真实的工程任务?**
-课程真正关心的问题是:
+现在的答案是:没有 harness 就不行。
+
+```text
+ WITHOUT HARNESS WITH HARNESS
+ ============== ============
+
+ Session 1: agent writes code Session 1: agent reads instructions
+ agent breaks tests agent runs init.sh
+ agent says "done" agent works on one feature
+ you fix it manually agent verifies before claiming done
+ agent updates progress log
+ Session 2: agent starts fresh agent commits clean state
+ agent has no memory
+ of what happened before Session 2: agent reads progress log
+ agent re-does work agent picks up exactly where it left off
+ or does something else entirely agent continues the unfinished feature
+ you fix it again you review, not rescue
+
+ Result: you spend more time Result: agent does the work,
+ cleaning up than if you you verify the result
+ did it yourself
+```
+
+课程真正关心的问题:
- 哪些 harness 设计会提升任务完成率?
- 哪些设计会减少返工和错误完成?
- 哪些机制能让长时任务更稳定地持续推进?
- 哪些结构能让系统在多轮 agent 运行后仍然可维护?
-## 核心观点
-
-以后让模型干活,人只需要定好规则和边界。这就是 harness。
-
-**这事的关键:** 模型很强,但不代表它能自动靠谱地完成真实工程任务。它需要一套明确的规则来约束自己的行为范围、需要清晰的交接机制来维持长时任务的连续性、需要验证手段来确认自己做对了。
-
-我们不是在尝试“让模型本身更聪明”,而是在研究:怎么给模型搭建一个靠谱的工作环境,让同一个模型做出更可靠的工作。
+---
-## 快速开始
+## 快速开始:今天就能改善你的 agent
不用读完 12 个讲义再动手。如果你已经在用 coding agent 做项目,下面这些能立刻改善效果。
思路很简单:不是光写提示词,而是在仓库里放一组结构化的文件——告诉 agent 该做什么、做完了什么、怎么验证。这些文件就放在项目里,每次会话都从同一个状态开始。
+```text
+ 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 <-- what happened each session
+ └── src/ <-- your actual code
+```
+
**第一步.** 把根指令文件复制到项目根目录:
- [`AGENTS.md`](./docs/resources/zh/templates/AGENTS.md) 通用版,或者 [`CLAUDE.md`](./docs/resources/zh/templates/CLAUDE.md) 如果你用 Claude Code
@@ -71,67 +171,215 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
每个文件的详细用法写在 [中文模板指南](./docs/resources/zh/templates/index.md)。英文版见 [英文模板指南](./docs/resources/en/templates/index.md)。
-如果你想直接用 OpenAI 那篇 harness engineering 文章里的更完整高级结构,可以继续看
-[`docs/resources/zh/openai-advanced/`](./docs/resources/zh/openai-advanced/index.md)
-和 [`docs/resources/en/openai-advanced/`](./docs/resources/en/openai-advanced/index.md)。
-
-## 课程大纲
+如果你想直接用 OpenAI 那篇 harness engineering 文章里的更完整高级结构,可以继续看 [`docs/resources/zh/openai-advanced/`](./docs/resources/zh/openai-advanced/index.md) 和 [`docs/resources/en/openai-advanced/`](./docs/resources/en/openai-advanced/index.md)。
+
+---
+
+## 贯穿项目:一个真实的应用
+
+全部 6 个课程项目都围绕同一个产品:**一个基于 Electron 的个人知识库桌面应用**。
+
+```text
+ ┌─────────────────────────────────────────────────────┐
+ │ 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 │ │ around an agent model... ││
+ │ │ ... │ │ [citation: doc-002.md] ││
+ │ └──────────────┘ └──────────────────────────────┘│
+ │ │
+ │ ┌─────────────────────────────────────────────────┐│
+ │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ └─────────────────────────────────────────────────┘│
+ └─────────────────────────────────────────────────────┘
+
+ Core features:
+ ├── Import local documents
+ ├── Manage a document library
+ ├── Process and index documents
+ ├── Run AI-powered Q&A over imported content
+ └── Return grounded answers with citations
+```
-### 讲义
-
-- [Lecture 01. 模型能力强,不等于执行可靠](./docs/lectures/lecture-01-why-capable-agents-still-fail/index.md)
-- [Lecture 02. Harness 的定义](./docs/lectures/lecture-02-what-a-harness-actually-is/index.md)
-- [Lecture 03. 让代码仓库成为唯一的事实来源](./docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)
-- [Lecture 04. 把指令拆分到不同文件里](./docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)
-- [Lecture 05. 让跨会话的任务保持上下文连续](./docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md)
-- [Lecture 06. 让 agent 每次工作前先初始化](./docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)
-- [Lecture 07. 给 agent 划清每次任务的边界](./docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md)
-- [Lecture 08. 用功能清单约束 agent 该做什么](./docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)
-- [Lecture 09. 防止 agent 提前宣告完成](./docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md)
-- [Lecture 10. 跑通完整流程才算真正验证](./docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)
-- [Lecture 11. 让 agent 的运行过程可观测](./docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)
-- [Lecture 12. 每次会话结束前都做好交接](./docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)
-
-### 项目
-
-- [Project 01. 只写提示词让 agent 做,和定好规则再让它做,差多少](./docs/projects/project-01-baseline-vs-minimal-harness/index.md)
-- [Project 02. 让 agent 看懂项目、接住上次的工作](./docs/projects/project-02-agent-readable-workspace/index.md)
-- [Project 03. 让 agent 关掉再打开还能接着干](./docs/projects/project-03-multi-session-continuity/index.md)
-- [Project 04. 用运行反馈修正 agent 的行为](./docs/projects/project-04-incremental-indexing/index.md)
-- [Project 05. 让 agent 自己检查自己做的对不对](./docs/projects/project-05-grounded-qa-verification/index.md)
-- [Project 06. 搭建一套完整的 agent 工作环境](./docs/projects/project-06-runtime-observability-and-debugging/index.md)
+选择这个项目是因为它同时具备:很强的实际价值感、足够真实的产品复杂度、以及很适合观察 harness 优化前后的效果差异。
-### 资料库
+每个课程项目的 starter/solution 是这个 Electron 应用在对应演化阶段的完整副本。P(N+1) 的 starter 从 P(N) 的 solution 衍生而来——应用跟着你的 harness 技能一起进化。
-- [资料库总览](./docs/resources/index.md)
-- [中文资料库](./docs/resources/zh/index.md)
-- [英文资料库](./docs/resources/en/index.md)
+---
-## 学习路径推荐
+## 学习路径
这门课按顺序来效果最好,每一阶段都建立在前一个的基础上。
-**第一阶段 — 先看到问题。** 读讲义 01-02,做项目 01。你会跑两次同样的任务:一次只给提示词,一次加了最基本的规则。差距一目了然。
+```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
-**第二阶段 — 让项目对 agent 友好。** 讲义 03-04,项目 02。你会重组项目结构,让 agent 能读懂,并且加上跨会话的持久文件。
-**第三阶段 — 让会话接得上。** 讲义 05-06,项目 03。这里开始有意思了,让 agent 在你关掉会话后重新打开,还能从上次停下的地方接着干。
+ Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
+ ========================== =========================
-**第四阶段 — 加上反馈和范围控制。** 讲义 07-08,项目 04。防止 agent 做多了或做少了,用运行反馈让它保持在正轨上。
+ 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
-**第五阶段 — 验证和自查。** 讲义 09-10,项目 05。让 agent 学会验证自己的工作,而不是做完就说“好了”。
-**第六阶段 — 全部串起来。** 讲义 11-12,项目 06。这是综合项目。你将从零开始搭建一套完整的 harness,把前面学的全用上。
+ Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
+ ===================== ============================
+
+ L09 Stop agents from L11 Make agent's runtime
+ declaring victory early observable
+
+ L10 Full-pipeline run = L12 Clean handoff at end of
+ real verification every session
+
+ | |
+ v v
+ P05 Agent verifies its own work P06 Build a complete harness
+ (capstone project)
+```
每个阶段大约一周(兼职节奏)。想快的话,前三个阶段一个周末就能跑完。
+---
+
+## 课程大纲
+
+### 讲义 — 12 个概念单元,每个只回答一个核心问题
+
+| Session | 核心问题 | 关键概念 |
+| ------- | -------- | -------- |
+| [L01](./docs/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 模型能力强,不等于执行可靠 | 基准测试与真实工程之间的能力鸿沟 |
+| [L02](./docs/lectures/lecture-02-what-a-harness-actually-is/index.md) | Harness 到底是什么 | 五个子系统:指令、状态、验证、范围、生命周期 |
+| [L03](./docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 让仓库成为唯一事实来源 | agent 看不到的东西,对它来说就不存在 |
+| [L04](./docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | 为什么一个巨大的指令文件会失败 | 渐进式展开:给地图,不给百科全书 |
+| [L05](./docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | 为什么长时任务会丢失上下文 | 把进度持久化到磁盘,从停下的地方继续 |
+| [L06](./docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | 为什么初始化需要单独一个阶段 | agent 开始工作前先验证环境是否健康 |
+| [L07](./docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | 为什么 agent 会多做或少做 | 一次一个功能,显式的完成定义 |
+| [L08](./docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | 为什么功能清单是 harness 原语 | 机器可读的范围边界,agent 无法忽略 |
+| [L09](./docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | 为什么 agent 会提前宣告完成 | 验证缺口:自信 ≠ 正确 |
+| [L10](./docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | 为什么端到端测试会改变结果 | 只有跑通完整流程才算真正验证 |
+| [L11](./docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | 为什么可观测性属于 harness | 看不到 agent 做了什么,就修不了它搞坏的东西 |
+| [L12](./docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | 为什么每次会话都要留干净状态 | 下次会话的成功,取决于这次会话的清理 |
+
+### 项目 — 6 个实践项目,把讲义方法落实到同一个 Electron 应用上
+
+| Project | 你要做什么 | Harness 机制 |
+| ------- | ---------- | ------------ |
+| [P01](./docs/projects/project-01-baseline-vs-minimal-harness/index.md) | 跑两次同样的任务:只写提示词 vs 定好规则 | 最小 harness:AGENTS.md + init.sh + feature_list.json |
+| [P02](./docs/projects/project-02-agent-readable-workspace/index.md) | 重组项目结构,让 agent 能读懂 | Agent 可读的工作空间 + 持久化状态文件 |
+| [P03](./docs/projects/project-03-multi-session-continuity/index.md) | 让 agent 关掉再打开还能接着干 | 进度日志 + 会话交接 + 多会话连续性 |
+| [P04](./docs/projects/project-04-incremental-indexing/index.md) | 防止 agent 做多了或做少了 | 运行反馈 + 范围控制 + 增量索引 |
+| [P05](./docs/projects/project-05-grounded-qa-verification/index.md) | 让 agent 自己验证自己的工作 | 自验证 + 带引用的问答 + 基于证据的完成判定 |
+| [P06](./docs/projects/project-06-runtime-observability-and-debugging/index.md) | 从零搭建一套完整的 harness(综合项目) | 完整 harness:全部机制 + 可观测性 + 消融实验 |
+
+```text
+ PROJECT EVOLUTION
+ =================
+
+ P01 Prompt-only vs. rules-first You see the problem
+ |
+ v
+ P02 Agent-readable workspace You restructure the repo
+ |
+ v
+ P03 Multi-session continuity You connect sessions
+ |
+ v
+ P04 Runtime feedback & scope You add feedback loops
+ |
+ v
+ P05 Self-verification You make the agent check itself
+ |
+ v
+ P06 Complete harness (capstone) You build the full system
+
+ Each project's solution becomes the next project's starter.
+ The app evolves. Your harness skills grow with it.
+```
+
+### 资料库
+
+- [资料库总览](./docs/resources/index.md)
+- [中文资料库](./docs/resources/zh/index.md) — 中文模板、清单和方法参考
+- [英文资料库](./docs/resources/en/index.md) — English templates, checklists, and method references
+
+---
+
+## Agent 会话生命周期
+
+这门课的一个核心理念:**agent 的会话应该遵循结构化的生命周期,而不是自由发挥。** 它长这样:
+
+```text
+ 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."
+```
+
+---
+
## 适合谁
这门课适合:
- 已经在使用 coding agent、希望提升稳定性和质量的工程师
- 想系统理解 harness 设计的研究者或构建者
-- 需要理解“环境设计如何影响 agent 表现”的技术负责人
+- 需要理解"环境设计如何影响 agent 表现"的技术负责人
这门课不适合:
@@ -139,6 +387,8 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
- 只关心 prompt,而不打算做真实实现的人
- 不准备让 agent 在真实仓库里工作的学习者
+---
+
## 环境要求
这是一门真正需要动手跑 coding agent 的课程。
@@ -158,17 +408,23 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
如果你没有这类工具,仍然可以阅读课程内容,但无法按预期完成课程项目。
+---
+
## 本地预览
本仓库使用 VitePress 作为文档查看器。
```sh
npm install
-npm run docs:dev
+npm run docs:dev # Dev server with hot reload
+npm run docs:build # Production build
+npm run docs:preview # Preview built site
```
然后在浏览器里打开 VitePress 输出的本地地址即可。
+---
+
## 先修要求
必需:
@@ -184,6 +440,8 @@ npm run docs:dev
- 有测试、日志、软件架构方面的经验
- 已经接触过 Codex、Claude Code 或类似 coding agent
+---
+
## 核心参考资料
主参考:
@@ -198,40 +456,31 @@ npm run docs:dev
- [Thoughtworks: Harness Engineering](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html)
- [HumanLayer: Skill Issue: Harness Engineering for Coding Agents](https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents)
-## 贯穿项目
-
-本课程的大多数项目都围绕同一个产品展开:
-
-- 一个基于 Electron 的个人知识库桌面应用
-
-核心目标包括:
-
-- 导入本地文档
-- 管理文档库
-- 处理与索引文档
-- 对导入内容发起 AI 问答
-- 返回带引用且可追溯的回答
-
-之所以选择这个项目,是因为它同时具备:
+---
-- 很强的实际价值感
-- 足够真实的产品复杂度
-- 很适合观察 harness 优化前后的效果差异
-
-## 课程作业形式
-
-本课程包含两类内容:
-
-- **讲义**:12 个概念单元,每个单元只回答一个核心问题
-- **项目**:6 个实践项目,把讲义里的方法落实到同一个 Electron 应用上
-
-每个 project 都要求你:
+## 仓库结构
-- 让 Codex 或 Claude Code 执行真实任务
-- 比较弱 harness 与强 harness 的差别
-- 观察可靠性、连续性、验证质量、可维护性的变化
+```text
+learn-harness-engineering/
+├── docs/ # VitePress documentation site
+│ ├── lectures/ # 12 lectures (index.md + code/ examples)
+│ │ ├── lecture-01-*/
+│ │ ├── lecture-02-*/
+│ │ └── ... (12 total)
+│ ├── projects/ # 6 project descriptions
+│ │ ├── project-01-*/
+│ │ └── ... (6 total)
+│ └── resources/ # Bilingual templates & references
+│ ├── en/ # English templates, checklists, guides
+│ └── zh/ # 中文模板、清单和指南
+├── projects/
+│ ├── shared/ # Shared Electron + TypeScript + React foundation
+│ └── project-NN/ # Per-project starter/ and solution/ directories
+├── package.json # VitePress + dev tooling
+└── CLAUDE.md # Claude Code instructions for this repo
+```
-最后一个项目同时也是整个课程的综合 harness。
+---
## 课程组织方式
@@ -239,12 +488,10 @@ npm run docs:dev
- 整门课配套 6 个项目
- 每个项目都要求 agent 真正干活
- 每个项目都要做弱 harness / 强 harness 对照
-- 我们关心的是效果变化,而不是“写了多少说明文档”
+- 我们关心的是效果变化,而不是"写了多少说明文档"
-## 仓库结构
+---
-- `docs/lectures/` - 全部讲义
-- `docs/projects/` - 全部实践项目,包括综合项目
-- `docs/resources/` - 中英双语的可复用模板、检查清单和方法参考
+## 致谢
-每个讲义都带一个 `code/` 目录,用来放小型真实示例和配套材料。
+本课程的灵感和部分思路来自 [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) —— 一个从零开始搭建 agent harness 的渐进式教程,从单个循环到隔离的自主执行。
diff --git a/README.md b/README.md
index cbafdaf..83d3d5b 100644
--- a/README.md
+++ b/README.md
@@ -6,19 +6,115 @@ This course is a work in progress. Content may change as it evolves.
[中文版本](./README-CN.md)
-## Overview
+---
-Harness engineering is about building a complete working environment around the model so it produces reliable results. It's not just about writing prompts. It also covers:
+## The Model Is Smart, The Harness Makes It Reliable
-- Where code lives and how it's organized
-- What the agent is and isn't allowed to do
-- How to track task progress and pick up where you left off
-- How to verify that work was done correctly
-- How to diagnose problems when they arise
-- What rules must always be followed
-- How to leave things clean after each session
+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.**
-This course is **hands-on**. We won't stop at concepts. You'll have Codex or Claude Code work repeatedly on the same evolving Electron application, comparing weak harnesses against strong ones.
+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.
+
+This isn't a model problem. It's a harness problem.
+
+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.
+
+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.
+
+**This course teaches you how to build that environment.**
+
+```text
+ THE HARNESS PATTERN
+ ====================
+
+ You --> give task --> Agent reads harness files --> Agent executes
+ |
+ harness governs every step:
+ |
+ +--> Instructions: what to do, in what order
+ +--> Scope: one feature at a time, no overreach
+ +--> State: progress log, feature list, git history
+ +--> Verification: tests, lint, type-check, smoke runs
+ +--> Boundaries: what counts as "done," what counts as "broken"
+ |
+ v
+ Agent stops only when
+ verification passes
+```
+
+---
+
+## What Harness Engineering Actually Means
+
+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.
+
+A harness has five subsystems:
+
+```text
+ ┌─────────────────────────────────────────────────────────────────┐
+ │ 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 │ │
+ │ └──────────────┘ └──────────────────────────────────────┘ │
+ │ │
+ └─────────────────────────────────────────────────────────────────┘
+
+ The MODEL decides what code to write.
+ The HARNESS governs when, where, and how it writes it.
+ The harness doesn't make the model smarter.
+ It makes the model's output reliable.
+```
+
+Each subsystem has one job:
+
+- **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.
+- **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.
+- **Verification** — Only a passing test suite counts as evidence. The agent cannot declare victory without runnable proof.
+- **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.
+- **Session Lifecycle** — Initialize at the start. Clean up at the end. Leave a clean restart path for the next session.
+
+---
+
+## Why This Course Exists
+
+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?**
+
+Right now, the answer is: not without a harness.
+
+```text
+ WITHOUT HARNESS WITH HARNESS
+ ============== ============
+
+ Session 1: agent writes code Session 1: agent reads instructions
+ agent breaks tests agent runs init.sh
+ agent says "done" agent works on one feature
+ you fix it manually agent verifies before claiming done
+ agent updates progress log
+ Session 2: agent starts fresh agent commits clean state
+ agent has no memory
+ of what happened before Session 2: agent reads progress log
+ agent re-does work agent picks up exactly where it left off
+ or does something else entirely agent continues the unfinished feature
+ you fix it again you review, not rescue
+
+ Result: you spend more time Result: agent does the work,
+ cleaning up than if you you verify the result
+ did it yourself
+```
The questions this course actually cares about:
@@ -27,20 +123,24 @@ The questions this course actually cares about:
- Which mechanisms keep long-running tasks progressing steadily?
- Which structures keep the system maintainable after multiple agent runs?
-## Core Thesis
+---
-When you let models do work, the human's job is to define the rules and boundaries. That's the harness.
+## Quick Start: Improve Your Agent Today
-**The key point:** Models are powerful, but that doesn't mean they can reliably complete real engineering tasks on their own. They need explicit rules to constrain their scope, clear handoff mechanisms to maintain continuity across long tasks, and verification methods to confirm they did the work correctly.
-
-We're not trying to "make the model smarter." We're studying how to build a reliable working environment around the model so the same model produces more reliable output.
-
-## Quick Start
-
-You don't need to read all 12 lectures before you start getting value from this course. If you're already using a coding agent on a real project, here's how to improve it right now.
+You don't need to read all 12 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.
+```text
+ 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 <-- what happened each session
+ └── src/ <-- your actual code
+```
+
**Step 1.** Copy the root instruction file into your project root:
- [`AGENTS.md`](./docs/resources/en/templates/AGENTS.md) for most agents, or [`CLAUDE.md`](./docs/resources/en/templates/CLAUDE.md) if you're using Claude Code
@@ -71,60 +171,207 @@ When your project gets more complex, add these:
Each file has detailed usage instructions in the [English template guide](./docs/resources/en/templates/index.md). Chinese versions are available in [中文模板指南](./docs/resources/zh/templates/index.md).
-If you want the fuller OpenAI-style repository layout from the
-"Harness engineering" post, use the advanced pack in
-[`docs/resources/en/openai-advanced/`](./docs/resources/en/openai-advanced/index.md) or
-[`docs/resources/zh/openai-advanced/`](./docs/resources/zh/openai-advanced/index.md).
+For the fuller OpenAI-style repository layout, use the advanced pack in [`docs/resources/en/openai-advanced/`](./docs/resources/en/openai-advanced/index.md) or [`docs/resources/zh/openai-advanced/`](./docs/resources/zh/openai-advanced/index.md).
+
+---
+
+## Capstone Project: A Real App
+
+All six course projects revolve around the same product: **an Electron-based personal knowledge base desktop app**.
+
+```text
+ ┌─────────────────────────────────────────────────────┐
+ │ 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 │ │ around an agent model... ││
+ │ │ ... │ │ [citation: doc-002.md] ││
+ │ └──────────────┘ └──────────────────────────────┘│
+ │ │
+ │ ┌─────────────────────────────────────────────────┐│
+ │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ └─────────────────────────────────────────────────┘│
+ └─────────────────────────────────────────────────────┘
+
+ Core features:
+ ├── Import local documents
+ ├── Manage a document library
+ ├── Process and index documents
+ ├── Run AI-powered Q&A over imported content
+ └── Return grounded answers with citations
+```
-## Syllabus
+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.
-### Lectures
-
-- [Lecture 01. Strong models don't mean reliable execution](./docs/lectures/lecture-01-why-capable-agents-still-fail/index.md)
-- [Lecture 02. What harness actually means](./docs/lectures/lecture-02-what-a-harness-actually-is/index.md)
-- [Lecture 03. Make the repository your single source of truth](./docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)
-- [Lecture 04. Split instructions across files, not one giant file](./docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)
-- [Lecture 05. Keep context alive across sessions](./docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md)
-- [Lecture 06. Initialize before every agent session](./docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)
-- [Lecture 07. Draw clear task boundaries for agents](./docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md)
-- [Lecture 08. Use feature lists to constrain what the agent does](./docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)
-- [Lecture 09. Stop agents from declaring victory early](./docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md)
-- [Lecture 10. Only a full-pipeline run counts as real verification](./docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)
-- [Lecture 11. Make the agent's runtime observable](./docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)
-- [Lecture 12. Clean handoff at the end of every session](./docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)
-
-### Projects
-
-- [Project 01. Prompt-only vs. rules-first: how much difference does it make](./docs/projects/project-01-baseline-vs-minimal-harness/index.md)
-- [Project 02. Make the project readable and pick up where you left off](./docs/projects/project-02-agent-readable-workspace/index.md)
-- [Project 03. Keep the agent working across session restarts](./docs/projects/project-03-multi-session-continuity/index.md)
-- [Project 04. Use runtime feedback to correct agent behavior](./docs/projects/project-04-incremental-indexing/index.md)
-- [Project 05. Make the agent verify its own work](./docs/projects/project-05-grounded-qa-verification/index.md)
-- [Project 06. Build a complete agent harness](./docs/projects/project-06-runtime-observability-and-debugging/index.md)
+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.
-### Resource Library
+---
-- [Resource Library Overview](./docs/resources/index.md)
-- [Chinese Resource Library](./docs/resources/zh/index.md)
-- [English Resource Library](./docs/resources/en/index.md)
+## Learning Path
+
+The course is designed to be done in order. Each phase builds on the last.
-## Recommended Learning Path
+```text
+ Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
+ ======================== ==========================
-This course is designed to be done in order. Each phase builds on the last.
+ 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 1 — See the problem.** Read lectures 1 and 2, then do project 1. You'll run the same task twice: once with just a prompt, once with a minimal harness. The difference will be obvious.
-**Phase 2 — Make the repo work for the agent.** Lectures 3 and 4, project 2. You'll restructure the repo so the agent can read it, and add files that survive between sessions.
+ Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
+ ========================== =========================
-**Phase 3 — Keep sessions connected.** Lectures 5 and 6, project 3. This is where things get interesting — you'll make the agent pick up from where it left off, even after you close the session.
+ 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 4 — Add feedback and scope control.** Lectures 7 and 8, project 4. You'll stop the agent from doing too much or too little, and use runtime feedback to keep it on track.
-**Phase 5 — Verification and self-check.** Lectures 9 and 10, project 5. The agent learns to verify its own work instead of just saying "done."
+ Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
+ ===================== ============================
-**Phase 6 — Put it all together.** Lectures 11 and 12, project 6. This is the capstone. You'll build a complete harness from scratch, using everything you've learned.
+ L09 Stop agents from L11 Make agent's runtime
+ declaring victory early observable
-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.
+ L10 Full-pipeline run = L12 Clean handoff at end of
+ real verification every session
+
+ | |
+ v v
+ P05 Agent verifies its own work P06 Build a complete harness
+ (capstone project)
+```
+
+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.
+
+---
+
+## Syllabus
+
+### Lectures — 12 conceptual units, each answering one core question
+
+| Session | Question | Core Idea |
+|---------|----------|-----------|
+| [L01](./docs/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 |
+| [L02](./docs/lectures/lecture-02-what-a-harness-actually-is/index.md) | What does "harness" actually mean? | Five subsystems: instructions, state, verification, scope, lifecycle |
+| [L03](./docs/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 |
+| [L04](./docs/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 |
+| [L05](./docs/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 |
+| [L06](./docs/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 |
+| [L07](./docs/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 |
+| [L08](./docs/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 |
+| [L09](./docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Why do agents declare victory too early? | Verification gaps: confidence ≠ correctness |
+| [L10](./docs/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 |
+| [L11](./docs/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 |
+| [L12](./docs/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 |
+
+### Projects — 6 hands-on projects applying lecture methods to the same Electron app
+
+| Project | What You Do | Harness Mechanism |
+|---------|------------|-------------------|
+| [P01](./docs/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 |
+| [P02](./docs/projects/project-02-agent-readable-workspace/index.md) | Restructure the repo so the agent can read it | Agent-readable workspace + persistent state files |
+| [P03](./docs/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 |
+| [P04](./docs/projects/project-04-incremental-indexing/index.md) | Stop the agent from doing too much or too little | Runtime feedback + scope control + incremental indexing |
+| [P05](./docs/projects/project-05-grounded-qa-verification/index.md) | Make the agent verify its own work | Self-verification + grounded Q&A + evidence-based completion |
+| [P06](./docs/projects/project-06-runtime-observability-and-debugging/index.md) | Build a complete harness from scratch (capstone) | Full harness: all mechanisms + observability + ablation study |
+
+```text
+ PROJECT EVOLUTION
+ =================
+
+ P01 Prompt-only vs. rules-first You see the problem
+ |
+ v
+ P02 Agent-readable workspace You restructure the repo
+ |
+ v
+ P03 Multi-session continuity You connect sessions
+ |
+ v
+ P04 Runtime feedback & scope You add feedback loops
+ |
+ v
+ P05 Self-verification You make the agent check itself
+ |
+ v
+ P06 Complete harness (capstone) You build the full system
+
+ Each project's solution becomes the next project's starter.
+ The app evolves. Your harness skills grow with it.
+```
+
+### Resource Library
+
+- [Resource Library Overview](./docs/resources/index.md)
+- [English Resource Library](./docs/resources/en/index.md) — templates, checklists, and method references
+- [Chinese Resource Library](./docs/resources/zh/index.md) — 中文模板、清单和方法参考
+
+---
+
+## 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
+ 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
@@ -140,6 +387,8 @@ This course is not for:
- 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.
@@ -159,17 +408,23 @@ The course assumes you can:
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.
```sh
npm install
-npm run docs:dev
+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:
@@ -185,6 +440,8 @@ Helpful but not required:
- Background in testing, logging, or software architecture
- Prior exposure to Codex, Claude Code, or similar coding agents
+---
+
## Core References
Primary:
@@ -199,40 +456,31 @@ Supplementary:
- [Thoughtworks: Harness Engineering](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html)
- [HumanLayer: Skill Issue: Harness Engineering for Coding Agents](https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents)
-## Capstone Project
-
-Most projects in this course revolve around the same product:
-
-- An Electron-based personal knowledge base desktop app
-
-Core goals include:
-
-- Importing local documents
-- Managing a document library
-- Processing and indexing documents
-- Running AI-powered Q&A over imported content
-- Returning grounded answers with citations
-
-This project was chosen because it combines:
+---
-- Strong practical value
-- Enough real-world product complexity
-- A good setting for observing before/after harness improvements
-
-## Course Format
-
-This course has two types of content:
-
-- **Lectures**: 12 conceptual units, each answering one core question
-- **Projects**: 6 hands-on projects that apply lecture methods to the same Electron app
-
-Each project requires you to:
+## Repository Structure
-- Have Codex or Claude Code execute real tasks
-- Compare weak vs. strong harnesses
-- Observe changes in reliability, continuity, verification quality, and maintainability
+```text
+learn-harness-engineering/
+├── docs/ # VitePress documentation site
+│ ├── lectures/ # 12 lectures (index.md + code/ examples)
+│ │ ├── lecture-01-*/
+│ │ ├── lecture-02-*/
+│ │ └── ... (12 total)
+│ ├── projects/ # 6 project descriptions
+│ │ ├── project-01-*/
+│ │ └── ... (6 total)
+│ └── resources/ # Bilingual templates & references
+│ ├── en/ # English templates, checklists, guides
+│ └── zh/ # Chinese templates, checklists, guides
+├── projects/
+│ ├── shared/ # Shared Electron + TypeScript + React foundation
+│ └── project-NN/ # Per-project starter/ and solution/ directories
+├── package.json # VitePress + dev tooling
+└── CLAUDE.md # Claude Code instructions for this repo
+```
-The final project also serves as the course's capstone harness.
+---
## How the Course Is Organized
@@ -242,10 +490,8 @@ The final project also serves as the course's capstone harness.
- Every project compares weak vs. strong harness results
- What matters is the measured difference, not how many docs were written
-## Repository Structure
+---
-- `docs/lectures/` - All lectures
-- `docs/projects/` - All hands-on projects, including the capstone
-- `docs/resources/` - Bilingual reusable templates, checklists, and method references
+## Acknowledgments
-Each lecture includes a `code/` directory for small real-world examples and supporting artifacts.
+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 agent harnesses from scratch, from a single loop to isolated autonomous execution.