BMAD-METHOD - 完整学习教程

教程级别： 从零到一 预计学习时间： 4-6 小时 前置知识： 命令行基础（终端操作）、Git 基本操作（clone、commit）、敏捷开发基本概念（Sprint、Story）、至少一种 AI IDE 工具使用经验（Claude Code 或 Cursor）

环境搭建指南

系统要求

• 操作系统：Windows / macOS / Linux（任意）
• Node.js：v20 及以上
• Python：3.10 及以上
• uv：Python 包管理器（可选，部分模块需要）
• AI IDE：Claude Code（推荐）、Cursor、Codex CLI 或 GitHub Copilot

安装步骤

第一步：安装前置依赖

# 检查 Node.js 版本（需要 v20+）
node --version

# 如果未安装或版本过低，使用 nvm 安装最新 LTS 版本
# macOS/Linux:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install --lts
nvm use --lts

# 检查 Python 版本（需要 3.10+）
python3 --version

# 安装 uv（Python 包管理器）
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows:
# powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

第二步：安装 BMAD-METHOD

# 使用 npx 安装 BMAD（无需全局安装）
npx bmad-method install

# 安装器会依次提示：
# 1. 选择安装目录（默认当前目录）
# 2. 选择模块（BMM 核心模块必选，其他可选）
# 3. 选择目标 AI 工具（Claude Code / Cursor / Codex CLI 等）

非交互式安装（推荐用于脚本或 CI/CD）：

# 仅安装 BMM 核心模块，配置为 Claude Code 工具
npx bmad-method install --directory /path/to/my-project --modules bmm --tools claude-code --yes

# 安装所有模块，配置为 Cursor 工具
npx bmad-method install --directory /path/to/my-project --modules bmm,bmb,tea --tools cursor --yes

基于官方 README（npm 版本 6.2.2）和 Getting Started 教程

验证安装

# 进入安装了 BMAD 的项目目录
cd /path/to/my-project

# 检查 .bmad 目录是否已创建
ls -la .bmad/

# 应该看到类似以下结构：
# .bmad/
# ├── agents/          # Agent 人格定义文件
# ├── workflows/       # 工作流定义文件
# ├── templates/       # 输出模板文件
# └── config.yaml      # 配置文件

# 如果使用 Claude Code，检查是否生成了 CLAUDE.md 或 .claude/ 配置
cat CLAUDE.md 2>/dev/null || echo "配置文件可能在 .claude/ 目录中"

.bmad/
├── agents/
├── workflows/
├── templates/
└── config.yaml

安装成功后，在 AI IDE 中打开项目目录即可开始使用 BMAD。如果使用 Claude Code，输入 bmad-help 可验证 Agent 人格是否加载成功。

注：以上目录结构为典型输出，实际结构可能因选择的模块和工具不同而略有差异。基于官方 README（npm 版本 6.2.2）

第一部分：入门篇

1.1 第一个 BMAD 项目：使用 Quick Flow

概念讲解：

BMAD-METHOD 提供两种开发路径：Full Flow（四阶段完整流程）和 Quick Flow（快捷通道）。Quick Flow 是为小型、明确的工作项设计的简化路径——例如 Bug 修复、小功能添加或一次性脚本。它跳过了 Phase 1（分析）到 Phase 3（方案），直接进入规格定义和代码实现。

对于初学者，建议从 Quick Flow 开始，先感受 BMAD 的核心工作方式，再逐步学习完整的四阶段流程。

Quick Flow 的核心步骤： 1. 使用 bmad-quick-dev 工作流 2. 描述你要完成的工作 3. BMAD Agent 引导你产出 spec-*.md 规格文件 4. 基于规格生成代码

代码示例：

# 基于官方 Getting Started 教程（版本 6.2.2）

# 1. 进入你的项目目录
cd /path/to/my-project

# 2. 启动 Claude Code（推荐）
claude

# 3. 在 Claude Code 中输入以下指令启动 Quick Flow
# 用户输入:
# "bmad-quick-dev I need to add a health check endpoint to my Express API"

# BMAD 的 Developer Agent 会引导你完成以下步骤:
# Step 1: 理解需求 - Agent 提问以明确需求细节
# Step 2: 产出 spec-health-check.md - 包含功能描述、约束和验收标准
# Step 3: 基于规格生成代码
# Step 4: 生成基本测试

执行结果：

# Agent 的典型引导流程（模拟）

[BMAD Developer Agent]
I'll help you add a health check endpoint using the Quick Flow.

Let me clarify a few things first:
1. Should the endpoint return database connectivity status?
2. Do you need version/uptime information in the response?
3. Any specific response format requirements?

[You]
1. Yes, check DB connectivity
2. Just version info is fine
3. JSON format

[BMAD Developer Agent]
Great! I've created spec-health-check.md with:
- Endpoint: GET /health
- Response: { status, version, dbConnected, timestamp }
- Error handling for DB connection failures

Now let me implement this based on your spec...

[Generates code for health check endpoint]
[Generates test file for the endpoint]

Implementation complete! Here's a summary:
- File created: src/routes/health.js
- Test created: tests/health.test.js
- Spec saved: docs/spec-health-check.md

注：以上输出为模拟结果，实际对话取决于 AI IDE 和模型版本。基于 BMAD Quick Flow 工作流设计

练习题： 1. 使用 Quick Flow 为你的项目添加一个简单的日志中间件功能。 2. 尝试使用 bmad-help 询问"Quick Flow 适合什么场景？"，理解何时该用 Quick Flow 而非 Full Flow。

