Article

AI-TDD: 需求契约驱动与多维证据链验收框架

AI-TDD 先把人类意图固化为 Manifest 需求契约，再用可复核证据链和 Gate 裁决验收 AI 生成结果。

AI TDD AI 工程化 Ai Coding Mentor Test Driven Development Manifest Driven Quality Gate Human AI Collaboration Software Engineering

引言：从”代码级TDD”到”需求契约驱动”

从GitHub Copilot技术预览到GPT-4、Claude Code、Codex等工具进入日常开发环境，AI编码已经从”代码补全”走向”需求理解、实现生成、测试修复和工程协作”。

真正的转变在于，问题从”AI能不能写代码”变成了”AI写出的代码是否满足需求边界”。

业界讨论的焦点已经从”AI能不能写代码”转变为”AI写的代码对不对”。当前主流大语言模型已经能够稳定生成大量可运行代码片段，但语法正确不等于需求对齐——基于代码层面的TDD有本质局限，因为缺乏需求的全局视野。

问题边界先于解决方案

这是AI时代软件架构的一条基础原则。正如软件工程的智慧：“在解决问题之前，先花大部分时间理解问题本身。“在AI时代，这个道理变得更加具体——当AI能快速生成大量代码时，真正决定成败的不再只是编码速度，而是问题边界是否被清晰定义。

边界模糊的需求会导致AI自由发挥，而自由发挥的结果往往与预期偏离。AI-TDD正是基于这一原理构建的方法论：不以Manifest为契约的AI生成，就是没有需求锚定的自由发挥。Manifest的本质，就是将模糊的需求边界转化为机器可读的、可验证的契约矩阵。

一个典型失效场景：AI生成用户模块的教训

下面是一个综合多个常见风险点构造的失效场景。产品负责人向AI描述需求：“实现一个用户注册功能，需要邮箱验证和密码加密。”

AI生成了代码，团队快速上线。然而上线后一周内发生了以下问题：

安全漏洞：AI使用了MD5而非bcrypt存储密码，虽然”加密”了，但容易被彩虹表攻击
并发问题：当大量用户同时注册时，系统创建了重复账户，因为AI没实现邮箱唯一性约束
边界溢出：用户可以上传任意大小的头像图片，导致存储成本失控——因为需求没说”限制图片大小”
功能漂移：AI实现了OAuth社交登录，但这是团队计划”下个季度”才做的功能

问题根源：自然语言需求存在歧义、隐含假设、边界模糊。AI按照自己的”理解”填补了这些空白，而这些理解与团队的真实意图存在偏差。

如果当时使用了AI-TDD Manifest：

must:
  - id: MUST-REG-EMAIL-001
    text: 用户可以通过邮箱注册
    validation: "email格式符合RFC 5322，password长度8-32字符"
  - id: MUST-REG-PASSWORD-001
    text: password必须加密存储
    validation: "使用bcrypt，cost factor >= 12，不是MD5或SHA"
  - id: MUST-REG-UNIQUE-001
    text: 防止重复注册
    validation: "数据库层唯一索引 + 应用层原子检查"

outOfScope:
  - id: OUT-AUTH-OAUTH-001
    text: 不支持OAuth社交登录
    reason: "本迭代不包含，移至REQ-OAUTH-001"

AI将在明确的契约约束下生成实现，而非自由发挥。

代码级TDD的局限

传统TDD（Test-Driven Development）的核心是”先写测试，再写实现”。这个实践在人工编码时代有效，因为开发者自己写测试、自己实现，需求在开发者的头脑中是一致的。

但当AI成为实现主体时，问题出现了：

测试代码只能覆盖局部，无法约束全局。

想象这样一个场景：你让AI实现一个用户注册模块。你写了单元测试验证”输入空密码时返回错误”。AI生成了代码，测试通过了。但上线后你发现：

AI没做邮箱格式验证（因为没有对应的测试）
AI用了明文存储密码（测试只验证了接口行为，没验证存储逻辑）
AI没处理并发注册的竞争条件（测试没覆盖并发场景）

这就是代码级TDD的本质局限：测试只能验证”我测了的部分”，而AI会按照”它自己理解的完整需求”来实现，两者之间的gap就是风险。

Manifest作为需求契约矩阵

软件工程实践中有一个长期共识：缺陷越晚被发现，修复成本通常越高。在AI生成代码的场景下，这个问题会被进一步放大，因为模型可以非常快地把一个模糊需求扩展成大量看似可运行的实现。

AI-TDD的核心突破在于：把验收标准从”代码级的测试用例”提升到”需求级的契约矩阵”。

我们称之为 AI-TDD Gate Manifest —— 一份在需求确认阶段就生成的、机器可读的需求契约清单。

Manifest不是简单的”测试列表”，而是需求的契约矩阵，包含 MUST、NEG（MUST NOT 负向断言）、OUT（OUT OF SCOPE 范围边界）、TRACE、EVD、ACC/E2E、FAIL/EDGE、CMD、ART 和 TASK 等核心 namespace。这些维度的完整技术定义和Schema规范，我会在第四章展开。

关键洞察：Manifest应该在执行开始前达到足够完备的状态。如果在执行阶段边做边补，模型更容易遗漏关键边界或出现实现漂移。

AI-TDD的核心思想

AI-TDD不是”先写测试再让AI生成”而是**“先定义问题边界，再验证边界内实现”**。

六大认知阶段：需求确认 → 架构确认 → 实施准备 → 执行闭合 → 审计复核 → 交付确认

两大关键门禁：Implementation Readiness Gate（准入门禁，期望状态 AI-TDD-RED，下文简称 TDD-RED）和 Delivery Closeout Gate（交付门禁，期望状态 AI-TDD-GREEN，下文简称 TDD-GREEN），确保”不准备好Manifest，不允许进入执行”和”Manifest有未验证项，禁止交付”。

这套框架的目标很直接：用机器可读的Manifest替代模糊的自然语言需求，在执行开始前建立完备的需求契约，再用可复现证据链判断当前实现是否可以交付。

AI-TDD的一等定义：需求契约驱动 + 多维证据链验收

本文对AI-TDD的定义不是”让AI跑TDD”，而是：

先把人类意图编码为需求契约，再用多维证据链证明当前实现满足该契约。

换成工程结构，就是：

Requirement Contract（需求契约）
→ Contract Slice（契约切片）
→ Evidence Chain（证据链）
→ Gate Verdict（门禁裁决）
→ Human Decision（人工决策）

这条链路由五层组成：

层级	典型 namespace	作用
声明层	`MUST` / `NEG` / `OUT`	定义必须做、禁止做和当前不做的边界
切片层	`TRACE` / `TASK`	把需求拆成可追溯、可验收的最小契约切片
场景层	`ACC` / `E2E` / `EDGE` / `FAIL`	定义正向、端到端、边界和失败路径
证据层	`EVD` / `CMD` / `ART` / hash / receipt	定义什么算证明、如何复现、产物在哪里
状态层	`AI-TDD-RED` / `IMPLEMENTING` / `CLOSEOUT_CANDIDATE` / `AI-TDD-GREEN` / `CLOSED`	用Gate判定契约生命周期是否可进入下一阶段

其中 TRACE row 是AI-TDD的最小契约单元。传统TDD的原子单位是test case，BDD的原子单位是scenario，AI-TDD的原子单位是contract slice：它必须说明覆盖哪个 MUST/NEG、由哪个场景验证、需要哪些证据、运行哪些命令、生成哪些产物；OUT 范围边界不进入 covers，而是通过 scopeAuditRefs 或等价字段绑定范围审计证据。

多维证据链验收的判定也要提前说清：测试通过只是证据之一，不是交付本身。一次交付只有在当前attempt的 TRACE -> EVD -> CMD -> ART 证据链闭合、Gate给出通过裁决，并留下 Human Decision 人工决策记录后，才可以称为 AI-TDD-GREEN。

3分钟阅读路线：如果你只想抓住本文主线，先读本节的一等定义，再看快速开始的“按证据链验收交付”，然后跳到第六章 Delivery Closeout Gate，最后用附录术语表核对 Requirement Contract -> Contract Slice -> Evidence Chain -> Gate Verdict -> Human Decision 这条链。

快速开始：上手AI-TDD

不想先看理论？没问题。跟着这个示例走一遍，你就能体会AI-TDD的核心思想。

示例：用AI-TDD实现一个计算器

你的需求：“实现一个加法函数”

传统做法的问题：直接告诉AI”写个加法函数”，AI可能会：

没处理非数字输入
没澄清数字边界条件
加了不必要的功能（比如减法、乘法）

AI-TDD做法：先写Manifest，再让AI生成。

关键状态流转：Manifest → AI-TDD-RED / TDD-RED（测试存在/实现缺失）→ CLOSEOUT_CANDIDATE（注册验证通过但尚未交付裁决）→ AI-TDD-GREEN / TDD-GREEN（证据链、Gate Verdict 和 Human Decision 闭合）→ 交付

步骤1：创建Manifest文件

创建 calculator-manifest.yaml：

manifest:
  version: "1.0.0"
  project: "calculator-demo"
  requirementId: "REQ-CALC-001"
  title: "加法函数"

  acceptanceCriteria:
    must:
      - id: "MUST-CALC-ADD-001"
        description: "接受两个数字参数，返回它们的和"
        validation: "add(2, 3) === 5"

      - id: "MUST-CALC-FLOAT-001"
        description: "处理浮点数"
        validation: "add(0.1, 0.2) 接近 0.3（考虑浮点精度）"

    mustNot:
      - id: "NEG-CALC-TYPE-001"
        description: "不接受非数字输入"
        validation: "add('a', 1) 抛出 TypeError"

    outOfScope:
      - id: "OUT-CALC-OPS-001"
        description: "减法、乘法、除法"
        reason: "本迭代只实现加法"

    evidence:
      - id: "EVD-CALC-UNIT-001"
        type: "unit_test"
        description: "加法、浮点数和非数字输入测试全部通过"
        requiredCommandRefs: ["CMD-CALC-TEST-001"]
        artifactRefs: ["ART-CALC-TEST-REPORT-001"]

      - id: "EVD-CALC-SCOPE-001"
        type: "scope_audit"
        description: "实现中不存在减法、乘法、除法等越界功能"
        requiredCommandRefs: ["CMD-CALC-SCOPE-001"]
        artifactRefs: ["ART-CALC-SCOPE-REPORT-001"]

    traceRows:
      - id: "TRACE-CALC-ADD-001"
        covers: ["MUST-CALC-ADD-001", "MUST-CALC-FLOAT-001"]
        evidenceRefs: ["EVD-CALC-UNIT-001"]
        commandRefs: ["CMD-CALC-TEST-001"]
        artifactRefs: ["ART-CALC-TEST-REPORT-001"]

      - id: "TRACE-CALC-NEG-001"
        covers: ["NEG-CALC-TYPE-001"]
        evidenceRefs: ["EVD-CALC-UNIT-001"]
        commandRefs: ["CMD-CALC-TEST-001"]
        artifactRefs: ["ART-CALC-TEST-REPORT-001"]

      - id: "TRACE-CALC-SCOPE-001"
        scopeAuditRefs: ["OUT-CALC-OPS-001"]
        evidenceRefs: ["EVD-CALC-SCOPE-001"]
        commandRefs: ["CMD-CALC-SCOPE-001"]
        artifactRefs: ["ART-CALC-SCOPE-REPORT-001"]

    commands:
      - id: "CMD-CALC-TEST-001"
        run: "npm test -- calculator.test.js --runInBand > artifacts/calculator-test-report.txt"
        producesArtifactRefs: ["ART-CALC-TEST-REPORT-001"]
      - id: "CMD-CALC-SCOPE-001"
        run: "node scripts/check-calculator-scope.mjs > artifacts/calculator-scope-report.txt"
        producesArtifactRefs: ["ART-CALC-SCOPE-REPORT-001"]

    artifacts:
      - id: "ART-CALC-TEST-REPORT-001"
        path: "artifacts/calculator-test-report.txt"
      - id: "ART-CALC-SCOPE-REPORT-001"
        path: "artifacts/calculator-scope-report.txt"

关键点：

must：加法要做什么（2+3=5，浮点数处理）
mustNot：加法不能做什么（不接受字符串）
outOfScope：明确排除其他运算（防止AI自由发挥）
traceRows：把需求边界绑定到证据、命令和产物
evidence / commands / artifacts：定义什么算证明、如何复现、证据保存在哪里

步骤2：AI生成测试代码

把Manifest给AI，Prompt：

基于以下Manifest生成测试代码，注意必须覆盖NEG（MUST NOT）的负向场景：

[粘贴Manifest]

AI会生成类似这样的测试：

// calculator.test.js
describe('加法函数', () => {
  // MUST-CALC-ADD-001
  test('2 + 3 = 5', () => {
    expect(add(2, 3)).toBe(5);
  });

  // MUST-CALC-FLOAT-001
  test('浮点数处理', () => {
    expect(add(0.1, 0.2)).toBeCloseTo(0.3, 10);
  });

  // NEG-CALC-TYPE-001
  test('拒绝非数字输入', () => {
    expect(() => add('a', 1)).toThrow(TypeError);
  });
});

说明：这里是概念示例，不是可直接运行的完整项目脚手架。若要本地执行，还需要先引入 add、初始化 Jest/Vitest 等测试框架，并在 package.json 中配置 npm test。

开发期红灯验证：可以先运行 npm test 快速确认测试失败；正式进入证据链时，使用Manifest中注册的 CMD-CALC-TEST-001 生成 ART-CALC-TEST-REPORT-001。

预期结果：测试全部失败（TDD-RED状态）✅

add函数还不存在 → 失败是正常的
这说明测试代码已就绪，可以开始实现了

步骤3：AI生成实现代码

Prompt：

基于以下Manifest和测试代码，实现add函数，确保所有测试通过：

[粘贴Manifest]
[粘贴测试代码]

AI会生成：

// calculator.js
function add(a, b) {
  if (typeof a !== 'number' || typeof b !== 'number') {
    throw new TypeError('参数必须是数字');
  }
  return a + b;
}

module.exports = { add };

运行注册命令：CMD-CALC-TEST-001

预期结果：测试全部通过，候选实现进入 closeout candidate 状态。此时还不能称为 AI-TDD-GREEN，因为交付证据链和人工决策还没有闭合。

