Skip to content

Commit daa0fa1

Browse files
committed
refactor: 统一第六至十一讲章节标题为课本风格,去除口语化表达
1 parent 6bfd233 commit daa0fa1

6 files changed

Lines changed: 14 additions & 14 deletions

File tree

  • docs/zh/lectures
    • 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

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ flowchart TB
3535
end
3636
```
3737

38-
## 混在一起做会怎样
38+
## 初始化和实现混合的问题
3939

4040
最直接的问题是基础设施搭不牢。Agent 花了 80% 的精力写功能代码,剩下 20% 随便搭了点基础设施。测试框架配了但没验证过,lint 规则设了但太宽松,进度文件没创建。这些缺陷在第一个会话里不明显(因为 agent 还记得它做了什么),但到第二个会话就暴露了:新 agent 不知道项目怎么跑、怎么测、做到哪了。
4141

@@ -58,7 +58,7 @@ OpenAI 的 Codex harness engineering 指南也强调"仓库作为操作记录"
5858
- **从开始到第一次测试通过**:衡量初始化效率的核心指标。时间越短,初始化越高效。
5959
- **后续会话的成功率**:后续会话不需要依赖隐式知识就能成功执行任务的比例,这是初始化质量的最佳衡量标准。
6060

61-
## 怎么做好初始化
61+
## 初始化的正确做法
6262

6363
**把初始化当作一个独立的阶段来执行。** 第一个会话只做初始化,不写任何业务功能代码。初始化的产出是:
6464

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,15 +59,15 @@ flowchart TB
5959
- **范围表面(Scope Surface)**:一个 DAG 结构,每个节点是一个工作单元,边是依赖关系。状态只有四种:未开始、进行中、阻塞、已通过。
6060
- **完成压力(Completion Pressure)**:harness 通过 WIP 限制和完成证据要求共同产生的约束力,迫使 agent 先完成当前任务再开始新任务。
6161

62-
## Overreach 和 Under-finish 是一对难兄难弟
62+
## 过度延伸如何导致不足完成
6363

6464
这两个问题互相加剧。overreach 导致注意力分散,注意力分散导致 under-finish,under-finish 留下的半成品代码又增加了系统复杂度,进一步导致下一个任务的 overreach,形成恶性循环。
6565

6666
用 Kanban 的语言说:Little 法则告诉我们 L = lambda * W。如果在制品数量 L 过大(同时做太多事),每个任务的前置时间 W 必然增加。对 agent 来说,这意味着每个功能从开始到验证通过的时间被拉长,失败概率被放大。
6767

6868
这在人类世界也是老问题了。Steve McConnell 在《Rapid Development》中记录,范围蔓延是项目失败的首要原因。但人类至少有"我已经做得够多了"的直觉,agent 完全没有。生成下一个想法的成本对模型来说太低了,写一行"顺便把这个也改了"几乎不消耗额外 token,但每个额外的修改都会稀释 agent 的注意力。
6969

70-
## 怎么做才对
70+
## 实施方法
7171

7272
### 1. 强制 WIP=1
7373

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
Anthropic 和 OpenAI 都强调:**工件必须外部化**。功能状态必须是仓库里机器可读的文件,不能是对话里的非结构化描述。
1313

14-
## Agent 不知道"做完"是什么意思
14+
## Agent 缺少明确的完成标准
1515

1616
Claude Code 和 Codex 都不会自动知道你心目中的"做完"是什么意思。你说"加一个购物车功能",模型的理解可能是"写一个 Cart 组件和 addToCart 方法"。而你的意思是"用户能从浏览商品到下单支付完整走通"。
1717

@@ -61,7 +61,7 @@ flowchart LR
6161
- **单一权威来源**:项目里关于"该做什么"的所有信息,必须从一个功能清单派生。不能出现功能清单和对话记录矛盾的情况。
6262
- **反向压力**:还没通过的功能项数量就是 harness 对 agent 施加的压力。压力归零 = 项目完成。
6363

64-
## 为什么功能清单必须是"原语"
64+
## 为什么功能清单必须是原语
6565

6666
文档是给人看的,原语是给系统用的。文档可以被忽略,原语不能被绕过。
6767

@@ -74,7 +74,7 @@ flowchart LR
7474
3. **交接报告器**:从功能清单自动生成会话交接摘要。
7575
4. **进度追踪器**:统计各状态分布,提供项目健康度指标。
7676

77-
## 怎么做
77+
## 实施方法
7878

7979
### 1. 定义一个最小化的功能清单格式
8080

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
@@ -74,7 +74,7 @@ Anthropic 在 2026 年的研究中发现了一个更深层的失败模式:**
7474

7575
> 来源:[Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
7676
77-
## 怎么防止过早声明完成
77+
## 预防过早完成的方法
7878

7979
### 1. 外部化终止判定
8080

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121

2222
**环境依赖性**:代码在测试环境(一切 mock)行为正确,在真实环境因配置差异、网络延迟、服务不可用而失败。
2323

24-
## 端到端测试不仅改变结果,还改变行为
24+
## 端到端测试同时影响结果与行为
2525

2626
这是很多人没意识到的一点:当 agent 知道它的工作要过端到端测试时,它的编码行为会改变。
2727

@@ -65,7 +65,7 @@ OpenAI 在 Codex 工程实践中强调:**为 agent 写的错误消息必须包
6565
- **审查反馈提升**:把重复出现的代码审查意见转化为自动化测试。每次发现重复问题就加一条规则,harness 会自动变强。
6666
- **面向 agent 的错误消息**:失败信息不只是说"出了什么问题",还要告诉 agent 具体怎么修,把测试失败变成自我修正的反馈循环。
6767

68-
## 怎么做
68+
## 实施方法
6969

7070
### 0. 先定好架构边界,再写端到端测试
7171

docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Agent 执行任务时常常像一个黑盒:它跑了 20 分钟,改了一堆
1111

1212
**没有可观测性,agent 在不确定状态中做决策,评估变成主观判断,重试变成盲目摸索。** OpenAI 和 Anthropic 都将可靠性定义为证据问题,harness 必须以可指导下一步决策的形式暴露运行时行为和评估信号。
1313

14-
## 可观测性缺失的真实代价
14+
## 可观测性缺失的影响
1515

1616
当 harness 缺乏可观测性时,四类问题会系统性出现。
1717

@@ -23,7 +23,7 @@ Agent 执行任务时常常像一个黑盒:它跑了 20 分钟,改了一堆
2323

2424
**会话交接信息断崖**:当未完成的工作移交给下一个会话时,缺乏可观测性意味着新会话必须从零诊断系统状态。Anthropic 的长期运行 agent 观察表明,这种重复诊断可能占会话总时间的 30-50%。
2525

26-
## Claude Code 的真实场景
26+
## 实际运行示例
2727

2828
来看一个使用"计划者-生成者-评估者"三角色工作流的 harness,执行"为应用添加暗色模式"任务。
2929

@@ -60,15 +60,15 @@ flowchart LR
6060
- **评估评分标准**:把质量评估从主观判断变成基于证据的结构化评分,使不同评估者对同一输出产生相似结论。
6161
- **双层可观测性**:系统层和过程层同时设计、相互增强。运行时信号解释行为,过程工件解释意图。
6262

63-
## 为什么 agent 自己解决不了这个问题
63+
## Agent 自行处理可观测性的局限
6464

6565
你可能在想:"agent 不能自己打日志吗?" 问题在于:
6666

6767
1. **agent 不知道它不知道什么**:它不会主动记录自己没意识到需要的信号。没有 harness 层面的约束,agent 只会记录它认为重要的东西,而它认为重要的东西往往不够。
6868
2. **日志格式不统一**:不同会话用不同的日志格式,无法做系统化分析。
6969
3. **过程可观测性不是日志能解决的**:冲刺合同和评分标准是结构化的工件,需要 harness 层面的支持,不是多 print 几行就能搞定的。
7070

71-
## 怎么搭建可观测性
71+
## 搭建可观测性的方法
7272

7373
### 1. 在 harness 里内置运行时信号采集
7474

0 commit comments

Comments
 (0)