1.2 理解 Agent 人格体系

概念讲解：

BMAD 的核心创新之一是专业化 Agent 人格（Agent Persona）。每个 Agent 模拟敏捷团队中的一个角色，具有特定的专业领域、工作风格和可用命令。这些 Agent 不是自主运行的程序，而是"带有菜单、记忆和人格的系统提示"——它们在你的 AI IDE 中以人格切换的方式工作。

BMAD 的 7 个核心 Agent 及其职责：

理解 Agent 人格的关键：你不是在"使用工具"，而是在"与专家协作"。当你调用 Architect Agent 时，AI 会以系统架构师的视角思考和建议；当你切换到 Developer Agent 时，AI 会以开发者的视角关注代码实现细节。

代码示例：

# 基于官方文档（版本 6.2.2）

# 在 Claude Code 中查看可用的 Agent 命令
# 用户输入:
# "bmad-help what agents are available?"

# 典型响应（模拟）:
# Available agents in your installation:
#
# *analyst    - Research, brainstorm, analyze markets
# *pm         - Create PRDs, define requirements, set metrics
# *architect  - Design systems, choose tech stacks, define APIs
# *po         - Shard epics, bridge planning to development
# *sm         - Plan sprints, facilitate stories, retrospectives
# *dev        - Implement code, write tests, fix bugs
# *qa         - Review code, assess risks, test strategies
#
# Type * followed by agent name to activate (e.g., *architect)

# 激活 Architect Agent
# 用户输入:
# "*architect"

# Architect Agent 激活后，AI 的行为会切换到架构师视角:
# "I'm now operating as your System Architect. I focus on:
#  - System design and architecture decisions
#  - Technology stack selection and rationale
#  - API design and data modeling
#  - ADR (Architecture Decision Records)
#
#  How can I help with your architecture today?"

执行结果：

# Agent 切换的典型输出（模拟）

[Activating Architect Agent...]
Agent: System Architect
Role: Technical Leadership
Commands: *design, *review, *recommend, *help

I'm now operating as your System Architect.
I focus on system design, technology decisions, and API design.

How can I help with your architecture today?

注：以上输出为模拟结果。基于 BMAD Agent 人格机制设计

练习题： 1. 依次激活 PM Agent 和 Architect Agent，观察它们对同一需求（如"构建一个用户注册系统"）的不同视角和建议。 2. 使用 bmad-help 查询每个 Agent 的详细命令列表。

1.3 使用 bmad-help 智能引导

概念讲解：

bmad-help 是 BMAD 的内置智能引导系统。它是一个上下文感知的帮助工具——不同于静态文档，bmad-help 会根据你当前所处的项目阶段和已完成的步骤，给出精确的下一步建议。

bmad-help 的三种使用方式： 1. 问"What's next?" — 获取当前阶段应执行的下一步操作 2. 描述当前状态 — 如"I just finished the architecture"获取阶段转换建议 3. 直接提问 — 如"How do I create a custom agent?"获取专题指导

代码示例：

# 基于官方 README（版本 6.2.2）

# 使用场景 1: 刚开始一个新项目，不知道从哪里入手
# 用户输入:
# "bmad-help I'm starting a new project, what should I do first?"

# 使用场景 2: 已完成架构设计，准备进入实施
# 用户输入:
# "bmad-help I just finished the architecture, what do I do next?"

# 使用场景 3: 遇到具体问题
# 用户输入:
# "bmad-help how do I use Party Mode?"

# 使用场景 4: 查询工作流状态
# 用户输入:
# "bmad-help what is the difference between Quick Flow and Full Flow?"

执行结果：

# 场景 2 的典型响应（模拟）

[bmad-help]
You've completed Phase 3 (Solutioning). Here's your path forward:

1. Run bmad-check-implementation-readiness
   → Verify all artifacts are in place before coding

2. Run bmad-sprint-planning
   → Initialize sprint tracking (creates sprint-status.yaml)

3. Run bmad-create-story
   → Prepare your first story for implementation

4. Run bmad-dev-story
   → Implement the story with guided development

Tip: If your project is small, consider using bmad-quick-dev
instead of the full sprint workflow.

注：以上输出为模拟结果。基于 bmad-help 工作流引导机制

练习题： 1. 在一个空项目中，使用 bmad-help 引导你从头开始，记录它推荐的完整流程。 2. 使用 bmad-help 查询"如何安装额外的模块（如 TEA 或 BMGD）"。

第二部分：进阶篇

2.1 Full Flow Phase 1-2：分析与规划

概念讲解：

Full Flow（完整流程）是 BMAD 的核心方法论，包含四个阶段。Phase 1（分析）和 Phase 2（规划）是项目的基础阶段。

Phase 1: 分析阶段（可选但推荐） - 目标：验证项目想法、理解市场和用户需求 - 核心工作流：bmad-brainstorming、bmad-market-research、bmad-product-brief、bmad-prfaq - 核心产出：product-brief.md（项目愿景和核心价值主张） - 关键方法：Amazon 的"Working Backwards"（逆向工作法）——通过 bmad-prfaq 先写新闻稿来验证概念

Phase 2: 规划阶段 - 目标：将愿景转化为明确的需求规格 - 核心工作流：bmad-create-prd、bmad-create-ux-design - 核心产出：PRD.md（产品需求文档）和 ux-spec.md（用户体验规格） - PRD 包含：功能需求（FR）、非功能需求（NFR）、史诗（Epic）定义、成功指标

代码示例：

