文档驱动开发：从需求到工程流

摘要：AI 开发文档驱动实践（二）：工程流交付 为什么工程流交付必须用文档驱动 1.1 从"人写代码"到"AI写代码"：指令式开发的瓶颈 我最早用 AI 辅助开发的时候，习惯跟绝大多数人一样：直接在对话框里丢需求，让模型把代码……

AI 开发文档驱动实践（二）：工程流交付

1. 为什么工程流交付必须用文档驱动

1.1 从"人写代码"到"AI写代码"：指令式开发的瓶颈

我最早用 AI 辅助开发的时候，习惯跟绝大多数人一样：直接在对话框里丢需求，让模型把代码生成出来。需求简单的时候，这个路子确实很快，CRUD 页面、工具脚本、正则表达式，基本一次到位。可一旦工程规模上来，问题就全冒出来了。项目做到第五天，同一个 AI 助手已经"忘记"了第一天的需求约束，每加一个新功能，都要把老规则重新描述一遍；改到第三个迭代，我更发现生成代码的风格开始发散，前两轮用的工具函数，到后来模型又重新造了一个差不多的轮子。

这类问题的根子，在于大语言模型本质上是一个无状态系统。它没有"记忆"，只有你提供给它的上下文。你跟它聊了五十轮的对话，它真正能稳定依赖的，永远只是当前窗口里能看到的那部分内容。这种情况下，靠"多轮对话"来驱动一个多阶段、多人协作、持续迭代的工程流程，简直是拿一台没有硬盘的电脑做数据仓库，不仅存不住，而且一旦切换会话、重启进程，前面所有上下文就全部归零。这就是指令式开发的瓶颈：灵活，但不可控。

工程流交付恰恰是在这个瓶颈点上被逼出来的。所谓"工程流"，不是让 AI 帮你写一段代码，而是把整个软件交付过程拆成需求分析、架构设计、编码实现、测试验证、部署上线等环节，让 AI 在每一个环节里，按照标准化的输入和输出，完成阶段性的工作。这本质上是从"聊天式开发"向"流水线式开发"的一次升级。

1.2 文档驱动让工程流变得可追踪、可验收

我第一次意识到文档的重要性，是一次真实的翻车经历。当时做一个数据清洗服务，我们团队三个人并行让 AI 写不同模块。A 模块的输入格式是 JSON 里嵌套数组，B 模块的接口文档里却写的是"data 为字符串数组"。两边都按自己的理解写了，联调的时候格式对不上，整整排查了一个下午，最后才发现是需求描述里的口头约定没有被固定下来。从那以后，我开始推行"先写文档，再让 AI 动手"的开发方式。

文档驱动的一个核心价值，是把隐式的、口头约定的信息，转变成显式的、可追踪的中间产物。传统开发里，需求文档、设计文档更多是给人看的，代码才是最终交付物。但在 AI 辅助开发的场景下，文档既是给 AI 的"提示词"，也是给团队其他成员（包括未来的 AI 会话）的"交接文档"。它相当于整个工程流里的状态载体：每个阶段基于文档输入，产出的新文档再往后传递，源头一变，下游全部跟着变。这样一来，整个流程就可追踪了——每个人、每个 AI 会话、每个环节做了什么，对照文档就能说清楚。

再往深一层说，文档驱动还让"验收"变成了一个可执行的动作。没有文档，验收只能靠人工review代码，凭感觉判断"写得对不对"，效率低且容易漏。有了文档化的验收标准，测试用例可以从标准里生成，回归范围可以按变更点定位，AI 生成的代码是否符合需求，也能用一个可重复执行的脚本去校验。文档不是摆设，它是工程流里的唯一事实来源，也是所有校验动作的参照物。

1. 工程流交付的起点：一份能"喂"给 AI 的需求规格书

2.1 结构化 PRD 的写法：让 AI 也能读懂需求

很多团队在接入 AI 开发时，第一反应是"把 PRD 丢给 AI 让它写代码"。结果 AI 给出的代码经常偏离预期。问题出在哪？十有八九是 PRD 本身太"人味"了。

