Skip to content

Harness engineering beginner tutorial, from 0 to 1

Polish lecture formatting: standardize section headers and add structure

sanbuphy8692fae32f56
diff --git a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md
index e11c7db..c1a13ec 100644
--- a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md
+++ b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md
@@ -19,17 +19,13 @@ OpenAI 在 2025 年的 harness engineering 文章里把这件事说得更直白
## agent 到底卡在哪
-具体的失败模式其实就那么几种。
+具体的失败模式其实就那么几种:
-头一种是任务压根没交代清楚。"加个搜索功能"——这话说了等于没说。搜索的对象是什么?全文本还是结构化查询?结果要不要分页、要不要高亮?你没说明白,agent 就只好自己猜。猜对了算运气好,猜错了你再改,来回一折腾,比一开始说清楚多花好几倍的时间。
-
-架构约定也是暗坑。你们全组都用 SQLAlchemy 2.0 的新语法,但 agent 默认写了 1.x 的代码;所有 API 端点必须走 OAuth 2.0 认证,可这条规矩只存在于你脑子里和三个月前一条 Slack 消息里。Agent 压根不知道有这么回事,不是不想遵守,是真没见过。
-
-环境也常常出问题。开发环境配置不完整、依赖缺了、工具版本不对,agent 把宝贵的上下文窗口花在了 `pip install` 报错、Node 版本冲突这些事上,真正该干的活反而没精力做。
-
-更常见的是压根没有验证手段。没有测试、没有 lint、或者验证命令根本没告诉 agent。Agent 写完代码,自己看了看觉得没问题,就说完成了。Anthropic 还观察到一个有意思的现象:当 agent 感觉上下文快满了,它们会匆忙结束当前工作,跳过验证步骤,选一个简单的方案而不是最优方案。他们把这叫"上下文焦虑"。
-
-至于跨会话的长任务就更惨了。上次会话的发现全丢了,每个新会话都得重新探索项目结构、理解代码组织。缺乏持久化状态的 agent 在超过 30 分钟的任务中失败率急剧上升。
+- **任务没交代清楚。** "加个搜索功能",这话说了等于没说。搜索的对象是什么?全文本还是结构化查询?结果要不要分页、要不要高亮?你没说明白,agent 就只好自己猜。猜对了算运气好,猜错了你再改,来回一折腾,比一开始说清楚多花好几倍的时间。
+- **架构约定是暗坑。** 你们全组都用 SQLAlchemy 2.0 的新语法,但 agent 默认写了 1.x 的代码;所有 API 端点必须走 OAuth 2.0 认证,可这条规矩只存在于你脑子里和三个月前一条 Slack 消息里。Agent 压根不知道有这么回事,不是不想遵守,是真没见过。
+- **环境常常出问题。** 开发环境配置不完整、依赖缺了、工具版本不对,agent 把宝贵的上下文窗口花在了 `pip install` 报错、Node 版本冲突这些事上,真正该干的活反而没精力做。
+- **没有验证手段。** 没有测试、没有 lint、或者验证命令根本没告诉 agent。Agent 写完代码,自己看了看觉得没问题,就说完成了。Anthropic 还观察到一个有意思的现象:当 agent 感觉上下文快满了,它们会匆忙结束当前工作,跳过验证步骤,选一个简单的方案而不是最优方案。他们把这叫"上下文焦虑"。
+- **跨会话的状态丢失。** 上次会话的发现全丢了,每个新会话都得重新探索项目结构、理解代码组织。缺乏持久化状态的 agent 在超过 30 分钟的任务中失败率急剧上升。
## 关键名词解释
@@ -82,7 +78,7 @@ OpenAI 在 2025 年的 harness engineering 文章里把这件事说得更直白
模型没变。变的还是 harness。
-## 带走什么
+## 核心要点
- 模型能力和执行可靠性是两回事,千里马也得配上好马具。
- 失败的时候先看 harness,再看模型。换模型是成本最高的选择,而且很多时候根本不是模型的问题。
diff --git a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md
index 5ea87f9..b7f52d5 100644
--- a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md
+++ b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md
@@ -84,7 +84,7 @@ flowchart LR
四次迭代,模型一个字没改,成功率从 20% 到接近 100%。你没有换更好的模型,变的只是 harness。
-## 关键要点
+## 核心要点
- Harness = 指令 + 工具 + 环境 + 状态 + 反馈,五个子系统缺一不可。
- 不是模型权重的部分全是 harness,你的 harness 决定了模型能力能被发挥多少。
diff --git a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
index e9d1889..4e9a9b8 100644
--- a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
+++ b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
@@ -112,7 +112,7 @@ project/
改造后:同一 agent 能在冷启动时回答所有关键项目问题,任务完成质量显著提升。
-## 关键要点
+## 核心要点
- 不在仓库里的知识对 agent 来说等于不存在。把关键决策信息放进仓库是最基本的 harness 投资,画好地图才不会迷路。
- 用"冷启动测试"检验仓库质量:全新会话能不能只看仓库回答五个基本问题。
diff --git a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
index 8df07c6..d9a796f 100644
--- a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
+++ b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
@@ -107,7 +107,7 @@ Agent 表现开始明显下降:简单 bug 修复任务中 agent 花大量上
重构后:同一任务集的成功率从 45% 提升到 72%。安全约束遵循率从 60% 提升到 95%,因为规则从文件中间移到了路由文件顶部,不再被"中间迷失"了。
-## 关键要点
+## 核心要点
- "加条规则"是短期的止痛药,长期的毒药。每次加规则前想想,这条规则放专题文档是不是更合适。
- 入口文件是路由器,不是百科全书。50-200 行,只放概览、硬约束和链接。
diff --git a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index d4f9388..2f00597 100644
--- a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -153,7 +153,7 @@ Anthropic 的实际数据:对于 Sonnet 4.5,上下文焦虑足够严重,
定量对比:重建时间减少约 78%,功能完成率从 58% 提升到 100%,隐含缺陷率从 43% 降到 8%。
-## 关键要点
+## 核心要点
- 上下文窗口是有限的资源。长任务一定会跨会话,跨会话一定会丢信息,这是客观现实。
- 解决方案不是更大的窗口,而是更好的状态持久化。进度文件、决策日志、git 检查点,三者配合让新会话能接上之前的工作。
diff --git a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index 47a43fb..1bcab9a 100644
--- a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -132,7 +132,7 @@ OpenAI 的 Codex harness engineering 指南也强调"仓库作为操作记录"
整个项目周期对比:混合方式的总重建时间(跨所有会话)比独立初始化多约 60%。独立初始化多花的那 20 分钟在后续会话中被成倍收回。前期多投入一点时间把初始化做扎实,后续的效率反而更高。
-## 关键要点
+## 核心要点
- 初始化和实现的优化目标不同,混在一起只会互相拖后腿。
- 初始化的产出不是业务代码,而是基础设施:可运行的环境、可验证的测试、自举契约、任务分解。
diff --git a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index 0aa1eb0..6035d95 100644
--- a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -108,7 +108,7 @@ harness 应该持续跟踪 VCR(Verified Completion Rate)= 已通过验证的
结果:总代码量更少(800 行 vs 1200 行),但有效代码更多。完成率 87.5% vs 37.5%。
-## 关键要点
+## 核心要点
- **WIP=1 是 agent harness 的默认安全设置**:做完一个再做下一个,不要试图并行。
- **完成证据必须是可执行的**:"代码看起来没问题"不算完成,"curl 返回 201"才算。
diff --git a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index d64543f..5622a7a 100644
--- a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -118,7 +118,7 @@ agent 不能直接把状态改成 `passing`。它只能提交验证请求,harn
定量结果:使用结构化功能清单的项目,功能完成率比自由形式高 45%,零重复实现。
-## 关键要点
+## 核心要点
- **功能清单是 harness 的基础结构**,不是给人看的备忘录。调度器、验证器、交接器都依赖它。
- **每个功能项必须有三元组**:行为描述 + 验证命令 + 当前状态。缺一项就不完整。
diff --git a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index ca03c2d..d6bd486 100644
--- a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -119,7 +119,7 @@ OpenAI 在 Codex 实践中提出了一个特别有效的模式:**给 agent 写
**harness 介入**:终止校验强制执行,(1) 启动完整应用验证重置端点可访问;(2) 执行完整重置流程;(3) 验证数据库状态一致性。所有缺陷在会话内被发现,节省了 5-10 倍的后续修复成本。
-## 关键要点
+## 核心要点
- **agent 系统性地过度自信**,置信度校准偏差是客观存在的。代码写完了不代表做对了。
- **完成判定必须外部化**,harness 独立验证,不信任 agent 的"感觉"。
diff --git a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index 10ddcaf..ba68713 100644
--- a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -132,7 +132,7 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea
5 个缺陷全部被端到端测试捕获,单元测试一个都没发现。代价是测试时间从 2 秒增加到 15 秒,在 agent 工作流里完全可以接受。
-## 关键要点
+## 核心要点
- **单元测试对组件边界缺陷系统性盲视**:它们的隔离设计恰好使其无法检测交互问题。
- **端到端测试不仅检测缺陷,还改变 agent 的编码行为**:让它更关注集成和边界。
diff --git a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index 259bcbf..72d63a7 100644
--- a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -149,7 +149,7 @@ Evaluator 不是一开始就这么强。早期版本会识别出合理的问题
> 来源:[Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
-## 关键要点
+## 核心要点
- **可观测性是 harness 的架构属性**:不是事后添加的功能,而是设计时必须考虑的核心能力。
- **双层可观测性缺一不可**:运行时信号解释"发生了什么",过程工件解释"为什么这样做"。
diff --git a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index d468e88..6dea96b 100644
--- a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -172,7 +172,7 @@ npm run test # 验证清理未破坏功能
到第 12 周,实验组的构建通过率比对照组高 29 个百分点,测试通过率高 34 个百分点,新会话启动时间减少 85%。每个会话多花 5 分钟做清理,12 周下来省下了几十个小时的混乱时间。
-## 关键要点
+## 核心要点
- **清洁状态是会话完成的必要条件**,不是可选的善后工作,而是"完成定义"的一部分。
- **五个维度缺一不可**:构建、测试、进度、工件、启动,每个都要显式检查。