BMAD-METHOD/icsc/report/06-使用指南.md

# 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**:
```bash
# 使用 Homebrew
brew install node@22

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

**Linux (Ubuntu/Debian)**:
```bash
# 使用 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: 创建或进入项目目录

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

# 或现有项目
cd existing-project
```

#### 步骤 3: 安装 BMAD

```bash
# 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: 验证安装

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

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

**对于 Claude Code**:
```bash
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](./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 版本不兼容"

```bash
# 检查版本
node --version

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

#### 问题: "找不到 bmad 命令"

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

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

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

#### 问题: "安装卡住不动"

```bash
# 清除 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
```

**解决方案**:
```bash
# 检查文件是否存在
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

**解决方案**:
```bash
# 手动检查和修复
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 自定义代理语言和风格

**编辑配置**:
```yaml
# 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/
```

**复用自定义模块**:
```bash
# 在 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 官方资源

**文档**:
- 📚 [BMM 完整文档](../src/modules/bmm/docs/README.md)
- 🚀 [Quick Start Guide](../src/modules/bmm/docs/quick-start.md)
- 🤖 [Agents Guide](../src/modules/bmm/docs/agents-guide.md)
- 📖 [FAQ](../src/modules/bmm/docs/faq.md)

**视频**:
- 🎥 [YouTube Channel](https://www.youtube.com/@BMadCode)
- 教程即将发布 (v6)

**社区**:
- 💬 [Discord](https://discord.gg/gk8jAdXWmj)
  - #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](./07-总结建议.md) 了解整体评估