第一章. BMAD 的本质：为什么需要它

注：更详细的关于 BMAD 的方法论说明请跳转至：

1.1. 氛围编程的三大死穴

我们先从一个真实场景开始。

假设你正在用 AI 助手开发一个电商系统，对话进行到第 50 轮时，你突然发现：刚才让 AI 生成的订单服务代码，和 20 轮之前设计的用户服务完全不兼容。API 接口对不上，数据库字段也对不上。更糟糕的是，你已经记不清当时为什么要那样设计了。

这就是 氛围编程凭感觉与 AI 对话式编程，缺乏结构化规划 的典型困境。它有三个致命问题：

死穴一：上下文衰减

AI 对话的上下文窗口是有限的。即使是 Gemini 这样的长上下文模型，当对话超过 100 轮后，早期的关键决策也会被 “遗忘”。你会发现 AI 开始自相矛盾：

• 第 10 轮说用 REST API
• 第 80 轮突然建议改成 GraphQL
• 第 120 轮又回到 REST，但参数结构完全变了

更可怕的是，你自己也会忘记。三个月后回来维护代码，你会盯着屏幕问自己：“当初为什么要这么写？”

死穴二：幻觉累积

AI 在没有约束的情况下，会 “创造性地” 编造不存在的 API、配置项、甚至整个框架。举个例子：

1
2
3
4
5
6
7

// AI 生成的代码
import { MagicAuth } from '@awesome/auth-kit';

const auth = new MagicAuth({
  strategy: 'quantum-token', // 这个策略根本不存在
  autoRefresh: true
});

你兴高采烈地复制粘贴，运行后发现 @awesome/auth-kit 这个包压根不存在。回到对话里追问，AI 会一本正经地道歉，然后给你另一个同样不存在的方案。

在氛围编程中，这种幻觉会像滚雪球一样累积。因为没有 “规范文档” 作为事实基准，AI 每次回答都是基于概率模型的即兴发挥。

死穴三：架构漂移

没有预先规划的项目，架构会随着对话的进行而 “漂移”。最初你想做一个简单的 CRUD 应用，聊着聊着变成了微服务架构，再聊着聊着又加上了事件溯源和 CQRS。

这不是说这些技术不好，而是 决策缺乏一致性。你会发现：

• 用户模块用了 RESTful 风格
• 订单模块突然变成 RPC 调用
• 支付模块又引入了消息队列

整个系统像一个缝合怪，每个部分都能跑，但拼在一起就是灾难。

1.2. BMAD 的核心思想：规范驱动 + 人在回路

BMAD 的设计哲学可以用一句话概括：先把规则写清楚，再让 AI 按规则干活。

它通过两个核心机制解决氛围编程的问题：

规范驱动：工件即真相

在 BMAD 中，所有的关键决策都必须固化为 工件持久化的文档或代码，作为后续开发的事实依据。这些工件包括：

这些工件不是摆设，而是 AI 的行动指南。当你让 Dev 代理实现一个功能时，它必须严格遵循 PRD 和架构文档中的约定。如果 PRD 里说用 PostgreSQL，Dev 就不能擅自改成 MongoDB。

这就解决了 “幻觉累积” 的问题。因为 AI 不再是凭空想象，而是基于已经确认的文档进行推理。

人在回路：检查点机制

BMAD 不是让 AI 完全自主工作，而是在关键节点设置 人工检查点。整个流程分为四个阶段：

注意那两个虚线箭头，它们代表 必须由人来决定是否继续。具体来说：

检查点 1：Planning → Solutioning

在这个阶段，PO (Product Owner) 代理会生成一份检查清单，验证 PRD 和架构文档是否一致。例如：

• PRD 里提到的 “用户角色管理”，架构文档里有没有对应的数据表设计？
• 架构文档选择了 Redis 做缓存，PRD 里有没有说明缓存失效策略？

这份清单生成后，你必须人工审查。如果发现不一致，回到 Planning 阶段修正文档，而不是带着问题进入开发。

检查点 2：每个 Story 的 Review 阶段

当 Dev 代理完成一个故事的开发后，QA 代理会进行代码审查。审查报告会明确指出：

• 哪些地方符合规范
• 哪些地方需要改进
• 是否可以合并到主分支

这个决定权在你手上。如果 QA 发现了严重问题（比如缺少事务处理），你可以要求 Dev 返工，而不是 “先合并再说”。

这种机制确保了 质量门槛。每个阶段的输出都经过验证，不会把问题遗留到下一个阶段。

1.3. 适用场景判断树

BMAD 不是银弹，它有明确的适用边界。我们用一个决策树来说明：

我们逐个解释每个分支：

分支 1：需求不明确 → 对话式编程

如果你还在探索 “到底要做什么”，BMAD 反而会拖慢节奏。这时候应该用对话式编程快速试错：

• 写几个原型验证想法
• 和 AI 讨论不同的技术方案
• 频繁推翻重来

等需求逐渐清晰后，再切换到 BMAD 进行正式开发。

分支 2：小项目（< 1 天）→ Quick Flow

