Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
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.mdindex 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 TBend```-## 混在一起做会怎样+## 初始化和实现混合的问题最直接的问题是基础设施搭不牢。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.mdindex 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=1diff --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.mdindex 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 LR3. **交接报告器**:从功能清单自动生成会话交接摘要。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.mdindex 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.mdindex 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.mdindex 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 LR2. **日志格式不统一**:不同会话用不同的日志格式,无法做系统化分析。3. **过程可观测性不是日志能解决的**:冲刺合同和评分标准是结构化的工件,需要 harness 层面的支持,不是多 print 几行就能搞定的。-## 怎么搭建可观测性+## 搭建可观测性的方法### 1. 在 harness 里内置运行时信号采集