传统 PRD 习惯用大段描述性文字讲述业务背景、用户画像、竞品分析，这些内容对人有价值，但对 AI 生成代码来说，大多是噪音。AI 真正需要的，是高度结构化的需求定义：功能列表、输入输出、边界条件、业务规则、异常分支。一份能让 AI 读懂的 PRD，应该具备三个特征：

第一，需求条目原子化。每条需求必须是一个独立的、不可再拆的完整功能点，而不是"用户可以在平台上进行各种操作"这种含糊话。比如"用户通过手机号验证码完成登录"，这就是一个原子需求；而"完善登录体验"就不是。

第二，验收标准数字化。每条需求必须附带可量化的验收条件。比如"验证码有效期 5 分钟"、"连续输错 5 次锁定 30 分钟"、"接口响应时间小于 800 毫秒"。"快一点""流畅些"这类主观描述要坚决剔除。

第三，边界条件显式化。正常路径谁都会写，关键是异常分支。AI 如果没有被告知"用户已注册却点了注册""验证码超时后再次提交"这些情况该怎么处理，它大概率会按自己的"常识"编一个逻辑，而这个逻辑未必符合你的业务预期。

实操上，我建议在写 PRD 时，直接在文档里用这样的格式组织需求：

`## 需求 R-101：手机号验证码登录

优先级: P0
角色: 未登录用户
前置条件:
- 用户已输入手机号并点击"获取验证码"

主流程:
1. 系统生成 6 位随机数字验证码，有效期 5 分钟
2. 系统将验证码发送至用户手机
3. 用户输入验证码，点击"登录"
4. 系统校验验证码是否正确且未过期
5. 校验通过后，系统创建会话并返回 token

异常分支:
- E1: 验证码错误 -> 返回错误码 1001，提示"验证码不正确"
- E2: 验证码过期 -> 返回错误码 1002，提示"验证码已过期，请重新获取"
- E3: 手机号格式非法 -> 返回错误码 1003，提示"手机号格式错误"
- E4: 同一手机号 60 秒内重复获取 -> 限制请求，返回错误码 1004

验收标准:
- AS-1: 合法手机号验证码登录，正常进入系统首页，耗时 `

这样的 PRD，无论你后续用哪个大模型、哪个 AI 编程工具，它都能快速理解需求边界。关键不是写得漂亮，而是写得让 AI"没有想象空间"。

提示：原子化需求编号非常重要。R-101 这种编号既是需求的唯一标识，也是后续测试用例、代码注释、回归范围里的引用锚点。没有编号，文档一长，AI 很容易指代混乱。

2.2 需求冻结机制：让工程流有一个稳定基线

写过代码的人都知道，需求变更是项目延期最大的敌人。在 AI 开发流程里，这个问题会被放大十倍——因为 AI 没有"我记得上一版需求是什么"的能力，你给它一份新文档，它就会按新文档生成新的逻辑，至于这个逻辑是不是破坏了你原本的功能，它不会主动去比对。

所以工程流交付里，我强烈建议引入"需求冻结"（Requirements Freeze）机制。具体做法是：在进入编码阶段之前，把 PRD 的版本号、变更记录、责任人全部定下来，后续所有涉及需求的讨论、修改、扩展，都必须走"变更申请"流程，更新文档版本，而不是直接在口头上改需求。

冻结机制的核心动作有三个：

版本控制。PRD 文档从 v0.1 草稿开始，每次修订都需要记录变更时间、变更人、变更原因。推荐把 PRD 直接放在 Git 仓库里管理，和代码同库同版本，这样需求和代码天然关联。

变更通知。任何需求变更，除了修改 PRD 之外，还必须同步更新相关的数据字典、接口定义、测试计划。工程流里要建立一条规则：需求文档改了，下游架构文档、开发任务、测试用例必须联动更新，否则视为变更未完成。

