Skip to content

Harness engineering beginner tutorial, from 0 to 1

Fully localize Chinese README: translate all code blocks, diagrams, and links

sanbuphy3850f3c5fd03
diff --git a/README-CN.md b/README-CN.md
index 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 是围绕模型搭建一整套工作环境,让它产出可
```sh
npm 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
```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/ # 中文模板、清单和指南
+├── 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 的渐进式教程,从单个循环到隔离的自主执行。