第三章. BMAD 四阶段工作流：从需求到上线

🗺️ BMAD 方法论概览

3.1. Analysis 阶段：把模糊想法变成可执行需求

这个阶段的目标是 回答三个问题：我们要做什么？为什么要做？怎么判断做成功了？

启动 Analyst 代理

在 Claude Code 中打开一个新对话，输入：

1

*agent analyst

或者简写：

1

*analyst

系统会加载 _bmad/bmm/agents/analyst.md 文件，激活需求分析师角色（Mary）。这时你会看到：

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

📊 Business Analyst (Mary) 已激活
我将帮助你把模糊的想法变成清晰的需求。

菜单：
[MH] 重新显示菜单帮助
[CH] 与代理聊天（在当前会话与分析代理聊天）
[WS] 获取工作流状态或初始化工作流（可选）
[BP] 引导式项目头脑风暴会话（可选）
[RS] 引导式研究（市场、领域、竞品或技术研究）（可选）
[PB] 创建产品简报（推荐作为PRD的输入）
[DP] 记录你的现有项目（可选，但推荐用于现有项目）
[PM] 启动派对模式
[DA] 解散代理

注意：代理激活后会立即加载 _bmad/bmm/config.yaml 配置文件，读取项目名称、输出文件夹、用户名、沟通语言等设置。

WS（Workflow Status）

一个轻量级状态追踪工具，专门用来回答一个关键问题：

“我现在该做什么？” 🎯

🔍 它具体做什么？

1. 读取状态文件 — 它会查找 bmm-workflow-status.yaml 文件，里面记录了项目的整个工作流程进度
2. 展示当前状态 — 告诉你：
   - 项目类型和级别
   - 已完成的工作流
   - 待处理的工作流
   - 可选的工作流
3. 指引下一步 — 明确指出：
   - 下一个该做的工作流是什么
   - 应该调用哪个代理 来执行
   - 具体的命令是什么
4. 管理进度 — 允许你：
   - 标记工作流为「已完成」

- 跳过某些工作流

- 查看完整的状态文件

想象一下，你正在做一个大型项目，涉及需求分析、架构设计、测试等多个阶段… WS 就像一个进度灯塔 ，随时告诉你现在在哪里、下一步要去哪里！

头脑风暴：挖掘真实需求

第一步是进行头脑风暴。在 Analyst 代理的菜单中，选择 [BP] 或输入 BP（支持模糊匹配）。

Analyst 会启动 _bmad/core/workflows/brainstorming/workflow.md 工作流，开始引导式头脑风暴：

1
2
3

让我们开始头脑风暴会话。我会使用多种创意技巧来帮助你探索想法。

首先，请用一句话描述你的项目想法：

Analyst 的提问方式：它不问 “你想要什么功能”，而是问 “你遇到了什么问题”。

这解决了什么问题？防止需求蔓延。如果直接问 “你想要什么功能”，产品经理会列出 20 个功能。但如果问 “你遇到了什么问题”，他会聚焦在核心痛点上。

假设你回答：

1

我想做一个用户权限管理系统，因为当前权限分配太随意，没有审计记录。

Analyst 会继续追问：

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

很好！让我们深入挖掘一下：

1. "权限分配太随意" 具体指什么？
   - 是任何人都能改权限？还是权限变更没有审批流程？
   - 有没有发生过权限相关的安全事故？

2. 谁在使用这个系统？
   - 内部员工？外部客户？还是两者都有？
   - 不同角色的权限需求有什么不同？

3. 审计记录需要保留多久？
   - 是永久保留？还是只保留最近 6 个月？
   - 需要满足哪些合规要求？

这个过程会持续多轮对话，Analyst 会使用不同的创意技巧（从 brain-methods.csv 中加载），确保探索足够深入。

研究：市场与竞品分析

头脑风暴后，如果需要更深入的研究，可以选择 [RS] 启动研究流程：

1

[RS] 引导式研究

Analyst 会启动 _bmad/bmm/workflows/1-analysis/research/workflow.md，引导你进行：

• 市场研究：目标市场规模、趋势、机会
• 竞品分析：主要竞争对手的功能对比
• 技术研究：实现方案的技术可行性

研究结果会保存到 {output_folder}/analysis/research-{date}.md。

创建产品简报

头脑风暴和研究结束后，选择 [PB] 创建产品简报：

1

[PB] 创建产品简报

Analyst 会启动 _bmad/bmm/workflows/1-analysis/create-product-brief/workflow.md 工作流。这个工作流使用 step-file 架构，逐步执行：

步骤 1：初始化

1
2
3
4
5
6
7
8

我将创建一份产品简报，包含以下部分：
- 项目背景
- 目标用户
- 核心问题
- 成功指标
- 范围边界

准备好了吗？