# 基于官方 Getting Started 教程和工作流文档（版本 6.2.2）

# === Phase 1: 分析阶段 ===

# 1. 启动头脑风暴
# 用户输入:
# "*analyst I want to brainstorm a task management app for remote teams"

# Analyst Agent 引导你完成头脑风暴，产出 brainstorming-report.md

# 2. 创建产品简介
# 用户输入:
# "*pm let's create a product brief based on our brainstorming"

# PM Agent 引导你产出 product-brief.md，包含:
# - 目标用户画像
# - 核心价值主张
# - 市场定位
# - 关键假设和风险

# === Phase 2: 规划阶段 ===

# 3. 创建 PRD（产品需求文档）
# 用户输入:
# "*pm create a PRD based on the product brief"

# PM Agent 引导你产出 PRD.md，结构如下:

# PRD: TaskFlow - 远程团队任务管理应用

## 1. 产品概述
TaskFlow 是一个专为远程团队设计的任务管理应用...

## 2. 目标用户
- 远程工作团队（3-20 人）
- 分布式项目管理者和团队成员

## 3. 功能需求（FR）
- FR-001: 用户注册和登录（OAuth 2.0 + 邮箱）
- FR-002: 任务创建、分配和状态管理
- FR-003: 实时协作和评论
- FR-004: 看板视图和列表视图切换
- FR-005: 截止日期提醒和通知

## 4. 非功能需求（NFR）
- NFR-001: 页面加载时间 < 2 秒
- NFR-002: 支持 100 并发用户
- NFR-003: 99.9% 可用性
- NFR-004: 数据加密传输（HTTPS）

## 5. 成功指标
- 用户日活跃率 > 40%
- 任务完成率 > 80%
- 用户满意度评分 > 4.0/5.0

## 6. 史诗定义
- Epic 1: 用户认证和授权
- Epic 2: 任务核心功能
- Epic 3: 协作和沟通
- Epic 4: 通知和报告

# 4. 创建 UX 设计规格
# 用户输入:
# "*pm create a UX spec for the task management features"

# PM Agent 引导你产出 ux-spec.md

执行结果：

# Phase 1 完成后的文件结构

my-project/
├── .bmad/
├── docs/
│   ├── brainstorming-report.md     # 头脑风暴报告
│   └── product-brief.md            # 产品简介
└── (源码目录)

# Phase 2 完成后新增文件

my-project/
├── .bmad/
├── docs/
│   ├── brainstorming-report.md
│   ├── product-brief.md
│   ├── PRD.md                      # 产品需求文档
│   └── ux-spec.md                  # UX 设计规格
└── (源码目录)

注：以上文件内容和结构为模拟示例。基于 BMAD 工作流文档和产出物设计

注意事项： - Phase 1 是可选的，但强烈推荐。跳过分析阶段直接进入规划，可能导致需求不清晰，后续返工成本更高。 - PRD 的质量直接决定了后续所有阶段的输出质量。确保 PRD 中的功能需求有明确的验收标准。 - 每个阶段的产出文档应立即提交到 Git：git add docs/ && git commit -m "Add Phase 1 analysis documents"

练习题： 1. 为一个"个人记账应用"完成 Phase 1 的头脑风暴和产品简介。 2. 基于产品简介，使用 PM Agent 创建 PRD，至少包含 5 个功能需求和 3 个非功能需求。

2.2 Full Flow Phase 3：方案设计

概念讲解：

Phase 3（方案阶段）是将需求转化为技术方案的关键阶段。这个阶段由 Architect Agent 和 PO Agent 主导，产出技术架构文档和可实施的工作分解。

核心工作流： 1. bmad-create-architecture — Architect Agent 基于PRD 创建架构文档（含 ADR 架构决策记录） 2. bmad-create-epics-and-stories — PO Agent 将需求拆分为 Epic 和 Story 3. bmad-check-implementation-readiness — 实施就绪检查（Gate Check）

Epic Sharding（史诗分片） 是 Phase 3 的核心机制。PO Agent 将单体 PRD 拆分为独立的 Epic 文件，每个 Epic 包含相关的需求、架构约束和用户故事，解决 AI 上下文窗口的限制。

代码示例：

# 基于官方工作流文档（版本 6.2.2）

# 1. 激活 Architect Agent 创建架构文档
# 用户输入:
# "*architect create architecture based on PRD.md"

# Architect Agent 读取 PRD.md 和 ux-spec.md，引导你完成:
# - 技术栈选型（前端/后端/数据库/部署）
# - 系统架构设计（微服务/单体/Serverless）
# - API 设计
# - 数据模型设计
# - 安全策略
# - 架构决策记录（ADR）

# 产出 architecture.md，典型结构如下:

# Architecture: TaskFlow

## 技术栈
- 前端: React 18 + TypeScript + Tailwind CSS
- 后端: Node.js + Express + TypeScript
- 数据库: PostgreSQL 15 + Redis 7
- 部署: Docker + AWS ECS

## ADR-001: 使用 PostgreSQL 而非 MongoDB
- 上下文: 任务管理需要复杂的关系查询
- 决策: 使用 PostgreSQL 作为主数据库
- 理由: 任务-用户-团队的关系模型更适合关系型数据库
- 后果: 需要定义明确的 Schema，但获得了数据一致性保障

## 系统架构
[架构图描述]

## API 设计
- POST /api/auth/login — 用户登录
- GET /api/tasks — 获取任务列表
- POST /api/tasks — 创建任务
- PUT /api/tasks/:id — 更新任务
- DELETE /api/tasks/:id — 删除任务