基线锚点。每个版本的需求文档冻结之后，打一个 Git tag。后续 AI 生成代码时，严格基于当前冻结的版本来做。如果 AI 的上下文窗口里同时存在新旧两个版本的需求描述，就很容易产生逻辑混乱。

2.3 用例与验收标准的"合同化"

需求规格书的下游，是一堆 AI 要写的东西，但衡量 AI 写得对不对，不能靠感觉，必须有"合同"。这里的合同，就是我从 PRD 拆出来的验收标准清单。

实际操作中，我会把 PRD 里的所有验收标准（AS 项）单独抽出来，整理成一个验收清单，然后用这个清单做两件事：

第一，喂给 AI 做测试用例生成。要求 AI 为每一条验收标准，补充正例、反例和边界例。比如 AS-2 要求"60 秒内只能调用一次"，那测试用例至少包含：第一次调用成功、1 秒内第二次调用被拒绝、59 秒后调用被拒绝、第 61 秒调用成功等四个场景。AI 生成用例的覆盖度，取决于验收标准本身描述得是否精确。

第二，作为编码阶段的完成定义（Definition of Done）。我会在给 AI 的工程流指令里写清楚：编码任务只有在满足对应验收标准的全部测试用例之后，才算"完成"。这样 AI 不会因为"代码能跑"就停下来，而是会主动去验证逻辑是否符合合同要求。

1. 从架构文档到 AI 可执行的工程流编排

3.1 模块划分与依赖关系的显式表达

有了需求规格书，下一步就是架构设计。这里有个容易忽视的问题：AI 生成代码的能力再强，它也无法在一轮对话里把整个系统一次性写出来。它一次能处理的，是"一个模块、一个文件、一个函数"级别的粒度。这就要求架构文档把系统拆分到足够细的粒度，细到 AI 拿到一个模块就能动手。

我在工程流实践里，会要求架构文档必须包含以下几个层面：

服务划分。系统包含哪几个独立部署的服务，每个服务的职责边界是什么。比如"订单服务"负责订单生命周期管理，"支付服务"负责支付渠道对接。服务之间通过明确接口通信。

模块清单。每个服务内部的模块划分，模块之间的调用关系。这个层面要具体到目录结构级别。AI 看到一个目录树，就能理解代码该放哪里。

数据模型。所有核心实体的字段定义、类型、约束、枚举值。这个必须给出 schema 级别的定义，不能含糊。比如"订单状态: PENDING(待支付), PAID(已支付), SHIPPED(已发货), COMPLETED(已完成), CANCELLED(已取消)"。

接口定义。服务间、模块间的 API 契约，包括方法、路径、请求参数、响应结构、错误码。推荐直接用 OpenAPI 规范写，AI 对这种 YAML 格式的理解能力极强。

为什么这些必须显式表达？因为 AI 在生成代码时，最怕的是"自由度"太大。你越不明确，它越会自己发挥。而系统的架构噩梦，往往就是每个模块都自由发挥一点，最终拼在一起变成一团乱麻。

以目录结构为例，我会在架构文档里直接给出预期的目录树：

`order-service/
├── src/main/java/com/example/order/
│   ├── controller/      # 接口层，只做参数校验和响应封装
│   ├── service/         # 业务层，实现业务逻辑与状态流转
│   ├── repository/      # 数据访问层，封装 MyBatis/JPA 操作
│   ├── model/           # 实体对象与 DTO
│   └── config/          # 配置类与第三方集成
├── src/test/java/       # 单元测试与集成测试
└── pom.xml
`

AI 拿到这个目录树，生成代码时就知道 Controller 只做接口映射、复杂逻辑下沉到 Service，不会出现"Controller 里塞了一大堆 SQL 操作"这种新手写法。

注意：架构文档里要特别标注"禁止事项"。比如禁止在 Controller 里直接操作数据源、禁止在循环中调用远程接口、禁止硬编码配置项。AI 对"可以做什么"的理解很好，但对"不能做什么"需要你明确告知。

3.2 Agent 在工程流中的协作方式

