V模型遇上AI编程：8阶段门禁检查的落地实践

AI编程的"快乐老家"：跳过设计直接写代码

你有没有这样的体验？

打开AI编程工具，丢一句"帮我做个用户管理模块"，Agent唰唰唰开始写代码，文件一个接一个往外蹦，看着特别爽。十分钟后，一个完整的功能就摆在你面前——能跑，界面也像模像样。

你很开心，觉得AI编程真香。

但第二天问题来了。产品说"用户管理要加个角色字段"，你让Agent加，它加了。第三天，测试说"这个接口返回结构和文档对不上"，你查了一圈发现根本没有文档。第四天，前端联调报错，因为后端悄悄改了接口契约，没人通知。

一周后你回头看这个模块，发现一个残酷的事实：代码是写出来了，但没人知道它为什么这么写、改过哪些地方、该怎么测、该回到哪里去改。

这就是AI编程的"快乐老家"——跳过设计直接写代码，短期爽，长期疼。

我在栖睦项目早期踩过一模一样的坑。Agent写代码太快了，快到你来不及想"这个功能到底要满足什么需求""接口契约该谁定""改了代码要不要更新设计文档"。等你反应过来，技术债已经堆成山。

后来我们做了一个决定：把传统软件工程里的V模型搬进来，给AI编程套上8阶段门禁检查。

不是说V模型有多高级，而是AI Agent太容易"一路狂奔"了，必须有东西拦着它，逼它在每个阶段停下来、验一把、再往下走。

转发钩子：如果你也享受过"AI十分钟写完一个模块"的快乐，然后被"改不动、测不了、文档全没有"折磨过，转发这篇给队友。后面讲的8阶段门禁，专治这种"快乐老家后遗症"。

V模型基础：8阶段从需求到验收的对称结构

先快速过一下V模型是什么。

传统V模型长这样：左边往下走是设计和编码，右边往上走是测试和验收，左右对称，每一层设计都有对应的测试兜底。栖睦项目把它适配到AI编程场景，拆成了8个阶段：

L1 需求分析(阶段1) ───────────────────────── 阶段8 验收测试(L1) │ │ L2 概要设计(阶段2) ─────────────────────── 阶段7 系统测试(L2) │ │ L3 详细设计(阶段3) ─────────────────────── 阶段6 集成测试(L3) │ │ L4 编码(阶段4) ──────────── 阶段5 单元测试(L4)

逐个解释：

• 阶段1（L1需求）
  ：写需求文档，定义功能清单和验收标准。说白了就是"这个功能要做成什么样、怎么算合格"。
• 阶段2（L2概要设计）
  ：架构设计、技术选型、模块划分。决定用什么框架、分几个模块、模块间怎么通信。
• 阶段3（L3详细设计）
  ：接口契约、数据结构、API定义。这个阶段要产出能直接指导编码的文档，比如"用户接口返回 {id, name, role} 这三个字段"。
• 阶段4（L4编码）
  ：代码实现，严格遵循设计文档。Agent在这个阶段只能照着L3的契约写，不能自己发明接口。
• 阶段5（L4单元测试）
  ：typecheck + lint + 单元测试。和编码同层，是编码的"左臂"。
• 阶段6（L3集成测试）
  ：模块间集成、API联调。和详细设计同层，验证接口契约是否真的对得上。
• 阶段7（L2系统测试）
  ：端到端测试、Playwright E2E。和概要设计同层，验证整体架构是否成立。
• 阶段8（L1验收）
  ：用户验收，对照需求文档。和需求同层，验证"做出来的东西是不是用户要的"。

这个对称结构的关键在于：每一层测试都有一层设计给它兜底。L3集成测试发现接口对不上？回到L3详细设计查契约。L1验收发现功能不对？回到L1需求查清单。不会出现"测试失败了不知道该回哪改"的窘境。