## 数据模型
[ER 图描述]

# 2. 激活 PO Agent 进行 Epic Sharding
# 用户输入:
# "*po shard the PRD and architecture into epics"

# PO Agent 读取 PRD.md 和 architecture.md，产出分片的 Epic 文件:

# Epic Sharding 后的文件结构

my-project/
├── docs/
│   ├── PRD.md
│   ├── architecture.md
│   └── epics/
│       ├── epic-1-user-auth.md        # 用户认证和授权
│       ├── epic-2-task-core.md        # 任务核心功能
│       ├── epic-3-collaboration.md    # 协作和沟通
│       └── epic-4-notifications.md    # 通知和报告
└── ...

# 3. 运行实施就绪检查
# 用户输入:
# "*architect check implementation readiness"

# Architect Agent 检查:
# - PRD 是否完整（所有 FR/NFR 是否有验收标准）
# - 架构文档是否覆盖所有需求
# - Epic 文件是否完整拆分
# - 是否有遗漏的技术决策
# 产出: PASS / CONCERNS / FAIL 决策

执行结果：

# 实施就绪检查的典型输出（模拟）

[Implementation Readiness Check]

Checking artifacts...
✅ PRD.md: Complete (5 FRs, 4 NFRs, 4 Epics defined)
✅ architecture.md: Complete (tech stack, API design, data model)
✅ epics/: 4 epic files present and well-structured
⚠️ CONCERN: NFR-003 (99.9% availability) lacks specific infrastructure plan
⚠️ CONCERN: No error handling strategy defined in architecture

Status: CONCERNS
Recommendation: Address the 2 concerns above before proceeding.
Run *architect to update the architecture document.

注：以上输出为模拟结果。基于 BMAD Phase 3 工作流设计

注意事项： - 架构文档中的 ADR（Architecture Decision Records）非常重要——它们记录了"为什么"做出某个技术决策，而非仅记录决策本身。这为后续的开发和审查提供了上下文。 - Epic Sharding 的粒度很关键：每个 Epic 应该包含 3-8 个 Story，每个 Story 应该在 1-2 天内可完成。 - 实施就绪检查中的 CONCERNS 状态不阻止进入 Phase 4，但建议先解决标记的问题。 - 所有产出文档应提交到 Git：git add docs/ && git commit -m "Add Phase 3 solutioning documents"

练习题： 1. 为你的记账应用创建架构文档，至少包含 2 个 ADR。 2. 使用 PO Agent 将 PRD 拆分为 Epic 文件，确保每个 Epic 包含明确的验收标准。

2.3 Full Flow Phase 4：迭代实施

概念讲解：

Phase 4（实施阶段）是 BMAD 工作流的执行阶段，由 SM（Scrum Master）、Developer 和 QA Agent 协作完成。这个阶段采用 Sprint 迭代模式，将 Epic 中的 Story 逐个实施。

核心工作流循环： 1. bmad-sprint-planning — 初始化冲刺跟踪（整个项目只需执行一次） 2. bmad-create-story — SM Agent 准备下一个 Story 的详细规格 3. bmad-dev-story — Developer Agent 基于 Story 规格实现代码 4. bmad-code-review — QA Agent 审查代码质量 5. bmad-correct-course — 处理冲刺中的方向调整 6. bmad-sprint-status — 跟踪冲刺进度 7. bmad-retrospective — Epic 完成后的回顾

代码示例：

# 基于官方工作流文档（版本 6.2.2）

# 1. 初始化冲刺跟踪
# 用户输入:
# "*sm initialize sprint planning for epic-1-user-auth"

# SM Agent 创建 sprint-status.yaml:

# sprint-status.yaml（模拟）
sprint:
  name: "Sprint 1 - User Authentication"
  epic: "epic-1-user-auth"
  start_date: "2026-04-13"
  status: "in_progress"
stories:
  - id: "story-1-1"
    title: "User registration with email"
    status: "pending"
  - id: "story-1-2"
    title: "OAuth 2.0 login flow"
    status: "pending"
  - id: "story-1-3"
    title: "JWT token management"
    status: "pending"
  - id: "story-1-4"
    title: "Logout and session cleanup"
    status: "pending"

# 2. 创建第一个 Story 的详细规格
# 用户输入:
# "*sm create the next story"

# SM Agent 基于当前 Epic 和架构文档，产出超详细的 Story 文件:

# Story 1.1: User Registration with Email

## 上下文
- Epic: epic-1-user-auth
- 架构参考: architecture.md (ADR-002: Authentication Strategy)
- 技术约束: Node.js + Express + PostgreSQL

## 需求描述
实现基于邮箱的用户注册功能，包含:
- 邮箱格式验证
- 密码强度检查（最少 8 位，含大小写和数字）
- 密码加密存储（bcrypt）
- 注册成功后自动登录
- 重复邮箱检测

## 验收标准
- [ ] POST /api/auth/register 返回 201 和 JWT token
- [ ] 无效邮箱返回 400 和具体错误信息
- [ ] 弱密码返回 400 和密码强度提示
- [ ] 重复邮箱返回 409
- [ ] 密码以 bcrypt hash 存储
- [ ] 单元测试覆盖率 > 80%

## 实现指导
1. 创建 src/routes/auth.ts 路由文件
2. 创建 src/services/userService.ts 业务逻辑
3. 创建 src/models/User.ts 数据模型
4. 使用 zod 进行输入验证
5. 编写 tests/auth.test.ts 测试文件

# 3. 实施 Story
# 用户输入:
# "*dev implement story-1-1"

