# 02 - BMAD-METHOD 核心架构
## 1. 整体架构设计
### 1.1 三层架构模型
```
┌─────────────────────────────────────────┐
│ 应用层 (Application Layer) │
│ │
│ 用户 ←→ IDE ←→ 代理菜单 ←→ 工作流触发 │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 代理层 (Agent Layer) │
│ │
│ 19+ 专业代理 (PM, Architect, Dev...) │
│ - 角色定义 (Persona) │
│ - 专业知识 (Domain Knowledge) │
│ - 工作流菜单 (Menu) │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 工作流层 (Workflow Layer) │
│ │
│ 63+ 结构化工作流程 │
│ - 指令文档 (Instructions) │
│ - 模板文件 (Templates) │
│ - 任务调用 (Task Invocations) │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 框架层 (Core Layer) │
│ │
│ BMad-CORE 基础能力 │
│ - 配置管理 │
│ - 路径解析 │
│ - 依赖解析 │
│ - Party Mode 协调 │
└─────────────────────────────────────────┘
```
### 1.2 模块依赖关系
```
BMad-CORE (基础框架)
├── 必需：所有模块都依赖
│
├── BMad Method (BMM - 主模块)
│ ├── 依赖 CIS (用于头脑风暴)
│ └── 集成 BMGD (游戏开发扩展)
│
├── BMad Builder (BMB - 扩展工具)
│ └── 独立运行，创建新模块
│
├── Creative Intelligence Suite (CIS)
│ └── 独立或与其他模块集成
│
└── BMad Game Development (BMGD)
└── 使用 BMM 的 Sprint 工作流
```
---
## 2. 目录结构详解
### 2.1 顶级目录结构
```
/home/user/BMAD-METHOD/
│
├── README.md # 项目主文档
├── CONTRIBUTING.md # 贡献指南
├── CHANGELOG.md # 版本更新日志
├── LICENSE # MIT 许可证
├── package.json # Node.js 项目配置
├── .nvmrc # Node 版本：22
│
├── src/ # 📦 源代码目录
│ ├── core/ # BMad-CORE 基础框架
│ ├── modules/ # 功能模块
│ │ ├── bmm/ # BMad Method (2.3 MB)
│ │ ├── bmb/ # BMad Builder (463 KB)
│ │ ├── cis/ # Creative Intelligence (154 KB)
│ │ └── bmgd/ # Game Development (556 KB)
│ └── utility/ # 共享资源
│
├── tools/ # 🛠️ 工具集
│ ├── cli/ # 安装和构建工具
│ │ ├── bmad-cli.js # CLI 入口
│ │ ├── commands/ # 命令实现
│ │ └── bundlers/ # Web 打包器
│ ├── flattener/ # 文档展平工具
│ └── validate-*.js # 验证工具
│
├── docs/ # 📚 项目级文档
│ ├── ide-info/ # 15 个 IDE 集成指南
│ ├── installers-bundlers/ # 安装系统文档
│ └── *.md # 各种指南
│
├── web-bundles/ # 🌐 Web 部署包
│ ├── bmm/ # BMM Web 版本
│ ├── bmb/ # BMB Web 版本
│ └── cis/ # CIS Web 版本
│
├── test/ # ✅ 测试套件
│ ├── test-agent-schema.js
│ └── test-installation-components.js
│
├── bmad/ # 💾 已安装实例（示例）
│ ├── core/
│ ├── bmm/
│ ├── _cfg/ # 用户配置
│ └── agents/ # 编译后的代理
│
└── .claude/ # 🤖 IDE 配置（示例）
└── commands/ # Claude Code 斜杠命令
```
### 2.2 源代码目录详解
#### src/core/ - 核心框架
```
src/core/
├── agents/
│ └── bmad-master.agent.yaml # 主协调代理
│
├── workflows/
│ ├── brainstorming/ # 头脑风暴工作流
│ │ ├── workflow.yaml
│ │ ├── instructions.md
│ │ └── brainstorming-techniques.csv
│ └── party-mode/ # 多代理协作
│ ├── workflow.yaml
│ └── instructions.md
│
├── tasks/ # 原子级任务
│ ├── workflow.xml # 工作流任务
│ ├── adv-elicit.xml # 高级引导任务
│ └── adv-elicit-methods.csv # 引导方法库
│
├── tools/ # 核心工具
│ └── shard-doc/ # 文档分片工具
│
├── config.yaml # 核心配置
└── _module-installer/ # 安装配置
└── install-config.yaml
```
#### src/modules/bmm/ - BMad Method 模块
```
src/modules/bmm/
├── README.md # 模块概述
├── config.yaml # 模块配置
│
├── agents/ # 12 个专业代理
│ ├── pm.agent.yaml # 产品经理 (John)
│ ├── analyst.agent.yaml # 分析师 (Mary)
│ ├── architect.agent.yaml # 架构师 (Winston)
│ ├── sm.agent.yaml # Scrum Master (Bob)
│ ├── dev.agent.yaml # 开发者 (Amelia)
│ ├── tea.agent.yaml # 测试架构师 (Murat)
│ ├── ux-designer.agent.yaml # UX 设计师 (Sally)
│ ├── tech-writer.agent.yaml # 技术文档师 (paige)
│ ├── game-designer.agent.yaml # 游戏设计师
│ ├── game-dev.agent.yaml # 游戏开发者
│ ├── game-architect.agent.yaml # 游戏架构师
│ └── game-sm.agent.yaml # 游戏 Scrum Master
│
├── workflows/ # 34 个工作流
│ ├── workflow-status/ # 工作流状态管理
│ ├── 1-analysis/ # Phase 1: 分析 (5个)
│ │ ├── brainstorm-project/
│ │ ├── market-research/
│ │ ├── competitive-analysis/
│ │ ├── user-research/
│ │ └── product-brief/
│ │
│ ├── 2-plan-workflows/ # Phase 2: 规划 (6个)
│ │ ├── prd/ # PRD 工作流
│ │ │ ├── workflow.yaml
│ │ │ ├── instructions.md
│ │ │ ├── prd-template.md
│ │ │ └── create-epics-and-stories/
│ │ ├── tech-spec/ # 技术规格
│ │ ├── create-ux-design/ # UX 设计
│ │ └── brownfield-document/ # 现有代码文档化
│ │
│ ├── 3-solutioning/ # Phase 3: 方案 (2个)
│ │ ├── architecture/
│ │ └── solutioning-gate-check/
│ │
│ └── 4-implementation/ # Phase 4: 实现 (10个)
│ ├── sprint-planning/
│ ├── epic-tech-context/
│ ├── create-story/
│ ├── story-context/
│ ├── dev-story/
│ ├── story-review/
│ ├── story-ready/
│ ├── correct-course/
│ └── sprint-retrospective/
│
├── docs/ # 18 个指南文档
│ ├── README.md # 文档中心
│ ├── quick-start.md # 快速开始
│ ├── agents-guide.md # 代理指南
│ ├── scale-adaptive-system.md # 3轨系统
│ ├── workflows-*.md # 工作流指南
│ ├── faq.md # 常见问题
│ └── glossary.md # 术语表
│
├── teams/ # 预配置团队
│ ├── quick-flow-team.yaml
│ ├── bmad-method-team.yaml
│ └── enterprise-team.yaml
│
└── _module-installer/
└── install-config.yaml
```
### 2.3 安装后的目录结构
用户安装后在项目中创建：
```
your-project/
├── bmad/ # BMAD 安装目录
│ ├── core/ # 核心框架
│ │ ├── agents/
│ │ ├── workflows/
│ │ ├── tasks/
│ │ └── config.yaml
│ │
│ ├── bmm/ # BMad Method
│ │ ├── agents/ # 编译后的 .md 文件
│ │ ├── workflows/
│ │ └── config.yaml
│ │
│ ├── bmb/ # BMad Builder (可选)
│ ├── cis/ # Creative Intelligence (可选)
│ ├── bmgd/ # Game Development (可选)
│ │
│ └── _cfg/ # 用户配置和清单
│ ├── agents/ # 代理定制文件
│ ├── manifest.yaml # 安装清单
│ ├── workflow-manifest.csv # 工作流目录
│ ├── agent-manifest.csv # 代理元数据
│ └── files-manifest.csv # 文件完整性
│
├── .claude/ # Claude Code 工件
│ └── commands/
│ ├── bmad-bmm-workflows-prd.md
│ └── ... (所有工作流命令)
│
├── .cursor/ # Cursor 工件
│ └── rules/
│
├── .windsurf/ # Windsurf 工件
│ └── workflows/
│
└── docs/ # 项目输出文档
├── bmm-workflow-status.yaml # 工作流状态
├── sprint-status.yaml # Sprint 状态
├── PRD.md # 产品需求文档
├── architecture.md # 架构文档
└── ... (其他输出文档)
```
---
## 3. 技术栈和依赖
### 3.1 开发环境要求
```json
{
"Node.js": ">= 20.0.0",
"推荐版本": "22.x (见 .nvmrc)",
"包管理器": "npm",
"操作系统": "跨平台 (Linux, macOS, Windows)"
}
```
### 3.2 核心依赖分析
#### 运行时依赖 (15 个)
**CLI 框架**:
```javascript
commander@14.0.0 // CLI 命令框架
inquirer@8.2.6 // 交互式问答
ora@5.4.1 // 终端加载指示器
chalk@4.1.2 // 终端着色
boxen@5.1.2 // 盒式输出
figlet@1.8.0 // ASCII 艺术字体
```
**数据处理**:
```javascript
js-yaml@4.1.0 // YAML 解析和生成
xml2js@0.6.2 // XML 处理
csv-parse@6.1.0 // CSV 解析
```
**文件系统**:
```javascript
fs-extra@11.3.0 // 增强的文件系统操作
glob@11.0.3 // 文件模式匹配
ignore@7.0.5 // .gitignore 支持
```
**工具库**:
```javascript
semver@7.6.3 // 版本管理
wrap-ansi@7.0.0 // ANSI 文本换行
@kayvan/markdown-tree-parser // Markdown 解析
```
#### 开发依赖 (13 个)
**代码质量**:
```javascript
eslint@9.33.0 // 代码检查
prettier@3.5.3 // 代码格式化
eslint-config-prettier@10.1.8 // ESLint + Prettier 集成
```
**测试工具**:
```javascript
jest@30.0.4 // 测试框架
c8@10.1.3 // 代码覆盖率
```
**Git 工具**:
```javascript
husky@9.1.7 // Git hooks
lint-staged@16.1.1 // 暂存文件 lint
```
**Schema 验证**:
```javascript
zod@4.1.12 // Schema 验证
yaml-eslint-parser@1.2.3 // YAML 解析
```
### 3.3 构建和脚本
```json
{
"scripts": {
"install:bmad": "安装 BMAD 到项目",
"bundle": "生成 Web 部署包",
"test": "完整测试套件",
"test:schemas": "代理 Schema 验证",
"test:install": "安装组件测试",
"validate:schemas": "YAML Schema 验证",
"validate:bundles": "Web Bundle 完整性",
"lint": "ESLint 检查 (max 0 warnings)",
"format:check": "Prettier 格式检查",
"format:fix": "自动格式化"
}
}
```
### 3.4 质量保证流程
#### Pre-commit Hook
```bash
# 自动运行 (通过 husky)
1. lint-staged
├── 自动修复 JS/YAML 文件
├── 格式化所有文件
└── 仅处理 staged 文件
2. npm test
├── Schema 验证
├── 安装测试
├── Bundle 验证
├── Lint 检查
└── 格式检查
```
#### CI/CD (GitHub Actions)
```bash
# 每个 PR 自动运行
1. 并行执行
├── npm run test:schemas
├── npm run test:install
├── npm run validate:bundles
├── npm run lint
└── npm run format:check
2. 全部通过才能合并
```
---
## 4. 配置系统
### 4.1 配置层级
```
1. 核心配置 (bmad/core/config.yaml)
├── project_name
├── output_folder
├── user_name
└── communication_language
2. 模块配置 (bmad/bmm/config.yaml)
├── 继承核心配置
├── document_output_language
├── user_skill_level
└── project_track (quick-flow/bmad-method/enterprise)
3. 代理定制 (bmad/_cfg/agents/*.yaml)
├── 覆盖代理属性
├── 多语言支持
└── 更新时保留
```
### 4.2 路径占位符系统
工作流和代理使用占位符，运行时解析：
```yaml
# 编译时解析
{project-root} → /home/user/my-project
{output_folder} → /home/user/my-project/docs
{installed_path} → /home/user/my-project/bmad/bmm/workflows/prd
# 配置值解析
{user_name} → 从 config.yaml 读取
{communication_language} → 从 config.yaml 读取
{config_source}:key → 从指定配置读取键值
# 系统生成
{date} → 当前日期
{timestamp} → 当前时间戳
```
### 4.3 智能输入发现
工作流自动查找输入文档：
```yaml
input_file_patterns:
product_brief:
whole: "{output_folder}/*brief*.md" # 优先整体文档
sharded: "{output_folder}/*brief*/index.md" # 降级到分片
research:
whole: "{output_folder}/*research*.md"
sharded: "{output_folder}/*research*/index.md"
```
**处理逻辑**:
1. 尝试匹配 `whole` 模式
2. 如果找不到，尝试 `sharded` 模式
3. 加载找到的文档
4. 如果都没有，提示用户
---
## 5. 编译和安装系统
### 5.1 YAML 到 Markdown 编译
**为什么编译？**
- IDE 通常直接读取 Markdown 文件
- YAML 便于配置和维护
- 编译时注入激活块和处理器
**编译流程**:
```
src/modules/bmm/agents/pm.agent.yaml
↓
[读取 YAML]
↓
[解析元数据、角色、菜单]
↓
[注入激活步骤 XML]
↓
[应用 IDE 特定处理器]
↓
bmad/bmm/agents/pm.md (Markdown)
```
**激活步骤**:
```xml
加载配置文件
设置运行时变量
显示代理菜单
```
### 5.2 安装阶段
**6 阶段安装**:
```
阶段 1: 收集用户输入
├── 目标目录
├── 选择模块 (BMM, BMB, CIS, BMGD)
├── 选择 IDE
└── 自定义配置
阶段 2: 预安装检查
├── 验证目标目录
├── 检测 v4 安装（升级路径）
├── 备份现有安装
└── 4 阶段依赖解析
阶段 3: 安装核心和模块
├── 复制文件到 {target}/bmad/
├── 编译 YAML → Markdown
├── 合并 customize.yaml
└── 注入激活块
阶段 4: IDE 集成
├── 初始化 IDE 处理器
├── 生成 IDE 工件
│ ├── Claude Code: .claude/commands/
│ ├── Cursor: .cursor/rules/
│ └── 其他 13 个 IDE
└── 执行平台钩子
阶段 5: 生成清单
├── manifest.yaml (安装元数据)
├── workflow-manifest.csv
├── agent-manifest.csv
├── task-manifest.csv
└── files-manifest.csv
阶段 6: 验证和完成
├── 文件完整性检查
├── 代理编译验证
├── IDE 工件确认
└── 显示摘要和后续步骤
```
### 5.3 依赖解析
**4 阶段依赖解析系统**:
```
阶段 1: 直接依赖
└── 模块直接声明的依赖
阶段 2: 传递依赖
└── 依赖的依赖
阶段 3: 可选依赖
└── 建议但非必需
阶段 4: 冲突解决
└── 版本冲突和循环依赖检测
```
---
## 6. Web 打包系统
### 6.1 用途和目标
**目标**: 为 Web 部署创建自包含的代理和工作流包
**特点**:
- 单个 XML 文件包含所有依赖
- 无需文件系统访问
- 适用于 Web IDE 和浏览器环境
### 6.2 打包流程
```
输入: src/modules/bmm/agents/pm.agent.yaml
↓
编译（forWebBundle: true）
├── YAML → XML
├── 使用 web-bundle-activation-steps.xml
└── 递归解析所有依赖
↓
嵌入依赖
├── 工作流 YAML
├── 指令 Markdown
├── 模板文件
├── 数据 CSV
└── 任务 XML
↓ (所有包装在 标签)
输出: web-bundles/bmm/agents/pm.xml (自包含)
```
### 6.3 Web Bundle 结构
```xml
...
...
```
---
## 7. 小结
BMAD-METHOD 的架构特点：
✅ **模块化设计** - 核心 + 可选模块
✅ **配置驱动** - YAML 配置，编译时处理
✅ **IDE 无关** - 支持 15 个 IDE
✅ **可扩展** - 使用 BMB 创建新模块
✅ **更新安全** - 用户配置独立保存
✅ **质量保证** - 完整的测试和验证流程
**下一步**: 阅读 [03-模块详解.md](./03-模块详解.md) 了解各模块功能细节