Skip to content

Harness engineering beginner tutorial, from 0 to 1

refactor: 统一第六至十一讲章节标题为课本风格,去除口语化表达

sanbuphydaa0fa169013
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 a89ca57..d85e9a6 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
@@ -35,7 +35,7 @@ flowchart TB
end
```
-## 混在一起做会怎样
+## 初始化和实现混合的问题
最直接的问题是基础设施搭不牢。Agent 花了 80% 的精力写功能代码,剩下 20% 随便搭了点基础设施。测试框架配了但没验证过,lint 规则设了但太宽松,进度文件没创建。这些缺陷在第一个会话里不明显(因为 agent 还记得它做了什么),但到第二个会话就暴露了:新 agent 不知道项目怎么跑、怎么测、做到哪了。
@@ -58,7 +58,7 @@ OpenAI 的 Codex harness engineering 指南也强调"仓库作为操作记录"
- **从开始到第一次测试通过**:衡量初始化效率的核心指标。时间越短,初始化越高效。
- **后续会话的成功率**:后续会话不需要依赖隐式知识就能成功执行任务的比例,这是初始化质量的最佳衡量标准。
-## 怎么做好初始化
+## 初始化的正确做法
**把初始化当作一个独立的阶段来执行。** 第一个会话只做初始化,不写任何业务功能代码。初始化的产出是:
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 792f7fe..c88e780 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
@@ -59,7 +59,7 @@ flowchart TB
- **范围表面(Scope Surface)**:一个 DAG 结构,每个节点是一个工作单元,边是依赖关系。状态只有四种:未开始、进行中、阻塞、已通过。
- **完成压力(Completion Pressure)**:harness 通过 WIP 限制和完成证据要求共同产生的约束力,迫使 agent 先完成当前任务再开始新任务。
-## Overreach 和 Under-finish 是一对难兄难弟
+## 过度延伸如何导致不足完成
这两个问题互相加剧。overreach 导致注意力分散,注意力分散导致 under-finish,under-finish 留下的半成品代码又增加了系统复杂度,进一步导致下一个任务的 overreach,形成恶性循环。
@@ -67,7 +67,7 @@ flowchart TB
这在人类世界也是老问题了。Steve McConnell 在《Rapid Development》中记录,范围蔓延是项目失败的首要原因。但人类至少有"我已经做得够多了"的直觉,agent 完全没有。生成下一个想法的成本对模型来说太低了,写一行"顺便把这个也改了"几乎不消耗额外 token,但每个额外的修改都会稀释 agent 的注意力。
-## 怎么做才对
+## 实施方法
### 1. 强制 WIP=1
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 a73f20d..d576adb 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
@@ -11,7 +11,7 @@
Anthropic 和 OpenAI 都强调:**工件必须外部化**。功能状态必须是仓库里机器可读的文件,不能是对话里的非结构化描述。
-## Agent 不知道"做完"是什么意思
+## Agent 缺少明确的完成标准
Claude Code 和 Codex 都不会自动知道你心目中的"做完"是什么意思。你说"加一个购物车功能",模型的理解可能是"写一个 Cart 组件和 addToCart 方法"。而你的意思是"用户能从浏览商品到下单支付完整走通"。
@@ -61,7 +61,7 @@ flowchart LR
- **单一权威来源**:项目里关于"该做什么"的所有信息,必须从一个功能清单派生。不能出现功能清单和对话记录矛盾的情况。
- **反向压力**:还没通过的功能项数量就是 harness 对 agent 施加的压力。压力归零 = 项目完成。
-## 为什么功能清单必须是"原语"
+## 为什么功能清单必须是原语
文档是给人看的,原语是给系统用的。文档可以被忽略,原语不能被绕过。
@@ -74,7 +74,7 @@ flowchart LR
3. **交接报告器**:从功能清单自动生成会话交接摘要。
4. **进度追踪器**:统计各状态分布,提供项目健康度指标。
-## 怎么做
+## 实施方法
### 1. 定义一个最小化的功能清单格式
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 b235714..bed230d 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
@@ -74,7 +74,7 @@ Anthropic 在 2026 年的研究中发现了一个更深层的失败模式:**
> 来源:[Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
-## 怎么防止过早声明完成
+## 预防过早完成的方法
### 1. 外部化终止判定
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 d869f0d..d119f8f 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
@@ -21,7 +21,7 @@
**环境依赖性**:代码在测试环境(一切 mock)行为正确,在真实环境因配置差异、网络延迟、服务不可用而失败。
-## 端到端测试不仅改变结果,还改变行为
+## 端到端测试同时影响结果与行为
这是很多人没意识到的一点:当 agent 知道它的工作要过端到端测试时,它的编码行为会改变。
@@ -65,7 +65,7 @@ OpenAI 在 Codex 工程实践中强调:**为 agent 写的错误消息必须包
- **审查反馈提升**:把重复出现的代码审查意见转化为自动化测试。每次发现重复问题就加一条规则,harness 会自动变强。
- **面向 agent 的错误消息**:失败信息不只是说"出了什么问题",还要告诉 agent 具体怎么修,把测试失败变成自我修正的反馈循环。
-## 怎么做
+## 实施方法
### 0. 先定好架构边界,再写端到端测试
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 671ec31..d6baee8 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
@@ -11,7 +11,7 @@ Agent 执行任务时常常像一个黑盒:它跑了 20 分钟,改了一堆
**没有可观测性,agent 在不确定状态中做决策,评估变成主观判断,重试变成盲目摸索。** OpenAI 和 Anthropic 都将可靠性定义为证据问题,harness 必须以可指导下一步决策的形式暴露运行时行为和评估信号。
-## 可观测性缺失的真实代价
+## 可观测性缺失的影响
当 harness 缺乏可观测性时,四类问题会系统性出现。
@@ -23,7 +23,7 @@ Agent 执行任务时常常像一个黑盒:它跑了 20 分钟,改了一堆
**会话交接信息断崖**:当未完成的工作移交给下一个会话时,缺乏可观测性意味着新会话必须从零诊断系统状态。Anthropic 的长期运行 agent 观察表明,这种重复诊断可能占会话总时间的 30-50%。
-## Claude Code 的真实场景
+## 实际运行示例
来看一个使用"计划者-生成者-评估者"三角色工作流的 harness,执行"为应用添加暗色模式"任务。
@@ -60,7 +60,7 @@ flowchart LR
- **评估评分标准**:把质量评估从主观判断变成基于证据的结构化评分,使不同评估者对同一输出产生相似结论。
- **双层可观测性**:系统层和过程层同时设计、相互增强。运行时信号解释行为,过程工件解释意图。
-## 为什么 agent 自己解决不了这个问题
+## Agent 自行处理可观测性的局限
你可能在想:"agent 不能自己打日志吗?" 问题在于:
@@ -68,7 +68,7 @@ flowchart LR
2. **日志格式不统一**:不同会话用不同的日志格式,无法做系统化分析。
3. **过程可观测性不是日志能解决的**:冲刺合同和评分标准是结构化的工件,需要 harness 层面的支持,不是多 print 几行就能搞定的。
-## 怎么搭建可观测性
+## 搭建可观测性的方法
### 1. 在 harness 里内置运行时信号采集