1. 为什么需要把业务建模和 AI 编程助手放在一起
先说一个我观察到的现象：最近两年，团队里用 GitHub Copilot 的人越来越多，但同样是用了 AI 辅助编程，产出质量的差距却大到离谱。有的人用 Copilot 一个下午能把一个带校验、带事务、带异常处理的模块搭得整整齐齐；有的人用 Copilot 半小时就生成了看起来像模像样、一跑全是 bug 的代码，Debug 的时间比手写还长。差别不在打字速度，也不在 Prompt 写得漂不漂亮，而在一个很朴素的前提——AI 编程助手需要足够好的上下文，才能生成足够靠谱的代码。而绝大多数团队，恰恰在最该给 AI 提供上下文的地方，什么都没准备。
我自己在做应用开发的时候，一直在用一套叫 BMAD（Business Model Architecture Design）的业务建模方法，目前迭代到 v6 版本。这套方法的核心很简单：在写代码之前，把业务模型拆成角色、服务、数据、事件、规则这些最小单元，再把这些单元固化成"契约"。过去，这套契约主要拿来给架构师评审、给开发人员对齐口径；但现在我发现，它的价值被大大低估了——BMAD v6 产出的结构化契约，正好是 GitHub Copilot 最缺的东西。Copilot 不是没有能力，它缺的是可靠的、机器可读的上下文约束。
拿日常开发里最常见的一个痛点来说：需求文档写的是"用户下单时锁定库存，支付成功后扣减库存，超时未支付释放库存"。这句话听起来很清楚，但代码层面涉及的问题一个都没说清——锁定的粒度到底是 SKU 级别还是订单级别？扣减是同步还是异步？释放库存时如果订单已经部分支付怎么办？这些模糊地带，人类开发者在评审时可能还能凭着经验察觉，但 Copilot 不会替你想。它只会在你的上下文里找线索，有什么用什么。你的注释、接口签名、DTO 结构、枚举定义、异常类型，共同决定了它生成代码的上限。
所以这篇内容我想换个角度来聊：不是单纯讲 Copilot 怎么用，也不是单讲建模方法怎么画图，而是把 BMAD v6 和 Copilot 放在同一条流水线上，讲清楚"业务模型如何变成 AI 能消费的约束""约束如何变成高质量代码"这整条链路是怎么跑通的。适合正在带团队做应用开发的架构师、被 AI 生成代码折磨过的一线开发，以及想搞明白"到底该怎么给 AI 提供上下文"的人。
2. BMAD v6 到底产出了什么东西，和写需求文档有什么区别
先说个容易被误解的地方。很多人一听到"业务建模"，第一反应就是画流程图、画用例图、写一堆 UML 文档，然后这些东西评审完就吃灰了。BMAD v6 从一开始就不想往这个方向走。它强调的是产出"可执行的契约"，而不是"描述性的说明"。
2.1 契约和文档的边界在哪里
描述性的说明长这样：用户可以通过手机号登录，登录成功后进入首页。这种描述是人类友好、机器无感的，Copilot 看到这句话基本不会有什么正向反应，它没法从里面推断出登录接口的入参校验规则，也没法知道验证码错误和账号不存在的错误码应该怎么区分。
BMAD v6 的契约长什么样呢。简单来说，它把业务模型拆成四个层级的产物：
| 层级 | 核心内容 | 对应开发阶段的用途 |
|---|---|---|
| 全局上下文层 | 业务边界、角色清单、核心领域对象 | 确定模块划分和代码结构 |
| 接口契约层 | 每个业务动作的入参、出参、校验规则、错误码 | 生成 Controller、Service 方法签名 |
| 核心实现层 | 业务规则、状态流转、事务边界、并发约束 | 生成 Service 内部逻辑和分支判断 |
| 领域装饰层 | 事件、消息、定时任务、外部系统依赖 | 生成 MQ 生产者消费者、Job 定义和适配器 |
用登录这个例子对应过去：全局上下文里定义"用户"这个核心领域对象，归属"账号域"；接口契约层定义 login 动作的入参是手机号+验证码或手机号+密码，出参是会话 Token，校验规则包括手机号格式、验证码有效期；核心实现层定义密码错误连续五次锁定账号、锁定后 15 分钟不可登录；领域装饰层定义登录成功之后要发送一条登录通知消息。这四层合起来，才算一条完整的、可以被消费的契约。
2.2 为什么 v6 对 AI 尤其友好
BMAD 能迭代到 v6，说明它不是一个空中楼阁式的理论框架，而是被真实项目反复打磨过的东西。v6 相比早期版本，有三个特点和 Copilot 协作特别契合。
第一个特点是决策可编码。v6 不再满足于"把这个规则描述清楚"，而是要求把每个决策落到具体的枚举值、阈值、状态机上。比如"库存锁定超时 30 分钟自动释放"，写成契约字典就变成 LockTimeout=1800（秒），状态机出现 ORDER_PAID/STOCK_LOCKED/STOCK_RELEASED 这些显式节点。对 Copilot 来说，这种内容是金子——它不需要猜测"超时该用多长"，也不需要自己发明状态名。
第二个特点是全局上下文与局部上下文的分离。v6 明确区分了哪些约束是全局生效的（比如整个系统统一错误码格式、统一鉴权方式、统一返回结构），哪些约束是模块内生效的（比如订单模块的库存规则）。这个分离太重要了。因为 Copilot 的上下文窗口是有限的，你不可能把整个系统的模型全丢给它，它看不完，也没必要。BMAD v6 已经帮你切好了"哪些东西是每个模块生成代码时都要带的，哪些东西只有特定模块才需要"。我的做法就是，把全局上下文单独抽成一份 stable.md，作为所有 AI 会话的固定背景；模块级契约按需注入，缺哪块带哪块。
第三个特点是契约的各层粒度适合增量开发。Copilot 这种工具，最适合的工作方式是"分片战斗"——一次只生成一个文件、一个方法、一个测试用例，而不是让你一个提示词里塞超长需求让它一次输出整个系统。BMAD v6 的四层结构天然就提供了这个切片依据：先按接口契约层生成 DTO 和接口签名，再按核心实现层补 Service 逻辑，最后按装饰层补事件和集成代码。每一片都足够小、足够明确，正好落在 AI 能够稳定发挥的工作区间里。
所以 BMAD v6 和普通需求文档的第一个本质区别在于:文档写给人看，重点是传达意图；契约写给机器和 AI 看，重点是消除二义性。第二个本质区别在于：文档是一次性的、评审完就过期，契约是活的、可以逐层消费的。把这套契约整理好之后，Copilot 就不再是一个需要在真空里脑补业务的自动补全器，而是一个能踩着结构化定义干活的实现者。
3. GitHub Copilot 的能力边界，以及它真正需要的输入是什么
想把 Copilot 用好，第一步不是学提示词的技巧，而是搞清楚它的能力边界是什么。这一点上我踩过不少坑，也走了不少弯路。早期我以为 Copilot 是个什么都能干的 AI 程序员，后来发现这么说太笼统了——它更像一个"上下文驱动的联想引擎"。它的核心机制是从你正在编辑的上下文里提取线索，推断你接下来大概率要写什么。这个机制决定了它的强和弱都非常鲜明。
3.1 Copilot 擅长什么、不擅长什么
我总结了一张表，直接说清楚它在应用开发里的能力边界：
| 任务类型 | Copilot 表现 | 原因 |
|---|---|---|
| 标准 CRUD 代码 | 很强 | 模式非常固定，训练数据充足 |
| DTO、VO 之间的字段转换 | 很强 | 纯机械映射，几乎没有业务歧义 |
| 单元测试骨架、测试用例生成 | 较强 | 能根据函数签名推断边界情况 |
| 前端组件、接口调用封装 | 较强 | 依赖本地上下文，看得见接口定义就没问题 |
| 脚手架、基础配置、模板代码 | 很强 | 高度模板化 |
| 复杂业务规则的多分支处理 | 不稳定 | 需要理解规则之间的优先级和互斥关系 |
| 跨模块的数据一致性保障 | 很弱 | 只能看见当前文件，看不见别的模块 |
| 领域模型的抽象和边界划分 | 几乎不擅长 | 这是架构决策，不是代码生成 |
这个表格其实揭示了一件事：Copilot 对"局部确定性"强的任务表现好，对"全局判断型"的任务表现差。CRUD 之所以强，是因为字段、表名、接口签名摆在眼前，模式又高度雷同，它只需要做填空；而跨模块一致性之所以弱，是因为它压根没有另一边的上下文。
3.2 给 Copilot 喂上下文的正确姿势
既然边界清楚了，接下来的问题就是：在我们控制得了的范围内，要把什么喂给它，喂到什么程度。我现在的做法，总结下来是三条红线。
第一，一定给目标，不给方案。很多开发者让 Copilot 写代码时，喜欢在注释里写"请实现一个库存扣减的逻辑，考虑并发，使用乐观锁"，然后让 AI 自由发挥。这个 Prompt 其实是个陷阱。"考虑并发"是一个方案级别的暗示，但到底用乐观锁、悲观锁还是分布式锁，取决于业务场景和已有技术栈。更好的做法是描述目标："库存扣减必须满足：库存量不小于请求量才允许扣减；扣减后剩余量回写库存表；扣减操作与订单状态更新在同一事务内。"至于怎么锁、锁粒度多大，让实现者根据约束自己选——而 Copilot 在有明确约束的前提下，选出来的方案通常不会太离谱。
第二，把隐性的规则变成显性的上下文。这是 BMAD 契约介入的最关键位置。业务规则经常散落在代码注释、需求文档、IM 聊天记录里，Copilot 完全感知不到。比如"优惠券和满减活动互斥"这个规则，如果不写到当前文件的上下文里，Copilot 生成的结算逻辑里就会出现两个折扣叠加的问题。BMAD 契约里的核心实现层，专门把这些规则抽成显性条件，在开发时注入到相关文件。规则在上下文里，AI 看到了，生成的代码就会自然带上这些分支。
第三，按文件粒度组织上下文。我见过最典型的问题，是一个开发者为了让 Copilot 生成一个服务类的完整实现，把一个包含十几个接口、几千行代码的文件整个粘进了对话，结果 Copilot 生成的代码风格混乱、上下文互相干扰，产出质量直线下降。正确的做法是把上下文切成"背景信息"和"当前任务"两部分。背景信息全局稳定，一段话带过；当前任务精确到具体的类、方法、字段定义。BMAD 的四层契约天然可以做这个切分：全局上下文层和接口契约层是背景，核心实现层的规则和领域装饰层的事件定义是当前任务，每次带一小块，生成一块，验收一块。
这里我想强调一下，Copilot 的输入不是越多越好，而是越准越好。上下文越聚焦，输出越稳定。这一点在我把 BMAD v6 的契约引入到工作流之后体会特别深刻——以前我为了一次生成搞半天的 Prompt 优化，现在百分之七八十的时间花在整理契约和质量校验上，Prompt 本身反而变得特别简单，基本就是"背景 + 接口签名 + 规则列表 + 输出要求"四件套。真正把质量拉起来的，不是魔法咒语，而是背景知识的结构化程度。
4. 协同落地的四层路径：从业务契约到代码生成的完整流水线
前面说的都是"为什么要这样"，接下来进入正题：在实际项目里，我是怎么把 BMAD v6 的契约文件和 Copilot 组装成一条可复用的开发流水线的。整个过程可以拆成四层，每一层对应一种不同类型的输入和组织方式。
4.1 第一层：契约注册——让 AI 有据可查
万事开头难，第一层要做的事情是建立契约目录。我的做法是在项目仓库里建一个 contracts 目录，按域来组织，比如 order_contracts.md、user_contracts.md、payment_contracts.md。每个文件的结构是固定的，包括领域概述、角色清单、核心对象定义、接口契约、规则清单、状态机、错误码、领域事件。这一层不需要给 Copilot 看，它是给人看的，也是后续各层取材料的源头。
关键点在于，契约文件必须保持与代码同步更新。只要契约和代码不一致了，后续所有 AI 生成的内容都会建立在错误信息的沙子上。为了维护同步，我有一个笨但有用的习惯：每个契约文件顶部都写上"最近更新日期"和"修改原因"，任何一次需求变更，先改契约，再让 Copilot 改代码。顺序不能反。先让 Copilot 改了代码再来补契约，大概率补出来的东西跟实际行为对不上。
4.2 第二层：全局上下文注入——每个会话的固定背景
有了契约目录之后，第二层要做的是给 Copilot 建一份"全局上下文"文件，我一般叫它 ai_context.md。这份文件不用长，通常控制在 300 到 500 字之间，但必须包含以下内容：
- 项目技术栈：语言、框架、ORM、消息队列、缓存中间件
- 代码风格约定：分层结构、命名规范、异常处理方式、统一返回格式
- 全局错误码规范：通用错误码的枚举和含义
- 鉴权与上下文获取方式：当前用户怎么获取、权限怎么校验
这份文件的作用是"省流"。在 Copilot 的上下文窗口有限的情况下，把它作为每次会话的固定背景，就不用每个文件里反复粘贴同样的技术栈信息了。我实测下来的效果是，这一步能让 Copilot 生成的代码风格和项目现有代码的吻合度显著提高，尤其是命名和包结构这两个重灾区。
实际操作的时候，我不是每次都手动粘贴 ai_context.md 的内容，而是把它配置成项目级注释说明文件，放在 .github/copilot/instructions/ 下面。GitHub Copilot 的官方机制支持给仓库配置自定义指令，这样它会自动读取这些说明文件作为全局上下文。每个会话、每个文件生成时，这些背景约束都会被考虑进去。不需要每个开发者重复粘贴，团队里其他人也能享受到同样的上下文红利。
4.3 第三层：模块任务切片——一次只喂一小块
第三层是实际生成代码时最重要的一步。我称之为任务切片。拿到一个 BMAD v6 契约文件后，不要试图让 Copilot 一口气生成整个模块，而是把它切成五类小任务：
| 任务类型 | 输入材料 | 期望输出 |
|---|---|---|
| DTO/入参校验 | 接口契约层的字段与校验规则 | 请求/响应结构体、校验注解 |
| 数据访问 | 核心对象定义、仓储接口 | Mapper 或 Repository 实现 |
| 业务逻辑 | 契约规则清单、状态机 | Service 方法实现 |
| 事件集成 | 领域事件定义、消息通道 | 生产者和消费者 |
| 测试代码 | 接口签名、正常/异常分支 | 单元测试与边界用例 |
每次任务只喂一份材料。比如做订单的 DTO 时，我会把接口契约里 createOrder 的字段定义直接当作输入，加上一句"请按照字段定义生成请求 DTO，校验规则以注释行的形式标注"。这个任务非常聚焦，Copilot 基本不会跑偏。
做业务逻辑时我会有意识地给出状态机的显式定义，比如"订单状态：CREATED -> PAID -> SHIPPED -> COMPLETED，其中 CANCELLED 可由 CREATED 和 PAID 转移"。有了这个定义，Copilot 生成的 Service 会自然包含状态流转的合法性校验，而不是放一个处处可改的 status 字段。
4.4 第四层：约束回写——让生成代码反向校验契约
这层是我最想强调的，因为我们一般说"模型生成代码"是单向的，但 BMAD v6 和 Copilot 的协同应该是双向的。Copilot 生成代码之后，我的流程不是直接进 Code Review，而是有一个契约校验的环节。
具体做法是，把契约文件里的规则清单逐条列成表格，然后拿生成的代码逐条打勾。像"库存扣减必须校验库存充足""优惠券与满减互斥""锁定超时释放"这样的规则，在代码里都应该能找到对应的 if 判断、状态判断或事务注解。找不到的那一条，就是需要手工修正或者补充提示词的地方。
这一步的好处是，它把"AI 生成代码的正确性"这个问题变成了一个可验证的清单问题。你不需要靠运气去碰代码质量，你可以拿着契约逐条核对，哪条没实现一目了然。我在实际项目中还会把这份校验清单提交到代码评审的附件里，评审的人不需要重新读一遍需求文档，只需要对着清单看代码，效率显著提高了。
5. 从契约元素到代码结构的映射关系，用一个订单模块讲透
要想理解 BMAD v6 和 Copilot 的协同，光知道流程还不够，最关键的是要掌握一张映射表——契约里的每个元素，最终会落到代码的哪个位置。我拿订单模块举个例子，因为订单几乎包含了应用开发里所有典型的业务复杂度，而且大家都有体感。
5.1 六种典型映射关系
| BMAD v6 契约元素 | 代码落点 | 举个例子 |
|---|---|---|
| 业务角色 | Controller、鉴权注解 | 买家、卖家、管理员 --> |
| @PreAuthorize("hasRole('BUYER')") | ||
| 业务动作 | Service 方法 | createOrder、cancelOrder、payOrder |
| 业务对象 | Entity、DTO | OrderEntity、CreateOrderRequest |
| 业务规则 | Service 内部 if、校验、事务 | 库存校验、优惠互斥、金额计算 |
| 状态机 | 状态枚举、状态转换方法 | OrderStatus、transitionTo |
| 领域事件 | 事件类、发布器、消费者 | OrderPaidEvent、OrderEventListener |
这张表的价值在于，它可以被直接变成 Copilot 的生成指令。比如我让 Copilot 生成订单服务时，不是泛泛地写"实现一个订单服务"，而是把表格里对应的内容全部列出来，它会非常自然地按契约元素落位，生出来的代码分层清晰、结构统一。
5.2 完整示例：库存锁定与积分发放的约束注入
直接看一段实际工作中的例子。假设 BMAD 契约里有这样两条规则：
- 规则 A：下单时锁定库存，锁定数量等于订单商品数量；支付成功后才真正扣减库存。
- 规则 B：支付成功后发放用户积分，发放档位按实付金额计算，不足 100 元不发放，满 100 元发放 10 积分，每再满 100 元增加 10 积分。
在没有 BMAD 契约的情况下，我给 Copilot 的提示词可能是"请实现用户下单和支付成功的相关逻辑"。这个提示词太弱了，Copilot 生成的代码大概率只有 CRUD，锁定库存、扣减库存、判断积分门槛这些规则全都要靠人工后期去补。
在引入 BMAD v6 契约模板以后，我的一个典型任务提示词会是这样：
背景：订单模块开发，技术栈 Spring Boot + MyBatis-Plus + Redis。 业务规则（来自 BMAD v6 契约 order_contracts.md）： 1. 下单时锁定库存，LockTimeout=1800秒，超时释放； 2. 支付成功后扣减库存，并向 user_contracts.md 中定义的积分服务发送积分发放命令； 3. 积分发放档位：实付金额满100元发10积分，每增加100元多10分，不足100元不发放； 4. 库存扣减与订单状态更新必须在同一事务内； 5. 优惠券与满减互斥（CF_RULE_001）。 请实现 OrderServiceImpl 中 createOrder 和 handlePaidEvent 两个方法， 事务边界按照规则4设计，积分计算用单独方法封装并附单元测试。这个提示词本身不花哨，但信息密实。Copilot 生成的代码里，createOrder 会带上库存锁定逻辑和 Redis 过期键，handlePaidEvent 会带上事务注解和积分计算分支，还会自动生成一个 calculatePoints 的私有方法。效果稳定得相当明显——这份代码拿回来基本不用大改，评审清单也容易勾。
5.3 为什么状态机定义对生成质量影响这么大
代码生成过程中，我观察到一个特别有意思的现象：只要我在上下文里明确定义了状态机，Copilot 生成的代码质量会明显上升一个档次。原因其实也好理解——状态机是一个强约束，它同时约束了状态字段的类型定义、各种状态转移的合法性判断、非法操作的异常类型。有了状态机，AI 不需要臆测"订单是否能从 CANCELLED 变成 PAID"这种问题，它只需要忠实地把状态转移图翻译成代码。这类强约束越多，AI 发挥的自由空间就越小，出错的可能性也越低。
我还发现一个优化技巧：把状态机定义在注释里，而不只是放在需求文档里。比如在 OrderStatus 枚举的文件头部写上：
// 状态流转约束：CREATED -> PAID -> SHIPPED -> COMPLETED // CREATED -> CANCELLED（买家取消或超时未支付） // PAID -> CANCELLED（仅限退款场景） // 其余状态转移均不合法这个注释既是写的给人看的，也是写给 Copilot 看的。每次在这个文件里补充逻辑，Copilot 都能读到状态约束，生成代码时就会自动带上 while 条件判断、IllegalStateException 抛出逻辑，不需要额外提示。这件事给我的启发是：把契约里最关键的规则，同步复写到对应代码文件的注释里，是最省 token 又最有效的上下文注入方式。
6. 验收环节怎么把关：面向约束的评审清单替代凭感觉的 Code Review
有了 BMAD v6 的契约和 Copilot 生成代码之后，最后一个绕不开的问题是：怎么保证质量？说实话，早期我对 AI 生成代码的态度是"看得过去就收下，过不了就手动改"，后来发现这种凭感觉的评审方式效率很低。因为 Copilot 生成的代码，表面上的规范程度往往很高——命名统一、缩进对齐、异常处理完整——很容易给人一种"代码没问题"的错觉，但深层业务规则到底有没有实现，光看代码很难看出来，必须对着契约逐条核对。
所以我现在参与评审的时候，换了一套做法——面向约束的评审清单。步骤如下：
第一步，从契约文件里抽出规则清单。比如订单模块可能就是上面提到的规则 A、规则 B，再加上"退款不能超过实付金额""取消订单只能由买家操作"等。
第二步，把清单逐条带入生成的代码里找对应实现。规则 A 找库存锁定和扣减逻辑，规则 B 找积分计算的阈值和循环，退款规则找金额上限校验，取消权限规则找角色判断。找到了，打勾；找不到或代码里逻辑不一致，标记出来。
第三步，对没实现或实现错的规则，分两类处理。第一类是 Copilot 没看到约束导致的，处理方式是把约束更显式地补充到上下文里重新生成；第二类是规则本身在契约里就模糊的，这往往不是代码的问题，而是建模的问题，需要回到 BMAD 契约层把定义补充清楚再生成。
下面是我实际用过的一份订单模块评审清单，可以做个参考：
| 契约规则 | 代码对应实现 | 状态 |
|---|---|---|
| 下单锁定库存，1800秒超时释放 | OrderServiceImpl.lockStock() + Redis TTL | 通过 |
| 支付成功扣减库存，与状态更新同事务 | handlePaidEvent() 中 @Transactional | 通过 |
| 积分满100发10分，每增100加10分 | calculatePoints() 中 while 循环 | 通过 |
| 优惠券与满减互斥 | 未找到对应条件判断 | 未通过，已补充上下文重新生成 |
| 取消订单仅限 CREATED 状态 | StateValidator 中有状态判断 | 通过 |
这份清单可以直接附在评审记录里。团队里其他人看到这份清单，不需要重新翻需求文档也能理解评审结论。而且它还会反过来促进契约质量的提升——如果连续几次评审都发现"某条规则在代码里反复找不到"，那大概率说明这条规则在契约里定义得不够清晰，需要回炉重写。把质量校验和建模本身连接起来，这件事以前靠人力评审很难做到，因为人对于"规则没实现"和"规则写得不清楚"的边界往往得过且过。但现在有了一份可以逐条打勾的清单，这个问题就变的很直白。
7. 这几个踩坑场景，基本覆盖了协同过程中的大多数意外
再好的流程设计，实际跑起来也难免遇到各种意外。我在这个组合工作流里踩过不少坑，下面挑几个有代表性的说说，每一个都是真实发生的，不是凭空编的。
第一个坑：契约写得像需求文档，AI 自由发挥的空间太大。刚开始做契约文件时，我写规则习惯了用一句话描述，比如"下单时需要校验库存"，然后把这个丢给 Copilot 生成代码。结果 Copilot 生成的代码确实校验了库存，但用的是直接查库存表的方式，完全没有锁定机制。后来我把规则改成两条定义明确的描述——"锁库存必须写入 Redis，键名 pattern 为 lock:sku:{skuId}:order:{orderId}"和"锁库存数量必须等于商品购买数量"——AI 的生成结果立刻就不一样了。这件事给我的教训是，规则描述和 Copilot 的代码生成质量是直接相关的。你用自然语言给它留一毫米的缝隙，它就能在里面开出一条自由发挥的大路；你把约束写到一百二十分细，它反而能交出高度符合预期的产物。
第二个坑：想让 Copilot 一次生成的东西太多，结果人格分裂。有几次我想偷懒，在一个提示词里塞了订单创建、订单取消、订单退款三个方法的完整实现要求。Copilot 给出的结果表面上看三个方法都写全了，但细看会发现风格极不统一，校验逻辑前一个方法用 if 抛异常，后一个方法用断言，事务一个方法加在类上，另一个方法加在方法上。这个问题的根源，还是我前面说的任务切片。Copilot 适合在单个文件的局部上下文里做高度聚焦的生成，你给它多任务，它就会在多个模式间跳来跳去。后来我严格按 BMAD 的切片原则——一次一个方法、一次一个场景——再也没出现过这种问题。
第三个坑：契约更新后，上下文没有同步更新。这可能是最隐蔽的坑。有一次我们改了契约里的积分发放规则，从"满100发10积分"改成"满200发20积分"，但负责生成代码的开发者没有同步更新自己的上下文，还是用旧规则去生成，结果新代码全是旧规则。这个问题靠 AI 技术本身是没法解决的，纯粹是流程纪律问题。后来我把契约文件放在项目仓库里，凡是改动必须走 MR，MR 描述里必须标注"契约变更，生成代码时需使用最新版本"，才算把这个问题压下来。
第四个坑，也是最容易被忽视的：业务团队和开发团队的语言不一致，导致 AI 吃到的上下文是变味的。BMAD 契约如果由业务人员写，术语可能非常贴近业务语言；如果由开发人员转述，术语可能偏技术化。两者的差异会直接影响 Copilot 生成的代码风格和准确性。比如业务人员说"冻结库存"，开发人员转述成"标记库存状态为锁定"，这两句话在 BMAD 契约里是有语义差别的。为了避免这个问题，我在团队里要求契约文件的措辞保持统一，术语定义不能随意替换，并且任何一次新增术语都要经过建模评审，不能开发人员自己拍板就写进去。
8. 从工具协同到团队效率：整体工作流的最终形态
聊完踩坑，我把整个协同工作流串起来，说说它在实际项目里最终长什么样。我们现在跑得比较顺的开发路径是这样的：需求评审结束后，建模负责人先用 BMAD v6 产出契约文件，提交到 contracts 目录；开发者拿到契约后，把全局上下文文件配置好，按任务切片生成代码；每生成一个方法或一个文件，就对着规则清单打一次勾；最后代码入库前，附上一份约束验收清单。
这一套流程跑通之后，我的感受是：过去很多纯粹的开发时间，本质上都花在了"猜测和确认"上——猜需求里的模糊点，确认规则的优先级，确认状态转移的边界。现在这些模糊点都前置到了契约设计环节，AI 生成的代码天然带着约束分支，人力和提醒都省了一大截。我自己体验下来，一个中等复杂度的业务模块，从契约完成到代码评审通过，时间大概是传统写法的三分之一到二分之一。对于一个每周要交付好几个模块的团队来说，这个提升非常可观。
当然，也不是说这套流程没有成本。最大的成本是学习曲线——熟悉 BMAD v6 的建模理念需要时间，让团队新人理解"契约不是文档而是约束"也需要时间。但我觉得这笔投入是值得的，因为它换来的不是一个看似强大的开发助手，而是一套可以让 AI 稳定发力的工作秩序。
往后的扩展方向，我也在琢磨两个点。一个方向是把这些契约文件直接转化成更严格的机器可读格式，比如 JSON Schema 或 OpenAPI 定义，让 Copilot 生成代码之前能先通过轻量校验确保契约结构没问题。另一个方向是把约束验收清单自动化，抽取规则描述和代码实现之间的对应关系，做成半自动的静态检查工具。这两件事都不难，但都需要把 BMAD 契约的粒度再往细里打磨。从 v1 到 v6 的过程里，我最深刻的体会是：建模方法不是用来画漂亮的图让人欣赏的，它的终极价值就是成为人和 AI 之间一门共同讲得清楚的语言。