步骤 2-N：逐步构建

工作流会按顺序加载 steps/step-01-init.md、step-02-xxx.md 等文件，每个步骤：

1. 读取完整的步骤文件
2. 按顺序执行所有指令
3. 等待用户输入（如果有菜单）
4. 更新文档的 frontmatter 中的 stepsCompleted 数组
5. 加载下一个步骤文件

关键规则：

• 🛑 绝不 同时加载多个步骤文件
• 📖 总是 在行动前完整读取步骤文件
• 🚫 绝不 跳过步骤或优化顺序
• 💾 总是 在完成步骤后更新 frontmatter

所有步骤完成后，Analyst 会生成一份产品简报：

1
2
3
4
5
6
7
8
9

---
stepsCompleted: [1, 2, 3, 4, 5, 6]
date: 2025-01-15
---

# 产品简报：用户权限管理系统

## 项目背景
当前系统缺少统一的权限管理机制，导致权限分配混乱...

这份文档会自动保存到 {output_folder}/planning/product-brief-{date}.md（路径由 config.yaml 中的 planning_artifacts 配置决定）。

派对模式 (Party Mode) 是什么

想象一下——一场多位专家代理齐聚一堂的头脑风暴盛宴！这是一个多代理协作讨论模式，让所有已安装的 BMAD 专家代理们参与进来，各自发挥专长，进行自然流畅的集体对话！

🤖 它如何运作？

1. 集结专家团队 — 派对模式会加载所有 BMAD 代理的名单（比如 Mary 是商业分析师，还有产品经理、架构师、开发者、用户体验设计师等各路专家）
2. 智能匹配参与 — 根据你提出的话题或问题，系统会智能选择 2-3 位最相关的专家来参与讨论，确保多角度观点的碰撞！
3. 角色扮演对话 — 每个代理都会保持自己独特的性格和专业风格，互相引用、补充、甚至辩论，就像真人团队会议一样生动！
4. 协作解决问题 — 代理之间可以互相提问、建立共识、深化见解，最终为你提供全面、多维度的分析！

从业务分析的角度看，这就像把跨职能团队的专家们聚集在一张桌子旁——战略分析师、产品人、技术大牛、设计达人齐上阵！不同视角的碰撞往往能发现单一视角无法察觉的机会和风险！🔍✨

3.2. Planning 阶段：PRD 与架构文档的双保险

这个阶段的目标是 把需求翻译成两份文档：PRD（给开发看的功能清单）和架构文档（给开发看的技术约束）。

启动 PM 代理

关闭 Analyst 对话，开启一个新对话，输入：

1

*agent pm

或者简写：

1

*pm

系统会加载 _bmad/bmm/agents/pm.md 文件，激活产品经理角色（John）。

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

📋 主菜单
1. [MH] 重新显示菜单帮助
2. [CH] 与代理聊天
3. [WS] 获取工作流状态或初始化工作流（可选）
4. [CP] 创建产品需求文档 (PRD)
5. [VP] 验证产品需求文档 (PRD)
6. [EP] 编辑产品需求文档 (PRD)
7. [ES] 从 PRD 创建 Epics 和用户故事（在架构完成后必需）
8. [IR] 实施准备度评审（  实在实际开始编写代码之前，它会对你的 PRD、架构决策和 Epics & Stories 进行对抗性审查，找出缺失和问题。）
9. [CC] 航向修正分析（实施期间可选，当事情偏离轨道时）
10. [PM] 启动聚会模式
11. [DA] 解除代理

创建 PRD

在 PM 代理的菜单中，选择 [CP] 创建 PRD：

1

[CP] 创建产品需求文档（PRD）

PM 会启动 _bmad/bmm/workflows/2-plan-workflows/prd/workflow.md 工作流。这个工作流是 三模态 的：

如果模式不明确，PM 会询问：

1
2
3
4
5
6
7

PRD 工作流 - 选择模式：

[C] 创建 - 从零开始创建新的 PRD
[V] 验证 - 验证现有 PRD 是否符合 BMAD 标准
[E] 编辑 - 改进现有 PRD

你想选择哪个模式？

创建模式流程：

PM 会按顺序执行 steps-c/step-01-init.md 等步骤文件，引导你：

1. 发现输入文档：自动查找产品简报、项目上下文等
2. 定义愿景：用一句话描述项目成功后的改变
3. 识别用户：主要用户和次要用户
4. 拆分 Epic：将需求组织成大的功能模块
5. 编写用户故事：为每个 Epic 编写详细的用户故事
6. 定义验收标准：每个故事的可测试标准
7. 设置优先级：P0/P1/P2 划分
8. 定义非功能需求：性能、安全、可用性等

关键步骤示例：

步骤 5：编写用户故事

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

让我们为 Epic 1 编写用户故事：

