第四章. BMAD 灵活工作流：现有项目与快速开发

4.1. 场景识别：你的项目属于哪种类型？

在开始之前，先问自己三个问题：

1. 项目状态：这是新项目还是已有代码库？
2. 变更规模：你要做的是小功能还是大重构？
3. 文档完整度：现有项目有没有完整的文档？

根据答案，BMAD 提供了三种主要工作流：

不管是新项目还是老项目，功能规模才是决定工作流的关键因素。

4.2. Quick Flow：小功能的快速通道

Quick Flow 是 BMAD 为 小功能快速开发 设计的精简流程。它跳过了完整的 Analysis 和 Planning 阶段，直接从技术规格开始。

什么时候用 Quick Flow？

我们先看一个对比表：

✅ 适合的场景：

• 在现有系统中添加小功能（比如给用户表加一个字段）
• 需求已经明确，不需要深入分析（比如产品经理已经给了详细的原型）
• 时间紧迫，需要快速交付（比如修复线上 Bug）
• 功能相对独立，不涉及系统架构变更（比如添加一个导出 Excel 的接口）

❌ 不适合的场景：

• 需要多轮需求讨论的大型功能（比如重构整个权限系统）
• 涉及系统架构变更（比如从单体应用拆分成微服务）
• 需要多团队协作（比如前后端分离的大型功能）
• 有复杂的非功能需求（比如性能优化、安全加固）

Quick Flow 的两步走

Quick Flow 只有两个核心步骤：

步骤 1：Tech Spec（技术规格）

这一步的目标是 把需求翻译成可执行的技术任务。

Tech Spec 不是 PRD，它更关注 “怎么做” 而不是 “为什么做”。一份合格的 Tech Spec 必须包含：

1. 验收标准：用 Given-When-Then 格式描述
2. 技术任务：明确的文件路径和操作步骤
3. 依赖关系：任务之间的先后顺序
4. 现有代码模式参考：确保新代码与现有代码风格一致

步骤 2：Quick Dev（快速开发）

这一步的目标是 严格按照 Tech Spec 实现代码。

Quick Dev 的关键特点是 自包含。也就是说，即使你换一个全新的 AI 对话，只要加载 Tech Spec 文件，AI 就能继续实现，不需要读取之前的对话历史。

这解决了什么问题？防止上下文污染。如果在同一个对话中既做规划又做实现，AI 的思维会混乱。但如果用 Tech Spec 作为中间工件，规划和实现就完全分离了。

Quick Flow 的核心代理

Quick Flow 使用一个专门的代理：Quick Flow Solo Dev快速流程专家，负责从技术规格到代码实现的全流程（Barry）。

激活命令：

1

*quick-flow-solo-dev

Barry 的菜单只有 5 个核心命令：

Tech Spec 的关键要素

一份好的 Tech Spec 必须是 可操作的。什么叫可操作？就是一个从未接触过这个项目的开发者，拿到 Tech Spec 后，能直接开始写代码，不需要问任何问题。

我们用一个反例来说明：

❌ 不可操作的 Tech Spec：

1
2
3

## 任务 1：创建角色管理功能

实现角色的增删改查。

这个 Tech Spec 有什么问题？

1. 没有明确文件路径：开发者不知道代码应该写在哪里
2. 没有具体操作：开发者不知道应该创建哪些类、方法
3. 没有参考模式：开发者不知道应该遵循什么代码风格

✅ 可操作的 Tech Spec：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

## 任务 1：创建 Role 实体

**文件**：`src/models/Role.ts`

**操作**：
1. 创建 Role 接口，包含以下字段：
   - id: UUID（主键）
   - name: string（唯一）
   - description: string（可选）
   - createdAt: timestamp
2. 添加 TypeORM 装饰器（参考 `src/models/User.ts` 的模式）
3. 导出 Role 类

**参考**：
- 数据模型模式：`src/models/User.ts`
- TypeORM 装饰器用法：项目已有模式

这个 Tech Spec 的优点：

1. 文件路径明确：开发者知道要创建 src/models/Role.ts
2. 操作具体：开发者知道要创建哪些字段、添加哪些装饰器
3. 有参考模式：开发者知道应该参考 User.ts 的写法

Quick Dev 的执行原则

Quick Dev 在实现代码时，必须遵循三个原则：

原则 1：严格按任务顺序执行

Tech Spec 中的任务是有依赖关系的。比如：

• 任务 1：创建 Role 实体
• 任务 2：实现 RoleService（依赖任务 1）
• 任务 3：创建 API 路由（依赖任务 2）

如果跳过任务 1 直接做任务 2，代码会报错（因为 Role 实体还不存在）。

原则 2：遵循 TDD 原则

每个任务都应该先写测试，再写实现。这确保了代码的可测试性。

原则 3：保持代码风格一致

新代码必须与现有代码风格一致。这就是为什么 Tech Spec 中要包含 “现有代码模式参考”。

Quick Flow 的对抗性审查

Quick Dev 完成后，会进行 对抗性审查。这是 Quick Flow 的一个关键特点。

什么叫对抗性审查？就是让 AI 扮演一个 挑刺的角色，专门找代码的问题。