转发钩子：V模型不是新概念，但"8阶段对称结构"在AI编程里特别能打——因为它让Agent知道"测试挂了该回哪一层"。把这个图截给你的团队看，比开三次会都管用。

门禁检查：每个阶段推进前必须过的关

V模型的灵魂不在那8个阶段的名字，而在阶段与阶段之间的门禁检查。

什么叫门禁？就是你想从阶段4进到阶段5，不是"代码写完了就行"，而是必须满足一组硬性条件。条件没满足，门不开，Agent不能往下走。

栖睦项目目前落地了三道关键门禁：

阶段5→6的门禁（编码到集成）： - typecheck 0错误 - lint通过 - 单元测试覆盖率 ≥ 80%（领域层 ≥ 95%）

这条门禁拦的是"代码质量"。Agent写完代码，自动跑这三个检查，有一个不过就在阶段5打转，修到过为止。TS严格模式还有额外约束：禁止any类型、禁止@ts-ignore。C#领域层更狠：必须是纯函数，无状态。这些不是建议，是硬门槛。

阶段6→7的门禁（集成到系统）： - 集成测试通过 - API契约一致（前后端接口定义对得上）

这条门禁拦的是"接口漂移"。AI编程里最常见的坑就是后端Agent悄悄改了返回字段，前端不知道，联调时炸雷。门禁检查会对比L3详细设计里定义的契约和实际代码，对不上就拦住。

阶段7→8的门禁（系统到验收）： - E2E测试通过 - 性能达标

这条门禁拦的是"整体可用性"。端到端跑通整个用户流程，性能达到预定指标，才能交给用户验收。

实际效果怎么样？我拿数据说话。

引入门禁检查之前，我们项目的类型错误平均要到集成测试阶段才被发现，这时候代码已经写了好几天，回改成本很高。引入门禁之后，类型错误在阶段5单元测试就被拦住，发现时间平均提前了2.5天。

lint问题更明显。以前lint报错经常被忽略，因为"功能能跑就行"。现在门禁不过就不让推进，lint问题从"改不完的债"变成了"必须当场解决的债"。

转发钩子："门禁检查"听起来很重，但它救的不是流程，是你的回改成本。类型错误早发现2.5天和晚发现2.5天，差的是一个通宵还是按时下班。转发给那个总在联调时通宵改Bug的同事。

RTM追溯：让每个commit都能追溯到需求

门禁检查解决的是"质量关"，但还有一个更隐蔽的问题：改着改着，没人记得这个功能当初是为啥做的了。

传统团队靠口头沟通和会议纪要撑着，AI编程场景下这招完全失效——Agent没有"记忆"，它只看当前上下文。今天加了个字段，明天改了个接口，没人记录为什么改、改了什么、关联哪个需求。两周后回头看代码，就是一笔糊涂账。

我们的解法是RTM（Requirements Traceability Matrix，需求追溯矩阵）。

核心思路很简单：给每个阶段的产出物编号，然后用追溯链串起来：

REQ（需求）→ SD（概要设计）→ DD（详细设计）→ CODE（代码）→ TC（测试用例）

举例子： - L1需求阶段产出 REQ-001：用户管理模块支持角色字段 - L2概要设计产出 SD-001：用户模块架构设计，关联 REQ-001 - L3详细设计产出 DD-001：用户接口契约定义，关联 SD-001 - L4编码阶段，commit message 必须写 [backend] feat: 用户模块支持角色字段 (REQ-001, DD-001) - 测试阶段产出 TC-001：角色字段CRUD测试，关联 REQ-001

这样一来，随便拎出一个commit，都能顺着编号一路追回它对应的需求。反过来，随便一个需求，也能查到它被哪些代码、哪些测试覆盖了。

关键执行细节有三条：

第一，commit message强制关联编号。 这不是建议，是规则。栖睦项目的Git提交规范明确要求：提交信息格式为 [模块] type: 描述，必须关联REQ/SD/DD/TC编号。没编号的commit在review时直接打回。