步骤4：按证据链验收交付

交付不是看一句”测试通过”，而是检查本次attempt的契约切片是否闭合：

契约项	TRACE / Scope Audit	EVD	CMD	ART	Gate Verdict	Human Decision
`MUST-CALC-ADD-001` / `MUST-CALC-FLOAT-001`	`TRACE-CALC-ADD-001`	`EVD-CALC-UNIT-001`	`CMD-CALC-TEST-001`	`ART-CALC-TEST-REPORT-001`	pass	accept，记录 `decisionTimestamp` 与 `HD-CALC-001` receipt
`NEG-CALC-TYPE-001`	`TRACE-CALC-NEG-001`	`EVD-CALC-UNIT-001`	`CMD-CALC-TEST-001`	`ART-CALC-TEST-REPORT-001`	pass	accept，确认负向路径属于当前attempt
`OUT-CALC-OPS-001`	`TRACE-CALC-SCOPE-001.scopeAuditRefs`	`EVD-CALC-SCOPE-001`	`CMD-CALC-SCOPE-001`	`ART-CALC-SCOPE-REPORT-001`	pass	accept，确认范围审计receipt已归档

验收清单应写成证据链，而不是普通todo：

每个 MUST/NEG 都有 TRACE 覆盖
每个 TRACE 都绑定 EVD
每个 EVD 都能追溯到当前attempt运行过的 CMD
每个 CMD 都产生可审计的 ART
OUT-CALC-OPS-001 的范围审计确认AI没有越界添加其他运算
Gate Verdict 为 pass
Human Decision 为 accept，并记录timestamp、actor和receipt artifact

结论：只有当当前attempt的证据链闭合、Gate Verdict 为 pass、Human Decision 为 accept，Delivery Closeout Gate 才能给出 AI-TDD-GREEN。

CMD-CALC-SCOPE-001 不能直接用 rg 'subtract|multiply|divide' 的退出码做通过条件，因为 rg 在没有匹配时会返回 1。范围审计脚本应显式把”没有越界符号”转换成退出码 0，并写入 ART-CALC-SCOPE-REPORT-001。例如：

// scripts/check-calculator-scope.mjs
import { readFileSync } from 'node:fs';

const source = readFileSync('calculator.js', 'utf8');
const forbidden = ['subtract', 'multiply', 'divide'].filter((name) => source.includes(name));

if (forbidden.length > 0) {
  console.error(`Out-of-scope operations found: ${forbidden.join(', ')}`);
  process.exit(1);
}

console.log('Scope audit passed: only addition is implemented.');

对比：传统做法 vs AI-TDD

维度	传统做法	AI-TDD
需求表达	”写个加法函数”（模糊）	Manifest YAML（精确）
AI输出	可能包含减法、乘法	严格只做加法（边界明确）
错误处理	可能遗漏	NEG（MUST NOT）强制要求
验收标准	人工判断”好像对了”	TRACE/EVD/CMD/ART证据链闭合

下一步

如果这个示例让你产生兴趣，继续阅读第一章，理解为什么AI-TDD能解决AI生成代码的核心问题。

背景考证：AI-TDD的思想早于术语

先澄清一个术语边界：截至目前，AI-TDD还不是像TDD、BDD、CI/CD那样拥有统一定义的行业标准术语。公开资料中确实可以找到完全匹配的用法，例如2023年的开源项目di-sukharev/AI-TDD，以及面向团队培训的”AI Test-Driven Development (AI-TDD)“课程。但这些更多是工具名、课程名或社区实践名称，还不足以证明AI-TDD已经形成公认标准。

因此，本文使用AI-TDD时，不是把它当作一个已经被权威机构正式定义的既有术语，而是用它概括一条已经可考证的工程趋势：当AI开始承担越来越多代码生成工作时，TDD从”人工编码前的测试实践”演变为”约束AI生成行为的契约机制”。

2021年，GitHub Copilot以技术预览形式发布，第一次让大量开发者直观看到”大模型可以直接生成代码”。这时业界的关注点还主要是效率：AI能不能补全代码、能不能减少样板劳动、能不能让开发者更快完成实现。

2023年，问题开始从”能不能生成”转向”生成得对不对”。GPT-4发布后，大模型在多类专业和学术任务上展现出强能力，但幻觉、错误推理和需求误解仍然存在。同年8月，Paul Sobocinski在Martin Fowler网站发表《TDD with GitHub Copilot》，系统指出：LLM会提供无关信息甚至产生幻觉，因此在使用AI编码助手时，TDD反而更加必要。文章给出的关键判断是，测试不仅是反馈机制，也是把问题拆小、让AI逐步逼近正确实现的方式。

2023年，di-sukharev/AI-TDD开源项目已经以工具形式探索”人写测试、GPT写代码直到测试通过”的工作流。这个项目不能代表行业共识，但它说明AI-TDD这个缩写并非事后杜撰，而是很早就被用于描述AI与TDD结合的具体实践。

2024年到2026年，学术界开始用更谨慎的名称研究同一方向，例如Generative AI for Test Driven Development、Test-Driven Development for Code Generation、Tests as Prompt、Test-Driven Agentic Development和AI-native TDD framework。这些论文不一定使用AI-TDD这个缩写，但它们共同指向一个趋势：测试不只是验证产物，而是可以作为模型理解任务、约束生成、暴露错误的输入。换句话说，测试开始从”开发后的检查工具”变成”AI生成前的契约语言”。

2025年，围绕AI编码代理的讨论进一步升温。一些工程博客和团队实践开始把TDD重新解释为AI生成代码的质量控制机制；Kent Beck在The Pragmatic Engineer访谈中讨论了TDD与AI agents的关系，强调测试在AI协作中的约束价值。此时，“先定义可执行验证，再让AI实现”的实践开始从个人技巧变成团队工作流，但更严谨的说法仍然应该是：行业正在形成”AI辅助TDD / TDD with AI agents / AI-native TDD governance”这一实践谱系，而不是已经收敛到单一的AI-TDD标准术语。

2026年2月，Thoughtworks在犹他州Deer Valley举办”The Future of Software Development Retreat”。报告中有一个非常关键的判断：当AI承担越来越多代码生产工作时，工程严谨性不会消失，而是迁移到规格、测试、约束和风险管理中。报告特别指出，TDD能让AI coding agents得到显著更好的结果，因为当测试先于代码存在时，agent不能通过编写”验证错误行为”的测试来让错误实现变绿。

这条发展线说明，本文讨论的AI-TDD不是对某个既有标准术语的复述，而是对上述实践谱系的进一步抽象：从代码级测试，扩展为需求级契约；从局部断言，扩展为全局Manifest；从”测试驱动实现”，扩展为”契约驱动生成”。这就是本文提出AI-TDD Gate Manifest的背景和命名边界。

第一章：为什么需要需求契约驱动的AI-TDD

1.1 代码级TDD的本质局限

为什么传统TDD在AI时代行不通？核心问题不在于”测试先行”这个理念本身，而在于测试只能覆盖代码的局部，无法控制AI对需求的全局理解。

局限一：测试覆盖的局部性

单元测试只能覆盖代码的局部行为。一个用户注册功能可能需要：

输入验证（单元测试可以覆盖）
数据库操作（集成测试才能覆盖）
并发控制（并发测试才能覆盖）
安全合规（安全扫描才能覆盖）
性能指标（性能测试才能覆盖）

开发者往往只写自己最熟悉的测试类型（通常是单元测试），而遗漏其他维度。

局限二：需求理解的隐式性

测试代码本身是对需求的”编码”。但测试代码不能回答：

“这个测试覆盖了哪些需求？”
“还有哪些需求没有被覆盖？”
“需求之间是否有冲突？”

当AI生成代码时，它看到的是一个一个孤立的测试，看不到需求的全局图景。

局限三：边界定义的缺失

代码级TDD擅长定义”做什么”，但不擅长定义：

“不做什么”（OUT OF SCOPE）
“做到什么程度”（EVD）
“如何追溯”（TRACE rows）

AI会按照自己的理解”补全”这些缺失的定义，而这正是风险所在。

1.2 Manifest：从测试清单到契约矩阵

Manifest的本质是把需求从人类大脑中的隐式知识，转化为机器可读的显式契约。

Manifest vs 测试代码：

维度	测试代码	Manifest
抽象层级	代码级（How）	需求级（What）
覆盖范围	局部	全局
人类可读性	差（需要懂代码）	好（结构化文档）
机器可读性	好（可执行）	好（可解析）
可追溯性	弱（测试→需求？）	强（TRACE rows）
完备性检查	难（覆盖率≠需求覆盖）	易（验收项清单）

Manifest的核心价值：

全局视野：在执行开始前就定义”全部需求是什么”
机器可读：AI可以解析Manifest，理解需求的全局图景
完备性检查：可以自动检查”哪些需求还没有测试覆盖”
契约权威：Manifest一旦确认，成为人机之间的正式契约

1.3 AI-TDD Gate：Manifest的执行引擎

AI-TDD Gate是Manifest的技术实现层，负责：

1. Manifest解析与注册

读取ai-tdd-manifest.yaml
注册所有MUST/NEG/OUT/EVD/ACC/E2E验收项
建立TRACE rows映射

2. 验收测试生成

基于Manifest自动生成测试代码框架
关联E2E/ACC测试套件
生成测试覆盖率要求

3. 门禁状态判定

运行全量测试
判定TDD-RED（准入）或TDD-GREEN（交付）
拦截未达标项

4. 可追溯性记录

记录每次门禁运行的结果
维护需求→测试→结果的追溯链
支持事后审计

第二章：架构的第一性原理

2.1 从”解决问题”到”定义问题边界”

要判断AI-TDD是否成立，先要回到一个更底层的问题：软件架构到底在管理什么？

终极第一性原理：人类的认知能力是有限的

这可以视为许多软件工程方法背后的基础假设。如果人类的认知能力接近无限，那么很多架构原则、模式和方法论的重要性都会显著下降，因为我们对拆分、抽象和模块化的依赖会减少。

从终极原理推导出的根本目标：管理复杂度

正因为人类认知有限，所以当系统的复杂度超过人的认知阈值时，系统就会变得不可维护、不可修改、不可预测。所有的架构设计，最终都是为了将系统的整体复杂度控制在人类能够理解和处理的范围内。

实现目标的核心原则：问题边界先于解决方案

这是管理复杂度的一条高优先级原则。复杂度的首要来源不是解决方案本身，而是模糊的问题边界。只有先清晰地定义问题的边界，我们才能知道哪些复杂度是必要的，哪些是不必要的。任何脱离问题边界的解决方案，都是不必要的复杂度。

从工程视角看，可验证性往往与模型能力本身同样重要。如果一个任务的边界不清晰、结果无法被检查，那么仅靠优化模型架构也未必能稳定提升结果。只有先明确任务边界和验证标准，模型能力才更容易被有效引导。

传统架构思维的误区：过度关注”How”

软件架构领域长期以来存在一个认知偏差：我们过度关注”如何解决问题”，而忽视”问题边界在哪里”。

传统架构设计流程：

传统瀑布式架构设计：业务需求 → 技术选型 → 系统架构 → 模块划分 → 接口设计 → 编码实现

在这个流程中，架构师在每个阶段都关注”如何设计”（How）：

技术选型阶段：选择什么框架？（Spring Boot / Express / Django）
系统架构阶段：服务如何划分？（单体 / 微服务 / Serverless）
模块划分阶段：模块边界在哪里？（按领域 / 按功能 / 按团队）
接口设计阶段：API格式如何？（REST / GraphQL / gRPC）
编码实现阶段：具体如何实现？（设计模式 / 代码规范）

根本缺陷：当AI成为实现主体时，这种思维模式暴露出问题——AI可以生成无限种”How”，但如果”What”定义不清，所有”How”都可能是错误的。传统流程缺乏对”问题边界在哪里”的明确定义。

第一性原理：问题边界先于解决方案

AI-TDD的架构心智模型基于一个简单但深刻的洞察：

清晰的问题边界定义，比优雅的解决方案更重要。

这不是说解决方案不重要，而是强调在没有明确边界的情况下，任何解决方案都是危险的——因为AI会自主填补边界内的空白，而这些填补可能与人类意图相悖。

从”解决问题”到”定义问题边界”

两种架构设计范式的差异，决定了AI生成的代码是”对齐需求”还是”自由发挥”：

范式A：解决方案驱动（传统）

需求：实现用户注册功能
架构师思考：
- 使用什么框架？（Spring Boot / Express / Django）
- 数据库如何设计？（users表，password字段）
- API接口格式？（POST /api/users）
- 需要哪些中间件？（Redis缓存、RabbitMQ消息队列）

范式B：边界定义驱动（AI-TDD）

需求：实现用户注册功能
架构师思考：
- MUST：必须支持什么？（email注册、密码加密、重复检测）
- NEG / MUST NOT：禁止什么？（明文存储、SQL注入、并发竞态）
- OUT OF SCOPE：明确排除什么？（OAuth、手机验证码）
- EVD：如何验证？（单元测试、安全扫描、性能测试）
- BOUNDARY：系统边界在哪里？（只负责注册，不负责邮件发送？）

范式A的思考结果是一个设计方案。范式B的思考结果是一个契约矩阵。

关键差异：

范式A的交付物是”建议”——AI可以参考，也可以偏离
范式B的交付物是”约束”——AI必须在边界内实现，偏离即失败

边界定义的五个维度

AI-TDD的Manifest从五个维度定义问题边界：

功能边界（MUST）
- 系统必须做什么
- 每个MUST都有对应的验收标准和证据要求
负向与范围边界（NEG / MUST NOT + OUT OF SCOPE）
- 系统禁止做什么
- 明确排除的功能和场景
- 这是传统架构最容易忽视的维度
证据边界（EVD）
- 什么构成”完成”的证明
- 不是”我觉得完成了”，而是”这些命令都返回了0”
追溯边界（TRACE rows）
- 需求与验证之间的映射关系
- 确保每个需求都有测试覆盖，每个测试都对应需求
状态边界（TDD-RED/GREEN）
- 准入状态：应达到TDD-RED（测试存在但失败）
- 交付状态：应达到TDD-GREEN（当前attempt的 TRACE/EVD/CMD/ART 证据链闭合，Gate Verdict 为 pass，Human Decision 为 accept）