对于简单的功能（比如给现有系统加一个导出 Excel 的接口），完整的 BMAD 流程过于重量级。这时可以用简化版：

1. 直接写一个简单的 Story（跳过 PRD）
2. 用 Dev 代理实现
3. 用 QA 代理快速审查

这样既保留了 “规范驱动” 的核心思想，又不会陷入文档泥潭。

分支 3：大项目 + 长期维护 → 完整流程

如果你的项目满足以下任一条件，强烈建议用完整的 BMAD 流程：

• 开发周期超过 1 周
• 涉及多个模块或服务
• 需要多人协作（即使是 “你 + AI” 的协作）
• 三个月后还要继续迭代

这种情况下，前期在文档上多花的时间，会在后期以 “减少返工” 的形式百倍偿还。

1.4. 本章总结与决策速查

让我们回顾一下核心要点：

氛围编程的三大死穴

1. 上下文衰减：对话越长，早期决策越容易被遗忘
2. 幻觉累积：AI 会编造不存在的 API 和配置
3. 架构漂移：缺乏规划导致系统变成缝合怪

BMAD 的两大支柱

1. 规范驱动：用工件（PRD、架构文档、Story）固化决策
2. 人在回路：在关键节点设置人工检查点

决策速查表

自检问题

在开始一个项目前，问自己三个问题：

1. 三个月后，我还能看懂这些代码吗？（如果答案是 “不确定”，用 BMAD）
2. 这个项目会不会有第二个人参与？（如果是，用 BMAD）
3. 我能接受推倒重来的成本吗？（如果不能，用 BMAD）

第二章. BMAD 角色体系：21 个代理的分工逻辑

2.1. 先看看 BMAD 装了什么

在理解角色之前，我们先把 BMAD 的仓库拉下来看看。它以一个 Github 仓库 的形式存在，安装后会在你的项目里生成一个 .bmad 目录。

安装和初始化

1

npx bmad-method@alpha install

安装程序会启动一个交互式配置向导。这个过程会问你一系列问题，我们逐个解释：

问题 1：安装目录

1
2

? Installation directory: C:\Users\YourName\Desktop\BMAD
? Install to this directory? Yes

这个没什么好说的，选一个你想放项目的地方。

问题 2：选择开发工具

1
2
3
4

? Select tools to configure:
  ◉ Claude Code ⭐
  ◯ Windsurf
  ◯ VS Code

必须按空格键选中，然后按回车确认。只是高亮不算选中。

这里选择你用的 IDE。我们的教程以 Claude Code 为例，但其他 IDE 的流程本质上是一样的。

问题 3：配置语言和输出

1
2
3
4

? What shall the agents call you? Prorise
? Preferred chat language/style? Chinese
? Preferred document output language? Chinese
? Where should default output files be saved? _bmad-output

这里有个关键点：对话语言和文档语言可以分开设置。

• 对话语言：AI 用什么语言跟你交流
• 文档语言：PRD、架构文档等工件用什么语言输出

我选了中文，因为 PRD 和架构文档用中文写更自然。但如果你的团队是国际化的，可以选英文。

问题 4：选择模块

1
2
3
4

? Select modules to install:
  ◉ BMM: BMad Method Agile-AI Driven-Development
  ◯ BMB: BMad Builder (Create Custom Agents)
  ◯ CIS: Creative Innovation Suite

这里有三个模块：

第一次使用建议只选 BMM，因为想先体验标准流程。等熟悉了再用 BMB 定制自己的 Agent。

问题 5：是否启用 TTS

1

? Claude Code supports TTS (Text-to-Speech). Would you like to enable it? No

这个功能可以让 AI 用语音跟你对话。我选了 No，因为这部分我们不需要，没必要下载额外依赖。

安装完成后，会看到：

1
2
3

✨ BMAD is ready to use!
Installed to: C:\Users\Prorise\Desktop\BMAD\_bmad
Modules: bmm

2.2. 目录结构：核心文件在哪里

安装完后，项目里会多两个目录：

1
2
3

📂 BMAD/
├── 📂 _bmad/              # BMAD核心文件
└── 📂 _bmad-output/       # 工件输出目录

_bmad 目录：三个模块的分工

这个目录包含三个模块：

1
2
3
4

_bmad/
├── 📂 core/              # 核心功能
├── 📂 bmm/               # BMad Method模块
└── 📂 _config/           # 配置文件

我们逐个拆解。

core 模块：基础能力层

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

core/
├── 📂 agents/
│   └── bmad-master.md    # 主控Agent
├── 📂 tasks/
│   ├── index-docs.xml    # 文档索引任务
│   ├── review-adversarial-general.xml  # 对抗性审查任务
│   ├── shard-doc.xml     # 文档分片任务
│   └── workflow.xml      # 工作流任务
└── 📂 workflows/
    ├── advanced-elicitation/  # 高级需求挖掘
    ├── brainstorming/         # 头脑风暴
    └── party-mode/            # 多Agent协作模式

这里的 bmad-master 是总控 Agent，负责协调其他所有 Agent。它就像一个项目经理，知道什么时候该叫哪个 Agent 出来干活。