Story 1.1: 创建角色
作为系统管理员，我需要能够创建新角色，以便对权限进行分组管理。

验收标准：
- [ ] 可以输入角色名称和描述
- [ ] 角色名称不能重复
- [ ] 创建成功后显示在角色列表中

Story 1.2: 编辑角色
作为系统管理员，我需要能够编辑现有角色，以便调整权限配置。
...

注意每个 Story 都遵循固定格式：作为 [角色]，我需要 [功能]，以便 [目标]。

步骤 8：定义非功能需求

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

现在让我们定义非功能需求（NFR）：

性能需求：
- API 响应时间 < 200ms（P95）
- 支持 1000+ 并发用户

安全需求：
- 所有操作需要认证
- 敏感操作需要二次确认
- 审计日志不可篡改

可用性需求：
- 系统可用性 99.9%
- 数据备份每日一次

这些要求合理吗？

所有步骤完成后，PM 会生成完整的 PRD，保存到 {planning_artifacts}/prd.md。

验证 PRD 质量

PRD 生成后，不要急着进入下一步。选择 [VP] 运行验证模式：

1

[VP] 验证产品需求文档（PRD）

PM 会启动验证流程（steps-v/step-v-01-discovery.md），进行 13 项验证：

• 完整性：所有 Epic 都有对应的 Story 吗？
• 一致性：Story 之间有没有矛盾？
• 可测试性：验收标准是否可验证？
• 优先级：P0/P1/P2 的划分是否合理？
• 可追溯性：每个 Story 是否都能追溯到产品简报？

验证报告会指出问题：

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

## 验证报告

### 通过项 ✅
- Epic 拆分合理，无重叠
- 所有 Story 都有验收标准
- NFR 定义明确

### 需改进项 ⚠️
- Story 1.3 的验收标准过于模糊
  建议：将"用户体验良好"改为具体的响应时间要求

- Epic 3 缺少容量规划
  建议：补充日志存储策略和保留周期
...

根据报告修正 PRD，直到所有验证项都通过。

启动 Architect 代理

PRD 验证通过后，关闭 PM 对话，开启新对话：

1

*agent architect

或者简写：

1

*architect

系统会加载 _bmad/bmm/agents/architect.md 文件，激活架构师角色（Winston）。

1
2
3
4
5
6
7
8

请选择菜单项：
1. [MH] 重新显示菜单帮助
2. [CH] 与我聊任何话题
3. [WS] 获取工作流状态或初始化工作流（可选）
4. [CA] 创建架构文档
5. [IR] 实施就绪性审查
6. [PM] 启动派对模式
7. [DA] 解除代理

创建架构文档

在 Architect 代理的菜单中，选择 [CA]：

1

[CA] 创建架构文档

Architect 会启动 _bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md 工作流，这个工作流有多个步骤：

步骤 1：发现输入文档

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

我将基于 PRD 创建架构文档。让我先查找相关文档...

✓ 找到 PRD: {planning_artifacts}/prd.md
✓ 找到项目上下文: **/project-context.md

从 PRD 中识别出以下关键需求：

功能需求：
- 角色管理（CRUD）
- 用户权限分配
- 审计日志记录

非功能需求：
- API 响应 < 200ms
- 支持 1000+ 并发
- 99.9% 可用性

现在让我们开始架构设计...

步骤 2-N：逐步设计

工作流会引导你完成：

1. 技术栈选择：语言、框架、数据库等
2. 系统架构：整体架构图和组件划分
3. 数据模型：实体关系和表结构
4. API 规范：所有接口的请求/响应格式
5. 编码规范：命名约定、错误处理、日志等
6. 部署架构：部署方式和基础设施

关键步骤示例：

步骤 2：选择技术栈

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

根据需求，我建议以下技术栈：

后端：
- 语言：Node.js 18 LTS（考虑到团队熟悉度）
- 框架：Express 4.x（轻量级，满足性能要求）
- ORM：TypeORM 0.3.x（支持事务和迁移）
- 数据库：PostgreSQL 15（支持 JSONB，适合审计日志）

前端：
- 框架：React 18 + TypeScript
- 状态管理：Zustand（轻量级）
- UI 库：Ant Design 5.x

你同意这个选择吗？还是有其他偏好？

这里的关键是 每个选择都要有理由。不是 “我们用 PostgreSQL”，而是 “我们用 PostgreSQL，因为它支持 JSONB，适合存储审计日志的复杂结构”。

步骤 4：设计数据模型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

让我们设计核心数据模型：

User（用户）
- id: UUID
- username: string (unique)
- email: string (unique)
- password_hash: string
- created_at: timestamp
- updated_at: timestamp

Role（角色）
- id: UUID
- name: string (unique)
- description: string
- created_at: timestamp