为什么边界定义对AI时代至关重要？

人类开发者和AI的根本差异在于自主填补空白的方式：

人类开发者：基于经验、直觉、团队规范填补。如果边界模糊，人类会提问澄清
AI：基于概率、训练数据、模式匹配填补。如果边界模糊，AI会”猜测”最可能的实现

一个边界模糊的典型场景：

需求：“实现文件上传功能”

架构师A（传统思维）设计了上传API、存储方案、文件类型校验。但遗漏了一个边界：

单文件大小限制？
总存储配额？
病毒扫描要求？

AI生成的代码实现了”文件上传”，但没有大小限制。如果上线后出现超大文件上传，存储或服务稳定性就可能被拖垮。这不应简单归因于AI“写错了”，更准确的说法是：需求没有定义“允许上传什么、拒绝什么、如何验证”的边界。

如果AI-TDD Manifest定义了：

must:
  - id: MUST-UPLOAD-FILE-001
    text: 支持文件上传
    validation: "单文件最大100MB，支持jpg/png/pdf格式"

outOfScope:
  - id: OUT-UPLOAD-VIDEO-001
    text: 不支持视频文件上传
    reason: "本迭代不包含，移至REQ-VIDEO-001"

evidence:
  - id: EVD-UPLOAD-PASS-001
    text: 上传100MB文件成功
    threshold: "上传时间<30s"

  - id: EVD-UPLOAD-REJECT-001
    text: 上传110MB文件失败
    oracle: "返回413 Payload Too Large"

AI会在这些边界约束下生成实现，超过100MB的上传会被明确拒绝。

架构师的职责转变

在AI-TDD范式下，架构师的职责从”设计最佳方案”转变为”定义最清晰的边界”：

传统职责	AI-TDD职责
选择技术栈	定义技术约束（MUST使用某技术）
设计模块接口	定义接口契约（MUST满足某契约）
编写架构文档	生成机器可读Manifest
评审代码实现	验收TDD-GREEN证据

这不是降低架构师的价值，而是提升架构工作的精确性——从”建议”到”契约”，从”文档”到”可执行规范”。

2.2 人机协作的沟通本质：为什么单靠自然语言往往不足以充当AI的执行契约

AI-TDD使用结构化YAML而非自然语言作为需求载体，这不是技术偏好，而是基于对人机协作沟通本质的深层洞察。

自然语言的三个沟通陷阱

人类之间的沟通依赖自然语言，因为我们有共享的语境、经验和意图推断能力。但AI不具备这些能力，自然语言对AI而言存在三个根本性陷阱：

陷阱1：歧义的放大效应

自然语言的歧义对人类来说通常可以通过语境消解，但对AI来说是致命的：

人类指令："实现一个高性能的缓存"

AI可能的理解：
- 使用Redis（最常见）
- 使用Memcached（轻量级）
- 使用本地内存Map（最简单）
- 使用Caffeine（Java生态）
- 使用多级缓存（最"高性能"）

人类期望：也许是指Redis集群+本地缓存的多级方案
AI实现：选择了最简单的HashMap，因为指令中没有明确排除

陷阱2：隐含假设的不可见性

人类沟通大量依赖隐含假设。考虑这句话：

"实现用户登录，要安全"

人类理解的隐含假设：

“安全”意味着密码要加密存储（bcrypt，不是MD5）
“安全”意味着要防止SQL注入
“安全”意味着要有防暴力破解机制（失败次数限制）
“安全”意味着要使用HTTPS
“安全”意味着session要有过期时间

AI没有这些隐含知识。如果没有显式定义，AI可能：

使用MD5存储密码（在训练数据中见过）
忘记处理SQL注入
没有失败次数限制
使用HTTP而非HTTPS

陷阱3：完备性的无法验证

自然语言需求文档存在一个根本问题：你无法自动验证它是否”完备”。

需求文档：
- 用户可以通过邮箱注册
- 用户可以通过邮箱登录
- 用户可以修改密码

完备吗？对AI来说是的。
但遗漏了：
- 密码强度要求？
- 邮箱验证流程？
- 会话过期策略？
- 账户注销功能？
- 并发登录处理？

人类可以问”这些需求完备吗？“，但没有一个自动化工具可以扫描自然语言文档并回答”第3页第2段的需求在测试中没有对应覆盖”。

结构化契约的四个沟通优势

AI-TDD使用YAML Manifest取代自然语言需求，不是因为YAML更”酷”，而是因为它解决了自然语言的上述陷阱：

优势1：歧义的消除

# 不是"高性能缓存"，而是：
must:
  - id: MUST-CACHE-001
    text: 使用Redis作为缓存存储
    validation: "Redis集群模式，最少3个节点"

  - id: MUST-CACHE-002
    text: 本地二级缓存
    validation: "Caffeine缓存，TTL 5分钟"

outOfScope:
  - id: OUT-CACHE-MEMCACHED-001
    text: 不使用Memcached
    reason: "团队技术栈统一为Redis"

没有歧义：不是”高性能”（什么是高性能？），而是明确的”Redis集群+Caffeine二级缓存”。

优势2：隐含假设的显式化

must:
  - id: MUST-AUTH-001
    text: 密码加密存储
    validation: "使用bcrypt，cost factor >= 12"
    # 显式定义，不是隐含假设

  - id: MUST-AUTH-002
    text: 防止SQL注入
    validation: "所有数据库操作使用参数化查询"
    # 不是"要安全"，而是明确的约束

outOfScope:
  - id: OUT-AUTH-SSO-001
    text: 不支持SSO单点登录
    reason: "企业版功能，移至REQ-ENTERPRISE-001"
    # 明确排除，不是遗漏

优势3：完备性的机器可验证

must:
  - id: MUST-REG-EMAIL-001
    text: 用户可以通过邮箱注册
    evidenceRefs: [EVD-REG-TEST-001]
    coveredByTraceRows: [TRACE-REG-001]  # ← 必须有Trace覆盖

traceRows:
  - id: TRACE-REG-001
    covers: [MUST-REG-EMAIL-001]  # ← 反向声明覆盖
    evidenceRefs: [EVD-REG-TEST-001]
    acceptanceRefs: [ACC-REG-001]  # ← 必须有测试

acceptanceTests:
  - id: ACC-REG-001
    file: tests/acceptance/registration.test.ts

门禁可以自动验证：

“MUST-REG-EMAIL-001是否有Trace覆盖？”
“TRACE-REG-001是否有EVD支持？”
“EVD是否有CMD验证？”
“ACC-REG-001测试文件是否存在？”

完备性不是”感觉”，而是可以机器检查的事实。

优势4：执行语义的精确定义

自然语言告诉你”做什么”，但不告诉你”如何做”和”做到什么程度”。Manifest通过多层结构精确定义执行语义：

# 不只是"注册功能"，而是：
must:
  - id: MUST-REG-001
    text: 用户可以通过邮箱注册
    validation: |
      1. email格式符合RFC 5322
      2. password长度8-32字符
      3. 必须包含大小写字母和数字
    evidenceRefs: [EVD-REG-001, EVD-REG-002]
    coveredByTraceRows: [TRACE-REG-001]

evidence:
  - id: EVD-REG-001
    text: 注册成功证据
    requiredCommandRefs: [CMD-REG-TEST-001]
    artifactRefs: [ART-TEST-REPORT-001]

  - id: EVD-REG-002
    text: 注册失败边界证据
    requiredCommandRefs: [CMD-REG-TEST-002]
    # 负向测试：无效email、弱密码、重复注册

每一层都有明确的执行语义，AI不会”猜测”什么是”有效注册”——所有验证逻辑都在Manifest中显式定义。

人机协作的新沟通协议

AI-TDD本质上定义了一种人机协作的新沟通协议：

传统沟通	AI-TDD沟通
自然语言需求文档	YAML Manifest契约
”你懂的”隐含假设	显式MUST/NEG/OUT约束
人工完备性审查	自动TRACE rows验证
”大概完成了”感觉	TDD-GREEN客观证据
实现后人工验收	Implementation Readiness Gate前置拦截

关键洞察：

人类擅长：模糊意图、创造性思维、价值判断、边界权衡
AI擅长：模式匹配、大规模生成、一致性执行、快速迭代
Manifest的作用：把人类的模糊意图转化为AI可以精确执行的契约

不是取代人类判断，而是精确传递人类判断

AI-TDD的目标不是让AI代替人类做架构决策，而是让AI精确执行人类的架构决策。

自然语言适合人类之间的沟通，因为人类有共识和语境。YAML Manifest适合人机协作，因为它消除了歧义、显式化了约束、可验证完备性。

这不是沟通方式的降级，而是沟通精度的升级——从”大概理解”到”精确契约”。

2.3 契约即代码：Manifest作为人类意图与AI执行之间的桥梁

Manifest在AI-TDD中的角色，可以概括为一句话：契约即代码（Contract as Code）。

更准确地说，Manifest可以被当作人类意图的”源代码”，AI-TDD Gate承担类似”编译器和运行时”的角色，生成实现则是执行结果。

传统软件开发中的意图衰减

在传统软件开发中，需求从人类传递到实现，经历多次”翻译”，每次翻译都可能导致意图衰减：

人类意图（Product Manager）
    ↓ 翻译为自然语言
需求文档（PRD）
    ↓ 翻译为技术语言
技术方案（Architecture Doc）
    ↓ 翻译为代码
实现代码（Source Code）
    ↓ 翻译为机器指令
可执行程序（Binary）

每一步”翻译”都引入噪声：

PM的”高性能”被架构师理解为”使用缓存”
“使用缓存”被开发者理解为”加个Redis”
“加个Redis”被实现为”单节点Redis”而非”集群”
最终性能并不”高”

AI时代的意图衰减加剧

当AI成为实现主体时，问题更严重：

人类意图
    ↓ 自然语言Prompt
AI理解（概率模型推断）
    ↓ 生成代码
实现代码

AI的理解不是翻译，是推断——基于训练数据的概率推断。这个推断过程引入了额外的噪声层：

“高性能” → AI推断为”使用最熟悉的技术”
“安全” → AI推断为”常见的安全措施”
“可扩展” → AI推断为”微服务架构”（可能过度设计）

Manifest：消除翻译层，直接编码意图

AI-TDD的解决方案是消除中间翻译层，让人类意图直接成为机器可执行的契约：

人类意图（架构决策）
    ↓ 直接编码
Manifest契约（YAML）
    ↓ AI-TDD Gate解析执行
AI生成（在契约约束下）
    ↓ 验证
TDD-GREEN证据

关键差异：Manifest不是”描述”意图，而是”编码”意图。

契约即代码的三个层次

层次1：语法层——结构化编码

Manifest使用YAML语法，这不是偶然的。YAML的选择基于以下技术考量：

# 人类可读（Human-readable）
must:
  - id: MUST-REG-EMAIL-001  # 唯一标识符
    text: "用户可以通过邮箱注册"  # 人类意图
    validation: "email格式符合RFC 5322"  # 机器可验证的约束
    evidenceRefs: [EVD-REG-TEST-001]  # 显式依赖
    coveredByTraceRows: [TRACE-REG-001]  # 双向追溯

唯一标识符（ID）：每个需求都有全局唯一ID，可引用、可追踪
人类可读text：保留人类可理解的描述
机器可验证validation：精确的验证条件
显式依赖evidenceRefs：不隐式依赖，所有依赖显式声明
双向追溯coveredByTraceRows：建立需求↔验证的完整链路

层次2：语义层——可执行契约

Manifest不只是”文档”，它有明确的执行语义：

# 这些字段不是装饰，是可执行指令
traceRows:
  - id: TRACE-REG-001
    covers: [MUST-REG-EMAIL-001, MUST-REG-PASSWORD-001]  # ← 执行器检查：这些MUST是否已定义？
    evidenceRefs: [EVD-REG-TEST-001]       # ← 执行器检查：这些EVD是否提供？
    deliveryEvidenceCommandRefs: [CMD-REG-TEST-001]  # ← 执行器运行：执行这些命令
    acceptanceRefs: [ACC-REG-001]     # ← 执行器验证：这些测试是否通过？

AI-TDD Gate解析Manifest时：

静态验证：检查所有引用是否存在（MUST、EVD、CMD）
依赖解析：构建需求→证据→命令→测试的依赖图
执行调度：按照Trace顺序运行命令，收集证据
状态判定：根据证据判定TDD-RED或TDD-GREEN

层次3：元语义层——契约元编程

Manifest最强大的特性是自指性（Self-reference）——Manifest可以描述自身的完备性要求：

# Manifest描述"什么样的Manifest是完备的"
implementationConfirmation:
  status: user_confirmed

  must:
    - id: MUST-META-001
      text: Manifest必须包含所有MUST的Trace覆盖
      oracle: "每个MUST都有coveredByTraceRows"

    - id: MUST-META-002
      text: Manifest必须包含所有NEG（MUST NOT）边界声明
      oracle: "每个NEG都绑定EVD或FAIL路径；OUT OF SCOPE仅记录范围边界"

  closeoutReadinessPreview:
    requiredCommands: [CMD-VALIDATE-MANIFEST-001]
    # Manifest可以定义"如何验证自身"

这种自指性使得AI-TDD可以程序化地验证契约的结构完备性。业务语义是否完整仍需人工确认，但引用完整性、覆盖关系和证据绑定可以交给机器检查。

契约即代码 vs 代码即契约

有人可能会问：为什么不直接使用代码（测试代码）作为契约？这就是传统TDD的做法。

关键差异：

代码即契约（传统TDD）	契约即代码（AI-TDD）
契约是测试代码	契约是YAML Manifest
人类阅读测试推断需求	机器直接解析契约
需求隐含在测试中	需求显式声明
完备性无法自动检查	TRACE rows可自动验证
负向行为难以表达	OUT OF SCOPE原生支持
状态只有”通过/失败”	TDD-RED/GREEN显式状态

测试代码是”验证实现”的工具，Manifest是”编码意图”的工具。两者互补：Manifest定义”应该做什么”，测试验证”是否做到”。

Manifest作为意图的”单一事实源”（Single Source of Truth）

在AI-TDD中，Manifest应被维护为验收契约的主事实源：

Manifest中心化架构：所有参与者（人类、AI、门禁）都从同一个Manifest获取信息

