BMAD-METHOD 学习教程
BMAD-METHOD 学习教程
目录
一、快速入门
1.1 环境准备
系统要求： - Node.js 18.0 或更高版本 - npm 9.0 或更高版本 - Git
推荐工具（任选其一）： - Claude Code CLI - Cursor IDE - Windsurf IDE - VS Code + Cline/RooCode 扩展
1.2 安装 BMAD-METHOD
方式一：交互式安装
# 创建项目目录
mkdir my-project
cd my-project
# 运行安装命令
npx bmad-method install
安装过程会询问： 1. 选择安装目录（默认当前目录） 2. 选择模块（推荐新手选 BMM） 3. 选择工具（根据你使用的 IDE 选择）
方式二：命令行安装
# 快速安装（使用默认配置）
npx bmad-method install --directory ./my-project --modules bmm --tools claude-code --yes
1.3 验证安装
# 查看项目结构
ls -la
# 应该看到以下目录
# .bmad-core/ - BMAD 核心文件
# docs/ - 文档目录
# src/ - 源代码目录
1.4 第一个 BMAD 项目
Step 1：启动需求分析
在你的 IDE 或 Claude Code 中输入：
/analyst
然后描述你的项目需求：
我需要开发一个命令行待办事项管理工具，主要功能包括：
1. 添加待办事项
2. 列出所有待办事项
3. 标记完成
4. 删除待办事项
Step 2：生成 PRD
/pm
PM Agent 会基于 Analyst 的输出生成 PRD 文档。
Step 3：设计架构
/architect
Architect Agent 会设计系统架构和技术选型。
Step 4：拆分任务
/sm
Scrum Master Agent 会将功能拆分为可执行的 Story。
Step 5：开始开发
/dev story 1.1
Developer Agent 会开始实现第一个 Story。
二、Agent 命令详解
2.1 Analyst（业务分析师）
命令：/analyst
职责： - 收集和分析业务需求 - 识别用户痛点和机会 - 定义业务目标和成功指标 - 输出需求分析文档
使用示例：
/analyst
我正在开发一个电商网站，目标用户是小型商家。
他们需要一个简单的库存管理系统。
主要痛点是：
1. 手动记录容易出错
2. 库存预警不及时
3. 多渠道销售难以同步
输出：
- 业务需求文档（保存到 docs/requirements.md）
- 用户画像
- 业务流程图
2.2 PM（产品经理）
命令：/pm
职责： - 编写产品需求文档（PRD） - 定义功能规格 - 设定优先级 - 规划发布路线图
使用示例：
/pm
基于之前的分析，请帮我编写 PRD。
MVP 版本只需要核心功能。
输出：
- PRD 文档（保存到 docs/prd.md）
- 功能清单
- 优先级矩阵
2.3 Architect（架构师）
命令：/architect
职责： - 设计系统架构 - 选择技术栈 - 定义数据模型 - 设计 API 接口 - 规划部署架构
使用示例：
/architect
技术要求：
- 后端使用 Python FastAPI
- 数据库使用 PostgreSQL
- 前端使用 React
- 需要支持水平扩展
输出：
- 架构设计文档（保存到 docs/architecture.md）
- 数据模型
- API 设计
- 技术选型说明
2.4 Scrum Master（敏捷教练）
命令：/sm
职责： - 将功能拆分为 Epic 和 Story - 估算工作量 - 安排迭代计划 - 跟踪进度
使用示例：
/sm
请将 PRD 中的功能拆分为 Story。
每个 Story 应该能在 1-2 天内完成。
输出：
- Story 文件（保存到 docs/stories/）
- 迭代计划
- 依赖关系图
2.5 Developer（开发者）
命令：/dev
职责： - 实现 Story 中定义的功能 - 编写代码 - 编写单元测试 - 代码重构
使用示例：
# 开始实现特定 Story
/dev story 1.1
# 或者让 AI 选择下一个待处理的 Story
/dev next
工作流程： 1. 加载 Story 上下文 2. 加载相关架构文档 3. 实现代码 4. 编写测试 5. 更新 Story 状态
2.6 QA（测试工程师）
命令：/qa
职责： - 设计测试用例 - 执行测试 - 报告缺陷 - 验证修复
使用示例：
# 测试特定 Story
/qa story 1.1
# 运行所有测试
/qa all
2.7 其他 Agent
UX Designer：/ux
/ux
请设计用户注册流程的交互。
需要考虑：
- 表单验证反馈
- 错误处理
- 成功状态
Product Owner：/po
/po
验收 Story 1.1 的实现。
检查是否满足验收标准。
三、实战案例：构建 Todo CLI
3.1 项目初始化
# 创建项目
mkdir todo-cli
cd todo-cli
# 初始化 Git
git init
# 安装 BMAD
npx bmad-method install --modules bmm --tools claude-code --yes
3.2 Phase 1: Agentic Planning
Step 1: 需求分析
/analyst
项目名称：Todo CLI
项目描述：命令行待办事项管理工具
目标用户：
- 开发者
- 命令行爱好者
- 需要快速记录任务的用户
核心功能：
1. 添加任务（add）
2. 列出任务（list）
3. 完成任务（done）
4. 删除任务（delete）
5. 清空已完成任务（clear）
非功能需求：
- 响应时间 < 100ms
- 支持离线使用
- 数据本地存储
Step 2: 编写 PRD
/pm
基于需求分析，编写 PRD。
MVP 范围：
- 仅实现核心 CRUD 功能
- 使用 JSON 文件存储
- 单用户模式
暂不包含：
- 多用户支持
- 云同步
- 提醒功能
Step 3: 架构设计
/architect
技术栈：
- 语言：Python 3.10+
- CLI 框架：Click
- 存储：JSON 文件
- 测试：pytest
项目结构：
todo-cli/
├── todo/
│ ├── __init__.py
│ ├── cli.py # CLI 入口
│ ├── models.py # 数据模型
│ ├── storage.py # 存储层
│ └── commands/ # 命令实现
│ ├── add.py
│ ├── list.py
│ ├── done.py
│ └── delete.py
├── tests/
├── pyproject.toml
└── README.md
Step 4: 任务拆分
/sm
请将功能拆分为 Story，每个 Story 应该：
- 独立可测试
- 1-2 小时完成
- 有明确的验收标准
预期的 Story 列表：
| Story | 描述 | 预估 |
|---|---|---|
| 1.1 | 项目初始化和基础结构 | 1h |
| 1.2 | 数据模型和存储层 | 1h |
| 2.1 | 实现 add 命令 | 1h |
| 2.2 | 实现 list 命令 | 0.5h |
| 2.3 | 实现 done 命令 | 0.5h |
| 2.4 | 实现 delete 命令 | 0.5h |
| 3.1 | 单元测试 | 1h |
| 3.2 | 文档和发布 | 0.5h |
3.3 Phase 2: Context-Engineered Development
Story 1.1: 项目初始化
/dev story 1.1
实现项目初始化：
1. 创建 pyproject.toml
2. 设置项目结构
3. 配置 Click 入口
预期输出：
# pyproject.toml
[project]
name = "todo-cli"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["click>=8.0"]
[project.scripts]
todo = "todo.cli:main"
# todo/cli.py
import click
@click.group()
def main():
"""Todo CLI - 命令行待办事项管理"""
pass
if __name__ == "__main__":
main()
Story 1.2: 数据模型和存储层
/dev story 1.2
实现数据模型和存储：
1. Todo 数据类
2. JSON 文件存储
3. CRUD 操作
预期输出：
# todo/models.py
from dataclasses import dataclass, asdict
from datetime import datetime
from typing import Optional
import json
@dataclass
class Todo:
id: int
title: str
completed: bool = False
created_at: str = ""
def __post_init__(self):
if not self.created_at:
self.created_at = datetime.now().isoformat()
def to_dict(self):
return asdict(self)
# todo/storage.py
import json
from pathlib import Path
from typing import List, Optional
from .models import Todo
class TodoStorage:
def __init__(self, file_path: str = "~/.todos.json"):
self.file_path = Path(file_path).expanduser()
def load_all(self) -> List[Todo]:
if not self.file_path.exists():
return []
with open(self.file_path) as f:
data = json.load(f)
return [Todo(**item) for item in data]
def save_all(self, todos: List[Todo]):
with open(self.file_path, 'w') as f:
json.dump([t.to_dict() for t in todos], f, indent=2)
def add(self, title: str) -> Todo:
todos = self.load_all()
new_id = max([t.id for t in todos], default=0) + 1
todo = Todo(id=new_id, title=title)
todos.append(todo)
self.save_all(todos)
return todo
def get(self, todo_id: int) -> Optional[Todo]:
todos = self.load_all()
for todo in todos:
if todo.id == todo_id:
return todo
return None
def update(self, todo_id: int, **kwargs) -> Optional[Todo]:
todos = self.load_all()
for i, todo in enumerate(todos):
if todo.id == todo_id:
for key, value in kwargs.items():
setattr(todo, key, value)
self.save_all(todos)
return todo
return None
def delete(self, todo_id: int) -> bool:
todos = self.load_all()
for i, todo in enumerate(todos):
if todo.id == todo_id:
todos.pop(i)
self.save_all(todos)
return True
return False
Story 2.1-2.4: 实现命令
/dev story 2.1
实现 add 命令
预期输出：
# todo/commands/add.py
import click
from ..storage import TodoStorage
@click.command()
@click.argument('title')
def add(title: str):
"""添加新任务"""
storage = TodoStorage()
todo = storage.add(title)
click.echo(f"✓ 已添加任务 #{todo.id}: {title}")
# 在 cli.py 中注册
from .commands.add import add
main.add_command(add)
/dev story 2.2
实现 list 命令
预期输出：
# todo/commands/list.py
import click
from ..storage import TodoStorage
@click.command()
@click.option('--all', '-a', 'show_all', is_flag=True, help='显示所有任务')
def list_cmd(show_all: bool):
"""列出任务"""
storage = TodoStorage()
todos = storage.load_all()
if not todos:
click.echo("暂无任务")
return
for todo in todos:
status = "✓" if todo.completed else " "
if show_all or not todo.completed:
click.echo(f"[{status}] #{todo.id}: {todo.title}")
测试每个 Story
/qa story 1.1
/qa story 1.2
/qa story 2.1
3.4 完整的项目结构
todo-cli/
├── .bmad-core/
│ └── agents/
├── docs/
│ ├── prd.md
│ ├── architecture.md
│ └── stories/
│ ├── 1.1.project-init.md
│ ├── 1.2.models-storage.md
│ ├── 2.1.cmd-add.md
│ ├── 2.2.cmd-list.md
│ ├── 2.3.cmd-done.md
│ └── 2.4.cmd-delete.md
├── todo/
│ ├── __init__.py
│ ├── cli.py
│ ├── models.py
│ ├── storage.py
│ └── commands/
│ ├── __init__.py
│ ├── add.py
│ ├── list.py
│ ├── done.py
│ └── delete.py
├── tests/
│ ├── __init__.py
│ ├── test_models.py
│ └── test_storage.py
├── pyproject.toml
└── README.md
3.5 使用项目
# 安装
pip install -e .
# 添加任务
todo add "学习 BMAD-METHOD"
todo add "完成项目文档"
# 列出任务
todo list
# 完成任务
todo done 1
# 删除任务
todo delete 2
四、进阶用法
4.1 自定义 Agent
创建自定义 Agent 以适应特定需求：
Step 1: 创建 Agent 文件
# .bmad-core/agents/security-reviewer.md
## Role
Security Reviewer - 安全审查专家
## Responsibilities
- 审查代码安全漏洞
- 检查认证授权实现
- 识别潜在的安全风险
- 提供安全改进建议
## Skills
- OWASP Top 10 知识
- 代码审计经验
- 安全测试方法论
## Interaction
- 在 /dev 完成实现后调用
- 输出到 docs/security-review/
## Commands
/security - 启动安全审查
Step 2: 使用自定义 Agent
/security
请审查 Story 2.1 的实现，关注：
1. 输入验证
2. 注入攻击防护
3. 数据安全
4.2 多模块组合
组合多个模块以适应复杂项目：
# 安装 BMM + TEA
npx bmad-method install --modules bmm,tea --tools claude-code --yes
使用 TEA 模块进行测试驱动开发：
# 先写测试
/tea design auth-feature
# 再实现
/dev story 1.1
# 验证测试
/tea verify auth-feature
4.3 Document Sharding 实践
对于大型项目，拆分文档：
docs/
├── architecture/
│ ├── 00-overview.md
│ ├── 01-frontend.md
│ ├── 02-backend.md
│ ├── 03-database.md
│ └── 04-deployment.md
├── prd/
│ ├── 00-overview.md
│ ├── 01-user-management/
│ │ ├── auth.md
│ │ └── profile.md
│ └── 02-product-catalog/
│ ├── browse.md
│ └── search.md
└── stories/
├── epic-1-user-management/
│ ├── 1.1.user-registration.md
│ ├── 1.2.user-login.md
│ └── 1.3.password-reset.md
└── epic-2-product-catalog/
├── 2.1.product-list.md
└── 2.2.product-search.md
4.4 CI/CD 集成
在 CI/CD 流程中使用 BMAD：
# .github/workflows/bmad-check.yml
name: BMAD Check
on: [pull_request]
jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install BMAD
run: npm install -g bmad-method
- name: Verify Stories
run: |
# 检查所有已完成的 Story 是否有对应的测试
npx bmad-method verify --all-stories
五、最佳实践
5.1 Story 编写规范
好的 Story：
# Story 1.1: User Registration
## Context
- Epic: User Management
- Priority: High
- Dependencies: None
## User Story
As a new user, I want to register with my email,
so that I can access the system.
## Acceptance Criteria
- [ ] User can register with email and password
- [ ] Email must be valid format
- [ ] Password must be at least 8 characters
- [ ] Duplicate emails are rejected with clear message
- [ ] Success registration shows confirmation
## Technical Notes
- Use bcrypt for password hashing
- Validate email with regex
- Store user in users table
## Definition of Done
- [ ] Code implemented
- [ ] Unit tests passing
- [ ] Code reviewed
- [ ] Documentation updated
不好的 Story：
# Story 1.1: User Registration
实现用户注册功能。
5.2 上下文管理
原则： 1. 每次只加载必要的上下文 2. 定期归档已完成的 Story 3. 保持架构文档更新 4. 使用引用而非复制
示例：
# 在 Story 中引用架构
## References
- Architecture: docs/architecture/02-backend.md#authentication
- PRD: docs/prd/01-user-management/auth.md
- Related Story: 1.0 (User Model)
5.3 迭代工作流
┌─────────────────────────────────────────────────────┐
│ 迭代周期 │
│ │
│ Day 1: Planning │
│ ├── /analyst - 收集新需求 │
│ ├── /pm - 更新 PRD │
│ └── /sm - 拆分新 Story │
│ │
│ Day 2-4: Development │
│ ├── /dev story X.X - 实现 │
│ ├── /qa story X.X - 测试 │
│ └── 重复直到完成所有 Story │
│ │
│ Day 5: Review & Deploy │
│ ├── /po - 验收 │
│ ├── 部署到测试环境 │
│ └── 准备下一迭代 │
└─────────────────────────────────────────────────────┘
5.4 常见陷阱
- 过度规划
- 问题：规划阶段花费太多时间
-
解决：MVP 优先，迭代改进
-
上下文膨胀
- 问题：加载太多文档导致效率降低
-
解决：使用 Document Sharding，只加载必要的
-
忽略测试
- 问题：跳过 QA 步骤
-
解决：每个 Story 必须通过测试
-
文档不一致
- 问题：代码更新但文档未更新
- 解决：每次迭代结束时同步更新
六、故障排除
6.1 常见错误
错误：找不到 Agent 命令
Error: Unknown command '/analyst'
解决方案：
1. 确认 BMAD 已正确安装
2. 检查 .bmad-core/agents/ 目录存在
3. 确认使用的工具支持 BMAD
错误：上下文超长
Error: Context length exceeded
解决方案： 1. 使用 Document Sharding 拆分文档 2. 减少加载的文档数量 3. 归档已完成的 Story
错误：Story 依赖冲突
Error: Story 2.1 depends on incomplete Story 1.3
解决方案： 1. 先完成依赖的 Story 2. 或者更新依赖关系
6.2 调试技巧
查看当前状态：
# 查看所有 Story 状态
cat docs/stories/status.json
# 查看项目结构
tree docs/
重置 Story 状态：
# 重置特定 Story
echo '{"status": "pending"}' > docs/stories/1.1.status.json
清理并重新开始：
# 备份当前进度
cp -r docs docs.backup
# 重新初始化
rm -rf docs
npx bmad-method install --modules bmm --tools claude-code --yes
6.3 获取帮助
- GitHub Issues: https://github.com/bmad-code-org/BMAD-METHOD/issues
- GitHub Discussions: https://github.com/bmad-code-org/BMAD-METHOD/discussions
- 官方文档: https://docs.bmad-method.org/
附录：命令速查表
| 命令 | 用途 | 示例 |
|---|---|---|
/analyst |
启动业务分析师 | /analyst |
/pm |
启动产品经理 | /pm |
/architect |
启动架构师 | /architect |
/sm |
启动敏捷教练 | /sm |
/dev |
启动开发者 | /dev story 1.1 |
/qa |
启动测试工程师 | /qa story 1.1 |
/ux |
启动 UX 设计师 | /ux |
/po |
启动产品负责人 | /po |
教程生成时间：2026-03-21