UserRole（用户角色关联）
- user_id: UUID (FK → User.id)
- role_id: UUID (FK → Role.id)
- assigned_at: timestamp
- assigned_by: UUID (FK → User.id)

这个设计能满足 PRD 的需求吗？

步骤 6：定义 API 规范

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

让我们定义 API 规范：

POST /api/roles
创建角色

请求：
{
  "name": "管理员",
  "description": "系统管理员角色"
}

响应：
{
  "id": "uuid",
  "name": "管理员",
  ...
}

GET /api/roles
查询角色列表

参数：
- page: number (默认 1)
- pageSize: number (默认 20)
...

所有步骤完成后，Architect 会生成完整的架构文档，保存到 {planning_artifacts}/architecture.md。

Planning 阶段的检查清单

在进入下一个阶段前，确认以下问题：

• [ ] PRD 是否通过了验证？
• [ ] 架构文档是否明确了技术栈？
• [ ] 数据模型是否支持所有 Story？
• [ ] API 规范是否完整（包含所有接口）？
• [ ] 编码规范是否明确（命名、错误处理、日志）？

3.3. Solutioning 阶段：Epic 与 Story 的创建

这个阶段的目标是 把 PRD 和架构文档转换成可执行的 Epic 和 Story 文件

在开发尤其是 Agile/敏捷开发 和 Scrum（阶段性冲刺） 中，Epic（史诗） 是一个项目管理术语，而不是一种代码语法

Story 全称是 User Story（用户故事）。它是 Agile 开发中 最小的需求描述单位。

什么叫“故事”而不是“功能”？因为它是 从用户的视角 来描述需求的，而不是从技术的视角。它强调的是 价值。

作为一个 <角色>， 我想要 <执行某个动作>， 以便于 <获得某种价值/解决某个问题>。

创建 Epic 和 Story

继续使用 PM 代理（或重新激活），选择 [ES]：

1

[ES] 从 PRD 创建 Epic 和用户故事（架构完成后必需）

PM 会启动 _bmad/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md 工作流。

步骤 1：验证前置条件

工作流首先检查：

1
2
3
4
5
6
7

正在验证前置条件...

✓ PRD 文件存在: {planning_artifacts}/prd.md
✓ 架构文档存在: {planning_artifacts}/architecture.md
✓ 项目上下文存在: **/project-context.md

所有前置条件满足，可以开始创建 Epic 和 Story。

步骤 2-N：逐步创建

工作流会：

1. 提取 Epic：从 PRD 中识别所有 Epic
2. 创建 Epic 文件：为每个 Epic 生成详细文档
3. 提取 Story：从 PRD 中识别所有用户故事
4. 创建 Story 条目：将 Story 组织到对应的 Epic 中
5. 添加 BDD 场景：为每个 Story 编写 Given-When-Then 场景
6. 添加技术任务：为每个 Story 拆分技术实现任务

最终生成的文件结构：

1
2
3

{planning_artifacts}/
├── epics.md                    # 所有 Epic 和 Story 的汇总
└── epic-1-role-management.md   # Epic 1 的详细内容（如果分片）

每个 Epic 文件包含：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# Epic 1: 角色管理

## Story 1.1: 创建角色

### 描述
作为系统管理员，我需要能够创建新角色，以便对权限进行分组管理。

### 验收标准
- [ ] 可以输入角色名称和描述
- [ ] 角色名称不能重复
- [ ] 创建成功后显示在角色列表中

### BDD 场景

Given 我是一个系统管理员
When 我创建一个新角色，名称为 "财务审核员"
Then 角色应该成功创建
And 角色应该出现在角色列表中
And 角色名称应该是 "财务审核员"


### 技术任务
1. [ ] 创建 Role 实体（src/entities/Role.ts）
2. [ ] 实现 RoleService.create()
3. [ ] 创建 POST /api/roles 接口
4. [ ] 编写单元测试
5. [ ] 前端角色创建表单

实现就绪检查

Epic 和 Story 创建完成后，运行实现就绪检查。可以选择 PM 代理的 [IR] 或 Architect 代理的 [IR]：

给予 PM 【IR】 功能是因为我们在拆分 epic 的时候是 PM 视角拆分的，他可以继续延续上下文进行审查

1

[IR] 实现就绪审查

PM 或 Architect 会启动 _bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md 工作流，进行 6 项检查：

检查 1：文档一致性

1
2
3
4
5

检查 PRD 和架构文档是否一致...

✓ PRD 中的所有 Epic 都有对应的数据模型
✓ PRD 中的所有 Story 都有对应的 API 规范
✓ 架构文档中的技术栈能满足 NFR 要求

检查 2：Story 完整性

1
2
3
4
5
6
7
8

检查 Story 是否完整...