tasks 目录里是可复用的任务定义。比如 review-adversarial-general.xml 定义了 对抗性审查让一个 AI 挑战另一个 AI 的输出，找出逻辑漏洞和潜在问题 的逻辑：让一个 AI 挑战另一个 AI 的输出，找出问题。

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

bmm 模块：21 个角色的定义

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

bmm/
├── 📂 agents/
│   ├── analyst.md              # 需求分析师
│   ├── pm.md                   # 产品经理
│   ├── architect.md            # 架构师
│   ├── sm.md                   # Scrum Master
│   ├── dev.md                  # 开发工程师
│   ├── tea.md                  # 测试工程师
│   ├── ux-designer.md          # UX设计师
│   ├── tech-writer.md          # 技术文档工程师
│   └── quick-flow-solo-dev.md  # Quick Flow专用Agent
├── 📂 workflows/
│   ├── 1-analysis/             # 第一阶段：分析
│   ├── 2-plan-workflows/       # 第二阶段：规划
│   ├── 3-solutioning/          # 第三阶段：方案设计
│   ├── 4-implementation/       # 第四阶段：实现
│   ├── bmad-quick-flow/        # Quick Flow工作流
│   └── ...
└── 📂 data/
    ├── documentation-standards.md  # 文档规范
    └── project-context-template.md # 项目上下文模板

这里才是真正的 21 个角色和 50+ 工作流。

打开 agents/analyst.md，你会看到需求分析师的完整定义：

1
2
3
4
5
6
7
8

# Business Analyst

你是一个需求分析师，负责把模糊的想法变成清晰的需求。

## 职责
- 收集和分析业务需求
- 识别关键约束和风险
...

每个 Agent 的定义包含三个部分：

1. 职责边界：这个 Agent 负责什么，不负责什么
2. 工作方式：这个 Agent 怎么思考问题
3. 输出规范：这个 Agent 产出什么格式的工件

这解决了什么问题？防止角色越界。如果没有明确的职责定义，Analyst 可能会开始讨论技术实现，Architect 可能会开始质疑需求合理性。但有了这些定义，每个 Agent 只关注自己的领域。

workflows 目录：四阶段的具体流程

这个目录是 BMAD 的核心。我们重点看四个阶段的目录结构。

1-analysis 阶段：

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

1-analysis/
├── create-product-brief/      # 创建产品简报
│   ├── product-brief.template.md
│   └── steps/
│       ├── step-01-init.md
│       ├── step-02-vision.md
│       ├── step-03-users.md
│       ├── step-04-metrics.md
│       ├── step-05-scope.md
│       └── step-06-complete.md
└── research/                  # 研究工作流
    ├── domain-steps/          # 领域研究
    ├── market-steps/          # 市场研究
    └── technical-steps/       # 技术研究

每个工作流都拆成了多个步骤。比如 create-product-brief 有 6 个步骤：初始化 → 愿景 → 用户 → 指标 → 范围 → 完成。

为什么要拆这么细？因为大脑一次只能处理 7±2 个信息块。如果一次性问你 20 个问题，你会懵。但如果分成 6 个步骤，每个步骤问 3-4 个问题，你就能清晰地回答。

2-plan-workflows 阶段：

1
2
3
4
5
6
7
8
9

2-plan-workflows/
├── prd/                       # PRD创建
│   ├── steps-c/               # 创建模式（12个步骤）
│   ├── steps-e/               # 编辑模式（4个步骤）
│   ├── steps-v/               # 验证模式（13个步骤）
│   └── templates/
│       └── prd-template.md
└── create-ux-design/          # UX设计
    └── steps/                 # 14个步骤

PRD 工作流有三种模式：

这解决了什么问题？防止文档质量参差不齐。如果没有验证模式，你可能会写出一份 “看起来很完整，但实际上漏洞百出” 的 PRD。但有了 13 个验证步骤，每个步骤检查一个维度（完整性、一致性、可测试性等），就能确保 PRD 的质量。

3-solutioning 阶段：

1
2
3
4
5
6
7

3-solutioning/
├── create-architecture/       # 架构设计
│   └── steps/                 # 8个步骤
├── create-epics-and-stories/  # 创建Epic和Story
│   └── steps/                 # 4个步骤
└── check-implementation-readiness/  # 实现就绪检查
    └── steps/                 # 6个步骤

这个阶段的关键是 check-implementation-readiness。它会检查：

• PRD 和架构文档是否一致？
• 所有 Epic 都有对应的技术方案吗？
• 技术栈能满足非功能需求吗？
• 有没有遗漏的依赖或风险？

只有通过这 6 个检查，才能进入开发阶段。这就是我们在第一章提到的 “人在回路” 检查点。

4-implementation 阶段：

1
2
3
4
5
6

4-implementation/
├── sprint-planning/           # 迭代规划
├── dev-story/                 # 开发Story
├── code-review/               # 代码评审
├── sprint-status/             # 迭代状态
└── retrospective/             # 回顾会议

这个阶段的工作流是循环的：规划 → 开发 → 评审 → 回顾 → 下一个迭代。

bmad-quick-flow：

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

