Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
Fully localize Chinese README: translate all code blocks, diagrams, and links
sanbuphy3850f3c5fd03
diff --git a/README-CN.md b/README-CN.mdindex 1598652..a77aeb3 100644--- a/README-CN.md+++ b/README-CN.md@@ -23,22 +23,22 @@ 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 模式+ ============++ 你 --> 给出任务 --> agent 读取 harness 文件 --> agent 开始执行+ |+ harness 管控每一步:+ |+ +--> 指令:做什么、按什么顺序+ +--> 范围:一次一个功能,不越界+ +--> 状态:进度日志、功能清单、git 历史+ +--> 验证:测试、lint、类型检查、冒烟测试+ +--> 边界:什么算"完成"、什么算"有问题"+ |+ v+ agent 只在验证通过后+ 才会停下来```---@@ -51,10 +51,10 @@ Harness engineering 是围绕模型搭建一整套工作环境,让它产出可```text┌─────────────────────────────────────────────────────────────────┐- │ THE HARNESS │+ │ HARNESS ││ ││ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │- │ │ Instructions │ │ State │ │ Verification │ │+ │ │ 指令 │ │ 状态 │ │ 验证 │ ││ │ │ │ │ │ │ ││ │ AGENTS.md │ │ progress.md │ │ tests + lint │ ││ │ CLAUDE.md │ │ feature_list │ │ type-check │ │@@ -63,29 +63,29 @@ Harness engineering 是围绕模型搭建一整套工作环境,让它产出可│ └──────────────┘ └──────────────┘ └──────────────────────┘ ││ ││ ┌──────────────┐ ┌──────────────────────────────────────┐ │- │ │ 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 │ │+ │ │ 一次一个 │ │ 开工时跑 init.sh │ │+ │ │ 功能 │ │ 结束时跑清理检查清单 │ │+ │ │ 显式的完成 │ │ 给下次会话留交接笔记 │ │+ │ │ 定义 │ │ 只在可以安全恢复时才 commit │ ││ └──────────────┘ └──────────────────────────────────────┘ ││ │└─────────────────────────────────────────────────────────────────┘- 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.+ 模型决定写什么代码。+ Harness 管控什么时候写、在哪里写、怎么写。+ Harness 不会让模型变聪明。+ 它让模型的产出变可靠。```每个子系统各司其职:-- **Instructions(指令)** — 告诉 agent 做什么、按什么顺序、开工前先读什么。不是一个巨大的文件,而是渐进式展开的结构,agent 按需导航。-- **State(状态)** — 跟踪做了什么、正在做什么、下一步是什么。持久化到磁盘,下次会话从上次停下的地方继续。-- **Verification(验证)** — 只有通过的测试套件才算数。agent 不能没有可运行的证据就说"做完了"。-- **Scope(范围)** — 约束 agent 一次只做一个功能。不多做,不少做,不偷偷改功能清单掩盖未完成的工作。-- **Session Lifecycle(会话生命周期)** — 开始时初始化,结束时清理,给下次会话留一条干净的重启路径。+- **指令** — 告诉 agent 做什么、按什么顺序、开工前先读什么。不是一个巨大的文件,而是渐进式展开的结构,agent 按需导航。+- **状态** — 跟踪做了什么、正在做什么、下一步是什么。持久化到磁盘,下次会话从上次停下的地方继续。+- **验证** — 只有通过的测试套件才算数。agent 不能没有可运行的证据就说"做完了"。+- **范围** — 约束 agent 一次只做一个功能。不多做,不少做,不偷偷改功能清单掩盖未完成的工作。+- **会话生命周期** — 开始时初始化,结束时清理,给下次会话留一条干净的重启路径。---@@ -96,24 +96,23 @@ Harness engineering 是围绕模型搭建一整套工作环境,让它产出可现在的答案是:没有 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 有 HARNESS+ ============== ===========++ 会话 1: agent 写代码 会话 1: agent 读指令+ agent 搞坏测试 agent 跑 init.sh+ agent 说"做完了" agent 一次只做一个功能+ 你手动修复 agent 验证后才说完成+ agent 更新进度日志+ 会话 2: agent 从头开始 agent 干净地 commit+ agent 没有上次+ 的记忆 会话 2: agent 读进度日志+ agent 重新做一遍 agent 从上次停下的地方继续+ 或者做了完全不同的东西 agent 继续未完成的功能+ 你再修一次 你是审查,不是救火++ 结果:你花的时间比 结果:agent 干活,+ 自己做还多 你验证结果```课程真正关心的问题:@@ -132,46 +131,46 @@ Harness engineering 是围绕模型搭建一整套工作环境,让它产出可思路很简单:不是光写提示词,而是在仓库里放一组结构化的文件——告诉 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 <-- agent 的操作手册+ ├── CLAUDE.md <-- (备选,如果你用 Claude Code)+ ├── init.sh <-- 一条命令完成安装 + 验证 + 启动+ ├── feature_list.json <-- 有哪些功能、哪些已完成+ ├── claude-progress.md <-- 每次会话做了什么+ └── src/ <-- 你的代码```**第一步.** 把根指令文件复制到项目根目录:-- [`AGENTS.md`](./docs/resources/zh/templates/AGENTS.md) 通用版,或者 [`CLAUDE.md`](./docs/resources/zh/templates/CLAUDE.md) 如果你用 Claude Code+- [`AGENTS.md`](./docs/zh/resources/templates/AGENTS.md) 通用版,或者 [`CLAUDE.md`](./docs/zh/resources/templates/CLAUDE.md) 如果你用 Claude Code- 把里面的命令、路径和规则换成你自己项目的**第二步.** 把启动脚本复制进去:-- `docs/resources/zh/templates/init.sh` —— 一条命令完成依赖安装、验证和启动+- `docs/zh/resources/templates/init.sh` —— 一条命令完成依赖安装、验证和启动- 把 `INSTALL_CMD`、`VERIFY_CMD`、`START_CMD` 换成你自己的**第三步.** 把进度日志复制进去:-- [`claude-progress.md`](./docs/resources/zh/templates/claude-progress.md) —— 每轮会话记录做了什么、验证了什么、下一步是什么+- [`claude-progress.md`](./docs/zh/resources/templates/claude-progress.md) —— 每轮会话记录做了什么、验证了什么、下一步是什么- agent 每次开工会先读这个文件,从上次停下的地方继续**第四步.** 把功能清单复制进去:-- [`feature_list.json`](./docs/resources/zh/templates/feature_list.json) —— 机器可读的功能列表,每个功能有状态、验证步骤和证据+- [`feature_list.json`](./docs/zh/resources/templates/feature_list.json) —— 机器可读的功能列表,每个功能有状态、验证步骤和证据- 把示例功能换成你自己的四个文件,最小起步就够了。比光靠一段提示词稳定得多。等项目变复杂了,再补这些:-- [`session-handoff.md`](./docs/resources/zh/templates/session-handoff.md) —— 会话之间的交接摘要-- [`clean-state-checklist.md`](./docs/resources/zh/templates/clean-state-checklist.md) —— 每次会话结束前的清理清单-- [`evaluator-rubric.md`](./docs/resources/zh/templates/evaluator-rubric.md) —— 评审 agent 产出质量的评分表+- [`session-handoff.md`](./docs/zh/resources/templates/session-handoff.md) —— 会话之间的交接摘要+- [`clean-state-checklist.md`](./docs/zh/resources/templates/clean-state-checklist.md) —— 每次会话结束前的清理清单+- [`evaluator-rubric.md`](./docs/zh/resources/templates/evaluator-rubric.md) —— 评审 agent 产出质量的评分表-每个文件的详细用法写在 [中文模板指南](./docs/resources/zh/templates/index.md)。英文版见 [英文模板指南](./docs/resources/en/templates/index.md)。+每个文件的详细用法写在 [中文模板指南](./docs/zh/resources/templates/index.md)。英文版见 [英文模板指南](./docs/en/resources/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/zh/resources/openai-advanced/`](./docs/zh/resources/openai-advanced/index.md) 和 [`docs/en/resources/openai-advanced/`](./docs/en/resources/openai-advanced/index.md)。---@@ -181,28 +180,28 @@ Harness engineering 是围绕模型搭建一整套工作环境,让它产出可```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] ││+ │ │ doc-001.md │ │ 问:什么是 harness eng? ││+ │ │ doc-002.md │ │ 答:围绕 agent 模型搭建的 ││+ │ │ doc-003.md │ │ 工作环境... ││+ │ │ ... │ │ [引用:doc-002.md] │││ └──────────────┘ └──────────────────────────────┘││ ││ ┌─────────────────────────────────────────────────┐│- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││+ │ │ 状态栏:42 篇文档 | 38 篇已索引 | 上次同步 3分钟 │││ └─────────────────────────────────────────────────┘│└─────────────────────────────────────────────────────┘- 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+ 核心功能:+ ├── 导入本地文档+ ├── 管理文档库+ ├── 处理与索引文档+ ├── 对导入内容发起 AI 问答+ └── 返回带引用且可追溯的回答```选择这个项目是因为它同时具备:很强的实际价值感、足够真实的产品复杂度、以及很适合观察 harness 优化前后的效果差异。@@ -216,47 +215,47 @@ Harness engineering 是围绕模型搭建一整套工作环境,让它产出可这门课按顺序来效果最好,每一阶段都建立在前一个的基础上。```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+ 阶段 1:看到问题 阶段 2:组织仓库+ =================== ===================++ L01 模型强 ≠ 执行可靠 L03 仓库作为唯一+ 事实来源+ L02 Harness 到底是什么+ L04 把指令拆分到+ | 不同文件里v- P01 Prompt-only vs. |- rules-first comparison v- P02 Agent-readable workspace+ P01 只写提示词 |+ vs 定好规则 v+ P02 agent 可读的工作空间- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE- ========================== =========================+ 阶段 3:连接会话 阶段 4:反馈与范围+ =================== ===================- 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+ L05 让跨会话任务 L07 划清任务边界+ 保持连续+ L08 功能清单作为+ L06 每次开工前 harness 原语+ 先初始化+ |+ | v+ v P04 运行反馈修正+ P03 多会话连续性 agent 行为- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER- ===================== ============================+ 阶段 5:验证 阶段 6:全部串起来+ =================== ===================- L09 Stop agents from L11 Make agent's runtime- declaring victory early observable+ L09 防止 agent 提前 L11 让 agent 运行+ 宣告完成 过程可观测- L10 Full-pipeline run = L12 Clean handoff at end of- real verification every session+ L10 跑通完整流程 L12 每次会话结束+ 才算真的验证 前做好交接- | |- v v- P05 Agent verifies its own work P06 Build a complete harness- (capstone project)+ | |+ v v+ P05 agent 自己验证工作 P06 搭建完整 harness+ (综合项目)```每个阶段大约一周(兼职节奏)。想快的话,前三个阶段一个周末就能跑完。@@ -267,62 +266,61 @@ Harness engineering 是围绕模型搭建一整套工作环境,让它产出可### 讲义 — 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) | 为什么每次会话都要留干净状态 | 下次会话的成功,取决于这次会话的清理 |+| 讲义 | 核心问题 | 关键概念 |+| ---- | -------- | -------- |+| [L01](./docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 模型能力强,不等于执行可靠 | 基准测试与真实工程之间的能力鸿沟 |+| [L02](./docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md) | Harness 到底是什么 | 五个子系统:指令、状态、验证、范围、生命周期 |+| [L03](./docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 让仓库成为唯一事实来源 | agent 看不到的东西,对它来说就不存在 |+| [L04](./docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | 为什么一个巨大的指令文件会失败 | 渐进式展开:给地图,不给百科全书 |+| [L05](./docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | 为什么长时任务会丢失上下文 | 把进度持久化到磁盘,从停下的地方继续 |+| [L06](./docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | 为什么初始化需要单独一个阶段 | agent 开始工作前先验证环境是否健康 |+| [L07](./docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | 为什么 agent 会多做或少做 | 一次一个功能,显式的完成定义 |+| [L08](./docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | 为什么功能清单是 harness 原语 | 机器可读的范围边界,agent 无法忽略 |+| [L09](./docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | 为什么 agent 会提前宣告完成 | 验证缺口:自信 ≠ 正确 |+| [L10](./docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | 为什么端到端测试会改变结果 | 只有跑通完整流程才算真正验证 |+| [L11](./docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | 为什么可观测性属于 harness | 看不到 agent 做了什么,就修不了它搞坏的东西 |+| [L12](./docs/zh/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:全部机制 + 可观测性 + 消融实验 |+| 项目 | 你要做什么 | Harness 机制 |+| ---- | ---------- | ------------ |+| [P01](./docs/zh/projects/project-01-baseline-vs-minimal-harness/index.md) | 跑两次同样的任务:只写提示词 vs 定好规则 | 最小 harness:AGENTS.md + init.sh + feature_list.json |+| [P02](./docs/zh/projects/project-02-agent-readable-workspace/index.md) | 重组项目结构,让 agent 能读懂 | agent 可读的工作空间 + 持久化状态文件 |+| [P03](./docs/zh/projects/project-03-multi-session-continuity/index.md) | 让 agent 关掉再打开还能接着干 | 进度日志 + 会话交接 + 多会话连续性 |+| [P04](./docs/zh/projects/project-04-incremental-indexing/index.md) | 防止 agent 做多了或做少了 | 运行反馈 + 范围控制 + 增量索引 |+| [P05](./docs/zh/projects/project-05-grounded-qa-verification/index.md) | 让 agent 自己验证自己的工作 | 自验证 + 带引用的问答 + 基于证据的完成判定 |+| [P06](./docs/zh/projects/project-06-runtime-observability-and-debugging/index.md) | 从零搭建一套完整的 harness(综合项目) | 完整 harness:全部机制 + 可观测性 + 消融实验 |```text- PROJECT EVOLUTION- =================+ 项目演进+ ========- P01 Prompt-only vs. rules-first You see the problem+ P01 只写提示词 vs 定好规则 你看到问题|v- P02 Agent-readable workspace You restructure the repo+ P02 agent 可读的工作空间 你重组仓库|v- P03 Multi-session continuity You connect sessions+ P03 多会话连续性 你连接会话|v- P04 Runtime feedback & scope You add feedback loops+ P04 运行反馈与范围控制 你加上反馈循环|v- P05 Self-verification You make the agent check itself+ P05 自验证 你让 agent 检查自己|v- P06 Complete harness (capstone) You build the full system+ P06 完整 harness(综合项目) 你搭建完整系统- Each project's solution becomes the next project's starter.- The app evolves. Your harness skills grow with it.+ 每个项目的 solution 成为下一个项目的 starter。+ 应用跟着你的 harness 技能一起进化。```### 资料库-- [资料库总览](./docs/resources/index.md)-- [中文资料库](./docs/resources/zh/index.md) — 中文模板、清单和方法参考-- [英文资料库](./docs/resources/en/index.md) — English templates, checklists, and method references+- [中文资料库](./docs/zh/resources/index.md) — 中文模板、清单和方法参考+- [英文资料库](./docs/en/resources/index.md) — English templates, checklists, and method references---@@ -331,44 +329,44 @@ Harness engineering 是围绕模型搭建一整套工作环境,让它产出可这门课的一个核心理念:**agent 的会话应该遵循结构化的生命周期,而不是自由发挥。** 它长这样:```text- AGENT SESSION LIFECYCLE- ======================+ AGENT 会话生命周期+ =================┌──────────────────────────────────────────────────────────────────┐- │ 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) │+ │ 1. agent 读取 AGENTS.md / CLAUDE.md │+ │ 2. agent 运行 init.sh(安装、验证、健康检查) │+ │ 3. agent 读取 claude-progress.md(上次做了什么) │+ │ 4. agent 读取 feature_list.json(做完哪些、接下来做哪个) │+ │ 5. agent 检查 git log(最近的改动) ││ │- │ SELECT │+ │ 选择 ││ │- │ 6. Agent picks exactly ONE unfinished feature │- │ 7. Agent works only on that feature │+ │ 6. agent 选定且只选一个未完成的功能 │+ │ 7. agent 只做这一个功能 ││ │- │ 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 │+ │ 8. agent 实现这个功能 │+ │ 9. agent 运行验证(测试、lint、类型检查) │+ │ 10. 如果验证失败:修复后重跑 │+ │ 11. 如果验证通过:记录证据 ││ │- │ 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 │+ │ 12. agent 更新 claude-progress.md │+ │ 13. agent 更新 feature_list.json │+ │ 14. agent 记录还没做完和还没验证的东西 │+ │ 15. agent commit(只在可以安全恢复时) │+ │ 16. agent 给下次会话留干净的重启路径 ││ │└──────────────────────────────────────────────────────────────────┘- 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."+ Harness 管控这个生命周期里的每一次状态转换。+ 模型决定每一步写什么代码。+ 没有 harness 时,第 9 步变成"agent 说看起来没问题"。+ 有 harness 时,第 9 步是"测试通过、lint 干净、类型检查通过"。```---@@ -416,9 +414,9 @@ Harness engineering 是围绕模型搭建一整套工作环境,让它产出可```shnpm install-npm run docs:dev # Dev server with hot reload-npm run docs:build # Production build-npm run docs:preview # Preview built site+npm run docs:dev # 开发服务器(热更新)+npm run docs:build # 生产构建+npm run docs:preview # 预览构建结果```然后在浏览器里打开 VitePress 输出的本地地址即可。@@ -462,22 +460,21 @@ npm run docs:preview # Preview built site```textlearn-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/ # 中文模板、清单和指南+├── docs/ # VitePress 文档站+│ ├── index.md # 语言选择页(中文 / English)+│ ├── zh/ # 中文完整内容+│ │ ├── lectures/ # 12 个讲义(index.md + code/ 示例)+│ │ ├── projects/ # 6 个项目+│ │ └── resources/ # 模板、参考、高级资源包+│ └── en/ # 英文完整内容+│ ├── lectures/ # 12 lectures+│ ├── projects/ # 6 projects+│ └── resources/ # templates, references, advanced pack├── 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+│ ├── shared/ # Electron + TypeScript + React 共享基础+│ └── project-NN/ # 每个项目的 starter/ 和 solution/+├── package.json # VitePress + 开发工具+└── CLAUDE.md # Claude Code 指令文件```---@@ -494,4 +491,4 @@ learn-harness-engineering/## 致谢-本课程的灵感和部分思路来自 [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) —— 一个从零开始搭建 agent harness 的渐进式教程,从单个循环到隔离的自主执行。+本课程的灵感和部分思路来自 [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) —— 一个从零开始搭建 agent 的渐进式教程,从单个循环到隔离的自主执行。