HARNESS ENGINEERING PLAYBOOK 9 / 35
打开全书目录

导读

  1. 00 Harness Engineering 手册:百倍生产力的可靠软件交付
  2. 01 引言:为什么需要 Harness Engineering

卷一:可靠的 Agent 编程(1→10x)

  1. 02 意图对齐:Vibe Coding 为什么失败
  2. 03 用结构传达意图:分层与维度
  3. 04 迭代出一份可执行的规约
  4. 05 实践:AILock-Step Feature Workflow
  5. 06 验证:确保代码忠实于规约
  6. 07 测试基建前置:把规约变成可执行约束
  7. 08 Code Review:补位测试覆盖不到的意图漂移
  8. 09 实践:AILock-Step 的验证链路
  9. 10 演进:规约与验证的持续迭代
  10. 11 卷一回顾:从闭环到演进

卷二:规模化 Agent 开发(10→100x)

  1. 12 规约:让意图能被并行分发
  2. 13 规约规模转变:人类脱离循环
  3. 14 设计原则:自包含
  4. 15 产出方式:可判定决策驱动
  5. 16 实践:博客系统审核队列
  6. 17 验证:当人不再能兜底
  7. 18 验证责任转移
  8. 19 大规模验证的锚点
  9. 20 三层机制:硬门禁、软门禁、集成验证
  10. 21 实践:博客审核队列的验证链路
  11. 22 演进:harness 必然演化
  12. 23 卷二回顾:迭代的harness系统

卷三:治理百倍速的组织

  1. 24 组织重构:当 Agent 改变了协作的前提
  2. 25 为什么旧结构失效了
  3. 26 瓶颈转移:从代码到组织
  4. 27 让流程匹配 Agent 速度
  5. 28 角色重定义:从执行者到治理者
  6. 29 围绕治理重新设计角色
  7. 30 用机制替代人际协调
  8. 31 演进:组织资产与新护城河

专题补遗:企业落地

  1. 32 补遗:把 Agent 接进可复现的交付现场
  2. 33 补遗:用交付事实衡量 Harness

附录

  1. 32 贡献者
03B / 卷一:可靠的 Agent 编程(1→10x)

Code Review:补位测试覆盖不到的意图漂移

测试验证的是行为:spec 说的功能,代码做到了吗。但代码中还有一类问题,行为层面完全正确,测试全绿,意图却在悄悄偏离。Code review 的工作就是捕获这些测试的盲区。

更新于 · 阅读 Markdown

内容来源:Agents-Zone/harness-engineering-playbook ↗

测试验证的是行为:spec 说的功能,代码做到了吗。但代码中还有一类问题,行为层面完全正确,测试全绿,意图却在悄悄偏离。Code review 的工作就是捕获这些测试的盲区。

测试看不见什么

Spec 要求用配置文件管理数据库连接字符串,Agent 把连接字符串直接写在代码里。功能完全正常,测试全部通过,但部署到另一个环境就会失败。

Spec 要求实现用户注册功能,Agent 实现了注册,顺手重构了登录模块的错误处理逻辑。注册功能测试通过,但登录模块的行为发生了未经审查的变化。

Spec 里定义的实体叫 Order,Agent 在代码里把它命名为 Transaction。功能没有任何问题,但当下一个 Agent 接手这个模块时,它拿着 spec 找 Order 的实现,找到的是一个叫 Transaction 的类,两者之间没有任何显式关联。

这些问题的共同特征是:它们不违反任何行为断言,测试不会捕获它们。硬编码、超出范围的改动、架构偏离、过度实现、术语漂移,都属于这一类。它们不是 bug,但它们是代码在慢慢偏离 spec 定义的框架的信号。如果不被发现,这些偏离会在后续迭代中累积,让代码和 spec 之间的映射关系逐渐模糊,直到 spec 失去作为 single source of truth 的作用。

Review 的标准是规约

传统 code review 的问题清单是:变量命名是否规范?有没有潜在的性能问题?异常处理是否完备?这些问题的参照系是代码本身和通用的工程最佳实践。

Agent 开发中的 code review 只问三件事:这段代码和 spec 说的是不是一回事?这段代码有没有做 spec 没要求的事?代码中的概念和 spec 中的术语是否对应?

参照系从代码变成了 spec。Review agent 的核心输入是变更的代码和 spec,不需要看 Agent 的编码过程,不需要理解它的实现思路。工作就是拿着 spec 逐条对照代码变更,标注匹配、偏离和缺失。

这意味着 review 的产出不是一份泛泛的”建议改进”清单,而是一份 spec 一致性报告:哪些 acceptance criteria 被满足了,哪些存在偏离,哪些完全缺失。这份报告直接对应 spec 的结构,人类审查的时候可以聚焦在偏离和缺失的条目上,不需要逐行阅读代码。

编码与审查的 Agent 必须独立

如果让同一个 Agent 先写代码再审查自己的产出,编码过程中积累的上下文会影响它的判断。它在写代码时决定把 Order 命名为 Transaction,这个决策和它的理由都留在 context 里。审查时它看到 Transaction,context 里的推理过程告诉它这个命名是合理的,它不会对照 spec 重新评估。后端漏掉了一个校验,它记得自己在前端已经做了,context 里有这个记忆,它不会追问后端是否也需要。审查变成了对编码过程中已有推理的确认,而不是对 spec 的独立验证。

所以写代码的 Agent 和 review 的 Agent 必须在独立的 session 中运行。Review agent 没有编码过程的任何上下文。它不知道代码为什么这样写,只知道 spec 要求了什么,代码做了什么,两者是否一致。

用不同的模型做交叉审查能进一步降低共享盲区的风险。不同模型家族有不同的训练数据和推理偏好,编码 Agent 系统性忽略的问题,另一个模型可能恰好敏感。这和规约章讲的交叉验证是同一个原则:独立的视角才能发现漂移。

Anthropic 在 Claude Code 的最佳实践文档中把 writer/reviewer 分离列为最高优先级的建议之一,明确指出 fresh context 能显著提高 review 的质量。他们内部的 code review 系统在几乎每个 PR 上都运行多个 agent 并行审查,每个 agent 针对不同的问题类别(逻辑错误、边界条件、API 误用、权限漏洞、项目规范)。上线后,得到实质性发现的 PR 比例从 16% 上升到 54%。在 1000 行以上的大 PR 中,84% 得到发现,平均每个 PR 标注 7.5 个问题。工程师不同意审查结论的比例低于 1%。

OpenAI 的实践提供了另一个规模参照:自动化 code review 系统处理超过每天 10 万个 PR,正面反馈率超过 80%。

这些数据指向一个实践结论:独立的、基于明确标准的审查,在规模化开发中是可行的,而且比人类审查更一致。当 Agent 的产出速度远超人类的审查能力时,用独立的 Agent 做 spec 一致性审查是唯一能跟上产出速度的方案。


Harness Engineering Playbook · AgentsZone Community