参与者	如何使用Manifest	输出
人类	阅读HTML确认页	决策与确认
AI	解析YAML执行生成	实现代码
AI-TDD Gate	验证执行状态	门禁报告与证据

优势：可以显著减少”人类理解的需求”和”AI实现的代码”之间的版本漂移。所有参与者基于同一份契约工作，差异也更容易被追溯。

实践启示：编写Manifest即编程

把Manifest当作代码来编写：

版本控制：Manifest纳入Git管理，每次修改都有历史记录
代码审查：Manifest的修改需要Review，就像代码Review一样
自动化检查：CI/CD流水线自动验证Manifest的语法和语义
重构支持：需求变更时，Manifest的重构对应测试和实现的重构
文档即代码：Manifest是自文档化的，不需要额外的”需求文档”

关键洞察：

Manifest不是”更好的需求文档”，而是一种新型的编程语言——专门用于表达人类意图和机器契约的领域特定语言（DSL）。

学习AI-TDD不是学习如何”写更好的文档”，而是学习如何用契约的语言思考和编码。

第三章：AI-TDD与现有技术方案对比

3.1 从TDD到BDD再到AI-TDD——方法论的演进

传统TDD、BDD和AI-TDD代表了三个不同阶段的软件工程方法论演进。要理解AI-TDD的独特价值，需要先看清TDD和BDD在AI时代暴露的盲区——它们都假设”人类编写测试、人类编写实现”，而当AI成为实现主体时，这个假设被彻底打破。

TDD到BDD到AI-TDD演进 图1：这张图回答的问题是：TDD、BDD 与 AI-TDD 的抽象层是如何演进的。

传统TDD：测试驱动的开发

传统TDD的核心理念是”测试先行”（Test First）：先写测试，再写实现。这个模式在人工编码时代有效，但在AI生成时代面临根本挑战。

传统TDD隐含的三个假设：

测试编写者与实现者是同一个人——需求在开发者头脑中是一致的
测试代码可以表达完整需求——通过测试可以推断出正确行为
测试遗漏可以在代码审查中发现——人类可以识别缺失的测试场景

在AI时代，这三个假设全部失效：

测试编写者是人类，实现者是AI——两者的”需求理解”可能完全不同
AI看不到测试的全局图景——它只能看到孤立的测试用例，看不到需求之间的约束关系
AI生成的代码可能让现有测试通过，但遗漏关键场景——代码审查者难以发现AI的”隐式假设”

传统TDD vs AI-TDD对比：

维度	传统TDD	AI-TDD
需求载体	测试代码 + 开发者记忆	Manifest契约矩阵
完整性验证	依赖人工审查	机器自动检查（TRACE rows）
边界定义	隐含（不写测试=不做）	显式（OUT OF SCOPE必须声明）
负向约束	难以表达	原生支持（NEG / MUST NOT）
状态流转	无显式状态	TDD-RED→TDD-GREEN门禁驱动
执行主体	人类开发者	AI执行，人类确认
验收标准	测试通过	Manifest全部EVD验证

BDD/Gherkin：行为驱动的开发

BDD（Behavior-Driven Development）通过自然语言描述行为，试图弥合业务人员与开发者之间的鸿沟：

Feature: 用户注册
  Scenario: 有效注册
    Given 用户输入有效邮箱和密码
    When 提交注册请求
    Then 返回201 Created
    And 密码必须加密存储

BDD的核心假设与AI时代的现实：

BDD隐含三个假设：

自然语言足够清晰——业务人员、开发者、测试人员能理解同一套描述
Step Definitions是准确映射——自然语言可以准确地转换为代码实现
人类是执行主体——开发者根据BDD描述手工实现功能

在AI时代，这三个假设面临挑战：

挑战1：自然语言的歧义性被AI放大

BDD的Given/When/Then对人类来说足够清晰，但对AI来说充满歧义：

# 对人类清晰，对AI模糊
Then 密码必须加密存储

AI可能理解为：

在响应中返回加密后的密码（错误）
在数据库中存储bcrypt哈希（正确，但哈希强度？）
使用AES加密后存储（错误，可逆加密）
使用SHA256（错误，不适合密码）

挑战2：BDD的追溯能力是单向的

BDD的追溯链：Scenario → Step Definitions → 代码实现。这是一个单向映射，缺少反向验证能力：

代码审查者可以问：“这个函数对应哪个Scenario？“——需要人工查找
AI无法实现：“给定代码实现，自动检查是否满足所有Scenario”
没有全局契约矩阵来验证”所有需求是否都被覆盖”

挑战3：BDD无法表达负向契约

BDD擅长表达”应该发生什么”，但不擅长表达”禁止发生什么”：

# 别扭的负向表达
Scenario: 不应该明文存储密码
  Given 用户注册成功
  Then 数据库中不应该存在明文密码

# 更别扭的边界排除
Scenario: 不包含社交登录
  Given 这是标准注册流程
  Then 不应该出现OAuth选项

这些”否定式”Scenario在BDD中是反模式的——BDD鼓励正向描述行为，而不是负向声明约束。

BDD/Gherkin vs AI-TDD Gate Manifest对比：

维度	BDD/Gherkin	AI-TDD Gate Manifest
格式	自然语言 (Given/When/Then)	结构化YAML（机器可读）
抽象层级	行为描述（Behavior）	需求契约矩阵（Contract Matrix）
完整性验证	依赖人工审查Scenario覆盖	机器自动检查（TRACE rows）
追溯能力	弱（Scenario→Step Definitions）	强（五维追溯矩阵）
状态管理	无内置状态机	TDD-RED/TDD-GREEN显式状态流转
门禁控制	无	Implementation Readiness Gate + Delivery Closeout Gate
证据要求	测试通过即可	必须关联EVD、ART、CMD
负向约束	难以表达（Given not… awkward）	原生支持（NEG / MUST NOT + OUT OF SCOPE）
执行约束	松散（Step可遗漏）	严格（Trace必须覆盖所有MUST/NEG）

关键差异详解：

1. 机器可读性 vs 人类可读性

BDD优先考虑人类可读性：

# 人类友好，机器难以精确解析
Then 密码必须加密存储且符合安全规范

AI-TDD优先保证机器可读性：

# 机器可读，语义精确
must:
  - id: MUST-REG-PASSWORD-001
    text: password必须加密存储
    validation: "数据库中存储的是bcrypt哈希，不是明文，cost factor >= 12"
    evidenceRefs: [EVD-SEC-PASSWORD-001]

当AI成为实现主体时，机器可读性优先——AI需要精确的约束，而不是需要人类解读的描述。

2. 契约完整性机制

BDD没有”契约是否完备”的检查机制：

你可以写100个Scenario，仍然可能遗漏关键的负向约束
没有机器可以问：“哪些需求还没有Scenario覆盖？”

AI-TDD的TRACE rows强制要求双向追溯：

must:
  - id: MUST-REG-EMAIL-001
    text: 接受有效email和password
    evidenceRefs: [EVD-REG-TEST-001]
    coveredByTraceRows: [TRACE-REG-001]  # 必须有Trace覆盖

traceRows:
  - id: TRACE-REG-001
    covers: [MUST-REG-EMAIL-001]  # 反向声明覆盖
    evidenceRefs: [EVD-REG-TEST-001]
    deliveryEvidenceCommandRefs: [CMD-REG-TEST-001]
    acceptanceRefs: [ACC-REG-001]

门禁可以自动验证：“MUST-REG-EMAIL-001是否有Trace覆盖？TRACE-REG-001是否有EVD支持？”

3. 负向行为的一等公民地位

BDD中负向行为只能别扭地表达。AI-TDD中负向行为是契约的核心：

mustNot:
  - id: NEG-SEC-PLAIN-PASSWORD-001
    text: 禁止存储明文password
    evidenceRefs: [EVD-SEC-PASSWORD-001]
    oracle: negative control oracle

outOfScope:
  - id: OUT-SEC-STRESS-001
    text: SQL注入专项压测不在本轮交付范围
    reason: 移至安全专项任务

edgeCases:
  - id: EDGE-REG-CONCURRENCY-001
    category: explicit_error_case_mapping
    condition: 并发注册时出现重复邮箱
    expectedBehavior: Fail closed
    forbiddenBehavior: 静默覆盖已有账户

为什么AI时代必须显式定义负向行为？

因为AI会”创造性”地填补需求空白。如果你不明确说”禁止明文存储”，AI可能选择实现最简单的方式（明文存储）来让功能”快速工作”。负向契约是防止AI过度自由的边界围栏。

4. TDD-RED/GREEN状态机

BDD没有状态概念——Scenario要么通过，要么失败。AI-TDD有显式的状态流转：

acceptanceTests:
  - id: ACC-REG-001
    file: tests/acceptance/user-registration.test.ts
    covers: [MUST-REG-EMAIL-001]
    expectedPreImplementationState: expected_red  # 准入门禁期望TDD-RED
    commandRefs: [CMD-REG-TEST-001]

TDD-RED状态的价值：在实施准备阶段，与本次新增或关联验收项对应的测试应先失败。这说明：

测试确实在执行（不是假测试）
实现确实缺失（不是预实现）
Manifest确实被用于验证

BDD无法区分”测试还没写”和”测试写了但实现缺失”——这两种情况在BDD中都是”失败”，但在AI-TDD中是根本不同的状态。

5. 证据链完整性

BDD的”通过”是二元的：测试通过=完成。AI-TDD的”通过”是多层证据链：

五维证据链结构（核心五层）：

层级	元素	作用
L1	MUST (需求)	业务承诺
L2	TRACE (执行切片)	执行追踪
L3	EVD (证据定义)	验证标准
L4	CMD (验证命令)	可复现执行
L5	ART (交付物)	物理产出

完整的证据链还包括：ACC（自动化验证）、EXIT CODE（客观结果）、AUDIT RECEIPT（审计追溯）。

每一条链路都可以独立审计和验证。BDD的Scenario通过可能被过度mock/stub削弱可信度；AI-TDD的证据链通过命令、产物和审计记录提高了伪造成本，但仍然需要审计约束。

AI-TDD：契约驱动的开发

传统TDD和BDD都是”描述驱动”——描述应该发生什么，然后期望实现符合描述。AI-TDD是”契约驱动”——在执行前定义完备的契约矩阵，然后强制实现满足契约。

三种方法的演进关系：

年代	方法论	核心特征	抽象层提升
2000s	传统TDD	测试先行，先红后绿	基础层
2010s	BDD	自然语言描述行为，业务参与	抽象层提升
2020s	AI-TDD	结构化契约定义需求，AI执行	抽象层再提升 + 机器可读约束

演进路径：传统TDD（测试驱动）→ BDD（行为驱动）→ AI-TDD（契约驱动）

AI-TDD解决的核心问题：

解决”测试覆盖≠需求覆盖”问题
- BDD：100个Scenario通过，仍然可能遗漏关键约束
- AI-TDD：TRACE rows强制要求每个MUST/NEG都有覆盖，门禁自动检查
解决”AI理解偏差”问题
- BDD：自然语言的歧义被AI放大
- AI-TDD：机器可读的YAML消除歧义，validation字段精确约束
解决”负向行为难以表达”问题
- BDD：“不应该”只能别扭地表达
- AI-TDD：NEG / MUST NOT 与 OUT OF SCOPE 都是一等公民，有专门验证策略
解决”证据链不完整”问题
- BDD：测试通过即完成
- AI-TDD：五维追溯矩阵，每层都可审计
解决”状态管理缺失”问题
- BDD：无状态概念
- AI-TDD：TDD-RED→TDD-GREEN显式状态流转，双门禁控制

迁移建议：

如果你已有TDD或BDD实践，迁移到AI-TDD的路径：

保留现有测试/Scenario作为人类沟通工具——但不要把它当成契约
在之上增加AI-TDD Manifest——用YAML定义机器可读的契约
从测试/Scenario提取MUST/NEG——问自己：“这对应哪个MUST？遗漏了哪些NEG？”
补充缺失的OUT OF SCOPE——明确声明本迭代不包含的功能
添加Trace覆盖——确保每个需求都有对应的验收测试和证据

关键洞察：

传统TDD的测试代码是验证工具
BDD的Scenario是沟通工具
AI-TDD的Manifest是本文定义的契约载体
三者可以共存：Scenario用于人类沟通，测试用于验证，Manifest用于机器执行

3.2 迁移示例：从TDD到AI-TDD的推荐流程

如果你已有TDD实践，建议按以下步骤迁移到AI-TDD：

阶段一：并轨运行

保留现有TDD测试，继续运行
选择1个新功能，尝试编写AI-TDD Manifest
对比两种方法的差异：“测试代码”vs”契约矩阵”

阶段二：发现问题

关注现有测试覆盖不到的负向场景
记录AI生成代码中出现的”需求漂移”案例
识别哪些NEG（MUST NOT）应该在Manifest中显式定义

阶段三：逐步切换

新功能优先使用AI-TDD
遗留功能在重构时补充Manifest
建立团队内部的Manifest模板和最佳实践

迁移中的常见陷阱：

❌ 陷阱1：一次性重写所有测试 → ✅ 应该并轨运行，逐步切换
❌ 陷阱2：删除现有测试 → ✅ 保留TDD测试作为回归测试
❌ 陷阱3：Manifest写得太细 → ✅ 聚焦边界定义，而非实现细节

第四章：AI-TDD Gate Manifest详解

4.0 Manifest Schema规范（v1.0）

在查看具体示例前，需要明确Manifest的Schema规范：

字段命名规范：

使用camelCase（如mustNot、outOfScope、traceRows）
顶级容器：manifest → acceptanceCriteria
核心维度：must、mustNot（承载NEG-*）、outOfScope（承载OUT-*）、evidence（承载EVD-*）、traceRows（承载TRACE-*）
状态字段：gateStatus → implementationReadiness / closeout

版本说明：

version: "1.0.0" 遵循SemVer规范
Major：需求范围变更（MUST/OUT OF SCOPE增删）
Minor：验证条件细化（validation修改）
Patch：文本描述优化

4.1 Manifest的核心结构

Manifest结构解析 图2：这张图回答的问题是：Manifest 的核心结构由哪些契约层组成。

文件：ai-tdd-manifest.yaml