# Developer Agent 读取 Story 文件和相关上下文，生成代码

# 4. 代码审查
# 用户输入:
# "*qa review the code for story-1-1"

# QA Agent 审查代码质量、安全性和测试覆盖率

执行结果：

# 冲刺进度跟踪的典型输出（模拟）

[Sprint Status Update]
Sprint: Sprint 1 - User Authentication
Progress: 1/4 stories complete

✅ Story 1.1: User registration with email — COMPLETE
   - Files: src/routes/auth.ts, src/services/userService.ts
   - Tests: 8/8 passing, 92% coverage
🔄 Story 1.2: OAuth 2.0 login flow — IN PROGRESS
⬜ Story 1.3: JWT token management — PENDING
⬜ Story 1.4: Logout and session cleanup — PENDING

Sprint velocity: 3 story points (1 day elapsed)
Estimated completion: 3 more days

注：以上输出为模拟结果。基于 BMAD Phase 4 工作流设计

注意事项： - 每个 Story 文件都包含超详细的实现指导——这不是简单的需求描述，而是包含了具体的文件路径、实现步骤和技术约束。 - bmad-dev-story 工作流中，Developer Agent 会基于 Story 文件中的上下文生成代码。确保 Story 文件引用了正确的架构约束和技术栈信息。 - 代码审查（bmad-code-review）应在每个 Story 完成后立即执行，而非累积到 Sprint 结束。 - 社区反馈指出，单个 Story 工作流可能消耗 40-50k Token。注意控制 Story 的粒度，避免过于复杂的 Story。

练习题： 1. 为你的记账应用执行一个完整的 Sprint，至少完成 2 个 Story 的创建、实施和审查。 2. 使用 bmad-retrospective 在 Epic 完成后进行回顾，记录 3 条经验教训。

第三部分：高级篇

3.1 Party Mode：多 Agent 协作

概念讲解：

Party Mode 是 BMAD 的独特功能，允许将多个 Agent 人格引入同一个会话中进行协作和讨论。这模拟了真实敏捷团队中的"站会"或"设计评审"场景——不同专业视角的 Agent 可以就同一问题展开讨论，提供更全面的决策依据。

典型使用场景： - 架构评审：Architect Agent 提出方案，QA Agent 提出安全和质量顾虑，PM Agent 确认是否满足需求 - 需求澄清：PM Agent 解释需求意图，Developer Agent 提出技术可行性问题 - 冲刺回顾：SM Agent 主持回顾，Developer Agent 和 QA Agent 分享各自的观察

代码示例：

# 基于官方文档和社区案例（版本 6.2.2）

# 启动 Party Mode 进行架构评审
# 用户输入:
# "I want to discuss the database choice for TaskFlow.
#  Bring in the Architect, PM, and QA agents."

# Party Mode 的典型交互流程:

# [Architect Agent]:
# "Based on our PRD requirements for complex task-user relationships,
#  I recommend PostgreSQL over MongoDB. See ADR-001 for details."

# [QA Agent]:
# "I have a concern about the scalability of PostgreSQL for real-time
#  collaboration features. We should plan for read replicas or consider
#  Redis for caching frequently accessed task data."

# [PM Agent]:
# "The PRD specifies NFR-002 (100 concurrent users) and NFR-003 (99.9%
#  availability). PostgreSQL with read replicas should meet these
#  requirements within our budget constraints."

# [You]:
# "Good points. Let's go with PostgreSQL + Redis for caching.
#  Architect, please update ADR-001 accordingly."

执行结果：

# Party Mode 交互总结（模拟）

[Party Mode Session Summary]
Participants: Architect, PM, QA
Topic: Database choice for TaskFlow

Decisions:
1. Primary database: PostgreSQL (confirmed)
2. Caching layer: Redis for frequently accessed data (new)
3. Action item: Update ADR-001 to include Redis caching strategy

Follow-up:
- Architect: Update architecture.md with Redis configuration
- QA: Create test strategy for cache invalidation scenarios
- PM: Verify budget implications with NFR constraints

注：以上输出为模拟结果。基于 BMAD Party Mode 机制设计

注意事项： - Party Mode 会显著增加 Token 消耗——每个参与的 Agent 都需要加载其人格定义和相关上下文。建议限制 Party Mode 参与者不超过 3 个 Agent。 - Party Mode 最适合用于决策点（如架构评审、需求澄清），而非日常的开发工作。 - 在 Party Mode 中，确保人类开发者保持"引导者"角色——不要让 Agent 之间的讨论偏离主题。

3.2 使用 BMad Builder 创建自定义 Agent

概念讲解：

BMad Builder（BMB）是 BMAD 的扩展模块，允许你创建自定义的 Agent 人格和工作流。这使 BMAD 不局限于软件开发领域——你可以为任何专业领域创建专用的 Agent。

Agent 人格定义的核心结构： - agent 块：名称、ID、标题、自定义规则（专业领域、约束、拒绝事项） - persona 块：角色、风格、身份、关注点 - dependencies：关联的任务和模板 - commands：可调用的命令列表

"One-Agent Rule"：建议一次只构建一个 Agent，使用一周后再决定是否需要下一个。

代码示例：

# 基于官方 BMad Builder 文档（版本 6.2.2）
# 创建一个 DevOps Engineer Agent

# 文件路径: .bmad/agents/devops-engineer.md