bmad-quick-flow/
├── quick-spec/                # 快速规格说明
│   └── steps/
│       ├── step-01-understand.md
│       ├── step-02-investigate.md
│       ├── step-03-generate.md
│       └── step-04-review.md
└── quick-dev/                 # 快速开发
    └── steps/
        ├── step-01-mode-detection.md
        ├── step-02-context-gathering.md
        ├── step-03-execute.md
        ├── step-04-self-check.md
        ├── step-05-adversarial-review.md
        └── step-06-resolve-findings.md

Quick Flow 是完整流程的简化版。它只有两个工作流：

• quick-spec：4 步生成技术规格说明
• quick-dev：6 步完成开发（包含自检和对抗性审查）

注意 quick-dev 的第 5 步是 “对抗性审查”。即使是简化版，也保留了质量检查机制。

testarch 目录：

1
2
3
4
5
6
7
8
9
10
11

testarch/
├── knowledge/                 # 测试知识库（35个文档）
│   ├── overview.md
│   ├── test-levels-framework.md
│   ├── component-tdd.md
│   └── ...
└── workflows/
    ├── atdd/                  # 验收测试驱动开发
    ├── test-design/           # 测试设计
    ├── test-review/           # 测试评审
    └── ...

这个目录包含 35 个测试知识文档，涵盖 TDD、契约测试、性能测试等各种测试模式。

为什么需要这么多测试文档？因为测试是最容易被忽略的环节。很多开发者写完代码就觉得完成了，但实际上没有测试的代码是不可靠的。BMAD 通过提供完整的测试知识库，确保每个 Story 都有对应的测试策略。

_config 目录：配置和清单

1
2
3
4
5
6
7
8
9

_config/
├── agents/
│   ├── bmm-analyst.customize.yaml
│   ├── bmm-architect.customize.yaml
│   ├── bmm-dev.customize.yaml
│   └── ...
├── agent-manifest.csv         # Agent清单
├── workflow-manifest.csv      # 工作流清单
└── manifest.yaml              # 主清单

这些 .customize.yaml 文件是用来定制 Agent 行为的。打开 bmm-dev.customize.yaml，你会看到：

1
2
3
4
5
6
7
8

agent:
  name: Developer
  personality: 专业、严谨、注重细节
  code_style:
    naming: camelCase
    indent: 2 spaces
    max_line_length: 100
  ...

你可以修改这些配置，让 Dev Agent 使用你喜欢的代码风格。

各种 manifest 文件记录了系统里有哪些 Agent、工作流、任务。打开 agent-manifest.csv：

1
2
3
4

id,name,module,path,enabled
bmm-analyst,Business Analyst,bmm,bmm/agents/analyst.md,true
bmm-pm,Product Manager,bmm,bmm/agents/pm.md,true
...

这个清单的作用是 让系统知道有哪些 Agent 可用。当你输入 *agent pm 时，系统会查这个清单，找到 bmm-pm 对应的定义文件，然后加载它。

_bmad-output 目录：工件的归宿

1
2

_bmad-output/
└── implementation-artifacts/  # 实现阶段的工件

这个目录一开始是空的。当你跑完工作流后，所有生成的文档、代码、测试报告都会存在这里。

比如跑完 PRD 工作流后：

1
2
3
4

_bmad-output/
├── product-brief-20250115.md
├── prd-20250115.md
└── validation-report-20250115.md

跑完架构设计后：

1
2
3
4

_bmad-output/
├── architecture-20250115.md
├── architecture-decisions-20250115.md
└── epics-and-stories-20250115.md

注意文件名都带了日期。这是因为 工件是有版本的。如果你三个月后修改了 PRD，会生成一个新的文件 prd-20250415.md，而不是覆盖旧文件。这样你可以随时对比不同版本的差异。

2.3. 四个阶段在做什么

现在我们知道了 BMAD 的目录结构，接下来理解四个阶段的分工逻辑。

Analysis：把模糊想法变成清晰问题

这个阶段的目标是：把 “我想要个用户管理” 变成 “需要哪些字段、权限、接口”。

为什么需要这个阶段

因为大部分需求一开始都是模糊的。

产品说 “我想要个用户管理”，但他没说：

• 用户有哪些字段？姓名、邮箱、手机号？
• 用户有哪些权限？管理员、普通用户、访客？
• 用户怎么登录？账号密码、手机验证码、第三方登录？

如果直接开始写代码，这些问题会在实现过程中不断冒出来。每次冒出来，都要停下来讨论，然后改代码。

Analysis 阶段就是把这些问题提前问清楚。

这个阶段产出什么

一个 产品简报包含背景、目标、约束、风险、成功标准的需求分析文档，包含：

• 背景：为什么要做这个功能
• 目标：这个功能要解决什么问题
• 约束：有哪些限制条件（时间、预算、技术栈）
• 风险：可能遇到哪些问题
• 成功标准：怎么判断这个功能做成功了

对比：有 Analysis vs 没有 Analysis

没有 Analysis 的情况：

1
2
3
4
5
6