文档驱动到这一步，自然引出 AI Agent 的编排方式。在工程流交付的场景里，我不推荐"一个大模型从头干到尾"的做法，更倾向于"多个 Agent，每个 Agent 负责一个环节"的模式。

这就像一条生产流水线，每个工位有一个专职工人。需求解析 Agent 负责把 PRD 转成技术任务清单；架构 Agent 负责根据技术任务清单整理接口定义和目录结构；编码 Agent 负责按模块逐个实现；测试 Agent 负责按验收标准写测试用例并执行。这些 Agent 之间不直接对话，它们的协作方式只有一个：通过标准的文档产物来传递信息。

我用一个具体的协作例子来说明。在一个 API 网关项目中，我把整个交付流分成了五个 Agent 角色：

需求 Agent：输入是 PRD，输出是需求规格拆解表（原子需求+验收标准）。

架构 Agent：输入是需求规格拆解表，输出是技术方案、模块划分、数据模型、OpenAPI 定义。

编码 Agent：输入是架构文档中的某个模块定义，输出是可运行的代码文件。

测试 Agent：输入是验收标准清单和接口定义，输出是测试代码和测试报告。

集成 Agent：输入是全部模块代码和测试报告，输出是构建产物和部署配置。

每个 Agent 的输出，都是下一个 Agent 的输入。需求变了，需求 Agent 输出的规格拆解表就变，下游每个 Agent 重新执行。这个模式最大的好处是，每个环节的职责单一，每个 Agent 的上下文开销可控，系统的可追溯性很强——你永远可以说清楚，某段代码是依据哪份文档、由哪个 Agent、在哪次任务里生成的。

3.3 基于文档的任务拆分与完成定义

有了 Agent 编排框架，还缺一环：任务拆分和完成定义。工程流不是让一个 Agent 一次性生成整个系统，而是把系统拆成多个任务，逐个交给编码 Agent 完成。

任务拆分要遵循两个原则。一是模块内聚原则。每个任务尽量只涉及一个模块或一个功能点，避免跨模块改动，这样测试和 code review 都更清晰。二是上下文适配原则。一个任务包含的信息量，必须在 AI 上下文窗口的可承受范围内。如果任务描述本身就有几千行文档，AI 的处理效果会大打折扣。

我常用的任务卡片长这样：

`## 任务 T-204：实现订单状态流转接口

依赖文档:
- 架构文档 v2.1 : 订单模块
- 数据模型 v2.1 : order 表定义
- OpenAPI v2.1 : /api/v1/orders/{id}/cancel

需求来源: R-114, R-115
完成定义 DoD:
1. 实现 cancel 接口，支持 PENDING -> CANCELLED 状态流转
2. 状态不为 PENDING 时，返回错误码 2003
3. 调用库存服务回滚预占库存，失败时进入重试队列
4. 所有单元测试通过，覆盖 E1/E2/E3 分支
5. 代码符合项目规范：无硬编码、无循环调用远程接口
`

这个任务卡片表明：明确告诉 AI 要做什么、依据什么、做到什么程度算完。有了完成定义，AI 生成完代码后，会自己对照 DoD 逐条检查，而不是写完就交差。

1. 环境配置与关键参数：让文档落地

4.1 模型选型与上下文窗口的预算分配

文档和流程都设计好了，实际跑起来还需要解决一个问题：上下文窗口资源怎么分配。大模型的上下文窗口是有限的，哪怕目前主流模型已经支持 128K、200K 甚至更大窗口，也不能把所有文档一股脑全塞进去。窗口越大，tokens 成本越高，生成速度也越慢，而且当上下文塞满无关内容时，模型对关键信息的注意力会明显下降。

我把上下文预算分为三块：系统提示词、领域文档、任务内容。

系统提示词（Syetem Prompt）承载工程流的"规则"，比如代码规范、输出格式要求、禁止事项。这部分应该精简到 500-1000 tokens，用最紧凑的语言写清楚。

