19 KiB

Raw Blame History

06 - BMAD-METHOD 使用指南

1. 安装和配置

1.1 前置要求

系统要求:

操作系统: Linux, macOS, Windows
Node.js: >= 20.0.0 (推荐 22.x)
npm: 自带于 Node.js
磁盘空间: ~100 MB (包含所有模块)

开发环境:

IDE: 以下任一
├── Claude Code (推荐)
├── Cursor
├── Windsurf
├── VS Code + Copilot
└── 其他 11 个 IDE

LLM 访问:
├── Claude API (推荐 Sonnet 4.5)
├── OpenAI API (GPT-4)
├── 或 IDE 内置的 LLM
└── 推荐 200k+ 上下文窗口

1.2 安装步骤

步骤 1: 安装 Node.js

macOS:

# 使用 Homebrew
brew install node@22

# 或下载安装包
# https://nodejs.org/

Linux (Ubuntu/Debian):

# 使用 nvm (推荐)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

# 或使用包管理器
sudo apt update
sudo apt install nodejs npm

Windows:

下载安装包: https://nodejs.org/
运行安装程序

步骤 2: 创建或进入项目目录

# 新项目
mkdir my-project
cd my-project

# 或现有项目
cd existing-project

步骤 3: 安装 BMAD

# v6 Alpha (推荐)
npx bmad-method@alpha install

# 或 稳定 v4
npx bmad-method install

步骤 4: 交互式配置

模块选择:

? 选择要安装的模块:
  [x] BMad Method (BMM) - AI 驱动敏捷开发
  [x] BMad Builder (BMB) - 创建自定义组件
  [x] Creative Intelligence Suite (CIS) - 创意工作流
  [ ] BMad Game Development (BMGD) - 游戏开发

基本配置 (BMM):

? 你的名字: Alice
? 沟通语言 (communication_language):
  > English
    中文
    Español
    ...

? 文档输出语言 (document_output_language):
  > English
    中文
    ...

? 技能水平:
  > Intermediate
    Beginner
    Advanced

? 项目轨道默认值:
  > bmad-method (推荐)
    quick-flow
    enterprise-method

IDE 选择:

? 选择你的 IDE:
  > Claude Code
    Cursor
    Windsurf
    VS Code + Copilot
    其他...

步骤 5: 验证安装

# 检查安装结果
ls -la bmad/

# 应该看到:
bmad/
├── core/
├── bmm/
├── bmb/      (如果选择)
├── cis/      (如果选择)
└── _cfg/

对于 Claude Code:

ls -la .claude/commands/

# 应该看到大量 .md 文件
bmad-bmm-workflows-prd.md
bmad-bmm-workflows-tech-spec.md
...

2. 快速开始指南

2.1 第一个项目: Bug 修复 (Quick Flow)

目标: 修复一个验证 Bug，体验 BMAD 流程

第 1 步: 初始化工作流

1. 在 IDE 中打开项目

2. 加载 Analyst 代理
   - Claude Code: 打开 bmad/bmm/agents/analyst.md
   - Cursor: @analyst
   - Windsurf: 类似方式

3. 等待代理菜单出现

4. 告诉代理:
   用户: "*workflow-init"

   或自然语言:
   用户: "Run workflow init"

第 2 步: 回答 workflow-init 问题

代理: "描述你的项目或任务"
用户: "修复登录页面的 email 验证 Bug"

代理: "这是新项目还是现有代码库？"
用户: "现有代码库"

代理: "这个任务的复杂度？"
用户: "很简单，只是一个小 Bug"

代理: "推荐使用 Quick Flow Track，是否同意？"
用户: "同意"

输出: docs/bmm-workflow-status.yaml 被创建

第 3 步: 创建 Tech Spec

1. 开启新对话 (Fresh Chat)

2. 加载 PM 代理
   - 打开 bmad/bmm/agents/pm.md

3. 告诉代理:
   用户: "*tech-spec"

4. 回答问题:
   代理: "描述 Bug 的现象"
   用户: "用户可以输入无效的 email 格式（如'test@'），
         但系统没有拒绝"

   代理: "期望的行为是什么？"
   用户: "应该验证 email 格式，显示错误消息"

   代理: "有哪些测试场景？"
   用户: [描述测试场景]

5. 输出: docs/tech-spec.md
   包含:
   - 问题描述
   - 解决方案
   - 3 个 Story

第 4 步: 规划 Sprint

1. 开启新对话