agent:
  name: "DevOps Engineer"
  id: "devops-engineer"
  title: "Infrastructure and Deployment Specialist"
  customization_rules:
    expertise: "CI/CD 管道、容器编排（Docker/K8s）、基础设施即代码（Terraform）、监控（Prometheus/Grafana）"
    constraints: "遵循项目的部署策略和云平台约束"
    refuses: "直接修改生产环境配置而不经过审查流程"

persona:
  role: "DevOps 工程师"
  style: "实用、自动化导向、关注可靠性"
  identity: "具有 10 年经验的基础设施和部署专家"
  focus: "部署自动化、基础设施可靠性、监控和告警"

dependencies:
  tasks: ["setup-ci-pipeline", "configure-monitoring", "deploy-infrastructure"]
  templates: ["deployment-plan-tmpl.yaml"]

commands:
  - "*help"              # 显示可用命令
  - "*setup-ci"          # 设置 CI/CD 管道
  - "*deploy"            # 执行部署
  - "*monitor"           # 配置监控
  - "*troubleshoot"      # 排查基础设施问题
  - "*review-infra"      # 审查基础设施配置

执行结果：

# 自定义 Agent 安装后的验证

[BMAD Installer]
Custom agent "DevOps Engineer" installed successfully.

Agent definition: .bmad/agents/devops-engineer.md
Commands registered: *help, *setup-ci, *deploy, *monitor, *troubleshoot, *review-infra
Dependencies: 3 tasks, 1 template

To activate, type: *devops-engineer in your AI IDE.

注：以上输出为模拟结果。基于 BMad Builder 文档结构

注意事项： - 遵循"One-Agent Rule"——先创建一个 Agent，在实际项目中使用一周，根据实际需求再决定是否需要下一个 Agent。 - Agent 的 customization_rules 中的 refuses 字段很重要——它定义了 Agent 不会做的事情，防止 AI 在不合适的领域给出建议。 - 使用 elicit: true 标志让 Agent 在不确定时主动提问，而非自行假设。这能显著提升 Agent 的输出质量。

3.3 Token 优化与最佳实践

概念讲解：

BMAD 的多层提示和上下文加载机制会导致较高的 Token 消耗。社区反馈显示，单个 Story 工作流可能消耗 40-50k Token。以下策略帮助你优化 Token 使用：

优化策略 1：合理选择工作流级别 - 小型任务（Bug 修复、小功能）→ 使用 Quick Flow - 中型任务（单模块开发）→ 使用 Phase 3-4 的精简流程 - 大型任务（全新项目）→ 使用完整的四阶段 Full Flow

优化策略 2：控制上下文加载 - 使用 project-context.md 明确定义技术栈，避免 Agent 在每个 Story 中重复加载技术约束 - 通过 Epic Sharding 确保每个 Story 只加载相关的 Epic 文件，而非全部 PRD

优化策略 3：批量处理相似 Story - 将技术栈相似的 Story 放在同一个 Sprint 中，利用 IDE 的对话历史减少重复的上下文加载

代码示例：

# 优化策略 1：使用 project-context.md 减少重复上下文

# 创建 project-context.md（可手动创建或通过 bmad-generate-project-context 自动生成）
# 用户输入:
# "bmad-generate-project-context"

# project-context.md

## 技术栈
- 前端: React 18 + TypeScript + Tailwind CSS
- 后端: Node.js 20 + Express + TypeScript
- 数据库: PostgreSQL 15
- 运行时: Docker + Node.js 20 Alpine

## 实现规则
- 使用 TypeScript strict 模式
- API 遵循 RESTful 设计规范
- 测试框架: Jest + Supertest
- 代码风格: ESLint + Prettier
- Git 分支策略: GitHub Flow

## 目录结构
- src/routes/ — API 路由
- src/services/ — 业务逻辑
- src/models/ — 数据模型
- src/middleware/ — 中间件
- tests/ — 测试文件

执行结果：

# project-context.md 生成后的效果

[BMAD Context Manager]
Project context file created: docs/project-context.md

This file will be automatically loaded by Developer Agent,
reducing the need to repeat tech stack information in each story.

Estimated token savings per story: ~5,000-8,000 tokens

注：以上输出为模拟结果。基于 BMAD 上下文管理机制

注意事项： - project-context.md 应在 Phase 3（架构设计）完成后创建，因为此时技术栈和实现规则已经确定。 - 定期更新 project-context.md，确保它反映当前的技术栈状态。 - 如果 Token 消耗成为瓶颈，考虑使用 Token 计数工具（如 Claude Code 的 /cost 命令）监控每个工作流的消耗。

第四部分：实战项目

项目需求

构建一个"待办事项 REST API"（Todo API），综合运用以下知识点： 1. Quick Flow（知识点 1.1）：对简单功能使用快捷通道 2. Full Flow Phase 1-2（知识点 2.1）：完成分析和规划阶段 3. Full Flow Phase 3（知识点 2.2）：完成架构设计和 Epic Sharding 4. Agent 人格切换（知识点 1.2）：在不同阶段激活不同的 Agent 5. bmad-help 引导（知识点 1.3）：使用智能帮助系统导航工作流

功能要求： - 用户注册和登录（JWT 认证） - 待办事项的 CRUD 操作 - 按状态（待办/进行中/已完成）筛选 - 基本的统计接口（总数、完成率）

项目设计