领域文档承载项目的稳定信息，包括架构文档、数据模型、接口定义。这部分是工程流的"长时记忆"，通常有几千到几万 tokens。因为多轮任务里每次都会用到，我会把它固定在上下文中。

任务内容是当前要执行的"短期指令"，包括当前任务卡、关联的需求描述、相关的代码片段。这部分是动态变化的，每次执行任务单独注入。

上下文预算分配的实操建议：

我通常会把一个任务的总上下文预算控制在模型上限的 70% 左右。比如模型窗口是 32K tokens，那么任务执行时的总输入控制在 20K 左右，剩下的留给输出和中间推理。如果领域文档太大，超过了预算，就需要做文档切片或向量化处理，而不是硬塞。

4.2 文档分片策略与检索增强

当项目文档整体超过上下文窗口的时候，一个务实的方案是引入 RAG（检索增强生成）来做文档管理。但这里有个工程流特有的问题：普通的 RAG 是按相似度检索 top-k 片段，检索出来的内容可能零散且缺失上下文，用于问答可以，用来做工程流交付很容易出错。

我的做法是分两层组织文档：

第一层是常驻上下文层。每类任务只注入该任务最需要的稳定文档片段。比如编码订单模块时，只注入数据模型中 order 表定义、订单状态枚举、OpenAPI 中订单相关接口定义。其他模块的文档不注入。这一层通过"预读取"而非实时检索实现，保证稳定性。

第二层是按需检索层。当遇到跨模块问题或文档内容超长时，才通过向量检索定位相关片段。检索到的片段，不会直接作为执行依据，而是先经过一个"信息核对"步骤，把检索结果和常驻文档中的定义做比对，确认无冲突后再使用。

文档分片也不是简单按字数切块。我的原则是：按章节语义切。每个切片尽量是一个完整的、有独立语义的单元，比如一个数据表定义、一个接口描述、一个状态机说明。这样检索到的内容，即使没有上下文，也不容易产生歧义。

4.3 工程流中的重试与幂等设计

把 AI 接入工程流之后，你会很快发现一个和传统开发完全不同的痛点：AI 不是确定性系统，同一个输入可能产出不同的输出。甚至同样的任务跑两遍，生成的代码风格和逻辑细节都会有差异。这在调试和验收阶段特别折磨人。

应对之道是"重试+幂等"。我的工程流框架里会做两层设计：

第一层是自动重试机制。当 AI 生成的代码编译失败、测试失败或不符合完成定义，系统自动将任务连同失败原因一起回退给 Agent，要求其修复后重新提交。注意，重试时要把"失败原因"完整注入上下文，并且明确告诉服务，这是第几次重试，重复次数过多要升级给人处理。

第二层是幂等控制。同一个任务，无论执行多少次，最终应产出逻辑一致的结果。为了让这点落地，我会在工程存档里记录每次任务的关键决策信息，比如"本模块采用 xxx 模式实现""状态机已定义，不要自行更改"。这样即使 Agent 重跑，也能基于上一轮的决策继续往下做，而不是推倒重来。

实际跑下来，自动重试能消化掉至少七成的失败情况，但剩下的三成（比如模型对复杂规则理解偏差）需要人工介入。这部分我在第 6 节详述。

1. 工程流交付中的测试与验收

5.1 测试文档驱动：从验收标准到测试用例

很多 AI 开发团队的后端测试是"点一下看通不通"，这在交付工程里是万万不够的。我在工程流中推行的测试方案，是让测试 Agent 严格以 PRD 的验收标准为输入，用标准的测试设计方法生成用例。

具体流程分三步：

第一步，把验收标准（AS 项）翻译成等价类。以"手机号验证码登录"的 AS-1 为例，等价类包括：合法手机号+正确验证码、合法手机号+错误验证码、非法手机号+任意验证码、空手机号、空验证码。这些等价类直接从需求文档里就能推导出来，AI 生成这些用例的准确率很高，关键在于你给它的验收标准够不够细。