你：帮我写个用户管理模块
AI：好的，这是代码...
你：等等，用户需要有权限管理
AI：好的，我加上...
你：不对，权限应该是角色级别的
AI：好的，我改一下...

改了 5 次，每次都要重新生成代码。

有 Analysis 的情况：

1
2
3
4
5
6
7

Analyst：这个用户管理模块，需要支持哪些功能？
你：基本的增删改查，还有权限管理
Analyst：权限是用户级别的，还是角色级别的？
你：角色级别的
Analyst：需要支持第三方登录吗？
你：需要，微信和支付宝
Analyst：好的，我整理一下需求...

一次性把需求问清楚，后面不用反复改。

Planning：拆任务表和里程碑

这个阶段的目标是：把需求拆成 10 个可执行的任务，排好优先级。

为什么需要这个阶段

因为一个大需求直接开始写，很容易失控。

“用户管理模块” 听起来很简单，但实际上包含：

• 用户表设计
• 注册接口
• 登录接口
• 权限校验
• 角色管理
• 第三方登录
• 用户列表
• 用户详情
• 用户编辑
• 用户删除

如果不拆任务，你会在这 10 个功能之间跳来跳去，最后哪个都没做完。

Planning 阶段就是把大需求拆成小任务，一个一个做。

这个阶段产出什么

两个工件：

1. PRD 文档：详细描述每个功能的用户故事和验收标准
2. Epic 和 Story 列表：把 PRD 拆分成可执行的开发任务

PRD 的核心是 验收标准。它用可验证的条件定义 “什么叫做完了”：

1
2
3
4
5
6
7

## Story: 用户登录

### 验收标准
- [ ] 输入正确的用户名和密码后，跳转到首页
- [ ] 输入错误密码 3 次后，账号锁定 15 分钟
- [ ] 登录成功后，生成 JWT Token
...

注意每一条都是 可测试的。QA 代理在审查代码时，会逐条检查这些标准是否满足。

Solutioning：定技术方案和架构

这个阶段的目标是：定技术栈、画架构图、定接口规范。

为什么需要这个阶段

因为同一个需求，可以有多种实现方式。

“用户管理模块” 可以用：

• 技术栈：Node.js + Express + MySQL，或者 Python + Django + PostgreSQL
• 架构：单体应用，或者微服务
• 认证方式：JWT，或者 Session

如果不提前定方案，开发过程中会不断纠结 “用哪个更好”。

Solutioning 阶段就是把技术方案定下来，后面不用纠结。

这个阶段产出什么

两个工件：

1. 架构文档：描述系统的整体架构、技术栈、关键设计决策
2. 接口契约：定义所有接口的请求和响应格式（OpenAPI 格式）

架构文档的核心是 约束而非自由。它不是告诉 Dev “你可以用任何数据库”，而是明确规定 “必须用 PostgreSQL，且所有表必须有 created_at 和 updated_at 字段”。

Implementation：写代码和测试

这个阶段的目标是：按任务写代码，每个任务一个 Story。

为什么用 Story 而不是直接修改文件

因为 Story 是可追溯的。

一个 Story 包含：

• 变更说明：为什么要改
• 影响范围：改了哪些文件
• 代码 diff：具体改动
• 测试用例：如何验证

如果直接修改文件，三个月后你不记得为什么这么改。但如果用 Story，你可以随时查看这个 Story 的变更说明。

这个阶段产出什么

每个任务产出一个 Story 文档：

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

# Story 1.1: 用户注册接口

## 变更说明
实现用户注册接口，支持邮箱和手机号注册

## 影响文件
- src/routes/user.js (CREATE)
- src/controllers/user.controller.js (CREATE)
...

## 代码变更
[具体的代码diff]

## 测试用例
- 测试邮箱注册成功
- 测试手机号注册成功
...

2.4. 角色切换的黄金法则

BMAD 的一个核心原则是：一次只用一个代理，且必须在新的干净对话中启动。

什么是角色污染？

假设你在同一个对话中先用 SM 创建了一个 Story，然后直接让 Dev 实现。这时候会发生什么？

AI 的上下文中既有 SM 的 “规划思维”，又有 Dev 的 “实现思维”。结果就是 Dev 可能会：

• 擅自修改 Story 的验收标准（因为它觉得 “这样实现更简单”）
• 偏离架构文档的约束（因为它 “忘记” 了架构师的规定）

这就是角色污染。两个角色的职责混在一起，导致输出质量下降。

正确的切换方式

步骤 1：完成当前角色的任务

在 SM 对话中，创建完 Story 后，把内容保存到项目目录：

1

docs/stories/story-1.1.md

步骤 2：开启新的干净对话

关闭当前对话，打开一个全新的对话窗口。

步骤 3：激活新角色

在新对话中输入：

1
2

*agent dev
develop-story story-1.1

这时 Dev 代理会读取 docs/stories/story-1.1.md 文件，基于这份文档开始工作。它的上下文中 只有 Story 的内容，没有 SM 的思考过程。

为什么要这么麻烦？

因为这确保了 职责的单一性。每个代理只关注自己的任务：

• SM 只负责拆分 Story，不关心怎么实现
• Dev 只负责实现功能，不关心为什么要这样拆分
• QA 只负责审查质量，不关心实现细节