第二，追溯链断链检测自动化。 我们写了个 rtm-traceability-check 的检测工具，专门扫描"REQ→SD→DD→CODE→TC"这条链有没有断。比如某个需求有REQ编号但没有对应的TC测试用例，或者某段代码commit里关联了DD编号但DD文档根本不存在，都会被报出来。

第三，编号规范统一定义。 49份工作流规范文档里专门有一份"V模型文档编号规范定义"，规定了REQ/SD/DD/TC的编号格式、命名规则、存放路径。31条规则文件（.trae/rules/目录下）则把"必须关联编号"这条硬约束写死。

实际效果：现在我们随便翻一个commit，5秒内就能知道它对应哪个需求、哪个设计文档、哪些测试。排查"这个功能为什么这么做"的时间，从以前的翻半天聊天记录，变成了查一下追溯矩阵。

转发钩子：RTM追溯矩阵这东西，大公司都有，但小团队和AI编程场景几乎没人做。原因很简单——人手动维护太累。但如果你让Agent在commit时强制带编号、再用工具自动检测断链，维护成本几乎为零。转发给团队里管质量的同学，这套方法可以直接抄。

双环反馈：测试失败时该回退到哪一层？

门禁检查会拦住不合格的代码，但拦住之后呢？测试失败了，该回到哪一层去修？

这里有个很容易踩的雷：跨层修改。

举个例子。集成测试（阶段6，L3层）发现接口返回结构和契约对不上。正确做法是回到L3详细设计，修正契约定义，再改代码。但AI Agent的"本能"是直接改代码——它在L4编码层待着，顺手就把代码改了，连契约文档都不看一眼。

结果就是：代码改了，契约文档还是旧的，下次集成测试还是对不上。更糟的是，Agent可能在改代码的时候顺手改了L1需求里没有的东西，把整个追溯链搞乱。

为了治这个病，我们引入了双环反馈机制：

内环G1（同层修复）：L4单元测试或L3集成测试失败时，只在同层左臂修复，严禁跨层修改L1/L2。

什么意思？单元测试挂了，就在L4层改代码，不能动L1需求文档和L2概要设计。集成测试挂了，就回到L3层修契约和代码，不能动L1/L2。内环修复不需要人介入，Agent自己跑：失败→分析原因→修复→重新验证，循环直到通过，最多重试3次。

外环G2（跨层跃迁）：L1验收不达标，说明需求层面就有问题，需要跨层跃迁回L1重新定义需求。

这种情况下不能让Agent自己搞，因为"需求到底该改成什么样"是业务决策，必须人确认。所以外环G2的规则是：报告用户，跨层跃迁需用户确认，必须提供RTM追溯和迁移脚本。

举个真实场景。我们做"通知偏好设置"功能，验收时产品说"不对，用户应该能按通知类型分别设置开关，不是一个总开关"。这是L1需求层面的偏差，属于外环G2。Agent不能自己拍脑袋改需求，而是报告用户，列出"当前需求定义、需要改成什么、影响哪些SD/DD/CODE/TC"，用户确认后再走跨层修改流程。

双环反馈的核心价值：把"测试失败"从"Agent自由发挥"变成"有规矩的回退"。内环自己修，外环人来定，界限清清楚楚。

转发钩子：测试失败时最怕的不是Bug本身，而是"不知道该回哪层改"。双环反馈机制用一句话解决：同层能修的自己修，跨层要改的必须人来定。转发给你的技术负责人，这套机制能省掉一半的"越改越乱"。

8步闭环：从安全护栏到提交收尾

V模型的8阶段是大框架，但具体到一个任务怎么跑完，我们还有一套8步闭环工作流。可以理解成V模型的"操作手册"：