✓ 所有 Story 都有验收标准
✓ 所有 Story 都有技术任务拆分
✓ 所有 Story 都标注了相关文档

⚠️ Story 2.3 缺少测试任务
建议：补充单元测试和集成测试任务

检查 3：依赖关系

1
2
3
4
5
6
7
8

检查 Story 之间的依赖关系...

✓ Story 1.1 无依赖，可以先做
✓ Story 1.2 依赖 Story 1.1（需要先有角色才能编辑）
✓ Story 2.1 依赖 Story 1.1（需要先有角色才能分配）

⚠️ Story 3.1 和 Story 1.1 可以并行开发
建议：调整优先级，提高开发效率

检查 4：技术风险

1
2
3
4
5
6
7
8
9

识别技术风险...

⚠️ 审计日志存储策略未明确
风险：日志量大时可能影响数据库性能
建议：考虑使用时序数据库或日志服务

⚠️ 并发控制策略未定义
风险：多人同时修改角色可能导致数据不一致
建议：在架构文档中补充乐观锁或悲观锁方案

检查 5：资源评估

1
2
3
4
5
6
7
8
9
10

评估开发资源...

预估工时：
- Epic 1: 3 天
- Epic 2: 2 天
- Epic 3: 2 天
总计：7 天

团队规模：1 人
建议迭代周期：2 周（包含测试和返工时间）

检查 6：生成检查报告

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

## 实现就绪检查报告

### 通过项 ✅
- 文档一致性检查通过
- Story 完整性检查通过
- 依赖关系清晰

### 需改进项 ⚠️
1. Story 2.3 缺少测试任务
2. 审计日志存储策略未明确
3. 并发控制策略未定义

### 建议
- 补充上述 3 项后，可以进入开发阶段
- 建议先做 Epic 1 和 Epic 3（可并行），再做 Epic 2

### 决定
状态：**需修正** → 补充后重新检查

根据报告修正问题，直到所有检查项都通过。

Solutioning 阶段的检查清单

在进入下一个阶段前，确认以下问题：

• [ ] Epic 和 Story 文件是否已创建？
• [ ] 所有 Story 是否都有完整的验收标准和技术任务？
• [ ] Story 之间的依赖关系是否清晰？
• [ ] 技术风险是否已识别并有应对方案？
• [ ] 实现就绪检查是否通过？

3.4. Implementation 阶段：故事驱动的开发循环

这个阶段的目标是 按 Story 写代码，每个 Story 一个完整的开发-审查循环。

启动 SM 代理

关闭 PM/Architect 对话，开启新对话：

1

*agent sm

或者简写：

1

*sm

系统会加载 _bmad/bmm/agents/sm.md 文件，激活 Scrum Master 角色（Bob）。

Sprint 规划

首先，选择 [SP] 生成或更新 sprint 状态文件：

1

[SP] 生成或重新生成 sprint-status.yaml（Epic+Story 创建后必需）

SM 会启动 _bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml 工作流，从 Epic 文件中提取所有 Story，生成 {implementation_artifacts}/sprint-status.yaml：

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

project_name: "用户权限管理系统"
sprint_start: "2025-01-15"
sprint_end: "2025-01-29"

epics:
  - epic_num: 1
    name: "角色管理"
    stories:
      - story_key: "story-1.1"
        title: "创建角色"
        status: "draft"
        priority: "P0"
        dependencies: []
      - story_key: "story-1.2"
        title: "编辑角色"
        status: "draft"
        priority: "P0"
        dependencies: ["story-1.1"]

这个文件会跟踪所有 Story 的状态：draft → approved → in_progress → review → done。

创建 Story 文件

选择 [CS] 创建下一个 Story 文件：

1

[CS] 创建 Story（准备 Story 用于开发）

SM 会启动 _bmad/bmm/workflows/4-implementation/create-story/workflow.yaml 工作流：

1. 读取 sprint-status.yaml：找到下一个待开发的 Story
2. 加载相关文档：PRD、架构文档、Epic 文件
3. 创建 Story 文件：生成详细的 Story 文件，包含：
   • Story 描述和验收标准
   • BDD 场景
   • 技术任务和子任务
   • 相关文档引用
   • 实现指南

生成的 Story 文件示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

---
story_key: story-1.1
epic_num: 1
status: approved
priority: P0
---

# Story 1.1: 创建角色

## 描述
作为系统管理员，我需要能够创建新角色，以便对权限进行分组管理。

## 验收标准
- [ ] 可以输入角色名称和描述
- [ ] 角色名称不能重复
- [ ] 创建成功后显示在角色列表中

## BDD 场景
[Given-When-Then 场景]

## 技术任务
1. [ ] 创建 Role 实体（src/entities/Role.ts）
   - [ ] 定义 Role 接口
   - [ ] 添加 TypeORM 装饰器
