19 KiB
19 KiB
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 开发环境要求
{
"Node.js": ">= 20.0.0",
"推荐版本": "22.x (见 .nvmrc)",
"包管理器": "npm",
"操作系统": "跨平台 (Linux, macOS, Windows)"
}
3.2 核心依赖分析
运行时依赖 (15 个)
CLI 框架:
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 艺术字体
数据处理:
js-yaml@4.1.0 // YAML 解析和生成
xml2js@0.6.2 // XML 处理
csv-parse@6.1.0 // CSV 解析
文件系统:
fs-extra@11.3.0 // 增强的文件系统操作
glob@11.0.3 // 文件模式匹配
ignore@7.0.5 // .gitignore 支持
工具库:
semver@7.6.3 // 版本管理
wrap-ansi@7.0.0 // ANSI 文本换行
@kayvan/markdown-tree-parser // Markdown 解析
开发依赖 (13 个)
代码质量:
eslint@9.33.0 // 代码检查
prettier@3.5.3 // 代码格式化
eslint-config-prettier@10.1.8 // ESLint + Prettier 集成
测试工具:
jest@30.0.4 // 测试框架
c8@10.1.3 // 代码覆盖率
Git 工具:
husky@9.1.7 // Git hooks
lint-staged@16.1.1 // 暂存文件 lint
Schema 验证:
zod@4.1.12 // Schema 验证
yaml-eslint-parser@1.2.3 // YAML 解析
3.3 构建和脚本
{
"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
# 自动运行 (通过 husky)
1. lint-staged
├── 自动修复 JS/YAML 文件
├── 格式化所有文件
└── 仅处理 staged 文件
2. npm test
├── Schema 验证
├── 安装测试
├── Bundle 验证
├── Lint 检查
└── 格式检查
CI/CD (GitHub Actions)
# 每个 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 路径占位符系统
工作流和代理使用占位符，运行时解析：
# 编译时解析
{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 智能输入发现
工作流自动查找输入文档：
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"
处理逻辑:
- 尝试匹配
whole模式 - 如果找不到，尝试
sharded模式 - 加载找到的文档
- 如果都没有，提示用户
5. 编译和安装系统
5.1 YAML 到 Markdown 编译
为什么编译？
- IDE 通常直接读取 Markdown 文件
- YAML 便于配置和维护
- 编译时注入激活块和处理器
编译流程:
src/modules/bmm/agents/pm.agent.yaml
↓
[读取 YAML]
↓
[解析元数据、角色、菜单]
↓
[注入激活步骤 XML]
↓
[应用 IDE 特定处理器]
↓
bmad/bmm/agents/pm.md (Markdown)
激活步骤:
<activation-steps>
<!-- 从 utility/models/fragments/ 注入 -->
<step>加载配置文件</step>
<step>设置运行时变量</step>
<step>显示代理菜单</step>
</activation-steps>
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
↓ (所有包装在 <file> 标签)
输出: web-bundles/bmm/agents/pm.xml (自包含)
6.3 Web Bundle 结构
<agent>
<metadata>...</metadata>
<persona>...</persona>
<menu>...</menu>
<embedded-files>
<file path="workflows/prd/workflow.yaml">
<!-- YAML 内容 -->
</file>
<file path="workflows/prd/instructions.md">
<!-- Markdown 内容 -->
</file>
<!-- 更多文件... -->
</embedded-files>
</agent>
7. 小结
BMAD-METHOD 的架构特点：
✅ 模块化设计 - 核心 + 可选模块 ✅ 配置驱动 - YAML 配置，编译时处理 ✅ IDE 无关 - 支持 15 个 IDE ✅ 可扩展 - 使用 BMB 创建新模块 ✅ 更新安全 - 用户配置独立保存 ✅ 质量保证 - 完整的测试和验证流程
下一步: 阅读 03-模块详解.md 了解各模块功能细节