2. 加载 Scrum Master 代理
   - 打开 bmad/bmm/agents/sm.md

3. 告诉代理:
   用户: "*sprint-planning"

4. 代理自动读取 tech-spec.md

5. 选择 Story:
   代理: "以下 Story 要在本 Sprint 完成吗？"
   - Story 1: 添加 email 验证函数
   - Story 2: 更新 UI 错误提示
   - Story 3: 添加测试

   用户: "全部"

6. 输出: docs/sprint-status.yaml

第 5 步: 实现 Story

对于每个 Story (重复 3 次):

1. 开启新对话

2. 加载 Developer 代理
   - 打开 bmad/bmm/agents/dev.md

3. 告诉代理:
   用户: "*dev-story"

4. 代理自动:
   - 读取 sprint-status.yaml
   - 找到下一个 ready 的 Story
   - 读取 Story 详情
   - 开始实现

5. 代理实现代码:
   - 创建/修改文件
   - 编写测试
   - 更新文档
   - 更新 Story 状态为 done

6. 验证:
   - 运行测试
   - 手动测试
   - Code Review (可选: *story-review)

第 6 步: 完成

总时间: 2-4 小时
输出:
├── docs/tech-spec.md
├── docs/sprint-status.yaml
├── docs/Story-001.md
├── docs/Story-002.md
├── docs/Story-003.md
└── 代码修改和测试

2.2 第二个项目: 新功能 (BMad Method)

目标: 添加用户通知系统

简化流程

Phase 1: 分析 (可选)
├── Analyst: *product-brief
└── 输出: product-brief.md (4 小时)

Phase 2: 规划 (必需)
├── PM: *create-prd
├── 输出: PRD.md + Epics.md (12 小时)
└── UX Designer: *create-ux-design (可选, 16 小时)

Phase 3: 方案 (必需)
├── Architect: *create-architecture
├── 输出: architecture.md (20 小时)
└── Architect: *solutioning-gate-check (2 小时)

Phase 4: 实现 (迭代)
├── SM: *sprint-planning
├── 对每个 Epic:
│   ├── SM: *epic-tech-context
│   └── 对每个 Story:
│       ├── SM: *create-story
│       ├── SM: *story-ready
│       ├── Developer: *dev-story
│       └── Developer: *story-review (可选)
└── SM: *sprint-retrospective

总时间: 2-3 周规划 + 8-12 周实现

详细步骤见: 04-工作流程.md 场景 2

3. 常见使用场景

3.1 场景: 现有代码库添加新功能

挑战: 现有代码缺少文档

解决方案:

Phase 0: 文档化现有代码 (Brownfield)

1. 加载 Architect 代理

2. 运行:
   用户: "*brownfield-document"

3. 代理引导:
   - 扫描级别选择 (Quick/Standard/Deep)
   - 关注的代码区域
   - 文档输出格式

4. 输出: docs/ 目录
   ├── system-overview.md
   ├── architecture.md
   ├── api-reference.md
   └── code-patterns.md

然后继续 Phase 1-4 (选择合适的轨道)

3.2 场景: 团队协作开发

设置:

团队: 1 PM, 1 Architect, 3 Developers
项目: 电商平台新支付模块

工作流:

Week 1-2: 规划 (PM + Architect)
├── PM 使用 PM 代理
│   ├── *create-prd
│   └── 输出: PRD.md
│
└── Architect 使用 Architect 代理
    ├── *create-architecture
    └── 输出: architecture.md

Week 3: Sprint 规划 (全体)
├── 使用 Party Mode
├── /bmad:core:workflows:party-mode
├── 讨论架构和实现策略
└── SM 代理 *sprint-planning

Week 4-8: 并行开发 (3 Developers)
├── Developer 1: Epic 1 (支付网关集成)
├── Developer 2: Epic 2 (订单管理)
└── Developer 3: Epic 3 (退款流程)

每个 Developer:
├── 使用 SM 代理创建 Story
├── 使用 Developer 代理实现
└── 每日同步 sprint-status.yaml

Week 9: 集成和测试
├── 使用 TEA 代理
├── *test-design
└── *nfr-assess

协作要点:

📁 共享 docs/ 目录 (Git 管理)
📊 共享 sprint-status.yaml
🔄 每日同步
💬 使用 Party Mode 做重大决策

3.3 场景: 技术债务清理

挑战: 识别和优先级排序技术债务

工作流:

1. 文档化现有系统
   Architect: *brownfield-document (Deep scan)