2. [ ] 实现 RoleService.create()
   - [ ] 参数校验
   - [ ] 唯一性检查
   - [ ] 保存到数据库
3. [ ] 创建 POST /api/roles 接口
   - [ ] 路由定义
   - [ ] 请求验证
   - [ ] 调用 Service
4. [ ] 编写单元测试
   - [ ] RoleService 测试
   - [ ] API 端点测试
5. [ ] 前端角色创建表单
   - [ ] 表单组件
   - [ ] 表单验证
   - [ ] API 调用

## 相关文档
- PRD: {planning_artifacts}/prd.md
- 架构: {planning_artifacts}/architecture.md
- Epic: {planning_artifacts}/epics.md

Story 文件会保存到 {implementation_artifacts}/{story_key}.md。

启动 Dev 代理

Story 文件创建完成后，关闭 SM 对话，开启新对话：

1

*agent dev

或者简写：

1

*dev

系统会加载 _bmad/bmm/agents/dev.md 文件，激活开发者角色（Amelia）。

开发 Story

在 Dev 代理的菜单中，选择 [DS]：

1

[DS] 执行 Dev Story 工作流（完整的 BMM 路径，包含 sprint-status）

Dev 会启动 _bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml 工作流：

1. 读取 Story 文件：加载完整的 Story 文件和相关文档
2. 按顺序执行任务：严格按照 Story 文件中的任务顺序执行
3. 遵循 TDD 原则：每个任务先写测试，再写实现
4. 更新 Story 状态：完成任务后更新 Story 文件中的复选框

关键规则：

• 🛑 绝不 跳过任务或重新排序
• 📖 总是 先读取完整的 Story 文件
• ✅ 总是 先写测试，再写实现
• 💾 总是 完成任务后更新 Story 文件
• 🚫 绝不 在测试失败时继续下一个任务

开发过程示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

正在加载 Story 1.1...

✓ 读取 Story 描述
✓ 读取验收标准
✓ 读取技术任务
✓ 加载相关文档：
  - {planning_artifacts}/prd.md
  - {planning_artifacts}/architecture.md
  - {planning_artifacts}/epics.md

开始开发...

任务 1: 创建 Role 实体
正在创建 src/entities/Role.ts...

✓ 定义 Role 接口
✓ 添加 TypeORM 装饰器
✓ 任务 1 完成

任务 2: 实现 RoleService.create()
正在创建 src/services/RoleService.ts...

✓ 参数校验
✓ 唯一性检查
✓ 保存到数据库
✓ 任务 2 完成

任务 3: 创建 POST /api/roles 接口
...

所有任务完成！
✓ 更新 Story 文件状态
✓ 运行完整测试套件：12/12 通过
✓ Story 状态更新：approved → in_progress → review

代码审查

Story 开发完成后，选择 [CR] 进行代码审查：

1

[CR] 执行彻底的代码审查（强烈推荐，使用新上下文和不同 LLM）

Dev 会启动 _bmad/bmm/workflows/4-implementation/code-review/workflow.yaml 工作流。这个工作流是 对抗性的，会：

1. 挑战一切：代码质量、测试覆盖、架构合规、安全性、性能
2. 找出问题：每个 Story 必须找出 3-10 个具体问题
3. 提供修复建议：可以自动修复（需用户批准）

审查报告示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

## 代码审查报告：Story 1.1

### 通过项 ✅
- 所有验收标准已满足
- 代码风格符合架构文档规范
- 测试覆盖率 87%（超过 80% 要求）

### 需改进项 ⚠️
1. RoleService.create() 缺少事务处理
   风险：并发创建可能导致数据不一致
   建议：使用 @Transaction 装饰器

2. 前端缺少加载状态
   风险：用户不知道操作是否成功
   建议：添加 loading 状态和 Skeleton 占位符

3. 缺少边界条件测试
   风险：角色名称过长时可能出错
   建议：补充角色名称长度边界测试

### 重构建议 💡
- 分页逻辑在多个 Service 中重复，建议抽取为 PaginationUtil

### 决定
状态：Review → **需修正**
修正完成后可合并到主分支

根据报告修正问题，然后重新提交审查。

循环继续

Story 1.1 完成后，回到 SM 对话：

1

[CS] 创建 Story

SM 会根据 sprint-status.yaml 和依赖关系，推荐下一个 Story：

1
2
3
4
5
6
7
8

Story 1.1 已完成 ✓

根据依赖关系，可以开始以下 Story：
- Story 1.2: 编辑角色（依赖 Story 1.1）
- Story 3.1: 记录审计日志（无依赖，可并行）

建议先做 Story 1.2，保持 Epic 的连贯性。
是否开始 Story 1.2？

重复 SM → Dev → CR 的循环，直到所有 Story 完成。

