Merge pull request #28 from lipingtababa/feat/03-verification

Rewrite chapter 03: verification as spec-faithful testing and code review

Author: fqzz2000

docs/ch03-outline.md

@@ -0,0 +1,216 @@
+# Chapter 03 Outline v3: 验证——确保代码忠实于规约
+
+## Chapter Takeaway（总）
+
+验证的本质不是检查代码质量，而是检查代码是否忠实于规约。Spec 是 single source of truth，所有验证动作都在回答一个问题：这段代码和文档说的是不是一回事？
+
+围绕这个原则，结合 Agent 的能力边界（上下文有限、执行中漂移），验证任务本身也必须被切成 Agent 能消化的小块：用测试基建让 spec 变成可执行约束，用 code review 补位测试覆盖不到的意图漂移。
+
+Spec + Verification = 单任务闭环。规约定义了目标，验证确保执行到达目标。
+
+---
+
+## 章节引言（03-verification.md）——做"总"的工作
+
+### 引言要完成的任务
+
+1. 承接上一章，建立问题
+2. 展示行业共识：验证很重要，大家都在做
+3. 但实际用过就知道不够，引出正确的原则
+4. 搭建 motivation 链：Agent 特性 → 为什么验证必须前置、必须过程中、必须模块化
+5. 预告两个 section + 一个实践
+
+### 内容结构
+
+**1. 承接：规约正确 ≠ 实现正确**
+
+02d 的 OKR 案例中，spec 全部正确，但 26/28 compliance check 说明执行中仍然漏了两条（BR-002 缺后端校验、BR-004 缺默认赛季选择）。规约解决了"告诉 Agent 做什么"，验证解决的是"Agent 是不是真的做了"。
+
+**2. 行业共识：验证是 harness 工程的核心**
+
+目前行业内已经承认验收工作是 harness 工程中最核心的内容之一（Anthropic 最近关于 evaluator 的 blog）。各框架也在验证上投入了大量工程：
+- BMAD：三层信息不对称审查（Blind Hunter / Edge Case Hunter / Acceptance Auditor）
+- Spec Kit：constitution 治理 + 10 类歧义检测 + 多层 phase gate
+- OpenAI/Anthropic：多 Agent 并行 code review、eval 框架
+- 社区实践：TDD、Trophy 测试、对抗式 review
+
+**3. 这些工具解决不了长期开发中的核心质量问题**
+
+如果你在真实项目中大规模使用过这些验证工具，你会发现：代码可以通过所有 lint、所有单元测试、所有对抗式 review，但它实现的功能和 spec 说的不是一回事。null check、命名规范、安全漏洞，这些代码质量问题 AI 自己就能发现并修复。真正难以检测的是意图偏离：spec 说要 A，代码实现了 B。上一节提到的 BR-002 就是这类问题：代码写得很好，只是漏掉了 spec 里的一条业务规则。任何不看 spec 的 review 都不会发现它。
+
+TDAD 论文也印证了这一点：告诉 Agent"遵循 TDD"（抽象的流程指令）反而让回归率从 6% 升到 10%。给 Agent 具体的测试目标（spec 上下文），回归率降到 1.8%。流程不是答案，spec 上下文才是。
+
+**4. 正确的原则：Spec 是 single source of truth**
+
+所有验证动作都在回答一个问题：这段代码和文档说的是不是一回事？
+- 测试在测"代码是否实现了 spec 说的行为"，不是在测"代码对不对"
+- Review 在问"代码和 spec 一致吗"，不是在问"代码好不好"
+
+**5. 验证必须前置、过程中、模块化**
+
+验证基建必须在编码前就位，在执行过程中持续运行，并且按模块拆分。这个结论由 Agent 的两个特性决定：
+
+（a）Agent 在执行中会漂移。规约章已经建立了漂移的概念。在代码实现阶段，Agent 对 spec 的理解随着上下文积累而偏移，小偏差在后续步骤中累积。如果等全部写完再验证，面对的是几十个失败的测试，每个指向不同问题，修复成本远高于过程中修复。所以验证必须是过程中的，不是事后的。
+
+（b）Agent 的上下文容量有限。不仅写代码有上下文限制，验证也有。让 Agent 写了 2000 行代码再让另一个 Agent review，review Agent 也没有足够的上下文做全面检查。所以验证的粒度必须和执行的粒度匹配。执行拆小块，验证跟着拆小块。
+
+这两个约束共同指向：验证基建必须在编码前就位。不是写完代码再补测试，而是先把 spec 转化为可执行的测试框架，让 Agent 从第一步开始就有反馈。
+
+DORA 报告的"放大器"效应佐证了这一点：有验证基建的团队，Agent 速度放大的是产出；没有验证基建的团队，Agent 速度放大的是混乱。
+
+（注：Anthropic 的 harness 设计原则可以在这里或章末引用："每个 harness 组件编码了一个关于模型不能做什么的假设。这些假设值得压力测试，因为它们可能是错的，而且随着模型进步会很快过时。" 验证体系不是固定教条，它跟着对 Agent 能力边界的判断而演化。）
+
+那么"前置的验证基建"具体包括什么？
+
+**6. 测试和 code review 缺一不可**
+
+验证 spec 一致性需要两个机制，不是一个。社区中反复出现的误区是只用其中一个，然后得出"AI 编程不可靠"的结论。
+
+只有 code review 没有测试的团队：review 能发现代码和 spec 的偏离，但验证不了代码的运行时正确性。review 说"这个逻辑看起来对"，不等于代码跑起来真的对。结果是"review 过了，一跑就崩"。
+
+只有测试没有 code review 的团队：测试能验证行为，但覆盖率很难达标，而且 Agent 会用硬编码绕过测试（比如直接 return 预期值来让测试通过）。测试全绿，但代码里埋着定时炸弹。结果是"测试全过了，但 AI 老是硬编码绕过去"。
+
+两者的目标是同一个：让 spec 变成可执行的约束。但切入角度不同：
+- 测试验证行为正确性（spec 说的功能，代码做到了吗）
+- Code review 验证语义完整性（代码有没有偏离 spec 的框架，有没有做 spec 没说的事）
+
+另外，测试的成本低、运行速度快、反馈即时，是过程中持续验证的主力。Code review 成本更高，适合在阶段节点做。两者在成本和覆盖面上互补。
+
+**7. 预告**
+
+围绕这个原则和这些约束，本章介绍两个机制：测试基建前置（03a），把 spec 变成可执行约束，让 Agent 在过程中持续拿到反馈；Code review against spec（03b），补位测试覆盖不到的意图漂移。最后用 AILock-Step 框架的实践展示这两个机制如何落地（03c）。
+
+---
+
+## Section 1（03a）：测试基建前置——把 Spec 变成可执行约束
+
+### Section Takeaway
+
+测试是 spec 的可执行形式。在第一行业务代码之前，把验收标准转化为集成测试，Agent 的每一步执行都能立即拿到反馈：这一步是否忠实于 spec。API contract 是测试的骨架，它定义了模块边界，让每个模块可以独立验证。
+
+### 内容结构
+
+**1. API Contract：验证的骨架**
+
+测试需要可测试的边界。引言中已经建立了验证必须模块化的原因（Agent 上下文有限）。API contract 就是模块化验证的骨架，它做三件事：
+- 定义每个模块的输入输出（接口规格）
+- 让 mock server 基于 contract 搭建（模块可以独立测试，不依赖其他模块完成）
+- 让测试断言有明确的参照物（contract 说返回什么，测试就验证什么）
+
+没有 contract → 模块边界模糊 → 测试只能做端到端全链路 → 粒度太粗，问题定位不到具体模块。
+有 contract → 每个模块独立验证"我是否实现了 contract 规定的行为" → 粒度可控，问题定位精确。
+
+这也是多 Agent 并行的前提（第五章会展开）：有 contract 才能让多个 Agent 独立开发不同模块而不互相冲突。
+
+**2. 从 Spec 和架构文档直接生成测试**
+
+这一步体现了本章的核心原则：测试从 spec 写，不是从代码写。
+
+测试的输入是 spec 中的验收标准和架构文档中的 API contract，不是 Agent 生成的代码。测试编写者（无论是人还是 Agent）在编写测试时不应该看到任何业务代码，因为它还不存在。这保证了测试独立于实现，是对 spec 意图的直接翻译。
+
+时间点：所有 spec 完成之后、第一行业务代码之前。
+
+具体做什么：
+- 从 spec 的验收标准生成集成测试（Given/When/Then → test case）
+- 从架构文档的 API contract 生成接口级测试（contract 定义的输入输出 → 断言）
+- 暂时不存在的依赖用 mock 替代（基于 API contract 搭建）
+- 测试在 Agent 编码前就存在，是红色的
+
+为什么集成测试而不是单元测试：
+- 集成测试验证"用户故事能不能走通"，直接对应 spec 的意图
+- 单元测试验证"函数返回值对不对"，这是实现细节，和 spec 意图距离太远
+- Agent 可以通过调整实现来"通过"单元测试，但很难伪造一个完整的用户旅程
+- 单元测试不是没用。Agent 可以自由编写单元测试辅助开发。但作为验收依据，集成测试是更可靠的信号。
+
+**3. 过程中验证：闭环**
+
+Agent 每完成一个小步骤，立即跑相关测试。偏差在产生的当轮就被捕获，不会扩散到后续步骤。
+
+闭环结构：spec → 测试 → Agent 编码 → 测试反馈 → 修正 → 下一步。这和规约章的迭代环是同一个结构在执行阶段的投影。
+
+**4. 写不出测试 = spec 不够具体**
+
+如果一条验收标准无法被转化为测试，这条标准需要回到规约阶段继续明确。测试是对 spec 质量的反向检验。这也是为什么测试基建要在编码前搭建：它能在最早的阶段暴露 spec 的模糊之处。
+
+测试基建解决了行为正确性的验证：spec 说的功能，代码做到了吗？但引言中已经指出，测试覆盖不了所有的意图漂移。硬编码、超出范围的改动、架构偏离，这些需要另一个机制。
+
+---
+
+## Section 2（03b）：Code Review——补位测试覆盖不到的意图漂移
+
+### Section Takeaway
+
+测试验证的是行为：spec 说的功能实现了吗？但代码中还有一类问题是测试捕捉不到的：硬编码、超出范围的改动、架构偏离、过度实现。Code review 补位这些测试盲区。review 的标准不是"代码好不好"，而是"代码和 spec 一致吗"。
+
+### 内容结构
+
+**1. 测试的盲区（问题建立）**
+
+测试能验证行为正确性，但验证不了：
+- 硬编码（magic numbers、hardcoded URLs、写死的配置）
+- 超出任务范围的改动（Agent 顺手"优化"了不该动的代码）
+- 架构偏离（spec 说用 strategy pattern，Agent 用了 if-else chain）
+- 过度实现（spec 只要求 A，Agent 实现了 A+B+C）
+- 命名和结构与 spec 术语的偏离（spec 叫"订单"，代码叫"transaction"）
+
+这些不是 bug，测试不会捕获它们。但它们是意图漂移的信号。
+
+**2. Review 的标准是 spec，不是代码审美**
+
+Agent 开发中 review 问的是：
+- 这段代码和文档说的是不是一回事？
+- 这段代码有没有做文档没要求的事？
+- 代码中的概念和 spec 中的术语是否对应？
+
+Review agent 只需要两样东西：diff + spec。不需要看编码过程，不需要理解实现思路。工作就是逐条对照。
+
+**3. 独立性原则**
+
+写代码的 Agent 和 review 的 Agent 必须独立：
+- 不同 session（避免上下文污染）
+- 最好不同模型（避免共享的推理盲区）
+- Anthropic 的实践：writer/reviewer 分离，fresh context 提高 review 质量
+- 这和规约章的"交叉验证"是同一个原则：独立的视角才能发现漂移
+
+**4. 实证**
+
+- Anthropic code review 系统：上线后 54% 的 PR 得到实质性发现（之前 16%）。大 PR（1000+ 行）84% 得到发现，平均 7.5 个问题。工程师不同意的比例 < 1%。
+- OpenAI：100k+ PR/天的自动化 review，80% 正面反馈。
+
+---
+
+## Section 3（03c）：实践——AILock-Step 的验证体系
+
+### Section Takeaway
+
+（待 Section 1-2 写完后明确。初步方向：用一个具体的框架实现展示上述原则如何落地。）
+
+### 内容结构（初步，待细化）
+
+**1. 框架中的测试生成**
+- 从 spec 的 Gherkin 场景自动生成集成测试
+- 测试在 implement 之前生成并 commit
+- 展示一个具体 feature 从 spec → test → implementation 的完整流程
+- 和 02d 的 OKR 案例衔接：02d 展示了 spec 流程，03c 展示同一个框架的验证流程
+
+**2. 框架中的 code review**
+- Review agent 拿到 diff + spec，逐条验证一致性
+- 展示 review 报告：哪些 AC 满足了，哪些偏离了，哪些缺失了
+
+**3. 验证结果与 compliance 报告**
+- 承接 02d 的 compliance check 机制
+- 展示完整的验证链：spec → test generation → implementation → code review → compliance report
+
+**4. 闭环**
+- Spec（02 章）+ Verification（03 章）= 单任务闭环
+- 一个人 + Agent 能够可靠地完成一个功能从 spec 到代码到合并
+- 预告：当你开始同时跑多个 Agent（卷二），这套验证基建从"好实践"变成"生存前提"
+
+---
+
+## 待定问题
+
+1. ~~Anthropic harness 原则~~ → 放在引言 motivation 链中
+2. 形式化验证（de Moura）→ 不提，留给 evolution 章节
+3. Section 3 demo 范围待 1-2 写完后确定。当前 AILock-Step 框架需要补建测试生成和 code review 功能。
+4. SUMMARY.md 子章节标题需要更新（03a-03f → 03a-03c）。