manifest:
  version: "1.0.0"
  project: "user-service"
  requirementId: "REQ-001"
  title: "User Registration"

  # 需求契约矩阵
  acceptanceCriteria:
    # MUST：必须满足的条件
    must:
      - id: "MUST-REQ-001"
        description: "接受有效的email和password"
        validation: "email格式符合RFC 5322，password长度8-32字符"
        test: "test_valid_registration"
        priority: "P0"

      - id: "MUST-REQ-002"
        description: "拒绝已存在的email"
        validation: "查询数据库，重复email返回409 Conflict"
        test: "test_duplicate_email"
        priority: "P0"

      - id: "MUST-REQ-003"
        description: "password必须加密存储"
        validation: "数据库中存储的是bcrypt哈希，不是明文"
        test: "test_password_hashing"
        priority: "P0"

    # NEG / MUST NOT：会阻断完成的负向断言
    mustNot:
      - id: "NEG-SEC-001"
        description: "禁止存储明文password"
        validation: "数据库字段中不包含明文password"
        test: "test_no_plaintext_storage"

      - id: "NEG-SEC-002"
        description: "禁止SQL注入"
        validation: "所有数据库操作使用参数化查询"
        test: "test_sql_injection_prevention"

    # OUT OF SCOPE：当前迭代的范围边界，不是完成阻塞项
    outOfScope:
      - id: "OUT-AUTH-001"
        description: "社交登录（OAuth）"
        reason: "本迭代不包含，移至REQ-010"

      - id: "OUT-PHONE-001"
        description: "手机验证码注册"
        reason: "本迭代不包含，移至REQ-011"

NEG vs OUT OF SCOPE 语义区分指南：

mustNot / NEG（禁止）：

场景1：安全/合规层面的绝对禁止（即使未来迭代也不允许）

场景2：技术约束导致的禁止（如”禁止使用明文存储密码”）

特征：有validation条件，可以被”违反”；违反时会阻断完成

outOfScope / OUT（范围边界）：

场景：功能层面的明确排除（当前迭代不实现，但未来可能）

特征：有reason说明和后续计划（移至REQ-XXX）

注意：OUT-* 是范围边界，不是完成阻塞项；它不应出现在 covers 中

简单判断：如果这个功能”以后可能会做”→用outOfScope；如果”永远不应该做”→用mustNot。

同一个Manifest还需要把证据、追溯矩阵和门禁状态显式写入：

manifest:
  acceptanceCriteria:
    # EVD：需要提供证据的断言
    evidence:
      - id: "EVD-TEST-001"
        type: "test_coverage"
        description: "代码覆盖率>=80%"
        threshold: "80%"
        artifact: "coverage_report.html"

      - id: "EVD-SEC-001"
        type: "security_scan"
        description: "无高危安全漏洞"
        tool: "bandit"
        artifact: "security_scan_report.json"

      - id: "EVD-PERF-001"
        type: "performance_test"
        description: "注册接口响应时间<200ms（P99）"
        threshold: "200ms"
        artifact: "perf_test_report.html"

  # TRACE rows：需求、任务、证据、命令、验收和产物的可执行切片
  traceRows:
    - id: "TRACE-REG-001"
      covers: ["MUST-REQ-001", "NEG-SEC-001"]
      taskRefs: ["TASK-REG-001"]
      evidenceRefs: ["EVD-TEST-001", "EVD-SEC-001"]
      contractValidationCommandRefs: ["CMD-REG-TEST-001"]
      acceptanceRefs: ["ACC-REG-001", "E2E-REG-001"]
      artifactRefs: ["ART-REG-REPORT-001"]
      status: "pending"

  # 失败路径：NEG 对应的必须失败场景
  failurePaths:
    - id: "FAIL-SEC-001"
      covers: ["NEG-SEC-001"]
      expectedFailure: "明文password写入尝试被测试拦截"
      evidenceRefs: ["EVD-SEC-001"]

  # 边界条件：实现需要覆盖但不新增业务范围
  edgeCases:
    - id: "EDGE-REG-001"
      covers: ["MUST-REQ-001"]
      case: "email大小写归一化后仍保持唯一性"
      evidenceRefs: ["EVD-TEST-001"]

  tasks:
    - id: "TASK-REG-001"
      description: "实现邮箱注册主路径和负向安全约束"

  # 端到端测试套件
  e2eTestSuites:
    - name: "user_registration_flow"
      path: "tests/e2e/user_registration.test.js"
      scenarios: ["happy_path", "duplicate_email", "invalid_input"]

  # 验收测试套件
  accTestSuites:
    - name: "user_registration_acc"
      path: "tests/acc/user_registration.test.py"
      criteria: "all_pass"

  # 门禁状态
  gateStatus:
    implementationReadiness:
      status: "TDD-RED"
      lastRun: "2026-05-27T10:00:00Z"
      summary:
        total: 15
        passed: 0
        failed: 15
        pending: 0

    closeout:
      status: "TDD-GREEN"
      closeoutAttemptId: "closeout-20260527-160000"
      lastRun: "2026-05-27T16:00:00Z"
      summary:
        total: 15
        passed: 15
        failed: 0
        pending: 0

  deliveryEvidence:
    closeoutAttemptId: "closeout-20260527-160000"
    manifestHash: "sha256:..."
    sourceSnapshotHash: "sha256:..."
    commandRunRefs: ["RUN-REG-TEST-001", "RUN-SEC-SCAN-001"]
    artifactRefs:
      - id: "ART-REG-REPORT-001"
        sha256: "sha256:..."

  gateVerdict:
    status: "pass"
    evaluatedAt: "2026-05-27T16:02:00Z"
    receiptArtifactRef: "ART-CLOSEOUT-REPORT-001"

  humanDecision:
    decision: "accept"
    actor: "tech-lead"
    decidedAt: "2026-05-27T16:05:00Z"
    receiptArtifactRef: "ART-HUMAN-DECISION-001"

五维追溯矩阵 图3：这张图回答的问题是：需求、执行、证据、命令和产物如何形成追溯链。

4.2 Manifest的生成过程

Manifest不是一次性写成的，而是通过原子化拆解迭代生成的。

迭代一：需求初稿 人类提供：“实现用户注册功能” AI生成：Manifest初稿（包含基本MUST项）人类审核：确认/修改/补充

迭代二：边界明确 人类补充：“需要邮箱验证、密码强度检查” AI更新：增加MUST项，生成OUT OF SCOPE列表人类审核：确认排除项

迭代三：证据定义 人类补充：“需要80%代码覆盖率” AI更新：增加EVD项人类审核：确认阈值

迭代四：追溯建立 AI生成：TRACE rows初稿人类审核：确认需求↔测试↔证据的映射关系

迭代五：最终确认 人类阅读：需求确认页HTML 人类决策：确认Manifest完整，进入下一阶段

关键原则：

Manifest必须在执行开始前就达到”完备”状态
“完备”的定义：MUST/NEG/OUT/EVD/TRACE rows全部定义，无遗漏
不完备的Manifest不允许通过Implementation Readiness Gate

4.3 Manifest的机器可读性

Manifest必须是机器可读的，这意味着：

1. 结构化格式

使用YAML或JSON
有严格的Schema定义
可以被程序解析和验证

2. 明确的字段语义

每个字段都有明确的类型和约束
支持自动化校验（如JSON Schema验证）

3. 可执行的引用

MUST项关联到具体的测试文件路径
EVD项关联到具体的验证工具
TRACE rows可以自动检查覆盖率

4. 状态可查询

可以程序查询”哪些MUST项还未验证”
可以程序查询”TRACE rows覆盖率”
可以程序判定”是否可以准入”或”是否可以交付”

第五章：AI-TDD的六大心智模型

图4：AI-TDD六大心智模型与门禁流转，展示两个门禁及其期望状态：准入门禁对应 AI-TDD-RED，交付门禁对应 AI-TDD-GREEN。

六大心智模型是AI-TDD的认知抽象层，描述用户在人机协作过程中的六个核心认知模式。

5.1 需求确认（Requirement Confirmation）

这是”问题边界先于解决方案”原则的第一个落地环节。需求确认的唯一目标，就是清晰地定义问题的业务边界。

认知核心：从模糊意图到机器可读契约的转化

核心思想：通过原子化拆解迭代，在需求确认阶段生成完备的AI-TDD Gate Manifest，建立需求契约矩阵。

关键洞察：

AI可以辅助生成Manifest，但需求的最终定义权在人类
Manifest应在执行开始前达到足够完备的状态，否则执行阶段更容易出现遗漏或漂移
Manifest不是自然语言文档，而是机器可读的结构化契约

关键动作：

原子化需求拆解

将”实现用户注册功能”拆解为：
- MUST-REG-INPUT-001: 接受email和password输入
- MUST-REG-EMAIL-FORMAT-001: 验证email格式合法
- MUST-REG-PASSWORD-LENGTH-001: 验证password长度≥8
- MUST-REG-UNIQUE-001: 拒绝已存在的email
- MUST-REG-PASSWORD-HASH-001: password必须加密存储
- NEG-SEC-PLAIN-PASSWORD-001: 禁止存储明文password
- NEG-SEC-SQL-INJECTION-001: 禁止SQL注入
- OUT-AUTH-SOCIAL-001: 社交登录（移至REQ-010）
- OUT-PHONE-VERIFY-001: 手机验证码（移至REQ-011）
定义EVD（可验证证据）
- EVD-TEST-COV-001: 代码覆盖率>=80%
- EVD-SEC-SCAN-001: 无高危安全漏洞
- EVD-PERF-REG-001: 注册接口响应时间<200ms（P99）
建立TRACE rows（追溯矩阵）

建立需求↔测试↔证据的完整追溯链，确保每个MUST项都有测试覆盖和证据支撑。
生成需求确认页（HTML）

生成人类阅读友好的需求确认页，包含：
- 业务目标与背景
- 完整的Manifest预览
- MUST/NEG/OUT清单
- EVD要求
- TRACE rows覆盖率
人工确认与决策

⚠️ Human-in-the-loop关键环节：
- 人类阅读需求确认页HTML
- 检查Manifest的完备性
- 做出决策：“Manifest已完备，可以进入下一阶段”

准出标准：

Manifest已完备生成（MUST/NEG/OUT/EVD/TRACE rows全部定义）
需求确认页HTML已生成
人类决策通过

5.2 架构确认（Architecture Confirmation）

在业务边界清晰的基础上，进一步定义技术边界。明确技术方案与接口契约，划定系统与外部世界的边界。

认知核心：从问题空间到解空间的映射

核心思想：在Manifest约束下，定义技术方案与接口契约，并生成架构确认页实现Human-in-the-loop决策。

关键洞察：

Manifest定义了”做什么”，架构确认定义”怎么做”
AI可以提供多个架构方案，但架构决策权在人类

关键动作：

技术方案评估
- AI提供2-3个备选架构方案
- 对比优缺点、风险、资源需求
定义接口契约
- API接口定义（OpenAPI/Swagger）
- 数据模型定义（JSON Schema）
- 错误码约定
生成架构确认页（HTML）

⚠️ Human-in-the-loop关键环节：
- 推荐的架构方案及理由
- 备选方案对比
- 风险评估
- 接口契约预览
人工确认与决策

技术决策者阅读架构确认页HTML，做出采用哪个方案的决策。

准出标准：技术方案已确认 + 架构确认页HTML已生成 + 人类决策通过 + 接口契约已定义

5.3 实施准备（Implementation Readiness）

验证边界是否可被测试覆盖。基于已定义的边界（Manifest）生成足够覆盖当前范围的验收测试基线，确认边界是可验证的。

认知核心：从契约定义到执行就绪的状态转换

核心思想：基于完备的Manifest生成验收测试基线，运行AI-TDD Gate，确立TDD-RED准入状态。

关键洞察：

测试不是”边写边生成”，而是基于Manifest一次性完备生成
TDD-RED状态（全红）是准入的必要条件

关键动作：

基于Manifest生成测试代码

不是人工写测试，而是AI-TDD Gate自动解析Manifest，生成：
- 单元测试（覆盖MUST项）
- 集成测试（覆盖接口契约）
- E2E测试（覆盖端到端场景）
- 验收测试（覆盖ACC项）
注册测试到AI-TDD Gate

所有测试必须在AI-TDD Gate中注册，与Manifest的TRACE rows建立关联。
运行AI-TDD Gate（准入运行）

首次运行AI-TDD Gate，此时：
- 测试代码已生成
- 实现代码尚未生成
- 新增或关联的验收测试应处于预期失败状态（TDD-RED）
确认TDD-RED状态

检查点：
- Manifest完整性检查 ✓
- 测试注册完整性检查 ✓
- TDD-RED状态确认 ✓

准出标准：AI-TDD Gate状态为TDD-RED（全红）

概念澄清：此处的TDD-RED是指”实施准备阶段首次运行AI-TDD Gate，验证测试基线已完备生成且实现尚未开始”的状态。这是进入下一阶段（执行闭合）的前提条件，而非最终交付标准。

脱敏示例：Stale Attempt检测机制

以下片段来自一个脱敏后的closeout runner需求契约，用于说明如何防止复用历史成功记录：

- id: FAIL-RUNNER-STALE-ATTEMPT-001
  title: stale_attempt_reused
  trigger: >-
    deliveryEvidence.requiredCommands[].lastRunRef.closeoutAttemptId
    与当前 attempt 不一致
  expectedBehaviorZh: >-
    AI TDD closeout 必须报告 stale_attempt 或
    current_attempt_command_missing
  forbiddenBehaviorZh: 历史成功满足当前 closeout

这个失效路径定义了一个关键防护：每次 closeout attempt 都有唯一 ID，历史成功不能证明当前迭代。 这防止了”用旧测试报告蒙混过关”的常见问题——即使之前的测试全部通过，只要当前 attempt 的证据链不完整，就必须重新验证。

5.4 执行闭合（Bounded Packet Closure）

AI在边界约束下生成实现。偏离边界定义的实现，需要被门禁或审计拦截，而不是被默认为可交付。

认知核心：在Manifest约束下有界收敛

核心思想：AI在Manifest约束下生成实现，迭代到注册验证通过并形成 closeout candidate，避免实现漂移。

关键洞察：

AI的生成应受Manifest约束，不能自由发挥
迭代的目标是”让Manifest中定义的验收项逐步收敛到通过状态”

关键动作：

将Manifest作为Prompt上下文

给AI的Prompt包含：
- Manifest全文
- 当前失败的测试列表
- 失败原因
AI生成实现