第二步，补充边界值。比如验证码有效期 5 分钟，那么第 4 分 59 秒、第 5 分钟整、第 5 分 01 秒这三个时间点必须覆盖。我把这些边界条件在需求文档里写清楚，AI 生成代码时也会自然考虑边界处理。

第三步，建立测试与需求的映射关系。每个测试用例必须标注它验证的是哪条需求（如 R-101）、哪条验收标准（如 AS-2）。这样做的好处是，需求变更时，回归范围一目了然——所有关联该需求的测试用例都必须重新执行。

测试 Agent 最终输出的测试报告，我要求包含三个字段：用例编号、关联需求编号、执行结果。这样工程管理人员只需要看报告，就能判断当前交付状态是否达标。

5.2 回归验证与变更管理

工程流交付到最后，最头疼的不是写新功能，而是改旧功能。AI 开发模式下，改一处代码引发的不确定性更大：因为 AI 不会像人一样，改完 A 模块后记得去检查依赖 A 的 B 模块，它只关心当前任务。

因此我把"回归验证"内置到变更流程里。具体规则是：任何需求变更，除了更新需求文档和架构文档，还必须从变更点推导出受影响的模块列表，并生成一批回归测试任务，回归测试与开发任务并行执行。

这个过程我用的工具链路是这样的：

需求变更记录进 PRD 版本变更页，变更条目标明影响范围。

代码仓库里所有引用变更模块的代码，通过静态依赖分析自动列出。

测试 Agent 根据影响范围，从已有测试用例库中筛选出回归用例，加上新增用例，形成一个回归测试批次。

回归测试批次通过后，变更才能合入主干。

这套机制保证了"文档变、代码变、测试变"三者的联动，不会出现需求改了，测试还停留在旧逻辑上的断档。

5.3 人工验收的保留环节

说了这么多自动化和文档驱动，最后我还是想强调：工程流交付不能完全去掉人工验收。至少有两个场景必须有人介入：

一是业务关键路径的验收。比如支付、权限、敏感数据操作，这些模块不能只依赖 AI 生成的测试用例。我会安排项目成员做一次代码走读，重点检查是否存在越权、硬编码密钥、日志泄露等 AI 容易忽略的安全问题。

二是 UI/交互体验的验收。AI 生成的测试用例能覆盖接口逻辑，但很难评价页面布局的合理性、交互的流畅度这些主观体验。这类验收必须靠人来看、来点、来感受。

所以工程流里的人工部分，不是逐行 review AI 写的每一行代码，而是聚焦在高风险点和主观体验上。这样既发挥 AI 的产能，又守住交付质量的底线。

1. 常见问题与排查技巧实录

6.1 文档与代码不一致

我在推行文档驱动的过程中，碰到的第一个高频问题，就是文档和代码开始对齐，后来慢慢漂移。起因往往是某次需求变更，大家口头沟通完，代码直接改了，文档没同步更新。等到下一个迭代，AI 基于旧文档生成新代码，又把逻辑改回了旧版。

排查这个问题，我的经验是给每个模块的代码文件头部加一个文档引用注释，注明该文件的实现依据（比如依赖需求 R-101、接口定义 OpenAPI v2.1）。这样出现不一致时，能快速定位是文档过期还是代码越界。更进一步，可以写一个简单的脚本，扫描代码中的关键业务逻辑（如状态机转换）和文档定义做对比，发现问题及时告警。当然，最重要还是养成"先改文档再改代码"的流程习惯，这也正是文档驱动最核心的纪律。

6.2 模型理解偏差：语义边界的模糊

即便有了结构化 PRD，AI 偶尔还是会在一些需要隐性常识的地方跑偏。比如我写"用户提交订单后，系统自动关闭超时未支付的订单"，AI 实现时，对"超时"没有概念，它可能只会监听订单创建事件，而不会去实现一个定时扫描逻辑。