这种分离带来了两个好处：

1. 输出质量更高：每个代理都能专注于自己的领域，不会被其他角色的思维干扰
2. 可追溯性更强：每个阶段的输出都有独立的文档，三个月后回来看，能清楚地知道 “当时为什么这么做”

2.5. 本章总结与角色速查表

让我们回顾一下核心要点：

BMAD 的目录结构

四个阶段的分工

角色切换检查清单

在切换角色前，问自己三个问题：

如果三个问题的答案都是 “是”，才能切换到下一个角色。

第三章. 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. 记录技术债务

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

第四章. 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. 独立阶段启动用于补充文档

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

第五章. 模块扩展：BMB 与 CIS 的进阶用法

5.1. 三个模块的分工逻辑

在安装 BMAD 时，你可能注意到了模块选择界面：

1
2
3
4
5

? Select modules to install:
  ◉ BMM: BMad Method Agile-AI Driven-Development
  ◯ BMB: BMad Builder (Create Custom Agents)
  ◯ CIS: Creative Innovation Suite
TIPS:还有一个游戏相关的模块我们就不涉及了

这三个模块不是互相替代的关系，而是 互补的关系。我们用一个表格来说明：

三个模块的协作关系

这个图的核心逻辑是：

1. CIS 为 BMM 提供高质量输入：用头脑风暴、设计思维等方法，产生更好的需求和方案
2. BMM 把创意落实成代码：用四阶段流程，把需求变成可交付的产品
3. BMB 把经验固化成工具：当你发现某个流程经常重复，用 BMB 把它固化成自定义代理或工作流

安装后的目录结构

安装完成后，_bmad/ 目录的结构是：

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

_bmad/
├── core/              # 核心引擎和通用工作流
│   ├── agents/
│   ├── tasks/
│   └── workflows/
├── bmm/               # BMad Method：四阶段开发流程
│   ├── agents/
│   ├── workflows/
│   └── data/
├── bmb/               # BMad Builder：创建自定义工具
│   ├── agents/
│   ├── workflows/
│   └── data/
├── cis/               # Creative Innovation Suite：创意工具
│   ├── agents/
│   ├── workflows/
│   └── data/
├── _config/           # 所有模块的配置和清单
└── _memory/           # 持久记忆（例如 storyteller 的偏好）

注意每个模块都有自己的 agents/、workflows/ 和 data/ 目录。这意味着：

• BMM 的代理（Analyst、PM、Architect 等）只负责开发流程
• BMB 的代理（Agent Builder、Workflow Builder 等）只负责创建工具
• CIS 的代理（Brainstorming Coach、Design Thinking Coach 等）只负责创意和策略

它们各司其职，不会互相干扰。

5.2. BMB：给创作者用的工具工厂

BMB 是干什么的？

BMB 的全称是 BMad Builder，它的目标是：让你能够创建属于自己的 BMAD 组件。

什么叫 “BMAD 组件”？包括三类：

1. Agent（代理）：比如 “教育产品专家”、“内部工具架构师”
2. Workflow（工作流）：比如 “课程大纲设计流程”、“内部需求 intake 流程”
3. Module（模块）：一整套代理 + 工作流 + 配置，打包成一个独立模块

为什么需要 BMB？

前面几章，我们一直在用 BMM 自带的代理：Analyst、PM、Architect、Dev、QA。但这些代理是 通用的，它们不了解你的特定领域。

举个例子：

场景 1：教育行业

如果你在做教育产品，BMM 的 PM 代理能帮你写 PRD，但它不知道：

• 教学设计的 ADDIE 模型
• 布鲁姆认知层次
• 学习路径设计的最佳实践

你需要一个 “教育产品专家” 代理，它懂这些领域知识。

场景 2：内部工具开发

如果你在做公司内部工具，BMM 的 Architect 代理能帮你设计架构，但它不知道：

• 你们公司的技术栈规范
• 内部系统的集成方式
• 权限管理的特殊要求

你需要一个 “内部工具架构师” 代理，它懂你们公司的规范。

BMB 就是用来创建这些自定义代理的工具。

BMB 的三个 Builder 代理

BMB 提供了三个 Builder 代理，分别用于创建不同类型的组件：

Agent Builder：创建自定义代理

Agent Builder 的工作流路径是：_bmad/bmb/workflows/agent/workflow.md

它有三种模式：

Create 模式的关键步骤

我们重点看 Create 模式，它包含以下步骤：

步骤 1：头脑风暴

1
2
3
4
5
6
7
8
9
10

让我们先理解一下这个代理要解决的问题：

1. 这个代理是为谁服务的？
   - 产品经理？开发者？运营人员？

2. 典型使用场景是什么？
   - 在什么情况下会用到这个代理？

3. 它要解决什么痛点？
   - 现有的代理为什么不够用？

这一步的目标是 明确代理的定位。不要急于设计，先把 “为什么需要这个代理” 说清楚。

步骤 2：类型与元数据

1
2
3
4
5
6

现在让我们定义代理的基本信息：