AI基于Manifest理解需求的全局图景，生成实现代码。
运行AI-TDD Gate（迭代运行）

运行全量测试，获取当前状态（TDD-RED或部分GREEN）。
迭代修正

如果有测试失败：
- 将失败信息反馈给AI
- AI重新生成修正代码
- 再次运行AI-TDD Gate
- 直至注册验证全部通过，形成 closeout candidate

准出标准：候选实现满足Manifest关联测试，进入 closeout candidate；最终 AI-TDD-GREEN 仍需在交付确认阶段完成证据链、Gate Verdict和Human Decision闭合

脱敏示例：Fail-Fast执行策略与证据原子性

以下片段来自同一类脱敏需求契约，展示AI-TDD如何处理命令执行失败：

- id: MUST-RUNNER-FAILFAST-001
  text: >-
    动态 runner 应把成功的 required commands 记录为当前 attempt 的
    artifact-bound deliveryEvidence.requiredCommands[]；任一 required command
    首次失败时，应立即停止剩余 required commands，在返回前写出 failed
    evidence packet，并返回非零。
  evidenceRefs:
    - EVD-RUNNER-SUCCESS-001
    - EVD-RUNNER-FAILURE-001
  coveredByTraceRows:
    - TRACE-RUNNER-FAILFAST-001

注意其中的关键设计：

coveredByTraceRows: 每个MUST应被至少一个trace覆盖
evidenceRefs: 每个trace应产生可验证的证据
Fail-Fast: 首个命令失败立即停止，防止”部分成功”的虚假状态
Artifact-Bound: 证据必须与产物绑定（文件哈希），不能仅靠exit code

这与传统”先写代码再补测试”的逆向流程形成鲜明对比——在AI-TDD中，需求和证据先于实现定义，实现必须向预定义的验证标准收敛。

5.5 审计复核（Audit Review）

验证实现是否严格遵循边界定义。多Agent批判审计，避免执行体自检的快速自洽，确保边界在执行中未被漂移。

认知核心：多Agent批判审计，避免执行体自检的快速自洽

核心思想：引入独立的审计Agent，对执行结果进行批判性审查，避免单一执行Agent的认知盲区。

关键洞察：

执行Agent在迭代过程中容易陷入”快速自洽”
审计Agent与执行Agent独立，提供批判视角

关键动作：

多Agent交叉审计
- 审计Agent独立审查执行结果
- 检查Manifest中定义的NEG（MUST NOT）项是否真正未违反
- 检查架构一致性
Findings记录与RCA
- 记录审计发现的问题（Findings）
- 进行根因分析（RCA）
评分与改进建议
- 对执行质量评分
- 生成改进建议

准出标准：审计Agent无阻塞性Findings，或所有Findings已修正并通过复验

脱敏示例：负向验证与”什么必须失败”

AI-TDD不仅定义”应该做什么”（MUST），更要定义**“什么情况下必须失败”**（NEG + FAILURE PATH）。以下片段展示了这一核心思想：

# 负向断言：定义什么不足以构成完成证明
- id: NEG-EVD-EXITCODE-001
  text: 仅 exit code 的证明不得满足 deliveryEvidence.requiredCommands[] 或 closeout
  whyItBlocksCompletionZh: >-
    缺少 artifact-bound proof 的成功进程不是当前 attempt 交付证据

# 对应的失效路径：定义具体触发条件和预期行为
- id: FAIL-RUNNER-CMD-001
  title: required_command_failed
  trigger: 某个 required command 返回非零
  expectedBehaviorZh: >-
    Runner 必须立即停止剩余 required-command 执行，在返回前为失败命令写出
    不走成功 implementation evidence ingest 路径的 failed evidence packet
  forbiddenBehaviorZh: >-
    Runner 继续执行剩余 required commands、遗漏 failed evidence packet、
    通过 implementation_evidence_ingested 提交 failed packet

这个设计的深刻之处在于：它不仅验证”成功”，更严格定义”失败”。

在传统开发中，我们常说”测试通过了”。但在AI-TDD中，必须追问：“什么情况下测试即使通过也不算数？”

只有exit code？不算数
没有产物绑定？不算数
历史运行的结果？不算数
当前attempt不匹配？不算数

审计复核的本质，就是验证”什么必须失败”的边界是否被严格执行。

5.6 交付确认（Delivery Closeout）

最终验证边界是否被完整实现。全量回归测试确认边界内的所有需求都已达成，无漂移。

认知核心：全量回归验证与正式收口

核心思想：重新运行AI-TDD Gate全量测试，确认执行过程中无漂移，生成交付确认页，正式完成交付确认。

关键洞察：

交付确认不是简单的”打包输出”，而是全量回归验证
必须重新运行Manifest中注册的所有验收测试

关键动作：

重新运行AI-TDD Gate全量测试

⚠️ 关键区别：
- Implementation Readiness Gate：首次运行，预期TDD-RED
- Delivery Closeout Gate：再次运行，期望达到TDD-GREEN
确保：
- 执行闭合阶段通过的测试仍然通过（无回归）
- Manifest中所有验收项状态为”VERIFIED”
生成交付确认页（HTML）

生成人类阅读友好的交付确认页，包含：
- Manifest完整状态（全部VERIFIED）
- 测试结果汇总（全绿）
- 代码质量指标
- 审计记录与Findings
人工最终审核

人类阅读交付确认页HTML，进行最终把关。
正式完成交付确认

人工决策记录为accept后，标记任务正式完成，归档所有项目资产。

准出标准：当前attempt的证据链闭合 + Gate Verdict为pass + Human Decision记录为accept + 交付确认页生成

脱敏示例：Gate裁决、Oracle和Artifact的Hash链校验

以下片段展示了AI-TDD交付确认的核心验证结构：

# 证据定义：什么构成"可交付"
- id: EVD-CLOSEOUT-GATE-001
  text: 只有更新后的 record 通过团队自定义 closeout gate 后才允许 closeout pass
  gate: vitest
  oracle: Runner returns 0 only when closeout report decision=pass and closeoutReadinessReport.ready=true
  requiredCommandRefs:
    - CMD-TEST-CLOSEOUT-GATES
  artifactRefs:
    - ART-AI-TDD-CLOSEOUT-REPORT

配合文档顶部的三重Hash校验机制：

# 源文档Hash：确保需求未被篡改
sourceDocumentHash: sha256:51f17f2172e951599153bbb744877386cd582f33e393bc597c6ea926e143a878

# 实现确认Hash：确保范围已被确认
implementationConfirmationHash: sha256:c1ca24b3b7bc63cfc5d8eee55b72e510cdbcb03c8cb4ceee9bc3806b15c537d3

# 确认页面Hash：确保渲染结果一致
confirmationPageHash: sha256:f00fbd4f6610bdf5ef0f87dbd9cfe0f1b69ecb2777e70d1a57021e2f1f75dd0f

Hash计算说明（避免循环依赖）：

sourceDocumentHash的计算方法：

对ai-tdd-manifest.yaml文件内容做SHA256

注意：计算时将此字段值设为空字符串或占位符，避免循环依赖

存储位置：建议存储在独立的.manifest.lock文件或Git标签中

implementationConfirmationHash的计算方法：

对需求确认阶段生成的HTML确认页做SHA256

用途：验证确认页未被篡改

confirmationPageHash的计算方法：

对交付确认页做SHA256

用途：验证最终交付物完整性

这个设计的精髓在于裁决链（Evidence → Gate → Oracle → Artifact）：

Gate（门禁）：团队自定义 closeout gate 是最终裁决者。示例中的 gate 名称是项目内伪代码，不代表公开CLI已经提供同名命令
Oracle（预言机）：decision=pass && ready=true 是明确的通过标准
Artifact（产物）：ART-AI-TDD-CLOSEOUT-REPORT 是可审计的证据文件

Hash链的意义：

如果源文档变更 → sourceDocumentHash 改变 → 必须重新确认
如果实现范围变更 → implementationConfirmationHash 改变 → 必须重新验证
如果渲染结果被篡改 → confirmationPageHash 改变 → 必须重新生成

交付确认的本质，是验证整个证据链的完整性和一致性。

第六章：两大关键门禁

本章与第五章的对应关系：第五章介绍的”六大认知阶段”中，阶段3（实施准备）的末端对应本章6.1节的”Implementation Readiness Gate（准入门禁）“；阶段6（交付确认）的末端对应本章6.2节的”Delivery Closeout Gate（交付门禁）“。两大门禁是六个认知阶段中的两个关键控制点，确保状态转换的可控性。

6.1 门禁一：Implementation Readiness Gate（准入门禁）

图5：AI-TDD状态机，展示从MANIFEST_DRAFT → AI-TDD-RED → IMPLEMENTING → CLOSEOUT_CANDIDATE → AI-TDD-GREEN → CLOSED的状态流转。

位置：位于”实施准备”之后，“执行闭合”之前

核心作用：确保”Manifest已完备，测试基线已建立”后才允许AI开始生成实现

准入标准：

需求确认已完成（Manifest已完备生成）
架构确认已完成（技术方案和接口契约已定义）
实施准备已完成（基于Manifest的测试代码已生成）

准出标准：新增或关联的验收测试应进入预期 TDD-RED状态

TDD-RED的精确定义：

必要条件：

基于Manifest生成的测试代码已注册到AI-TDD Gate

实现代码尚未生成或为空（不存在预实现）

新增或关联的验收测试返回预期失败（非通过）

排除条件（以下情况不算TDD-RED）：

测试失败原因是测试代码本身的错误 → 应视为BLOCKED状态，需修复测试

测试失败原因是环境配置问题 → 应视为ERROR状态，需修复环境

测试失败原因是外部依赖不可用 → 应视为DEFERRED状态，需等待依赖

关键原则：TDD-RED是”预期的失败”，而非”错误的失败”。

Manifest完备性检查
- 所有MUST项已定义，且关联到测试
- 所有NEG（MUST NOT）项已定义
- 所有OUT OF SCOPE项已明确排除
- 所有EVD项已定义阈值
- TRACE rows已建立，并覆盖本次Manifest声明的验收项
AI-TDD Gate注册检查
- 所有验收项已注册到AI-TDD Gate
- E2E TEST SUITES已注册
- ACC TEST SUITES已注册
TDD-RED状态确认
- 运行AI-TDD Gate全量测试
- 新增或关联的验收测试应处于预期失败状态（TDD-RED）
- 如新增验收测试已经通过，需要确认是否存在预实现、测试无效或验收项重复

门禁状态：

🔴 TDD-RED：预期状态，允许进入执行闭合
🔴 BLOCKED：Manifest不完备，禁止进入

失败处理：

Manifest不完备 → 退回需求确认重新迭代
存在预实现 → 清理预实现代码

6.2 门禁二：Delivery Closeout Gate（交付门禁）

位置：位于”审计复核”之后，正式交付之前

核心作用：确保”Manifest中所有契约切片已由当前attempt的证据链证明，无漂移、无越界、无陈旧证据复用”后才允许正式交付

准入标准：

执行闭合已完成（候选实现已满足Manifest关联测试）
审计复核已完成（无阻塞性Findings）
交付准备已完成（交付确认页、命令输出、证据产物和hash快照已准备）
本次closeout evaluation已生成唯一 closeoutAttemptId
Manifest/source hash、implementation snapshot hash、required command run refs 和 artifact refs 已写入候选交付记录

准出标准：Manifest关联的所有 TRACE 都达到证据链闭合状态，范围审计覆盖所有 OUT，且 Gate Verdict 为 pass、Human Decision 为 accept 后，Gate 才能给出 AI-TDD-GREEN

核心检查点：

Manifest验收状态检查
- 所有MUST项状态为”VERIFIED”
- 所有NEG（MUST NOT）项已验证不违反
- 所有OUT OF SCOPE项已通过范围审计，确认实现没有越界
- 所有TRACE rows覆盖本次Manifest声明的MUST/NEG，范围审计覆盖OUT
多维证据链检查
- 每个TRACE都有对应EVD
- 每个EVD都有本次attempt运行过的CMD
- 每个CMD都有可审计ART，例如测试报告、安全扫描报告、范围diff、closeout report
- 关键ART的hash与交付确认页记录一致
注册验证重跑检查（必要但不充分）
- 重新运行Manifest中注册的所有验收测试
- Manifest关联的验收测试必须通过，作为证据链输入之一
- 如有任何测试失败，禁止交付
- 测试通过本身不能产生 AI-TDD-GREEN；还必须通过证据、产物、hash、反伪造检查和人工决策
反伪造检查
- 旧run、旧报告、旧截图不能证明当前attempt
- 未绑定Manifest TRACE的测试通过不能算验收证据
- 只有exit code没有ART、hash或receipt时，不能算完成证明
- 人工确认必须留下decision、timestamp、confirmation page或等价receipt
交付确认页完整性
- 交付确认页HTML已生成
- 包含完整的TRACE rows
- 包含审计记录
人工最终审核
- 人类阅读交付确认页HTML
- 做出决策：“可以交付”或”退回修正”
- 决策结果写入confirmation page、audit receipt或等价交付记录

门禁状态：

🟢 TDD-GREEN + 人工通过：允许正式完成交付确认
🔴 TDD-RED：有测试未通过，禁止交付
🔴 BLOCKED：人工审核未通过

第七章：工具链与实施

7.1 AI-TDD工具链生态系统

AI-TDD工具链生态系统 图6：这张图回答的问题是：AI-TDD 的工具链分层由哪些层组成。

AI-TDD工具链采用分层架构，从底层核心引擎到上层Skill系统，形成完整的工程化支持体系。

7.2 核心引擎层（Core Engine）

1. Manifest Parser

YAML契约解析
ID提取与矩阵构建
Schema验证

2. Gate Controller

门禁状态管理
TDD-RED/GREEN状态判定
准入/交付拦截逻辑

3. Trace Engine

五维追溯矩阵执行
执行切片管理
依赖图构建

4. Evidence Log

证据哈希存储
防篡改验证
审计追溯

7.3 当前可执行CLI与集成边界

当前可执行CLI由 npm 包 bmad-speckit-sdd-flow 提供，核心入口是 bmad-speckit。根据本文实际验证过的命令，公开 CLI 当前主要覆盖 setup 检查、版本信息、dashboard 生命周期和更上层的编排入口。更底层的 Gate 实现属于项目集成层，不应被读者理解为本文仓库已经暴露的稳定公共命令。