对抗性审查的规则是：必须找出 3-10 个问题。如果找不出问题，说明审查不够严格，需要重新审查。

这解决了什么问题？防止 AI 自嗨。如果只有一个 AI 生成代码，它可能会觉得自己写得很完美。但如果有另一个 AI 专门挑刺，就能发现很多隐藏的问题。

4.3. 现有项目：棕地项目的处理

大多数情况下，你面对的不是新项目，而是 已有代码库（棕地项目已有代码库的项目，相对于从零开始的绿地项目）。BMAD 提供了专门的工作流来处理这种情况。

棕地项目的三大挑战

挑战 1：缺少文档

很多老项目没有文档，或者文档已经过时。AI 不知道现有代码的架构模式、编码规范、技术栈。

挑战 2：代码风格不一致

老项目可能经过多人维护，代码风格不一致。AI 不知道应该遵循哪种风格。

挑战 3：依赖关系复杂

老项目的模块之间可能有复杂的依赖关系。AI 不知道修改一个模块会影响哪些其他模块。

Document Project：棕地项目的第一步

如果你的项目缺少文档，第一步是 文档化现有项目。

BMAD 提供了一个专门的工作流：Document Project。这个工作流会：

1. 扫描代码库：识别技术栈、架构模式、编码规范
2. 分析依赖关系：找出模块之间的依赖关系
3. 生成文档：创建项目概览、源代码树、架构模式文档
4. 生成 project-context.md：这是 AI 代理理解项目的关键文件

激活 Analyst 代理，选择 [DP]：

1
2

*analyst
[DP] 记录你的现有项目

Document Project 的两种模式

Full Scan 适合第一次接触项目，或者项目规模较大。它会扫描整个代码库，生成完整的项目文档。

Deep Dive 适合已经熟悉项目，只需要深入分析某个模块。比如你要重构用户模块，可以用 Deep Dive 聚焦分析用户模块的代码。

project-context.md：AI 代理的项目手册

Document Project 最重要的输出是 project-context.md。这个文件包含：

1. 技术栈：后端、前端、数据库、工具链
2. 编码规范：文件命名、类命名、错误处理、日志
3. 架构模式：数据访问模式、API 风格、认证方式
4. 关键约定：必须遵守的规则（比如所有数据库操作必须使用事务）

这个文件会被所有 AI 代理自动加载。当 Dev 代理实现代码时，它会参考这个文件，确保新代码与现有代码风格一致。

这解决了什么问题？防止代码风格混乱。如果没有 project-context.md，AI 可能会用自己的风格写代码，导致新代码与老代码格格不入。

棕地项目的工作流选择

文档化完成后，根据功能规模选择工作流：

场景 1：添加小功能（1-5 Story）

使用 Quick Flow：

1
2
3

*quick-flow-solo-dev
[TS] 架构技术规格
[QD] 快速开发实现

Quick Flow 会自动加载 project-context.md，确保新代码与现有代码风格一致。

场景 2：添加大功能（10+ Story）

使用 BMAD Method 完整流程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

*pm
[CP] 创建 PRD

*architect
[CA] 创建架构文档（基于现有架构扩展）

*pm
[ES] 创建 Epic 和 Story
[IR] 实现就绪检查

*sm
[SP] Sprint 规划
[CS] 创建 Story

*dev
[DS] 开发 Story
[CR] 代码审查

注意这里的架构文档不是从零设计，而是 基于现有架构扩展。Architect 会读取 project-context.md，在现有架构的基础上设计新功能的架构。

4.4. 独立阶段启动：项目进行中的灵活应对

有时候项目已经进行到一半，你只需要补充某个阶段的文档。BMAD 允许你 独立启动任意阶段，不需要从头开始。

Workflow Status：项目进度的 GPS

任何代理都可以使用 [WS] 命令检查当前项目状态：

1

[WS] 获取工作流状态或初始化工作流

这个命令会：

1. 扫描项目目录：查找已有的工件（PRD、架构文档、Epic 文件等）
2. 分析完成度：判断每个阶段是否完成
3. 给出建议：告诉你下一步应该做什么

这解决了什么问题？防止重复劳动。如果你不知道项目当前状态，可能会重复创建已有的文档。但如果用 [WS] 检查状态，就能避免这个问题。

独立启动的典型场景

场景 1：有 PRD 但没有架构文档

1
2

*architect
[CA] 创建架构文档

Architect 会读取 PRD，基于 PRD 的需求设计架构。

场景 2：有 PRD 和架构文档，但没有 Epic 和 Story

1
2

*pm
[ES] 从 PRD 创建 Epic 和用户故事

PM 会读取 PRD 和架构文档，拆分成可执行的 Epic 和 Story。

场景 3：有 Epic 和 Story，但没有 sprint-status.yaml

1
2

*sm
[SP] 生成或重新生成 sprint-status.yaml

SM 会读取 Epic 文件，生成 sprint-status.yaml，用于跟踪 Story 的状态。

场景 4：直接开始开发

如果所有文档都齐全，可以直接进入开发：

1
2
3
4
5

*sm
[CS] 创建 Story