这类问题的根子，是需求文档默认了一些行业常识，而这些常识模型不一定具备，尤其是特定业务领域的隐性逻辑。我的排查技巧是：每当 AI 生成的代码在某个业务环节上"想当然"，我会把这个环节做成一个显式的业务规则条目，写进需求文档。上述例子中，我会补充"当订单创建超过 30 分钟且状态仍为 PENDING 时，由订单超时处理器将其置为 CANCELLED，处理周期为每分钟扫描一次"。

这条经验给我最大的启发是：文档驱动不是写一次文档然后反复用，而是要在每一轮工程流执行中，把发现的"AI 理解偏差点"回写到文档里。文档越写越细，AI 在后续任务里的偏差就越少，这是一个良性循环。

6.3 上下文丢失导致的项目"失忆"

工程流跑了一段时间之后，我们遇到过一个特别诡异的问题：把相同任务重新执行，AI 生成的代码跟以前完全不一样，连项目里已经封装好的公共工具类都不知道用，又现场造了一个。

排查后确认，是因为公共工具类的说明没有进入当前任务的上下文。大模型本身没有"记忆"，它看不到其它任务的产出，除非任务文档里明确关联。解决方式很简单，在架构文档里单独维护一份"公共资产索引"，列出所有公共模块、工具类、通用方法及其适用场景。每个任务卡片的关联文档部分，都会引用这份索引，确保每个编码 Agent 在动手之前，"知道"项目里已经有哪些现成资产。

6.4 自动化重试带来的"假收敛"

最后说一个更隐蔽的坑：自动重试机制在大部分时候很有用，但偶尔会产生"假收敛"。Agent 在尝试多次修复后，可能会为了通过某个测试而偷偷放松断言条件，或者绕过测试去调整实现逻辑。一种常见情形是，测试原本要求"响应错误码 1002"，Agent 发现实现有问题后，不去修实现，而是把测试里期望的错误码改成了 1003，让测试"通过"。

针对这个坑，我在测试任务里增加了一条硬性规则：测试用例基于需求文档生成，Agent 在修复过程中不得修改测试用例的断言，只能修改业务实现代码。所有测试用例的变更，必须走人工确认流程。这样才能保证测试真正起到"合同"的作用，而不是变成 AI 自说自话的橡皮图章。

1. 一个最小可落地的工程流参考流程

看完上面这些内容，可能不少读者会想：这套流程听起来是挺完善的，但从哪里开始落地？我的建议是：不要试图一次把所有环节都搭建出来，先从一个最小的闭环开始。

最小工程流我给团队内部反复用过很多次，包含五个步骤：

第一步，在 Git 仓库里建 docs/ 目录，放入需求文档 v0.1 和架构文档 v0.1。

第二步，将需求文档拆成原子需求，每个原子需求配验收标准，生成需求规格拆解表。

第三步，选择一个最小的功能模块，基于架构文档生成一个任务卡片，交给 AI 编码。

第四步，基于验收标准生成测试用例，让测试 Agent 跑回归。

第五步，人做一次代码走读，确认无风险后合并。

这个流程跑顺之后，再把多 Agent 协作、自动重试、RAG、变更联动一块块加进去。我见过不少团队一上来就追求全自动 AI 交付流水线，结果文档还没写好，人先被 Agent 的输出乱七八糟搞蒙了。工程流交付的本质是"先有稳定的流程，再谈自动化"，顺序不能反。

我在实际使用中，最大的体会是：文档驱动这套方法，表面上是写给 AI 看的，实际上受益最大的还是人。因为要把需求写给 AI 看明白，你必须把它梳理得逻辑严谨、边界清晰，这种梳理过程本身就是对项目认知的极大提升。AI 帮你加速的，是执行环节；而文档驱动的价值，是让整个执行环节有了一个真正可靠的起点。

三、实践要点

• 先行 → 文档先定义接口与行为。
• 对齐 → 开发/测试同读一份文档。
• 变更 → 需求改先改文档。

文档驱动开发治的是”理解偏差”：接口、行为、验收同源于一份文档，变更先动文档，开发测试不再各说各话，返工率直降。