1. 代理名称（name）：例如 "education-product-expert"
2. 显示名称（display_name）：例如 "教育产品专家"
3. 描述（description）：一句话说明这个代理的作用
4. 适用模块（module）：这个代理属于哪个模块？

这一步定义代理的 身份信息。

步骤 3：Persona 设计

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

让我们设计代理的人格：

1. 角色（role）：这个代理扮演什么角色？
   例如："资深教育产品顾问，有 10 年教学设计经验"

2. 沟通风格（communication_style）：
   - 正式还是轻松？
   - 详细还是简洁？
   - 鼓励性还是批判性？

3. 核心原则（principles）：
   - 这个代理坚持什么原则？
   - 例如："以学习者为中心"、"基于证据的设计"

这一步定义代理的 性格和价值观。

步骤 4：菜单和命令

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

让我们设计代理的菜单：

这个代理需要哪些命令？例如：

[MH] 重新显示菜单帮助
[CH] 与代理聊天
[CD] 创建课程大纲
[LD] 设计学习路径
[AD] 设计评估方案
[PM] 启动派对模式
[DA] 解散代理

每个命令对应一个工作流或任务。

这一步定义代理的 功能菜单。

步骤 5：激活逻辑

1
2
3
4
5
6
7
8

代理启动时需要加载哪些文件？

例如：
- config.yaml（项目配置）
- project-context.md（项目上下文）
- education-standards.md（教育标准文档）

这些文件会在代理激活时自动加载到上下文中。

这一步定义代理的 启动行为。

步骤 6：生成代理文件

所有步骤完成后，Agent Builder 会生成一个完整的代理文件：

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

---
name: education-product-expert
display_name: 教育产品专家
module: custom
version: 1.0.0
---

# 教育产品专家

你是一位资深教育产品顾问，有 10 年教学设计经验...

## 核心原则
- 以学习者为中心
- 基于证据的设计
- 遵循 ADDIE 模型

## 菜单
[MH] 重新显示菜单帮助
[CH] 与代理聊天
[CD] 创建课程大纲
...

这个文件会保存到 _bmad/custom/agents/education-product-expert.md。

自定义代理的使用

创建完成后，你可以像使用 BMM 代理一样使用它：

1

*agent education-product-expert

系统会加载你创建的代理文件，激活 “教育产品专家” 代理。

Workflow Builder：创建自定义工作流

Workflow Builder 的工作流路径是：_bmad/bmb/workflows/workflow/workflow.md

它也有三种模式：Create、Edit、Validate。

Create 模式的关键步骤

步骤 1：定义工作流目标

1
2
3
4
5
6
7
8
9
10

让我们先理解这个工作流要做什么：

1. 这个工作流的输入是什么？
   - 用户提供什么信息？

2. 这个工作流的输出是什么？
   - 最终生成什么文档或结果？

3. 这个工作流分几个阶段？
   - 每个阶段做什么？

步骤 2：设计步骤文件

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

让我们把工作流拆分成步骤：

阶段 1：需求收集
  - step-01-understand.md：理解用户需求
  - step-02-research.md：调研现有方案

阶段 2：方案设计
  - step-03-brainstorm.md：头脑风暴
  - step-04-select.md：选择最佳方案

阶段 3：文档生成
  - step-05-generate.md：生成文档
  - step-06-review.md：审查文档

每个步骤是一个独立的 Markdown 文件。

步骤 3：定义步骤内容

1
2
3
4
5
6
7

让我们为每个步骤定义内容：

step-01-understand.md：
- 这个步骤要问用户什么问题？
- 这个步骤要读取哪些文件？
- 这个步骤要写入哪些文件？
- 这个步骤完成后，下一步是什么？

步骤 4：生成工作流文件

Workflow Builder 会生成：

1. workflow.md：工作流的主文件
2. steps/ 目录：所有步骤文件
3. data/ 目录（可选）：工作流需要的数据文件

生成的文件会保存到 _bmad/custom/workflows/your-workflow/。

Module Builder：创建自定义模块

Module Builder 的目标是：打包一整套代理 + 工作流 + 配置，形成一个独立模块。

什么时候需要创建模块？

场景 1：为特定领域创建完整工具集

例如，你想为 “教学设计” 创建一个完整的 BMAD 模块：

• 代理：课程设计师、测评专家、运营策划
• 工作流：课程结构设计、作业设计、考试出题、教学复盘
• 数据：教学设计模板、评估标准、案例库

场景 2：为团队创建内部工具集

例如，你想为公司内部创建一个 “内部工具开发” 模块：

• 代理：内部系统 PO、权限设计顾问、数据接口协调人
• 工作流：内部需求 intake 流程、系统间集成设计流、变更影响分析流
• 数据：公司技术栈规范、内部系统清单、权限模板

Module Builder 的工作流

Module Builder 会引导你：

1. 定义模块元数据：名称、描述、版本
2. 选择包含的代理：哪些代理属于这个模块
3. 选择包含的工作流：哪些工作流属于这个模块
4. 配置模块依赖：这个模块依赖哪些其他模块
5. 生成安装脚本：如何安装和卸载这个模块