2. 识别问题
   Architect: *architecture
   └── 创建 "理想架构"

3. Gap 分析
   使用 Party Mode
   ├── 召集 Architect + Developer + TEA
   ├── 对比现状和理想
   └── 列出技术债务清单

4. 优先级排序
   PM: *create-prd
   └── 将技术债务作为 Epic

5. 增量改进
   正常 Sprint 流程
   └── 每个 Sprint 包含 1-2 个技术债务 Story

3.4 场景: 代码审查和质量保证

使用 Story Review 工作流:

Developer 完成实现后:

1. 开启新对话

2. 加载 Developer 代理

3. 运行:
   用户: "*story-review"

4. 代理检查:
   ├── 代码符合 Story 要求
   ├── 测试覆盖率
   ├── 代码质量 (复杂度、可读性)
   ├── 安全问题 (基本)
   └── 文档更新

5. 输出:
   ├── 审查报告
   ├── 改进建议
   └── 批准/需要修改

6. 如需修改:
   ├── Developer 修复
   └── 重新运行 story-review

4. 故障排除

4.1 安装问题

问题: "Node.js 版本不兼容"

# 检查版本
node --version

# 如果 < 20.0.0
# 使用 nvm 升级
nvm install 22
nvm use 22

问题: "找不到 bmad 命令"

# 检查 npm 全局路径
npm config get prefix

# 如果路径不在 PATH 中
export PATH=$PATH:$(npm config get prefix)/bin

# 或使用 npx (推荐)
npx bmad-method@alpha install

问题: "安装卡住不动"

# 清除 npm 缓存
npm cache clean --force

# 重试
npx bmad-method@alpha install

4.2 代理加载问题

问题: "代理菜单不显示"

Claude Code:

1. 确认文件路径正确
   - bmad/bmm/agents/pm.md 存在

2. 重新加载
   - 关闭文件
   - 重新打开

3. 检查 Claude Code 设置
   - 确保启用了 MCP

Cursor:

1. 使用 @ 符号
   @pm

2. 或使用斜杠命令
   /bmad:bmm:agents:pm

问题: "工作流找不到文件"

错误信息:

Error: Cannot find workflow file at:
/path/to/bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml

解决方案:

# 检查文件是否存在
ls bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml

# 如果不存在，重新安装
npx bmad-method@alpha install

4.3 工作流执行问题

问题: "AI Hallucination - 代理生成不准确信息"

症状:

引用不存在的文件
重复之前的对话内容
逻辑混乱

解决方案: ✅ 使用 Fresh Chat 原则

每个工作流使用新对话
❌ 错误: 在同一对话中连续运行多个工作流
✅ 正确: 每个工作流开启新对话

✅ 减少上下文长度

使用 Document Sharding
- 分片大文档
- 只加载相关部分

✅ 验证输出

不要盲目信任 AI
- 检查生成的代码
- 验证文档准确性
- 运行测试

问题: "工作流卡在某个步骤"

症状:

代理不继续执行
等待很长时间无响应

解决方案:

1. 检查 LLM 配额
   - API 限制
   - Token 限制

2. 提供缺失的信息
   - 代理可能在等待回答

3. 重新触发
   - 重新运行工作流
   - 使用新对话

问题: "状态文件不同步"

症状:

sprint-status.yaml 显示错误状态
工作流找不到 Story

解决方案:

# 手动检查和修复
cat docs/sprint-status.yaml

# 如果损坏，备份并重新生成
cp docs/sprint-status.yaml docs/sprint-status.yaml.bak

# 重新运行 sprint-planning
# 使用 SM 代理: *sprint-planning

4.4 性能问题

问题: "工作流执行很慢"

可能原因和解决方案:

原因 1: 文档太大
解决: 使用 Document Sharding
├── 手动分片
└── 或使用 shard-doc 工具

原因 2: 上下文窗口太大
解决: Fresh Chat + 减少输入文档

原因 3: LLM 模型慢
解决:
├── 切换到更快的模型
└── 或使用本地 LLM

5. IDE 集成详解

5.1 Claude Code

安装后结构:

.claude/
└── commands/
    ├── bmad-bmm-workflows-prd.md
    ├── bmad-bmm-workflows-tech-spec.md
    ├── bmad-bmm-workflows-dev-story.md
    └── ... (所有工作流)

使用方式:

方式 1: 加载代理