en/README.md

@@ -73,13 +73,10 @@ The book unfolds along a productivity ladder. Chapter 1 analyzes the structural
   * [Conveying Intent Through Structure: Layers and Dimensions](chapters/02b-structured-intent.md)
   * [Iterating Toward an Executable Spec](chapters/02c-iterative-spec.md)
   * [In Practice: AILock-Step Feature Workflow](chapters/02d-case-study.md)
-* [The Backbone of Reliable Delivery: Automated Quality Control](chapters/03-verification.md)
-  * [From Wish List to Executable Constraints: Test First](chapters/03a-test-first.md)
-  * [AI Writes Code and Tests: The Collusion Problem](chapters/03b-collusion.md)
-  * [What Kind of Tests Are Hardest to Game: The Trophy Testing Model](chapters/03c-trophy-testing.md)
-  * [Not Check After Done, but Check While Doing: Continuous Feedback During Execution](chapters/03d-continuous-feedback.md)
-  * [Output Too Fast to Review: Using Agents to Verify Agents](chapters/03e-adversarial-verification.md)
-  * [So What Do I Do: From Reviewing Code to Designing Verification Systems](chapters/03f-new-role.md)
+* [Verification: Ensuring Code Stays Faithful to the Spec](chapters/03-verification.md)
+  * [Test Infrastructure First: Turning Specs into Executable Constraints](chapters/03a-test-first.md)
+  * [Code Review: Catching Intent Drift That Tests Miss](chapters/03b-code-review.md)
+  * [In Practice: AILock-Step's Verification Pipeline](chapters/03c-practice.md)
 
 ### Part II: Scaling Agent Development (10→100x)
 

en/SUMMARY.md

@@ -9,13 +9,10 @@
   * [Conveying Intent Through Structure: Layers and Dimensions](chapters/02b-structured-intent.md)
   * [Iterating Toward an Executable Spec](chapters/02c-iterative-spec.md)
   * [In Practice: AILock-Step Feature Workflow](chapters/02d-case-study.md)
-* [The Backbone of Reliable Delivery: Automated Quality Control](chapters/03-verification.md)
-  * [From Wish List to Executable Constraints: Test First](chapters/03a-test-first.md)
-  * [AI Writes Code and Tests: The Collusion Problem](chapters/03b-collusion.md)
-  * [What Kind of Tests Are Hardest to Game: The Trophy Testing Model](chapters/03c-trophy-testing.md)
-  * [Not Check After Done, but Check While Doing: Continuous Feedback During Execution](chapters/03d-continuous-feedback.md)
-  * [Output Too Fast to Review: Using Agents to Verify Agents](chapters/03e-adversarial-verification.md)
-  * [So What Do I Do: From Reviewing Code to Designing Verification Systems](chapters/03f-new-role.md)
+* [Verification: Ensuring Code Stays Faithful to the Spec](chapters/03-verification.md)
+  * [Test Infrastructure First: Turning Specs into Executable Constraints](chapters/03a-test-first.md)
+  * [Code Review: Catching Intent Drift That Tests Miss](chapters/03b-code-review.md)
+  * [In Practice: AILock-Step's Verification Pipeline](chapters/03c-practice.md)
 * [Systems Need Iteration Too: Evolving Specs and Verification](chapters/evolution-v1.md)
 
 ### Part II: Scaling Agent Development (5-10x → 100x)