第0步：安全护栏 → git status确认工作区、扫描活跃任务、检查冻结目录 第1步：识别输入 → 判断是需求/Bug/变更/重构/CodeGen哪类 第2步：识别阶段 → 判断该从V模型哪个阶段切入、内环还是外环 第3步：查阅文档 → 读主文档、构建验收Rubric草稿 第4步：分解任务 → TodoWrite列步骤、显式列出验收清单 第5步：选模式 → 串行执行 or 并行worktree+subagent 第6步：执行 → 按场景模板跑（新功能/Bug/变更/重构/CodeGen各有一套） 第7步：验证 → 跑门禁检查，失败自动回流修复，最多3次 第8步：收尾 → commit、更新RTM、git status确认无意外变更

这里有几个细节值得说道。

第0步的安全护栏不是走过场。 我们曾经出过一次严重事故：清理临时目录时路径配错了，Remove-Item -Recurse -Force 误删了 docs/ 下两天的设计文档，靠git和回收站才恢复。从此以后，任何涉及删除的操作前必须先 git status，路径包含 docs/src/backendprj 等敏感目录必须二次确认。还有一条铁律：git clean 禁止带 -x（会连node_modules一起删），必须带也得加 -e node_modules 且先干跑预览。

第4步必须显式列出验收清单。 这条是闭环的核心。不能做完才想"怎么验证"，而是在分解任务时就写清楚Rubric。比如"用户管理模块"的验收清单：typecheck零错误、单元测试覆盖率≥80%、无any类型、RTM编号已关联。清单写死了，第7步验证才有依据。

第7步的自动回流是省精力的关键。 typecheck报错？Agent自己分析错误、自己修、自己重跑，不用你盯着。我们设了重试上限：同一类错误自动修复不超过3次，超了就停下来报告"剩余错误、已尝试的修复、需要你决策的点"。既保证Agent能自主闭环，又不会陷入死循环。

转发钩子：8步闭环里最容易被忽略的是第0步和第4步——安全护栏和验收清单。一个是保命，一个是保质。很多团队AI编程翻车，翻的就是这两步。转发给团队，建议把这两步直接写进你们的Agent规则文件里。

AI适配：传统V模型在AI编程场景的4个关键改造

讲了这么多，你可能会问：V模型是几十年前的东西了，直接套到AI编程上，能行吗？

答案是：不能直接套，必须改造。栖睦项目做了4个关键改造。

改造1：门禁检查强制"先设计后编码"

传统V模型里，"先设计后编码"是靠人的自觉和流程规范。AI编程场景下，Agent完全没有这个自觉——你给它需求，它第一反应就是开始写代码，设计文档是啥？不认识。

所以我们的门禁检查把"设计完成"做成了编码的前置硬条件。进入阶段4编码前，必须通过7项就绪检查：PRD完成、设计完成、任务分解、依赖排序、风险评估、测试规划、RTM建立。任何一项没过，门禁不开，Agent碰不到代码。

这条改造直接消灭了"AI跳过设计直接编码"的老毛病。

改造2：RTM追溯强制关联

传统团队靠人记得更新文档和追溯关系，AI编程场景下Agent没有这个记忆。我们的改造是：commit message强制带编号 + 自动断链检测工具。Agent不写编号？commit规范打回。写了编号但链断了？检测工具报红。用规则和工具替代人的记忆。

改造3：双环反馈约束跨层修改

传统V模型的回退靠人判断"这个Bug该回哪层"。AI Agent的判断力不够，容易乱跨层。双环反馈用规则把回退路径锁死：内环同层修，外环人来定。Agent不需要自己判断该不该跨层，规则替它判断了。

改造4：验证失败自动回流

传统V模型里，测试失败后是人去改、人去重测。AI编程场景下，Agent有能力自己改自己测。我们的闭环工作流第7步把这件事自动化了：失败→分析→修复→重跑，循环到通过或重试上限。这条改造把"人盯Agent"变成了"Agent自己闭环"，是省精力的最大来源。