todo-api-bmad/
│
├── docs/                          # BMAD 产出物
│   ├── product-brief.md           # Phase 1 产出
│   ├── PRD.md                     # Phase 2 产出
│   ├── architecture.md            # Phase 3 产出
│   ├── epics/                     # Phase 3 Epic 文件
│   │   ├── epic-1-auth.md
│   │   └── epic-2-todo-crud.md
│   └── project-context.md         # 上下文优化
│
├── src/                           # 源码（Phase 4 产出）
│   ├── routes/
│   │   ├── auth.ts
│   │   └── todos.ts
│   ├── services/
│   │   ├── authService.ts
│   │   └── todoService.ts
│   ├── models/
│   │   ├── User.ts
│   │   └── Todo.ts
│   ├── middleware/
│   │   └── auth.ts
│   └── app.ts
│
├── tests/                         # 测试（Phase 4 产出）
│   ├── auth.test.ts
│   └── todos.test.ts
│
├── .bmad/                         # BMAD 配置
└── package.json

完整实施代码

以下是通过 BMAD 工作流引导产出的核心代码文件：

// 基于架构文档中定义的技术栈（Phase 3 产出）
// 文件: src/app.ts

import express from 'express';
import { authRouter } from './routes/auth';
import { todoRouter } from './routes/todos';
import { errorHandler } from './middleware/errorHandler';

const app = express();

// 中间件
app.use(express.json());

// 路由
app.use('/api/auth', authRouter);
app.use('/api/todos', todoRouter);

// 错误处理
app.use(errorHandler);

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`待办事项 API 运行在端口 ${PORT}`);
});

export default app;

// 文件: src/models/Todo.ts
// 基于 Story 2.1 的数据模型设计

export interface Todo {
  id: string;
  userId: string;
  title: string;
  description?: string;
  status: 'pending' | 'in_progress' | 'completed';
  createdAt: Date;
  updatedAt: Date;
}

// 文件: src/services/todoService.ts
// 基于 Story 2.2 的业务逻辑实现

import { Todo } from '../models/Todo';

// 内存存储（生产环境应使用数据库）
const todos: Map<string, Todo> = new Map();

export class TodoService {
  // 创建待办事项
  static create(userId: string, title: string, description?: string): Todo {
    const todo: Todo = {
      id: crypto.randomUUID(),
      userId,
      title,
      description,
      status: 'pending',
      createdAt: new Date(),
      updatedAt: new Date(),
    };
    todos.set(todo.id, todo);
    return todo;
  }

  // 获取用户的所有待办事项（支持按状态筛选）
  static list(userId: string, status?: string): Todo[] {
    const userTodos = Array.from(todos.values())
      .filter(todo => todo.userId === userId);
    if (status) {
      return userTodos.filter(todo => todo.status === status);
    }
    return userTodos;
  }

  // 更新待办事项
  static update(id: string, userId: string, data: Partial<Todo>): Todo | null {
    const todo = todos.get(id);
    if (!todo || todo.userId !== userId) return null;
    const updated = { ...todo, ...data, updatedAt: new Date() };
    todos.set(id, updated);
    return updated;
  }

  // 删除待办事项
  static delete(id: string, userId: string): boolean {
    const todo = todos.get(id);
    if (!todo || todo.userId !== userId) return false;
    return todos.delete(id);
  }

  // 获取统计信息
  static stats(userId: string) {
    const userTodos = this.list(userId);
    const total = userTodos.length;
    const completed = userTodos.filter(t => t.status === 'completed').length;
    return {
      total,
      completed,
      pending: userTodos.filter(t => t.status === 'pending').length,
      inProgress: userTodos.filter(t => t.status === 'in_progress').length,
      completionRate: total > 0 ? (completed / total * 100).toFixed(1) : '0.0',
    };
  }
}

// 文件: src/routes/todos.ts
// 基于 Story 2.3 的 API 路由实现

import { Router, Request, Response } from 'express';
import { TodoService } from '../services/todoService';
import { authenticate } from '../middleware/auth';

export const todoRouter = Router();

// 所有待办事项路由需要认证
todoRouter.use(authenticate);

// 获取待办事项列表（支持状态筛选）
todoRouter.get('/', (req: Request, res: Response) => {
  const userId = req.user!.id;
  const status = req.query.status as string | undefined;
  const todos = TodoService.list(userId, status);
  res.json({ data: todos });
});

// 创建待办事项
todoRouter.post('/', (req: Request, res: Response) => {
  const userId = req.user!.id;
  const { title, description } = req.body;
  if (!title) {
    return res.status(400).json({ error: '标题不能为空' });
  }
  const todo = TodoService.create(userId, title, description);
  res.status(201).json({ data: todo });
});

// 更新待办事项
todoRouter.put('/:id', (req: Request, res: Response) => {
  const userId = req.user!.id;
  const { id } = req.params;
  const todo = TodoService.update(id, userId, req.body);
  if (!todo) {
    return res.status(404).json({ error: '待办事项不存在' });
  }
  res.json({ data: todo });
});

// 删除待办事项
todoRouter.delete('/:id', (req: Request, res: Response) => {
  const userId = req.user!.id;
  const { id } = req.params;
  const deleted = TodoService.delete(id, userId);
  if (!deleted) {
    return res.status(404).json({ error: '待办事项不存在' });
  }
  res.status(204).send();
});

// 获取统计信息
todoRouter.get('/stats', (req: Request, res: Response) => {
  const userId = req.user!.id;
  const stats = TodoService.stats(userId);
  res.json({ data: stats });
});

代码解析

知识点运用说明：

1. Quick Flow（1.1 节）：统计接口（GET /api/todos/stats）可以作为 Quick Flow 的实践——它是一个小型、明确的功能点，可以直接使用 bmad-quick-dev 从规格到代码快速实现。

