File tree Expand file tree Collapse file tree
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 Expand file tree Collapse file tree Original file line number Diff line number Diff 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
Original file line number Diff line number Diff 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
Original file line number Diff line number Diff line change 1111
1212Anthropic 和 OpenAI 都强调:** 工件必须外部化** 。功能状态必须是仓库里机器可读的文件,不能是对话里的非结构化描述。
1313
14- ## Agent 不知道"做完"是什么意思
14+ ## Agent 缺少明确的完成标准
1515
1616Claude 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
74743 . ** 交接报告器** :从功能清单自动生成会话交接摘要。
75754 . ** 进度追踪器** :统计各状态分布,提供项目健康度指标。
7676
77- ## 怎么做
77+ ## 实施方法
7878
7979### 1. 定义一个最小化的功能清单格式
8080
Original file line number Diff line number Diff 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
Original file line number Diff line number Diff line change 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
Original file line number Diff line number Diff 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
67671 . ** agent 不知道它不知道什么** :它不会主动记录自己没意识到需要的信号。没有 harness 层面的约束,agent 只会记录它认为重要的东西,而它认为重要的东西往往不够。
68682 . ** 日志格式不统一** :不同会话用不同的日志格式,无法做系统化分析。
69693 . ** 过程可观测性不是日志能解决的** :冲刺合同和评分标准是结构化的工件,需要 harness 层面的支持,不是多 print 几行就能搞定的。
7070
71- ## 怎么搭建可观测性
71+ ## 搭建可观测性的方法
7272
7373### 1. 在 harness 里内置运行时信号采集
7474
You can’t perform that action at this time.
0 commit comments