Skip to content

Commit 8692fae

Browse files
sanbuphyclaude
andcommitted
Polish lecture formatting: standardize section headers and add structure
- Rename summary section from "带走什么"/"关键要点" to "核心要点" across all 12 Chinese lectures for consistency - Add bullet points and bold labels to Lecture 01 failure modes section for better scannability Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent b699754 commit 8692fae

12 files changed

Lines changed: 18 additions & 22 deletions

File tree

  • docs/zh/lectures
    • lecture-01-why-capable-agents-still-fail
    • lecture-02-what-a-harness-actually-is
    • lecture-03-why-the-repository-must-become-the-system-of-record
    • lecture-04-why-one-giant-instruction-file-fails
    • lecture-05-why-long-running-tasks-lose-continuity
    • lecture-06-why-initialization-needs-its-own-phase
    • lecture-07-why-agents-overreach-and-under-finish
    • lecture-08-why-feature-lists-are-harness-primitives
    • lecture-09-why-agents-declare-victory-too-early
    • lecture-10-why-end-to-end-testing-changes-results
    • lecture-11-why-observability-belongs-inside-the-harness
    • lecture-12-why-every-session-must-leave-a-clean-state

docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md

Lines changed: 7 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -19,17 +19,13 @@ OpenAI 在 2025 年的 harness engineering 文章里把这件事说得更直白
1919

2020
## agent 到底卡在哪
2121

22-
具体的失败模式其实就那么几种
22+
具体的失败模式其实就那么几种
2323

24-
头一种是任务压根没交代清楚。"加个搜索功能"——这话说了等于没说。搜索的对象是什么?全文本还是结构化查询?结果要不要分页、要不要高亮?你没说明白,agent 就只好自己猜。猜对了算运气好,猜错了你再改,来回一折腾,比一开始说清楚多花好几倍的时间。
25-
26-
架构约定也是暗坑。你们全组都用 SQLAlchemy 2.0 的新语法,但 agent 默认写了 1.x 的代码;所有 API 端点必须走 OAuth 2.0 认证,可这条规矩只存在于你脑子里和三个月前一条 Slack 消息里。Agent 压根不知道有这么回事,不是不想遵守,是真没见过。
27-
28-
环境也常常出问题。开发环境配置不完整、依赖缺了、工具版本不对,agent 把宝贵的上下文窗口花在了 `pip install` 报错、Node 版本冲突这些事上,真正该干的活反而没精力做。
29-
30-
更常见的是压根没有验证手段。没有测试、没有 lint、或者验证命令根本没告诉 agent。Agent 写完代码,自己看了看觉得没问题,就说完成了。Anthropic 还观察到一个有意思的现象:当 agent 感觉上下文快满了,它们会匆忙结束当前工作,跳过验证步骤,选一个简单的方案而不是最优方案。他们把这叫"上下文焦虑"。
31-
32-
至于跨会话的长任务就更惨了。上次会话的发现全丢了,每个新会话都得重新探索项目结构、理解代码组织。缺乏持久化状态的 agent 在超过 30 分钟的任务中失败率急剧上升。
24+
- **任务没交代清楚。** "加个搜索功能",这话说了等于没说。搜索的对象是什么?全文本还是结构化查询?结果要不要分页、要不要高亮?你没说明白,agent 就只好自己猜。猜对了算运气好,猜错了你再改,来回一折腾,比一开始说清楚多花好几倍的时间。
25+
- **架构约定是暗坑。** 你们全组都用 SQLAlchemy 2.0 的新语法,但 agent 默认写了 1.x 的代码;所有 API 端点必须走 OAuth 2.0 认证,可这条规矩只存在于你脑子里和三个月前一条 Slack 消息里。Agent 压根不知道有这么回事,不是不想遵守,是真没见过。
26+
- **环境常常出问题。** 开发环境配置不完整、依赖缺了、工具版本不对,agent 把宝贵的上下文窗口花在了 `pip install` 报错、Node 版本冲突这些事上,真正该干的活反而没精力做。
27+
- **没有验证手段。** 没有测试、没有 lint、或者验证命令根本没告诉 agent。Agent 写完代码,自己看了看觉得没问题,就说完成了。Anthropic 还观察到一个有意思的现象:当 agent 感觉上下文快满了,它们会匆忙结束当前工作,跳过验证步骤,选一个简单的方案而不是最优方案。他们把这叫"上下文焦虑"。
28+
- **跨会话的状态丢失。** 上次会话的发现全丢了,每个新会话都得重新探索项目结构、理解代码组织。缺乏持久化状态的 agent 在超过 30 分钟的任务中失败率急剧上升。
3329

3430
## 关键名词解释
3531

@@ -82,7 +78,7 @@ OpenAI 在 2025 年的 harness engineering 文章里把这件事说得更直白
8278

8379
模型没变。变的还是 harness。
8480

85-
## 带走什么
81+
## 核心要点
8682

8783
- 模型能力和执行可靠性是两回事,千里马也得配上好马具。
8884
- 失败的时候先看 harness,再看模型。换模型是成本最高的选择,而且很多时候根本不是模型的问题。

docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ flowchart LR
8484

8585
四次迭代,模型一个字没改,成功率从 20% 到接近 100%。你没有换更好的模型,变的只是 harness。
8686

87-
## 关键要点
87+
## 核心要点
8888

8989
- Harness = 指令 + 工具 + 环境 + 状态 + 反馈,五个子系统缺一不可。
9090
- 不是模型权重的部分全是 harness,你的 harness 决定了模型能力能被发挥多少。

docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ project/
112112

113113
改造后:同一 agent 能在冷启动时回答所有关键项目问题,任务完成质量显著提升。
114114

115-
## 关键要点
115+
## 核心要点
116116

117117
- 不在仓库里的知识对 agent 来说等于不存在。把关键决策信息放进仓库是最基本的 harness 投资,画好地图才不会迷路。
118118
- 用"冷启动测试"检验仓库质量:全新会话能不能只看仓库回答五个基本问题。

docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ Agent 表现开始明显下降:简单 bug 修复任务中 agent 花大量上
107107

108108
重构后:同一任务集的成功率从 45% 提升到 72%。安全约束遵循率从 60% 提升到 95%,因为规则从文件中间移到了路由文件顶部,不再被"中间迷失"了。
109109

110-
## 关键要点
110+
## 核心要点
111111

112112
- "加条规则"是短期的止痛药,长期的毒药。每次加规则前想想,这条规则放专题文档是不是更合适。
113113
- 入口文件是路由器,不是百科全书。50-200 行,只放概览、硬约束和链接。

docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,7 @@ Anthropic 的实际数据:对于 Sonnet 4.5,上下文焦虑足够严重,
153153

154154
定量对比:重建时间减少约 78%,功能完成率从 58% 提升到 100%,隐含缺陷率从 43% 降到 8%。
155155

156-
## 关键要点
156+
## 核心要点
157157

158158
- 上下文窗口是有限的资源。长任务一定会跨会话,跨会话一定会丢信息,这是客观现实。
159159
- 解决方案不是更大的窗口,而是更好的状态持久化。进度文件、决策日志、git 检查点,三者配合让新会话能接上之前的工作。

docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ OpenAI 的 Codex harness engineering 指南也强调"仓库作为操作记录"
132132

133133
整个项目周期对比:混合方式的总重建时间(跨所有会话)比独立初始化多约 60%。独立初始化多花的那 20 分钟在后续会话中被成倍收回。前期多投入一点时间把初始化做扎实,后续的效率反而更高。
134134

135-
## 关键要点
135+
## 核心要点
136136

137137
- 初始化和实现的优化目标不同,混在一起只会互相拖后腿。
138138
- 初始化的产出不是业务代码,而是基础设施:可运行的环境、可验证的测试、自举契约、任务分解。

docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@ harness 应该持续跟踪 VCR(Verified Completion Rate)= 已通过验证的
108108

109109
结果:总代码量更少(800 行 vs 1200 行),但有效代码更多。完成率 87.5% vs 37.5%。
110110

111-
## 关键要点
111+
## 核心要点
112112

113113
- **WIP=1 是 agent harness 的默认安全设置**:做完一个再做下一个,不要试图并行。
114114
- **完成证据必须是可执行的**:"代码看起来没问题"不算完成,"curl 返回 201"才算。

docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ agent 不能直接把状态改成 `passing`。它只能提交验证请求,harn
118118

119119
定量结果:使用结构化功能清单的项目,功能完成率比自由形式高 45%,零重复实现。
120120

121-
## 关键要点
121+
## 核心要点
122122

123123
- **功能清单是 harness 的基础结构**,不是给人看的备忘录。调度器、验证器、交接器都依赖它。
124124
- **每个功能项必须有三元组**:行为描述 + 验证命令 + 当前状态。缺一项就不完整。

docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ OpenAI 在 Codex 实践中提出了一个特别有效的模式:**给 agent 写
119119

120120
**harness 介入**:终止校验强制执行,(1) 启动完整应用验证重置端点可访问;(2) 执行完整重置流程;(3) 验证数据库状态一致性。所有缺陷在会话内被发现,节省了 5-10 倍的后续修复成本。
121121

122-
## 关键要点
122+
## 核心要点
123123

124124
- **agent 系统性地过度自信**,置信度校准偏差是客观存在的。代码写完了不代表做对了。
125125
- **完成判定必须外部化**,harness 独立验证,不信任 agent 的"感觉"。

docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea
132132

133133
5 个缺陷全部被端到端测试捕获,单元测试一个都没发现。代价是测试时间从 2 秒增加到 15 秒,在 agent 工作流里完全可以接受。
134134

135-
## 关键要点
135+
## 核心要点
136136

137137
- **单元测试对组件边界缺陷系统性盲视**:它们的隔离设计恰好使其无法检测交互问题。
138138
- **端到端测试不仅检测缺陷,还改变 agent 的编码行为**:让它更关注集成和边界。

0 commit comments

Comments
 (0)