2. Full Flow Phase 1-2（2.1 节）：product-brief.md 和 PRD.md 通过 Phase 1-2 的 Analyst 和 PM Agent 引导产出。PRD 中定义的 5 个功能需求（CRUD + 统计）直接映射到 API 端点。

3. Full Flow Phase 3（2.2 节）：architecture.md 定义了技术栈（Express + TypeScript）和数据模型。Epic Sharding 将项目拆分为 epic-1-auth（认证）和 epic-2-todo-crud（待办事项 CRUD）两个独立的 Epic 文件。

4. Agent 人格切换（1.2 节）：在不同阶段激活不同 Agent——Phase 1 使用 Analyst Agent，Phase 2 使用 PM Agent，Phase 3 使用 Architect Agent 和 PO Agent，Phase 4 使用 Developer Agent 和 QA Agent。

5. bmad-help 引导（1.3 节）：在整个流程中，随时使用 bmad-help 获取下一步指导——特别是在阶段转换点（如"架构设计完成后该做什么？"）。

扩展挑战

1. 添加 Expansion Pack：使用 BMad Builder（BMB）创建一个"API 文档生成器"Agent，它能自动从代码注释和路由定义生成 OpenAPI/Swagger 文档。遵循"One-Agent Rule"，先用一周验证效果。

2. 集成 Party Mode：在架构评审阶段，引入 Architect Agent、QA Agent 和 DevOps Engineer Agent 同时讨论部署策略（本地开发 vs Docker vs 云部署），记录每个 Agent 的视角和建议。

3. 添加 TEA 模块：安装 Test Architect（TEA）模块，使用基于风险的测试策略为 Todo API 设计测试用例，重点关注认证绕过、未授权访问和数据一致性等风险。

第五部分：常见问题与排查指南

常见错误及解决方案

基于 BMAD 官方文档（版本 6.2.2）和社区常见问题

调试技巧

1. 检查 BMAD 安装完整性：如果 Agent 或工作流行为异常，首先检查 .bmad/ 目录结构是否完整。关键子目录（agents/、workflows/、templates/）应非空。使用 bmad-help check installation 验证安装状态。

2. 利用 Git 追溯上下文问题：如果某个阶段的产出质量不佳，使用 git log 查看前置阶段文档的提交历史。检查 PRD 和架构文档是否在实施阶段开始前已完成并提交。BMAD 的核心原则是"每个阶段基于前一个阶段的产出"，如果前置文档缺失或不完整，后续阶段必然受影响。

3. 分阶段验证 Token 消耗：使用 AI IDE 的 Token 计数功能，分别测量每个工作流的 Token 消耗。如果某个工作流消耗异常高，检查是否加载了不必要的上下文文档。典型参考值：Quick Flow 约 10-20k Token，单 Story 开发约 40-50k Token。

第六部分：学习路线推荐

官方文档推荐阅读顺序

由于 BMAD 的文档站（docs.bmad-method.org）内容丰富，建议按以下顺序阅读：

1. Getting Started 教程 — 重点理解安装流程和核心概念
2. 地址：https://docs.bmad-method.org/

3. 重点：安装步骤、模块选择、IDE 工具配置

4. Workflow Map 参考 — 重点理解四阶段工作流的完整映射

5. 地址：https://docs.bmad-method.org/reference/workflow-map/

6. 重点：Phase 1-4 的工作流列表、产出物类型、Quick Flow 入口

7. Agent 人格文档 — 重点理解每个 Agent 的角色和命令

8. 重点：7 个核心 Agent 的职责边界、命令列表、最佳使用场景

9. Roadmap 路线图 — 了解未来发展方向

10. 地址：https://docs.bmad-method.org/roadmap/
11. 重点：BMad Builder v1、Cross Platform Agent Team、Skills Architecture

推荐进阶资源

• Applied BMAD – Reclaiming Control in AI Development
• https://bennycheung.github.io/bmad-reclaiming-control-in-ai-dev

• 深入探讨 BMAD 的设计哲学、Control Manifest 概念和企业级应用场景

• BMAD Comparisons & Expansion Packs — Abhishek Mittal (Medium)

• https://theonlymittal.medium.com/bmad-comparisons-expansion-packs-7961f6d9ddc0

• BMAD 与 CrewAI、LangGraph、MetaGPT 的详细对比，以及 Expansion Pack 创建指南

• YouTube: BMAD Method V6 PRD, Architecture, Agents

• https://www.youtube.com/watch?v=vWoJuzHAnQ0
• 视频教程演示完整的 V6 工作流，适合视觉学习者

进阶方向建议

完成本教程后，建议按以下方向深入学习：

1. 掌握 BMad Builder (BMB)：学习创建自定义 Agent 和 Expansion Pack，将 BMAD 扩展到你的特定工作领域
2. 集成 TEA 测试模块：学习基于风险的测试策略，提升项目的质量保障水平
3. 参与社区贡献：通过 GitHub Discussions 和 Discord 社区分享你的 Expansion Pack，参与工作流改进讨论

信息来源与版本说明

• 教程基于版本： BMAD-METHOD V6（npm 包版本 6.2.2）
• 信息获取日期： 2026-04-13
• 信息来源列表：
• GitHub 仓库 bmad-code-org/BMAD-METHOD
• 官方文档站 docs.bmad-method.org
• NPM 包 bmad-method
• Workflow Map 参考
• Applied BMAD – Reclaiming Control in AI Development
• A Comparative Analysis of AI Agentic Frameworks
• BMAD Comparisons & Expansion Packs