命令	功能	示例
`bmad-speckit check`	安装/环境检查	`npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit check`
`bmad-speckit version`	查看CLI版本	`npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit version`
`bmad-speckit dashboard-status`	查看仪表盘状态	`npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit dashboard-status`

注意：门禁相关能力应优先通过CLI工作流进入。本文后续只展示稳定CLI入口；如果团队需要把Gate接入自己的流水线，应以本地项目中实际存在的脚本或CI任务为准。

真实CLI使用示例

步骤1：环境检查

$ npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit check
CLI version: 1.1.0
Template version: 1.1.0
Selected AI: cursor-agent
Subagent support: native
Check OK.

步骤2：查看已安装 CLI 版本

$ npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit version
CLI version: 1.1.0
Template version: 1.1.0
Node version: v22.x

步骤3：查看 dashboard 服务状态

$ npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit dashboard-status
{
  "ok": false,
  "mode": "stopped",
  "healthy": false
}

说明：上面的命令展示的是本文编辑时实际验证过的公开 CLI 行为。它们本身不会解析 Manifest，也不会直接执行项目自定义的准入门禁或交付门禁。具体门禁执行方式仍取决于团队如何在本地项目中接入 Gate 脚本、测试命令和证据产物。

实际工作流程

AI-TDD的实际工作流程由CLI入口 + 底层Gate脚本 + AI编码工具共同完成：

三个阶段：

准入门禁 - 优先通过bmad-speckit工作流进入；团队可在本地项目中接入自己的Gate脚本，验证Manifest完备性，状态应为AI-TDD-RED（新增验收测试存在且实现尚未满足）
AI生成实现 - 开发者将Manifest作为Prompt上下文粘贴到Claude/Cursor等AI工具，AI在边界约束内生成代码
交付门禁 - 优先通过bmad-speckit工作流进入；团队可在本地项目中接入交付Gate脚本，验证当前attempt的 TRACE/EVD/CMD/ART 闭合，重跑注册验证，校验artifact/hash/receipt并防止旧证据复用；只有 Gate Verdict 为 pass 且 Human Decision 为 accept，状态才应进入 AI-TDD-GREEN

完整状态流转见图5：AI-TDD状态机（/images/content/standalone/ai-tdd-framework/tdd-state-machine.svg），展示从MANIFEST_DRAFT → AI-TDD-RED → IMPLEMENTING → CLOSEOUT_CANDIDATE → AI-TDD-GREEN → CLOSED的完整流程，包含reject/revise和reconfirm两条回环路径。

关键边界：

开发者手动维护Manifest YAML文件
CLI是稳定入口，底层Gate脚本应由团队在自己的项目中接入和维护
AI代码生成通过外部工具（Claude、Cursor等）完成，而非内置命令

7.4 常见错误与解决方案

本节示例展示的是集成层常见报错形态，不是本文仓库保证存在的可执行命令。团队应把其中的占位命令替换成自己项目里真实接入的 Gate 脚本或 CI 任务。

错误1：Manifest文件未找到

$ npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit check
❌ Gate BLOCKED: Manifest文件未找到

期望路径: ./my-project/ai-tdd-manifest.yaml
实际状态: 文件不存在

修复：

确认项目根目录存在 ai-tdd-manifest.yaml。
或使用 --cwd 指定正确的项目目录。

错误2：Gate状态不符合预期

$ <你的团队准入门禁命令> --requirement-record ./records/REQ-001.json

🟢 Gate状态: TDD-GREEN (已实现)
❌ Gate BLOCKED: 预期状态为TDD-RED

问题分析：

所有测试已通过，说明实现已完成。
但 Implementation Readiness Gate 要求“测试存在但实现仍缺失”。

修复：

检查是否已有历史实现代码。
如需重新开始，清理实现文件并保留测试。
或跳过准入阶段，直接进入合适的交付确认流程。

错误3：测试覆盖不足

$ <你的团队交付门禁命令> --requirement-record ./records/REQ-001.json
❌ Gate BLOCKED: TRACE rows覆盖率不足

未覆盖MUST项:
  - MUST-REG-PASSWORD-LENGTH-001: 未关联测试

修复：

在 ai-tdd-manifest.yaml 中补上缺失的测试绑定。
重新运行 Manifest 生成与 Gate 检查流程。

AI-TDD的Skill系统是可扩展的Agent能力模块：

Skill	功能	场景
req-trace-matrix	需求追溯矩阵生成	从需求文档生成Manifest
contract-authoring	契约编写辅助	Manifest编写与验证
reverse-audit	反向审计	检查代码是否满足Manifest
checkpoint-gate	检查点门禁	自动化验收
encoding-integrity	编码完整性检查	文件编码与格式验证

7.5 外部集成层（External Integration）

AI-TDD与现有工具生态集成：

测试框架：Vitest、Jest、Playwright
版本控制：Git（commit hash作为证据）
LLM APIs：Claude、Codex、Gemini
YAML Parser：js-yaml、PyYAML
哈希算法：SHA256（证据防篡改）

7.6 实施路线图

阶段一：试点项目

选择一个小型功能模块
编写首个AI-TDD Manifest
运行Implementation Readiness Gate
AI生成实现并迭代至TDD-GREEN

阶段二：团队推广（1个月）

制定团队Manifest编写规范
建立CI/CD门禁流水线
培训团队使用AI-TDD流程

阶段三：规模化应用（3个月）

建立组织级Skill库
集成现有需求管理系统
建立审计与度量体系

7.7 最佳实践

1. Manifest编写原则

每个MUST必须有对应的EVD
每个OUT OF SCOPE必须说明原因和后续计划
使用明确的validation条件，避免模糊描述

2. 门禁配置建议

准入门禁期望TDD-RED（测试存在但失败）
交付门禁期望TDD-GREEN（关联验证通过且证据完整）
设置门禁超时，避免无限阻塞

3. 团队协作模式

产品经理负责需求确认阶段
架构师负责架构确认阶段
开发工程师负责实施准备和执行闭合
QA/审计Agent负责审计复核阶段

第八章：AI-TDD Gate机制详解

8.1 AI-TDD Gate的核心功能

AI-TDD Gate是Manifest的技术实现层：

1. Manifest解析

读取ai-tdd-manifest.yaml
解析MUST/NEG/OUT/EVD
建立TRACE rows

2. 测试代码生成

基于Manifest自动生成测试代码框架
关联E2E/ACC测试套件
生成覆盖率检查配置

3. 门禁运行

运行全量测试
判定TDD-RED或TDD-GREEN
生成门禁报告

4. 状态追踪

记录每次门禁运行的结果
维护需求→测试→结果的追溯链

8.2 CI/CD集成

下面的示例是集成示意。它展示的是如何把 bmad-speckit CLI、人工 AI 实现步骤和团队自有的 Gate 执行层串进 CI；不是本文仓库可直接照抄运行的完整工作流。

GitHub Actions 集成示意：

name: AI-TDD Gate

on: [pull_request]

jobs:
  implementation-readiness:
    name: "Implementation Readiness Gate"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check AI-TDD CLI Environment
        run: npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit check

      - name: Run team-specific Implementation Readiness Gate
        run: echo "Replace with your project's actual readiness gate command"

  ai-implementation:
    name: "AI Implementation"
    needs: implementation-readiness
    runs-on: ubuntu-latest
    steps:
      - name: AI Generate with Manifest Context
        run: echo "Use Claude/Cursor/Codex with the confirmed Manifest as context, then commit generated implementation."

  delivery-closeout:
    name: "Delivery Closeout Gate"
    needs: ai-implementation
    runs-on: ubuntu-latest
    steps:
      - name: Run team-specific Delivery Closeout Gate
        run: echo "Replace with your project's actual closeout gate command"

结语：需求契约驱动，证据链验收

在本文的定义里，AI-TDD 的核心洞见可以概括为一句话：不以 Manifest 为契约的 AI 生成，就是没有需求锚定的自由发挥；不以证据链为验收的交付，就是不可复核的乐观判断。

问题边界先于解决方案：AI时代的架构第一性原理

AI可以帮你写代码、写文档、做分析，甚至可以帮你设计架构。但是，AI不能独自替团队定义问题的业务边界。因为问题边界不仅是技术问题，也是业务问题、价值问题和判断问题。

软件工程里有一个长期存在的观点：代码不应该只让机器可执行，也应该让人类可理解。到了 AI 时代，这个观点可以进一步改写为：

“任何AI都能写出解决问题的代码。优秀的架构师定义值得解决的问题的边界。”

六大心智模型构成了人机协作的完整认知框架，每一个环节都围绕同一条主线展开：先锁定需求契约，再收集可复核证据。

需求确认：原子化拆解，生成机器可读的Manifest契约矩阵
架构确认：定义技术方案
实施准备：基于Manifest生成足够覆盖当前范围的验收测试基线
执行闭合：AI在Manifest约束下生成实现
审计复核：多Agent批判审计
交付确认：重新运行Manifest全量验证，确认TRACE/EVD/CMD/ART证据链、Gate Verdict和Human Decision闭合

两大关键门禁构成了质量防火墙：

Implementation Readiness Gate：检查Manifest是否完备，期望状态为 AI-TDD-RED / TDD-RED
Delivery Closeout Gate：检查Manifest关联证据链是否闭合，期望状态为 AI-TDD-GREEN / TDD-GREEN

AI-TDD在大规模工程中的应用展望

如果AI继续承担更多实现工作，AI-TDD方法论在以下领域可能更有价值：

1. 企业级微服务架构

在多服务复杂系统中，AI-TDD的TRACE rows可以帮助建立跨服务的需求追溯。每个服务的Manifest定义其接口契约，再通过统一的Gate进行端到端验证。

2. 安全关键系统

对于金融、医疗、航空等安全关键领域，AI-TDD的负向契约（NEG / MUST NOT）和范围边界（OUT OF SCOPE）审计机制可以补强安全约束管理。每个安全约束都需要明确的验证证据。

3. 合规驱动开发

在GDPR、SOX等合规要求严格的场景，AI-TDD的EVD机制可以沉淀合规审计材料，用于证明每个合规项都有对应的验证。

4. 开源项目协作

AI-TDD的Manifest可以成为开源项目的”社会契约”——贡献者在提交PR前对照Manifest确认改动范围，降低破坏项目约束的风险。

核心原则回顾

Manifest必须在执行开始前完备定义
Manifest是机器可读的，不是自然语言描述
AI-TDD Gate基于Manifest运行，不是基于散落的测试
没有完备Manifest，禁止进入执行
Manifest有未验证项，禁止交付

这就是AI-TDD的价值：让AI生成代码的质量，从自然语言猜测转向需求契约治理，从局部测试转向 TRACE/EVD/CMD/ART 证据链闭合验收。

第九章：常见问题解答（FAQ）

Q1：AI-TDD会增加多少开发时间？

A：会增加前期澄清和编写Manifest的时间，但通常会减少后期返工。具体收益取决于需求复杂度、团队熟练度、测试基础设施和AI参与深度。

以快速开始章节的计算器示例为例：

传统做法：直接让AI生成 → 发现边界遗漏后返工
AI-TDD：先编写Manifest → 生成测试 → 生成实现 → 按证据验收

净收益通常更容易出现在边界多、返工成本高、需要审计证据的项目中。

Q2：Manifest需要写多详细？

A：聚焦边界，而非实现。

❌ 过度详细（不好）：

must:
  - id: "MUST-SUM-LOOP-001"
    description: "使用for循环遍历数组，累加每个元素到累加器变量"
    # 太具体！限制了AI的实现方式

✅ 适度详细（好）：

must:
  - id: "MUST-SUM-RESULT-001"
    description: "计算数组元素总和"
    validation: "sum([1,2,3]) === 6，时间复杂度O(n)"
    # 只定义边界（输入/输出/性能），不定义实现

原则：Manifest定义”做什么”和”不能做什么”，AI决定”怎么做”。

Q3：如果AI反复无法让测试变绿怎么办？

A：分情况处理：

情况1：AI生成的实现有逻辑错误

人工介入，给AI更具体的提示
将复杂MUST拆分为多个简单MUST
使用审计Agent提供反馈

情况2：测试本身有问题

检查MUST的validation是否可实现
检查是否有矛盾的需求（例如MUST-REQ-A-001和MUST-REQ-A-002冲突）
修改Manifest，重新生成测试

情况3：AI能力边界

某些复杂算法可能超出当前AI能力
将这部分标记为OUT OF SCOPE，人工实现
其余部分继续AI-TDD流程

Q4：现有项目如何迁移到AI-TDD？

A：推荐”影子模式”迁移：

阶段1：并行验证

保持现有开发流程不变
选择1个新功能，同时用AI-TDD和传统方式实现
对比质量和时间差异

阶段2：选择性应用（1个月）

新功能优先使用AI-TDD
遗留功能在重构时补充Manifest
保留现有测试作为回归测试

阶段3：全面切换（持续）

建立团队内部模板
形成最佳实践
新人培训材料

不要：

❌ 一次性重写所有代码
❌ 删除现有测试
❌ 不分场景地强迫团队使用AI-TDD

Q5：AI-TDD与现有CI/CD如何集成？

A：AI-TDD可以作为独立验证阶段接入现有流水线。下面两个片段都是集成示意，不是本文仓库可直接照抄运行的完整配置；其中显式写出的 bmad-speckit check 只用于 setup smoke check，并不执行项目自定义的 AI-TDD 门禁。请把占位命令替换为你自己项目里的真实 Gate 命令或 CI 任务。

GitLab CI集成示意：

# .gitlab-ci.yml
stages:
  - validate    # 新增：AI-TDD验证
  - test
  - deploy

ai-tdd-validate:
  stage: validate
  script:
    - npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit check
    - echo "Replace with your project's actual implementation readiness gate command"
  only:
    - merge_requests

ai-tdd-closedout:
  stage: test
  script:
    - echo "Replace with your project's actual delivery closeout gate command"
  only:
    - main

GitHub Actions集成示意：

# .github/workflows/ai-tdd.yml
name: AI-TDD Gate
on: [pull_request]

jobs:
  ai-tdd-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: AI-TDD Validation
        run: |
          npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit check
          echo "Replace with your project's actual implementation readiness gate command"