Implementation 阶段的检查清单

每个 Story 完成后，确认以下问题：

• [ ] 所有验收标准是否已满足？
• [ ] 代码是否通过代码审查？
• [ ] 测试覆盖率是否达标（> 80%）？
• [ ] Story 文件中的任务是否全部完成？
• [ ] Story 状态是否已更新为 Done？
• [ ] sprint-status.yaml 是否已更新？

3.5. 本章总结与完整工作流速查

让我们把四个阶段的操作流程完整串联起来，并给出每个环节的最佳实践建议。****

完整工作流图谱

阶段一：Analysis（分析阶段）

目标：把模糊想法变成清晰的产品简报

操作流程：

关键检查点：

• [ ] 产品简报是否明确了 “为什么要做”？
• [ ] 目标用户是否清晰且完整？
• [ ] 成功指标是否可量化？
• [ ] 范围边界是否明确（包含什么，不包含什么）？
• [ ] 约束条件（时间、预算、技术）是否已识别？

推荐模型：

为什么推荐 Gemini：Analysis 阶段需要处理大量信息（市场研究、竞品分析、用户访谈），Gemini 的超大上下文窗口可以一次性加载所有资料，避免信息丢失。Thinking 模式能进行深度推理，挖掘隐藏需求。

阶段二：Planning（规划阶段）

目标：把产品简报翻译成 PRD 和架构文档

操作流程：

Part 1：创建 PRD

Part 2：创建架构文档

关键检查点：

• [ ] PRD 是否通过了 13 项验证？
• [ ] 所有 Epic 都有对应的 Story 吗？
• [ ] 所有 Story 都有验收标准吗？
• [ ] 非功能需求（NFR）是否明确？
• [ ] 架构文档是否明确了技术栈？
• [ ] 数据模型是否支持所有 Story？
• [ ] API 规范是否完整？
• [ ] 编码规范是否明确？

推荐模型：

为什么推荐 Claude：Planning 阶段需要输出高质量的结构化文档，Claude 在这方面表现最佳。它能严格遵循模板格式，输出的 PRD 和架构文档条理清晰、逻辑严密。验证模式需要挑刺能力，Claude 的批判性思维更强，而 Gemini1 的幻觉率高，对于这一类需要严苛保证标准的题材，Claude 往往更能发挥出优点

阶段三：Solutioning（方案阶段）

目标：把 PRD 和架构文档转换成可执行的 Epic 和 Story

操作流程：

关键检查点：

• [ ] 所有 Epic 都有对应的 Story 吗？
• [ ] 所有 Story 都有完整的验收标准吗？
• [ ] 所有 Story 都有技术任务拆分吗？
• [ ] 所有 Story 都有 BDD 场景吗？
• [ ] Story 之间的依赖关系是否清晰？
• [ ] 技术风险是否已识别并有应对方案？
• [ ] PRD 和架构文档是否一致？

推荐模型：

为什么推荐 Claude：Solutioning 阶段需要精细的任务拆解能力，Claude 能准确识别 Story 之间的依赖关系，避免遗漏。实现就绪检查需要对抗性思维，Claude 的批判性更强，能发现潜在问题。

阶段四：Implementation（实现阶段）

目标：按 Story 写代码，每个 Story 一个完整的开发-审查循环

操作流程：

Part 1：Sprint 规划（SM）

Part 2：开发 Story（Dev）

Part 3：循环继续

重复 SM → Dev → CR 的循环，直到所有 Story 完成。

关键检查点：

• [ ] sprint-status.yaml 是否已生成？
• [ ] Story 文件是否包含完整的技术任务？
• [ ] 是否严格按照任务顺序开发？
• [ ] 是否遵循 TDD 原则（先写测试）？
• [ ] 所有验收标准是否已满足？
• [ ] 代码是否通过审查？
• [ ] 测试覆盖率是否达标（> 80%）？
• [ ] Story 状态是否已更新为 Done？

推荐模型：

为什么推荐 Claude + Gemini 双模型：

• Claude：代码质量最高，严格遵循架构文档和编码规范。代码审查时批判性最强，能发现细微问题。适合 80% 的常规 Story。
• Gemini Thinking：思考深度更好，适合复杂的算法逻辑、性能优化、架构级重构。超大上下文适合处理大型代码库。适合 20% 的复杂 Story。

双模型协作策略：

1. 常规 Story：用 Claude 开发 + Claude 审查
2. 复杂 Story：用 Gemini Thinking 开发 + Claude 审查
3. 架构级重构：用 Gemini Thinking 开发 + Gemini Thinking 审查

角色切换的黄金法则

规则 1：必须在新对话中切换角色

❌ 错误做法：

1
2
3
4

你：*analyst
[完成 Analysis]
你：*pm
[在同一对话中继续]