1. 在 Claude Code 中打开:
   bmad/bmm/agents/pm.md

2. 等待代理激活

3. 使用快捷命令:
   用户: "*create-prd"

方式 2: 直接斜杠命令

用户: /bmad:bmm:workflows:prd

方式 3: Party Mode

用户: /bmad:core:workflows:party-mode

5.2 Cursor

安装后结构:

.cursor/
└── rules/
    ├── bmad-bmm-agents-pm.md
    └── ... (所有代理)

使用方式:

方式 1: @ 符号
用户: @pm

方式 2: 打开代理文件
打开 bmad/bmm/agents/pm.md

方式 3: 使用 Rules
Cursor 自动加载 .cursor/rules/

5.3 Windsurf

安装后结构:

.windsurf/
└── workflows/
    ├── bmad-bmm-workflows-prd.yaml
    └── ... (所有工作流)

使用方式:

类似 Cursor
支持 @ 符号和文件打开

5.4 VS Code + Copilot

安装后结构:

.github/
└── copilot/
    └── bmad/
        ├── agents/
        └── workflows/

使用方式:

1. 打开 Copilot Chat

2. 引用代理文件:
   @workspace bmad/bmm/agents/pm.md

3. 然后使用快捷命令:
   *create-prd

6. 高级技巧

6.1 自定义代理语言和风格

编辑配置:

# bmad/_cfg/agents/pm-customize.yaml
persona:
  name: "张明"  # 覆盖 "John"
  communication_style: "正式专业，使用中文"

  # 或保持英文名但用中文交流
  name: "John"
  communication_style: "Professional, communicates in Chinese"

生效方式:

定制文件在 bmad/_cfg/agents/
更新 BMAD 时保留这些定制

6.2 Document Sharding 使用

何时使用:

PRD > 30KB
Architecture > 20KB
Epic 文档 > 15KB

如何分片:

方式 1: 使用 shard-doc 工具 (BMad 提供)
bmad/core/tools/shard-doc/

方式 2: 手动分片
docs/PRD.md → docs/PRD/
├── index.md (目录)
├── 01-overview.md
├── 02-requirements.md
└── 03-epics.md

方式 3: 在工作流中自动处理
工作流会自动检测和使用分片版本

6.3 创建自定义工作流

使用 BMB:

1. 加载 BMad Builder 代理
   bmad/bmb/agents/bmad-builder.md

2. 运行:
   用户: "*create-workflow"

3. 回答向导问题:
   - 工作流名称: "code-migration"
   - 用途: "迁移代码到新框架"
   - 输入: "旧代码、新框架文档"
   - 输出: "迁移计划、新代码"
   - 步骤: [定义多个步骤]

4. 输出:
   bmad/custom/workflows/code-migration/
   ├── workflow.yaml
   ├── instructions.md
   └── templates/

6.4 多项目管理

场景: 同时管理多个项目

推荐结构:

workspace/
├── project-a/
│   ├── bmad/
│   ├── docs/
│   └── src/
│
├── project-b/
│   ├── bmad/
│   ├── docs/
│   └── src/
│
└── shared-bmad-modules/
    └── custom-modules/
        ├── enterprise-security/
        └── company-standards/

复用自定义模块:

# 在 project-a 中
ln -s ../../shared-bmad-modules/enterprise-security \
      bmad/enterprise-security

# 或复制
cp -r ../shared-bmad-modules/enterprise-security \
      bmad/enterprise-security

7. 最佳实践总结

7.1 工作流执行

✅ DO (推荐做法):

每个工作流使用新对话 (Fresh Chat)
按照 Phase 1→2→3→4 顺序
一次只实现一个 Story
完成后立即更新状态文件
定期运行 workflow-status 检查进度

❌ DON'T (避免做法):

在同一对话中连续运行多个工作流
跳过必需的 Phase
同时开发多个 Story
手动编辑状态文件 (让代理更新)
忽略代理的建议和警告

7.2 文档管理

✅ DO:

将 docs/ 目录纳入版本控制
大文档使用 Sharding
保持文档与代码同步
定期审查和更新文档

❌ DON'T:

将 bmad/ 目录纳入版本控制 (可选 .gitignore)
手动编辑生成的文档 (通过工作流更新)
删除旧版本文档 (可以归档)

7.3 团队协作

✅ DO:

共享配置 (bmad/bmm/config.yaml)
统一使用相同的 BMAD 版本
共享状态文件 (sprint-status.yaml)
使用 Party Mode 做重大决策
定期团队培训和分享