总结一下这4个改造的逻辑：传统V模型靠人的自觉和规范，AI编程场景下用门禁、追溯、双环、自动回流这4套机制，把人的自觉变成Agent的约束。

转发钩子：传统V模型套到AI编程上会"水土不服"，核心原因就一个——Agent没有自觉。这4个改造的本质，是用机制替代自觉。如果你在做AI编程，这4条建议直接抄作业。

实操建议：如何在小团队落地V模型

最后给点落地的实操建议，尤其是小团队。

第一，不要一上来就上全套。

8阶段、8步闭环、RTM追溯、双环反馈，看着就头大。我的建议是分三步走： - 第一步：先上"门禁检查"。挑你最痛的一个环节（比如类型错误发现太晚），加一道typecheck门禁。见效最快。 - 第二步：加上"验收清单前置"。分解任务时必须列出Rubric，不列不给开工。这一个动作就能消灭大量返工。 - 第三步：再上RTM追溯和双环反馈。等团队习惯了门禁和验收清单，再引入编号体系和回退规则，阻力会小很多。

第二，门禁检查要自动化，别靠人盯。

门禁检查如果靠人手动跑命令、手动判断过没过，那跟没有差不多——人一定会偷懒。栖睦项目的做法是把门禁检查写进Agent的规则文件（.trae/rules/目录下31条规则），Agent每次推进阶段前自动跑。人只看结果，不参与执行。

第三，RTM编号从最小编号开始。

不要一上来就搞REQ/SD/DD/TC全套编号体系，太重。先从commit message带需求编号开始，能追到需求就行。等追溯习惯了，再逐步加设计编号、测试编号。

第四，安全护栏不能省。

听起来跟V模型没关系，但AI编程场景下，Agent操作文件的能力太强了，一次路径错误就能删掉几天的工作成果。第0步的 git status 确认、敏感目录二次确认、删除前Test-Path，这些看着繁琐，但都是用血泪换来的。栖睦项目因为没做安全护栏，误删过文档、误删过node_modules、误删过整棵设计目录树。别重蹈覆辙。

第五，接受"前期慢，后期快"。

V模型门禁检查最大的体感是"前期变慢了"——以前丢需求给Agent十分钟出代码，现在要先写需求文档、设计文档、验收清单。但后期会快回来：返工少了、Bug发现早了、联调不炸雷了、改需求知道改哪了。我们实测，引入完整V模型门禁后，单个功能从"开始做"到"通过验收"的总周期，反而缩短了约30%——因为省掉了大量后期返工和排查时间。

转发钩子：小团队落地V模型最大的误区是"全套上"。记住三步走：先门禁、再验收清单、最后追溯。先解决最痛的那个点，见效了再扩。转发给你们的Tech Lead，这篇够开一次落地讨论会了。

写在最后

V模型不是什么高深的东西，它的价值在AI编程场景下反而被放大了——因为AI Agent太需要"被约束"了。

跳过设计直接编码、忘记更新文档、跨层乱改、堆积技术债，这些AI编程的通病，根源都是"缺约束"。8阶段门禁检查做的事情，就是把这个约束具象化：每个阶段有产出要求、阶段之间有门禁、追溯链不断、回退有规矩。

它不会让AI编程变慢，它让AI编程变得可控。

你不需要照搬栖睦项目的49份规范文档和31条规则文件。你需要的是理解背后的逻辑：给Agent设目标，给阶段设门禁，给追溯设编号，给回退设规矩。 做到这四点，你的AI编程体验会从"快乐老家"变成"快乐且可控的老家"。

下篇我们聊聊Codegen（代码生成）怎么和V模型配合，让"实体变了前端自动同步"这件事真正跑起来。敬请关注。

转发钩子：这篇是"项目复盘"系列第7周的内容，整个系列从AI编程实战一路复盘到工程化落地。如果你觉得有用，转发到团队群里，一起把AI编程从"能跑"做到"可控"。