✅ 正确做法：

1
2
3
4
5
6
7
8

对话 1：
你：*analyst
[完成 Analysis，保存产品简报]
/clear 清空上下文

对话 2：
你：*pm
[读取产品简报，创建 PRD]

为什么：防止角色污染。同一对话中切换角色，AI 的上下文会混杂两个角色的思维方式，导致输出质量下降。

规则 2：必须保存工件后再切换

❌ 错误做法：

1
2
3

Analyst：我已经完成头脑风暴...
你：好的，我现在切换到 PM
[没有保存产品简报]

✅ 正确做法：

1
2
3
4
5

Analyst：我已经完成头脑风暴...
你：请创建产品简报
Analyst：[生成 product-brief.md]
你：[确认文件已保存到 {planning_artifacts}/]
[关闭对话，切换到 PM]

为什么：工件是阶段之间的信息传递媒介。如果不保存工件，下一个阶段的代理无法获取前一个阶段的输出。

规则 3：必须通过检查点才能进入下一阶段

❌ 错误做法：

1
2
3

PM：PRD 已创建
你：好的，我现在去开发
[跳过 PRD 验证和架构设计]

✅ 正确做法：

1
2
3
4
5
6
7
8
9
10
11

PM：PRD 已创建
你：请验证 PRD
PM：[运行 VP，生成验证报告]
你：[根据报告修正 PRD]
PM：验证通过
你：[关闭对话，切换到 Architect]
Architect：[创建架构文档]
你：[关闭对话，切换到 PM]
PM：[创建 Epic/Story]
PM：[运行 IR，实现就绪检查]
你：[确认通过后，才进入开发]

为什么：每个检查点都是质量门槛。跳过检查点，问题会累积到后期，导致大量返工。

规则 4：必须使用正确的菜单命令

❌ 错误做法：

1
2

你：请执行 _bmad/bmm/workflows/2-plan-workflows/prd/workflow.md
[直接调用工作流文件]

✅ 正确做法：

1
2
3
4

你：*pm
PM：[显示菜单]
你：CP
PM：[启动 PRD 创建工作流]

为什么：菜单命令会自动处理前置条件检查、文件路径解析、配置加载等。直接调用工作流文件可能导致路径错误或配置缺失。

常见错误与纠正

自检清单

每个阶段结束时，问自己：

Analysis 阶段：

• [ ] 产品简报是否已保存到 {planning_artifacts}/product-brief-{date}.md？
• [ ] 产品简报是否明确了目标用户、核心问题、成功指标？
• [ ] 是否进行了必要的研究（市场/竞品/技术）？

Planning 阶段：

• [ ] PRD 是否已保存到 {planning_artifacts}/prd.md？
• [ ] PRD 是否通过了 VP 验证（13 项检查）？
• [ ] 架构文档是否已保存到 {planning_artifacts}/architecture.md？
• [ ] 架构文档是否明确了技术栈、数据模型、API 规范、编码规范？

Solutioning 阶段：

• [ ] Epic 和 Story 是否已保存到 {planning_artifacts}/epics.md？
• [ ] 所有 Story 是否都有验收标准、BDD 场景、技术任务？
• [ ] 是否通过了 IR 实现就绪检查（6 项检查）？

Implementation 阶段：

• [ ] sprint-status.yaml 是否已生成？
• [ ] 每个 Story 是否都有独立的 Story 文件？
• [ ] 每个 Story 是否都通过了代码审查？
• [ ] 测试覆盖率是否达标（> 80%）？
• [ ] sprint-status.yaml 中的 Story 状态是否已更新为 Done？

快速命令速查表

通用命令：

• WS：查看工作流状态（所有代理通用）
• PM：启动派对模式（所有代理通用）
• MH：重新显示菜单（所有代理通用）
• DA：解除代理（所有代理通用）

最后的建议

1. 不要急于求成

BMAD 的价值在于 减少返工，而不是 加快初始速度。前期在文档上多花的时间，会在后期以 “避免返工” 的形式百倍偿还，一个模型可能跑的比较旧，我们在后续的篇章中会推出更强大的公族流，并行执行多个模型进行工作，互相获取上下文并行工作…

2. 严格遵循流程

不要跳过任何检查点。每个检查点都是质量门槛，跳过一个，问题就会累积到下一个阶段。

3. 善用派对模式

当你对某个决策不确定时，启动派对模式（PM），让多个代理从不同角度讨论。这能避免单一视角的盲点。

4. 定期回顾工件

每完成一个阶段，回头看看之前的工件（产品简报、PRD、架构文档）。如果发现不一致，立即修正，不要拖到后期。

5. 记录技术债务

代码审查时发现的 “重构建议”，即使暂时不修复，也要记录到技术债务清单中。定期回顾和偿还技术债务。