最终生成的模块结构：

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

_bmad/your-module/
├── config.yaml              # 模块配置
├── agents/                  # 模块的代理
│   ├── agent-1.md
│   └── agent-2.md
├── workflows/               # 模块的工作流
│   ├── workflow-1/
│   └── workflow-2/
├── data/                    # 模块的数据文件
├── _config/                 # 模块的配置文件
│   └── modules/
│       └── your-module.config.yaml
└── README.md                # 模块文档

5.3. CIS：为 BMM 和 BMB 提供高质量创意燃料

CIS 模块的定位

CIS 的全称是 Creative Innovation Suite（创意创新套件）。它的目标不是写代码，而是：帮你想清楚做什么、为什么、从哪些角度想。

CIS 包含五类工作流：

CIS 的五个代理

在 _bmad/cis/agents/ 目录下，有五个代理：

Brainstorming：真正专业的创意发散

Brainstorming Coach 的工作流路径是：_bmad/cis/workflows/brainstorming/workflow.yaml

它的核心特点是：使用 36+ 种创意技巧，轮换引导你产出点子。

创意技巧库

在 _bmad/cis/workflows/brainstorming/data/design-methods.csv 文件中，包含 36 种创意技巧，分为 7 大类别：

Brainstorming 的工作流程

关键特点：

1. 技巧轮换：不会一直用同一种技巧，而是根据场景切换
2. 引导式提问：通过提问引导你产出，而不是 AI 自己写
3. 结构化输出：最终生成一份结构化的头脑风暴报告

适用时机

在 BMM 的 Analysis 阶段之前：

1
2
3
4
5
6

*brainstorming-coach
[开始头脑风暴]

# 产出大量点子后
*analyst
[PB] 创建产品简报（基于头脑风暴结果）

为 BMB 的 Module 设计提供创意素材：

1
2
3
4
5
6

*brainstorming-coach
[为新模块头脑风暴]

# 产出模块创意后
*agent module-builder
[创建模块]

Design Thinking：做真正的以用户为中心

Design Thinking Coach 的工作流路径是：_bmad/cis/workflows/design-thinking/workflow.yaml

它遵循设计思维的五个阶段：

五个阶段的关键活动

适用时机

在写 PRD 之前，先跑一轮设计思维：

1
2
3
4
5
6

*design-thinking-coach
[开始设计思维流程]

# 完成五个阶段后
*pm
[CP] 创建 PRD（基于设计思维的输出）

输出可以直接喂给 Analyst 或 PM，作为产品简报 / PRD 的原料。

Innovation Strategy：上到商业模式那一层

Innovation Strategist 的工作流路径是：_bmad/cis/workflows/innovation-strategy/workflow.yaml

它的目标不是设计一个小功``能，而是：思考产品 / 平台未来 6-12 个月的演化方向。

内置框架

适用时机

不是在做一个小功能，而是在考虑：

• 这个产品未来 6-12 个月的演化方向
• 要不要砍掉某块功能 / 打开新市场
• 如何建立竞争壁垒

这类输出，可以和 BMM 的 产品简报 + PRD 形成上下游关系。

Problem Solving：系统化拆解复杂问题

Creative Problem Solver 的工作流路径是：_bmad/cis/workflows/problem-solving/workflow.yaml

它的目标是：用系统化方法拆解复杂问题，找到根因和解法。

方法库

工作流程

适用时机

不是写一个新功能，而是：

• 现有系统经常出问题
• 性能、稳定性、协作、流程某处一直痛

产出的 “根因 → 解法” 可以转成：

• BMM 的 Epic / Story
• BMB 的 新 Workflow 设计

Storytelling：把一切讲成一个好故事

Storyteller 的工作流路径是：_bmad/cis/workflows/storytelling/workflow.yaml

它的目标是：把复杂的技术、产品、项目讲成一个引人入胜的故事。

故事模型库

在 _bmad/cis/workflows/storytelling/data/story-models.csv 文件中，包含 25 套故事模型：

适用时机

你想：

• 给团队讲清楚这个项目的 “英雄之旅”
• 把复杂的架构改变解释给非技术听众
• 做一个 “项目复盘故事”

输出可以用于：

• Pitch deck
• PRD 封面
• 内部分享会
• 项目复盘报告

5.4. 三个模块的协作模式

现在我们知道了三个模块各自的功能，接下来看它们如何协作。

模式 1：CIS → BMM（创意到实现）

这是最常见的协作模式：用 CIS 产生高质量创意，然后用 BMM 落实成代码。

具体流程：

步骤 1：用 CIS 挖掘创意和需求

1
2
3
4
5
6
7

*brainstorming-coach
[开始头脑风暴]
# 产出大量点子

*design-thinking-coach
[开始设计思维流程]
# 产出用户洞察和解决方案

步骤 2：用 BMM 落实成规格

1
2
3
4
5
6
7
8

*analyst
[PB] 创建产品简报（基于 CIS 的输出）

*pm
[CP] 创建 PRD

*architect
[CA] 创建架构文档

步骤 3：用 BMM 实现代码

1
2
3
4
5