*dev
[DS] 开发 Story

独立启动的关键原则

原则 1：检查前置条件

每个阶段都有前置条件。比如创建 Epic 和 Story 需要先有 PRD 和架构文档。如果前置条件不满足，工作流会报错。

原则 2：保持工件一致性

如果你修改了 PRD，需要重新生成 Epic 和 Story。否则 Epic 和 Story 会与 PRD 不一致。

原则 3：使用 WS 检查状态

在独立启动任何阶段前，先用 [WS] 检查状态，确保你知道项目当前的完成度。

4.5. 工作流路径选择指南

BMAD 提供了多种工作流路径，根据项目类型自动选择。我们用一个决策表来总结：

Greenfield 路径（从零开始）

适用于全新项目，完整流程：

1
2
3
4
5
6
7
8
9
10
11

Phase 1: Analysis（可选）
  - 头脑风暴、研究、产品简报

Phase 2: Planning（必需）
  - 创建 PRD、创建架构文档

Phase 3: Solutioning（必需）
  - 创建 Epic 和 Story、实现就绪检查

Phase 4: Implementation（必需）
  - Sprint 规划、创建 Story、开发 Story、代码审查

关键点：Phase 1 是可选的。如果需求已经明确，可以跳过 Analysis，直接从 Planning 开始。

Brownfield 路径（现有项目）

适用于已有代码库的项目：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Phase 0: Documentation（如果缺少文档）
  - 文档化项目

Phase 1: Analysis（可选）
  - 头脑风暴、研究、产品简报

Phase 2: Planning（必需）
  - 创建 PRD、创建架构文档（基于现有架构扩展）

Phase 3: Solutioning（必需）
  - 创建 Epic 和 Story、实现就绪检查

Phase 4: Implementation（必需）
  - Sprint 规划、创建 Story、开发 Story、代码审查

关键点：Phase 0 是 Brownfield 特有的。如果项目缺少文档，必须先文档化，否则 AI 不知道现有代码的架构模式。

Quick Flow 路径（快速开发）

适用于小功能快速迭代：

1
2
3
4
5
6
7
8

Step 1: Tech Spec
  - 架构技术规格

Step 2: Quick Dev
  - 快速开发实现

Step 3: Code Review（推荐）
  - 代码审查

关键点：Quick Flow 只有 3 个步骤，但 Code Review 是强烈推荐的。不要因为追求速度而跳过审查。

4.6. 本章总结与最佳实践

工作流选择的核心原则

原则 1：规模优先

功能规模是决定工作流的第一要素。不管是新项目还是老项目，小功能用 Quick Flow，大功能用完整流程。

原则 2：文档先行

现有项目如果缺少文档，必须先文档化。不要急于开发，否则新代码会与老代码风格不一致。

原则 3：灵活应对

项目进行中可以随时补充缺失的阶段。不需要从头开始，用 [WS] 检查状态，然后独立启动需要的阶段。

原则 4：质量门槛

不管用哪种工作流，代码审查都是必须的。不要因为追求速度而跳过审查。

最佳实践清单

开始任何任务前：

• [ ] 用 [WS] 检查项目状态
• [ ] 判断功能规模（Story 数量）
• [ ] 确认项目是否有文档
• [ ] 根据上述三点选择工作流

使用 Quick Flow 时：

• [ ] 确保需求已经明确
• [ ] 确保功能不涉及架构变更
• [ ] Tech Spec 必须包含文件路径和具体操作
• [ ] 必须进行对抗性审查
• [ ] 推荐使用新对话进行代码审查

使用完整流程时：

• [ ] 不要跳过任何阶段
• [ ] 每个阶段结束后检查工件是否完整
• [ ] PRD 必须通过验证
• [ ] 实现就绪检查必须通过
• [ ] 每个 Story 必须通过代码审查

处理现有项目时：

• [ ] 如果缺少文档，先运行 Document Project
• [ ] 确保 project-context.md 存在且完整
• [ ] 新代码必须与现有代码风格一致
• [ ] 修改现有代码前，先理解依赖关系

常见错误与纠正

我们用一个表格来对比不同工作流的效率：

关键洞察：Quick Flow 不是 BMAD Method 的简化版，而是 针对不同场景的优化版。它们各有适用场景，不存在谁优谁劣。

工作流组合策略

在实际项目中，你可能会 组合使用 多种工作流：

策略 1：先 Quick Flow，后完整流程

适用场景：需求不明确，需要快速验证

流程：

1. 用 Quick Flow 快速实现 MVP（最小可行产品）
2. 验证需求后，用完整流程重构和扩展

策略 2：先完整流程，后 Quick Flow

适用场景：大功能开发完成后，需要快速修复 Bug 或添加小功能

流程：

1. 用完整流程开发核心功能
2. 后续的小功能和 Bug 修复用 Quick Flow

策略 3：混合使用

适用场景：大型项目，不同模块规模不同

流程：

1. 核心模块用完整流程
2. 辅助模块用 Quick Flow
3. 独立阶段启动用于补充文档

关键点：不要教条地使用某一种工作流。根据实际情况灵活选择，甚至可以在同一个项目中混合使用。