Q6：小团队（1-3人）适合用AI-TDD吗？

A：取决于项目复杂度。

适合场景：

项目有明确的需求边界（如API服务、工具库）
需要长期维护（>3个月）
需求变更频繁（Manifest帮助追踪变更）

可能不适合：

一次性脚本/工具
纯粹的原型探索
个人学习项目

建议：即使是1人团队，也可以从”只写MUST，不写其他”的最简模式开始。

Q7：AI-TDD需要特殊的AI模型吗？

A：通常不需要专门模型。只要模型能理解结构化上下文、生成代码并根据失败反馈迭代，就可以参与AI-TDD流程；复杂项目仍然需要选择上下文长度、工具调用和代码能力更强的模型。

模型选择建议：

代码生成模型：选择支持工具调用（Function Calling）的模型，便于与Gate系统集成
上下文长度：复杂Manifest可能需要128K+上下文，选择支持长上下文的模型
多模态能力：如果需要处理截图、设计稿等，选择支持多模态的模型

提示技巧（与模型无关）：

在Prompt中明确指出”基于以下Manifest生成”
要求AI”严格遵守OUT OF SCOPE，不要实现”
要求AI”先理解NEG（MUST NOT），确保不违反”
提供Manifest Schema的简要说明，帮助AI理解结构

Q8：Manifest的Git管理策略是什么？

A：推荐以下策略：

分支策略：

main
├── feature/login-manifest      # 只改Manifest
├── feature/login-impl          # AI生成实现（基于Manifest）
└── hotfix/fix-auth-bug        # 紧急修复

提交规范：

# Manifest变更
feat(manifest): 增加用户注册MUST-REG-EMAIL-VERIFY-001

# 实现变更（由AI生成）
feat(impl): AI实现MUST-REG-EMAIL-VERIFY-001邮箱验证

# 门禁通过
gate(pass): Implementation Readiness Gate TDD-RED

# 审计通过
audit(pass): 3 Agents reviewed, 0 blockers

版本标签：

# Manifest确认版本
git tag -a manifest-v1.0.0 -m "需求确认通过"

# 交付版本
git tag -a release-v1.0.0 -m "AI-TDD Delivery Closeout Gate通过"

第十章：局限性与适用边界

AI-TDD并非银弹。在推广使用前，需要清醒认识其局限性和适用边界。

10.1 不适用场景

场景一：高度探索性的原型开发

当你连”要做什么”都不确定，需要快速试错时
Manifest的预定义会成为创新的束缚
建议：传统AI辅助编码更合适

场景二：极小型项目（<500行代码）

编写Manifest的时间可能超过直接编写代码
方法论的开销在小型项目中不划算
建议：只有当项目复杂度超过阈值（如>5个交互接口）时才使用

场景三：纯粹的前端UI开发

UI/UX需求主观性强，难以用MUST/EVD精确描述
“美观""流畅”等需求无法量化验证
建议：视觉驱动开发更合适，AI-TDD仅用于后端逻辑

10.2 使用成本

学习成本：

团队需要投入时间学习Manifest语法和AI-TDD流程
最好指定1名熟悉流程的人负责模板、门禁和审计口径

时间成本：

编写Manifest和确认流程会增加前期时间
如果需求边界复杂、返工成本高，后期返工通常会减少
净收益在大型、长期或高风险项目中更明显

工具成本：

需要可运行的AI-TDD Gate基础设施（自建、复用现有脚本，或接入团队已有流水线）
多Agent审计需要额外的Token消耗

10.3 失败风险

风险一：Manifest本身定义错误

如果人类对需求的理解就是错的，AI-TDD只能加速错误实现
缓解：加强需求确认阶段的人工审查

风险二：AI无法理解复杂约束

某些领域特定逻辑（如金融合规规则）可能超出当前AI能力
缓解：复杂约束拆分为更简单的子约束

风险三：过度依赖工具

团队可能陷入”为了用AI-TDD而用AI-TDD”
缓解：定期回顾，确认方法论确实带来价值

10.4 渐进式采用路径

第一阶段：单MUST项试水

选一个简单功能（如日志记录）
只定义1个MUST，体验完整流程

第二阶段：加入NEG / MUST NOT

增加负向约束（如”禁止硬编码密钥”）
体验TDD-RED拦截效果

第三阶段：完整流程

加入OUT OF SCOPE、EVD、TRACE rows
运行完整的AI-TDD Gate

第2个月：团队推广

总结第1个月的经验教训
制定团队内部的Manifest模板和最佳实践

附录A：术语表

术语	英文	定义
AI-TDD	本文定义的Manifest级AI-TDD	以AI为执行主体、以Manifest契约为核心的验收驱动开发方法；不是已标准化的行业术语
Manifest	AI-TDD Gate Manifest	YAML格式的需求契约矩阵，包含MUST/NEG/OUT/TRACE/EVD/ACC/E2E/FAIL/EDGE/CMD/ART/TASK
MUST	Must Requirement	系统必须实现的功能性需求
NEG	Must Not / Negative Assertion	会阻断完成的负向断言；`MUST NOT` 是概念别名，机器ID使用 `NEG-*`
OUT	Out Of Scope Boundary	当前迭代排除的功能边界；旧的“未完成范围”表述应迁移为 `OUT OF SCOPE / OUT-*`
TRACE	Trace Row	契约切片索引，绑定MUST/NEG、TASK、场景层ACC/E2E/EDGE/FAIL以及证据层EVD/CMD/ART；OUT通过范围审计引用绑定
EVD	Evidence	需求验证的证据项，包含验证阈值和产出物
ACC	Acceptance Test	面向验收项的自动化测试或检查
E2E	End-to-End Test	端到端场景验证
FAIL	Failure Path	`NEG-*` 相关的必须失败路径
EDGE	Edge Case	边界条件与异常输入场景
CMD	Command	可复现执行的验证命令
ART	Artifact	可审计的交付物或证据文件
TASK	Task	实施任务或执行切片
TDD-RED	TDD-RED	准入门禁状态：本次新增或关联验收测试存在且失败，表示实现尚未满足这些验收项
TDD-GREEN	TDD-GREEN	交付门禁状态：当前attempt证据链闭合，Gate Verdict为pass，且Human Decision为accept
CLOSEOUT_CANDIDATE	交付候选状态	注册验证已经通过，但证据链、Gate Verdict和Human Decision尚未全部闭合的中间状态
Implementation Readiness Gate	准入门禁	执行开始前必须通过的关卡，要求TDD-RED状态
Delivery Closeout Gate	交付门禁	交付前必须通过的关卡，要求证据链、门禁裁决和人工决策共同闭合
Requirement Contract	需求契约	经过人类确认并版本化的Manifest，用于约束AI执行范围
Contract Slice	契约切片	以TRACE row为核心的最小可验收单元，绑定需求、场景、证据、命令和产物
Evidence Chain	证据链	由TRACE、EVD、CMD、ART及其hash/receipt组成的可复核证明链
Gate Verdict	门禁裁决	Gate基于当前attempt证据链给出的pass、blocked或failed判定
Human Decision	人工决策	人类基于确认页和审计证据做出的可记录accept/reject决定
Bounded Packet Closure	有界闭合	AI在Manifest约束下迭代生成，直到候选实现满足注册验证并进入closeout候选状态
Human-in-the-loop	人机协作	关键决策点必须由人类确认的机制
Contract as Code	契约即代码	Manifest是人类意图的可执行编码
Reverse Audit	反向审计	从代码实现追溯验证是否满足Manifest的审计方式
Trace Row	执行切片	可独立执行的最小需求验证单元
Skill	Skill	AI-TDD的可扩展Agent能力模块
bmad	BMAD CLI	AI-TDD的命令行工具

参考与延伸

核心理论文献

Beck, K. (2002). Test-driven development: By example. Addison-Wesley.

Brooks, F. P. Jr. (1975). The mythical man-month: Essays on software engineering. Addison-Wesley.

GitHub. (2021, June 29). Introducing GitHub Copilot: Your AI pair programmer. https://github.blog/news-insights/product-news/introducing-github-copilot-ai-pair-programmer/

Humble, J., & Farley, D. (2010). Continuous delivery: Reliable software releases through build, test, and deployment automation. Addison-Wesley.

OpenAI. (2023). GPT-4 Technical Report. arXiv. https://arxiv.org/abs/2303.08774

Sobocinski, P. (2023, August 17). TDD with GitHub Copilot. Martin Fowler. https://martinfowler.com/articles/exploring-gen-ai/06-tdd-with-coding-assistance.html

Sukharev, D. (2023). AI-TDD: CLI for TDD - you write the test, GPT writes the code to pass it. GitHub. https://github.com/di-sukharev/AI-TDD

Piya, S., & Sullivan, A. (2023). LLM4TDD: Best Practices for Test Driven Development Using Large Language Models. arXiv. https://arxiv.org/abs/2312.04687

Mathews, N. S., & Nagappan, M. (2024). Test-Driven Development for Code Generation. arXiv. https://arxiv.org/abs/2402.13521

Cui, Y. (2025). Tests as Prompt: A Test-Driven-Development Benchmark for LLM Code Generation. arXiv. https://arxiv.org/abs/2505.09027

Schneider, J. G., Borjigin, A., Kamal, M., & Grundy, J. (2026). Test-Driven Agentic Development for Automated Software Evolution. arXiv. https://arxiv.org/abs/2604.26615

Beck, K. (2025, June 11). TDD, AI agents and coding with Kent Beck [Interview]. The Pragmatic Engineer. https://newsletter.pragmaticengineer.com/p/tdd-ai-agents-and-coding-with-kent

Thoughtworks. (2026). The Future of Software Engineering: Retreat Findings and Strategic Insights. https://www.thoughtworks.com/content/dam/thoughtworks/documents/report/tw_future%20_of_software_development_retreat_%20key_takeaways.pdf

作者注：本文提出的”AI-TDD”是一个以AI-TDD Gate Manifest为核心的工程化方法论。它以机器可读Manifest承载需求契约，用TRACE/EVD/CMD/ART组成多维证据链，再由Gate Verdict和Human Decision完成交付确认，把验收驱动从代码测试扩展到可复核的契约治理。这个框架仍在持续演进中，欢迎实践反馈与探讨。

Reading path

继续沿这条专题路径阅读

按推荐顺序继续阅读 AI 工程化实践相关内容，而不是只看同专题的随机文章。

查看完整专题路径 →

Next step

继续深入这个专题

如果这篇内容对你有帮助，下一步可以回到专题页继续系统阅读，或者订阅后续更新。

返回专题页订阅 RSS 更新

RSS Subscribe

订阅更新

通过 RSS 阅读器订阅获取最新文章推送，无需频繁访问网站。

推荐使用 Follow 、Feedly 或 Inoreader 等 RSS 阅读器

评论与讨论

使用 GitHub 账号登录参与讨论，评论将同步至 GitHub Discussions

正在加载评论...

引言：从”代码级TDD”到”需求契约驱动”

一个典型失效场景：AI生成用户模块的教训

代码级TDD的局限

Manifest作为需求契约矩阵

AI-TDD的核心思想

AI-TDD的一等定义：需求契约驱动 + 多维证据链验收

快速开始：上手AI-TDD

示例：用AI-TDD实现一个计算器

步骤1：创建Manifest文件

步骤2：AI生成测试代码

步骤3：AI生成实现代码

步骤4：按证据链验收交付

对比：传统做法 vs AI-TDD

下一步

背景考证：AI-TDD的思想早于术语

第一章：为什么需要需求契约驱动的AI-TDD

1.1 代码级TDD的本质局限

1.2 Manifest：从测试清单到契约矩阵

1.3 AI-TDD Gate：Manifest的执行引擎

第二章：架构的第一性原理

2.1 从”解决问题”到”定义问题边界”

2.2 人机协作的沟通本质：为什么单靠自然语言往往不足以充当AI的执行契约

2.3 契约即代码：Manifest作为人类意图与AI执行之间的桥梁

第三章：AI-TDD与现有技术方案对比

3.1 从TDD到BDD再到AI-TDD——方法论的演进

传统TDD：测试驱动的开发

BDD/Gherkin：行为驱动的开发

AI-TDD：契约驱动的开发

3.2 迁移示例：从TDD到AI-TDD的推荐流程

第四章：AI-TDD Gate Manifest详解

4.0 Manifest Schema规范（v1.0）

4.1 Manifest的核心结构

4.2 Manifest的生成过程

4.3 Manifest的机器可读性

第五章：AI-TDD的六大心智模型

5.1 需求确认（Requirement Confirmation）

5.2 架构确认（Architecture Confirmation）

5.3 实施准备（Implementation Readiness）

5.4 执行闭合（Bounded Packet Closure）

5.5 审计复核（Audit Review）

5.6 交付确认（Delivery Closeout）

第六章：两大关键门禁

6.1 门禁一：Implementation Readiness Gate（准入门禁）

6.2 门禁二：Delivery Closeout Gate（交付门禁）

第七章：工具链与实施

7.1 AI-TDD工具链生态系统

7.2 核心引擎层（Core Engine）

7.3 当前可执行CLI与集成边界

真实CLI使用示例

实际工作流程

7.4 常见错误与解决方案

7.5 外部集成层（External Integration）

7.6 实施路线图

7.7 最佳实践

第八章：AI-TDD Gate机制详解

8.1 AI-TDD Gate的核心功能

8.2 CI/CD集成

结语：需求契约驱动，证据链验收

AI-TDD在大规模工程中的应用展望

核心原则回顾

第九章：常见问题解答（FAQ）

Q1：AI-TDD会增加多少开发时间？

Q2：Manifest需要写多详细？

Q3：如果AI反复无法让测试变绿怎么办？

Q4：现有项目如何迁移到AI-TDD？

Q5：AI-TDD与现有CI/CD如何集成？

Q6：小团队（1-3人）适合用AI-TDD吗？

Q7：AI-TDD需要特殊的AI模型吗？

Q8：Manifest的Git管理策略是什么？

第十章：局限性与适用边界

10.1 不适用场景

10.2 使用成本

10.3 失败风险

10.4 渐进式采用路径

附录A：术语表

参考与延伸

核心理论文献

继续沿这条专题路径阅读

AI 工程化落地实践地图

构建RAG系统指南：架构、检索实现与质量门禁