❌ DON'T:

各自使用不同的工作流版本
不同步状态文件
独立决策影响整体架构的更改

7.4 质量保证

✅ DO:

使用 story-review 审查代码
运行自动化测试
使用 solutioning-gate-check 验证一致性
定期 retrospective
验证 AI 输出的准确性

❌ DON'T:

盲目信任 AI 生成的代码
跳过测试步骤
忽略质量门禁
不做 Code Review

8. 学习资源

8.1 官方资源

文档:

视频:

🎥 YouTube Channel
教程即将发布 (v6)

社区:

💬 Discord
- #general-dev - 技术讨论
- #bugs-issues - Bug 报告

8.2 学习路径

初学者 (Week 1):

Day 1: 安装和配置
Day 2: Quick Flow 教程
Day 3-4: 实践 Bug 修复项目
Day 5: BMad Method 概念学习

中级用户 (Week 2-4):

Week 2: 完整 BMad Method 项目
Week 3: 学习所有 12 个代理
Week 4: 尝试自定义工作流

高级用户 (Month 2+):

学习 BMB (创建自定义模块)
Party Mode 高级用法
企业集成和定制
贡献社区

8.3 示例项目

官方示例:

待发布 - 关注 GitHub 仓库

社区示例:

Discord #showcase 频道
分享你的项目！

9. 获取帮助

9.1 遇到问题时

步骤 1: 查看文档

本研究报告
官方文档
FAQ

步骤 2: 搜索已知问题

GitHub Issues
Discord 历史消息

步骤 3: 社区求助

Discord #bugs-issues 频道
描述问题和上下文
附上错误信息和截图

步骤 4: 提交 Issue

GitHub Issues
使用 Bug Report 模板
详细的复现步骤

9.2 联系方式

💬 Discord: https://discord.gg/gk8jAdXWmj
🐛 GitHub: https://github.com/bmad-code-org/BMAD-METHOD/issues
📧 Email: (查看 GitHub 仓库)

10. 小结

关键要点:

✅ 安装简单 - npx 命令即可 ✅ Fresh Chat - 每个工作流新对话 ✅ 按Phase执行 - 1→2→3→4 ✅ 验证输出 - 不盲目信任 AI ✅ 团队协作 - 共享文档和状态 ✅ 持续学习 - 文档、视频、社区

下一步: 阅读 07-总结建议.md 了解整体评估

19 KiB Raw Blame History Unescape Escape

06 - BMAD-METHOD 使用指南

1. 安装和配置

1.1 前置要求

1.2 安装步骤

步骤 1: 安装 Node.js

步骤 2: 创建或进入项目目录

步骤 3: 安装 BMAD

步骤 4: 交互式配置

步骤 5: 验证安装

2. 快速开始指南

2.1 第一个项目: Bug 修复 (Quick Flow)

第 1 步: 初始化工作流

第 2 步: 回答 workflow-init 问题

第 3 步: 创建 Tech Spec

第 4 步: 规划 Sprint

第 5 步: 实现 Story

第 6 步: 完成

2.2 第二个项目: 新功能 (BMad Method)

简化流程

3. 常见使用场景

3.1 场景: 现有代码库添加新功能

3.2 场景: 团队协作开发

3.3 场景: 技术债务清理

3.4 场景: 代码审查和质量保证

4. 故障排除

4.1 安装问题

问题: "Node.js 版本不兼容"

问题: "找不到 bmad 命令"

问题: "安装卡住不动"

4.2 代理加载问题

问题: "代理菜单不显示"

问题: "工作流找不到文件"

4.3 工作流执行问题

问题: "AI Hallucination - 代理生成不准确信息"

问题: "工作流卡在某个步骤"

问题: "状态文件不同步"

4.4 性能问题

问题: "工作流执行很慢"

5. IDE 集成详解

5.1 Claude Code

5.2 Cursor

5.3 Windsurf

5.4 VS Code + Copilot

6. 高级技巧

6.1 自定义代理语言和风格

6.2 Document Sharding 使用

6.3 创建自定义工作流

6.4 多项目管理

7. 最佳实践总结

7.1 工作流执行

7.2 文档管理

7.3 团队协作

7.4 质量保证

8. 学习资源

8.1 官方资源

8.2 学习路径

8.3 示例项目

9. 获取帮助

9.1 遇到问题时

9.2 联系方式

10. 小结

19 KiB

Raw Blame History