【免费下载链接】learn-harness-engineering
Harness engineering beginner tutorial, from 0 to 1
在 AI 编码 Agent 的日常运营中，"这套 Harness 到底有没有用"是最难回答的问题之一。本指南以 Learn Harness Engineering 仓库中 Lecture 12 的基准对比模板 为骨架，结合仓库内的可运行基准脚本与 12 周实测数据，系统讲解如何设计 A/B 对照实验、填写三个核心指标、解读"结果变化"与"成本变化"两个关键问题，并最终用数据决定一个 Harness 组件的去留。读完你可以在自己的项目里直接复制模板、搭建固定任务集，并完成一次可信的 Harness 消融实验。
模板从哪来：Lecture 12 的第二个练习
该模板是 Lecture 12：为什么每个会话结束时都必须留下干净状态 中练习 2（Benchmark Comparison）的配套工具。练习要求：
使用一组固定任务，配合两种 Harness 变体（带/不带 clean-state 要求），比较完成率、重试次数与缺陷逃逸率。
仓库为每种语言维护了同名模板（阿拉伯语版 与 英语版），模板本身极短——它刻意只保留实验的最小骨架，把设计自由留给使用者。这份骨架的价值在于：它强制你同时观察结果与获取结果的成本，避免只凭"能不能跑通"做判断。
模板原文与逐项解析
模板结构非常清晰，对两个 Harness 变体分别记录三组指标，最后回答两个解读问题：
Harness A（基准组）：
- 完成率（Completion rate）
- 平均尝试次数（Average attempts）
- 人工审查前发现的错误数（Errors caught before human review）
Harness B（实验组）：
- 完成率（Completion rate）
- 平均尝试次数（Average attempts）
- 人工审查前发现的错误数（Errors caught before human review）
解读（Interpretation）：
- 哪个 Harness 改变了结果？（Which harness changed the result?）
- 哪个 Harness 改变了获取结果的成本？（Which harness changed the cost of getting the result?）
指标一：完成率（Completion Rate）
在固定任务集上，Agent 最终通过全部验收标准（pass criteria）的任务占任务总数的比例。它回答"Harness 是否帮助 Agent 更可靠地到达终点"。注意 Lecture 12 对"完成"有严格定义：任务通过验证 且 clean-state 检查通过，二者缺一不可——构建失败、测试变红、进度未记录、残留临时文件、启动路径被破坏，都意味着会话"未完成"。
指标二：平均尝试次数（Average Attempts）
每个任务从开始到通过所需的平均尝试轮数。这是成本维度的核心代理指标：尝试次数越多，消耗的 token、时间与调试成本越高。一个能显著降低尝试次数的 Harness，即便完成率相同，也仍然证明了自身价值。
指标三：人工审查前发现的错误数（Errors Caught Before Human Review）
即"缺陷逃逸率"的反向度量——在人类介入审查之前，Agent 自己发现并修正了多少错误。它衡量的是 Harness 的自纠错能力：clean-state 检查、CI 验证、质量文档等机制，本质上是把错误拦截在人工审查之前。错误数越多，说明 Harness 捕获问题的能力越强，留给人类的认知负担越小。
两个解读问题：结果 vs 成本
模板的解读部分刻意把"结果"和"成本"分开提问，这是整个模板的精髓：
- 哪个 Harness 改变了结果？ 若 A/B 完成率差异明显，说明该 Harness 直接影响了 Agent 的能力边界，值得保留。
- 哪个 Harness 改变了获取结果的成本？ 若完成率相同、但尝试次数与缺陷逃逸显著不同，说明 Harness 影响的是效率而非能力——它同样有价值，但评价逻辑不同。
只有当两个问题都回答"没有差异"时，才可以考虑移除该组件（见下文消融实验）。
如何准备固定任务集：从模板到可运行基准
模板只定义了记录格式，任务集本身需要单独设计。仓库在 Lecture 12 的 code 目录 提供了两类示例：基准切片（benchmark slices）与清理任务（cleanup tasks）。
benchmark-runner.ts 展示了一个完整任务集的形状。每个任务由 BenchmarkTask 接口定义，包含五个关键字段：
| 字段 | 含义 | 模板中的对应维度 |
|---|---|---|
id / name | 任务唯一标识与名称 | — |
category | 任务类别（用于分组统计） | — |
passCriteria | 通过标准数组（全部满足才算通过） | 完成率判定依据 |
expectedDurationMs | 预期耗时（SLA 基准） | 成本维度 |
actualDurationMs / actualPass | 模拟的实际耗时与通过与否 | 成本维度 + 完成率 |
任务集必须覆盖多个类别才有说服力。仓库示例中按四类组织：文档管线（Document Pipeline）、问答管线（Q&A Pipeline）、安全（Security）与可靠性（Reliability）。通过标准必须可机械判定，例如：
Import markdown document：File accepted+Chunks created+Metadata storedAsk question with no relevant docs：Query received+Graceful 'no results' message+No hallucinated citationsConcurrent user access：Users isolated+No cross-user data leak+Performance within SLA
运行方式为：
npx tsx docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts
该脚本会输出按任务细分的表格（含 PASS/FAIL、标准通过数、预期/实际耗时、偏差 Delta）、失败原因明细，以及按类别的通过率汇总和 OVERALL 统计——这些输出正是填充模板"完成率"一栏的数据来源。
对照组怎么建：有/无 clean-state 约束
模板的 A/B 两组，对应 Lecture 12 的核心命题——clean-state 是不是有效的 Harness 约束。实验设计如下：
- 对照组（Harness A）：无 clean-state 要求，会话结束即可，不检查构建、测试、进度、残留物与启动路径。
- 实验组（Harness B）：在 Harness 中显式定义"会话完成 = 任务通过验证 + clean-state 检查通过"，并在
CLAUDE.md中写入会话退出清单：
## Session Exit Checklist
- [ ] Build passes (npm run build)
- [ ] All tests pass (npm test)
- [ ] Feature list updated
- [ ] No debug code remaining (console.log, debugger, TODO)
- [ ] Standard startup path available (npm run dev)
Lecture 12 记录了 12 周实测的对照组数据，可直接作为模板预期值的参照（来源：Lecture 12 index）：
| 周次 | 构建通过率 | 测试通过率 | 新会话启动耗时 |
|---|---|---|---|
| 第 1 周 | 100% | 100% | 5 分钟 |
| 第 4 周 | 95% | 92% | 15 分钟 |
| 第 8 周 | 82% | 78% | 35 分钟 |
| 第 12 周 | 68% | 61% | 60+ 分钟 |
同样项目采用清理策略后：第 12 周构建通过率 97%、测试通过率 95%、启动耗时 9 分钟。12 周后两组构建通过率相差 29 个百分点，新会话启动时间相差 85%。这说明：熵增是默认状态，若不主动清理，技术债会指数级累积；而模板记录的三项指标，正是捕捉这种差异的最小集合。
三个指标怎么填、怎么解读
填写模板时遵循以下准则，可最大限度减少偏差：
- 任务集必须完全一致：A/B 两组跑同一批任务、同一份 pass criteria，只允许 Harness 表面（约束、检查、文档）不同。
- 控制模型与起始状态：使用同一模型版本、同一仓库基线；新会话从相同的干净 commit 开始，避免把上一次运行的残留误记为本次结果。
- 成本要量化：平均尝试次数不要只记整数，建议连同平均耗时（
expectedDurationMs与actualDurationMs的偏差）一并记录，便于区分"试错型失败"与"一次性卡死"。 - 缺陷逃逸要分类：人工审查前发现的错误按构建错误、测试失败、逻辑缺陷分类，能帮助定位是 clean-state 检查、CI 还是质量文档起了作用。
解读的最终判定矩阵：
| 完成率差异 | 尝试次数/缺陷逃逸差异 | 结论 |
|---|---|---|
| 显著 | 显著 | Harness 同时改变能力与成本，核心组件，保留 |
| 显著 | 无 | 只改变能力边界，按能力收益评估 |
| 无 | 显著 | 只优化成本，按效率收益评估 |
| 无 | 无 | 无实际收益，考虑移除或替换 |
仓库里的落地工具：从模板到自动化检查
模板记录的是实验结果，而让实验可信的前提是 clean-state 本身可被机械验证。仓库在 project-06（Capstone）的 solution 目录 提供了完整落地实现：
- clean-state-checklist.md：把 Lecture 12 的五维要求展开成 10 类可勾选清单（构建、架构、运行时、日志、数据完整性、性能、仓库、脚本），每一条都对应具体命令或事件。
- benchmark.sh：4 项任务的基准套件——导入吞吐、索引速度、查询延迟、数据完整性校验，输出
PASS/FAIL与汇总，退出码可直接接入 CI。 - cleanup-scanner.sh：扫描数据目录的 5 类残留——孤儿内容文件、悬空 chunk 文件、缺失内容文件、不一致元数据、过期 Q&A 引用，输出
CLEAN或ISSUES FOUND。 - cleanup-loop.md：定义周期性清理任务——扫描过期文档、扫描结构违规、更新质量评级、开启定向重构 PR、清理后重跑固定基准切片。
- cleanup-scanner.ts：更细粒度的源码级扫描器，覆盖临时文件、源码树内的日志、死代码标记、
.gitignore缺失、构建产物混入源码、嵌套node_modules、会话残留文件与空目录，严重度分 critical / warning / info 三级。
这些工具与模板形成闭环：基准（模板记录）→ 扫描（发现问题）→ 清理（恢复干净）→ 复测（验证无回归）。清理操作本身必须幂等——重复运行不产生副作用，例如 rm -f（文件不存在时不报错）、git checkout -- .env.local（恢复到已知状态）、npm test（验证清理未破坏任何功能）。
进阶：把模板用于 Harness 消融实验
模板同样适用于 Lecture 12 的练习 3（Harness Simplification）——逐组件消融：
每月挑选一个 Harness 组件，临时禁用，运行基准任务。若结果不降级，永久移除；若降级，恢复或替换为更轻的替代方案。
流程与上面的 A/B 对比完全一致，只是把"有无 clean-state"换成"有无某组件"。关键洞察来自讲义的实录：每个 Harness 组件之所以存在，是因为模型当时无法可靠独立完成某件事；随着模型能力提升，这些假设会过时。因此组件决策不是一次性的 yes/no，而是依赖任务难度与模型能力的相对位置——同一组件在能力边界附近依然有效，在边界之内则可能成为纯开销。
常见误区与解读红线
- "下个会话再清理"等于永远不清理：新会话有自己的任务目标，不会替你收拾残局，反而会在混乱之上叠加混乱，形成熵增正反馈。模板里记录的尝试次数上升与缺陷逃逸增加，往往正是从第一次"推迟清理"开始的。
- "能编译"不等于干净状态：构建通过只是五个维度之一。测试（含历史测试）、进度记录、残留物、启动路径缺一不可，且验证应发生在 CI 而非"我机器上能跑"。
- 不要只盯完成率：模板同时要求记录成本指标，就是为了防止"用三倍成本换 5% 完成率提升"被误判为成功。
- 高吞吐场景的合并哲学需要配套调整：当 Agent 每天产出远超人工审查能力时，阻塞式合并门槛的代价高于快速修复的代价；但这仅在"修复平均成本 < 等待人工审查平均成本"时成立，低吞吐环境沿用此策略是不负责任的。
可直接复制的模板
以下为完整版模板，可直接复制到你的基准文档中使用：
# Benchmark Comparison Template
Harness A (baseline):
- Completion rate: __ / __ tasks (__%)
- Average attempts: __ attempts per task
- Errors caught before human review: __ (build __, tests __, logic __)
Harness B (with clean-state requirements):
- Completion rate: __ / __ tasks (__%)
- Average attempts: __ attempts per task
- Errors caught before human review: __ (build __, tests __, logic __)
Interpretation:
- Which harness changed the result?
(完成率差异分析，对照判定矩阵)
- Which harness changed the cost of getting the result?
(尝试次数与缺陷逃逸差异分析，成本是否可接受)
Conditions:
- Fixed task set: same tasks, same pass criteria
- Same model, same repo baseline commit
- Verified in CI, not "works on my machine"
小结
一份只有 18 行的对比模板，承载的是 Harness 工程里最核心的决策方法：先量化，再判断。完成率回答"能力是否提升"，平均尝试次数与缺陷逃逸率回答"成本是否可接受"，两个解读问题共同决定一个组件是保留、移除还是替换。配合仓库中 benchmark-runner.ts、cleanup-scanner.ts 与 project-06 的基准/扫描脚本，你可以在自己的仓库里以极低成本建立"记录→扫描→清理→复测"的闭环，让每一次 Harness 决策都有数据支撑，而不是凭感觉。
【免费下载链接】learn-harness-engineering
Harness engineering beginner tutorial, from 0 to 1
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
