BMAD Method 深度调研报告（源码级分析版）

执行摘要

BMAD Method（全称 Breakthrough Method for Agile AI-Driven Development，口号 Build More Architect Dreams）是由 Brian (BMad) Madison 创建的开源 AI 驱动敏捷开发框架，当前版本 v6.5.0，采用 MIT 协议。本报告基于对其 GitHub 主仓库（bmad-code-org/BMAD-METHOD）源代码的直接分析，纠正了网络二手信息中的多处偏差，从源码层面揭示了其 Agent 系统、Skills 体系、定制化机制的真实实现方式。

核心发现：BMAD 通过模块化的 Skill 目录结构 + 三层 TOML 覆盖配置 + Python 解析器实现了一套高度结构化的 Agent 定制体系。6 个具名 Agent（Mary、John、Winston、Amelia、Sally、Paige）并非简单的提示词模板，而是拥有硬编码身份、可定制人格、标准化 8 步激活流程的"虚拟专家"。Skills 由安装器从 module.yaml 清单动态生成，以 IDE 特定的 SKILL.md 形式落地。整个框架的设计哲学是：用结构化流程替代即兴问答，同时保留充分的可扩展性。

一、项目概况与版本信息

1.1 基础元数据（来自 package.json）

1.2 仓库结构

BMAD-METHOD/├── src/│   ├── core-skills/          # 核心模块技能（11+ 个）│   │   ├── bmad-help/        # 智能引导助手│   │   ├── bmad-brainstorming/│   │   ├── bmad-party-mode/│   │   ├── bmad-customize/   # 定制化引导技能│   │   ├── module.yaml       # 核心模块清单│   │   └── ...│   ├── bmm-skills/           # BMM（敏捷套件）技能│   │   ├── 1-analysis/       # 分析阶段 Agent + Workflows│   │   ├── 2-plan-workflows/ # 规划阶段│   │   ├── 3-solutioning/    # 方案阶段│   │   ├── 4-implementation/ # 实现阶段│   │   └── module.yaml       # BMM 模块清单│   └── scripts/              # 运行时脚本（如 resolve_customization.py）├── tools/│   └── installer/            # 安装器源码│       ├── bmad-cli.js       # 主 CLI│       ├── commands/         # 安装命令│       ├── core/             # 核心安装逻辑│       ├── ide/              # IDE 适配（Claude Code, Cursor 等）│       └── modules/          # 模块处理├── docs/                     # 文档站源码│   ├── how-to/               # 操作指南│   ├── explanation/          # 概念解释│   ├── reference/            # API 参考│   └── tutorials/            # 教程└── test/                     # 测试套件

1.3 核心理念（来自 README.md）

“Traditional AI tools do the thinking for you, producing average results. BMad agents and facilitated workflows act as expert collaborators who guide you through a structured process to bring out your best thinking in partnership with the AI.”

关键特性：

• AI Intelligent Help — bmad-help skill 随时提供下一步指导

• Scale-Domain-Adaptive — 根据项目复杂度自动调整规划深度

• Structured Workflows — 基于敏捷最佳实践的结构化流程

• Specialized Agents — 12+ 领域专家（实际是 6 个具名 Agent，覆盖 12+ 职能）

• Party Mode — 多 Agent 协作会话

• Complete Lifecycle — 从头脑风暴到部署的完整生命周期

100% 免费开源，无付费墙、无封闭内容。

二、模块生态系统

BMAD 采用模块化的扩展架构，核心模块始终安装，其他模块可选：

安装命令：npx bmad-method install，支持 --modules bmm --tools claude-code --yes 等非交互式安装。

三、Agent 系统深度解析

3.1 具名 Agent 的精确列表

BMAD shipped 6 个具名 Agent（Named Agents），而非网络传言的 “21 个”。每个 Agent 都有硬编码的姓名、头衔、图标和描述，这些信息写入 module.yaml 的 agents: 块中：

3.2 Agent 的源码实现结构

每个 Agent 在源码中是一个目录，位于 src/bmm-skills/{phase}/bmad-agent-{role}/，包含：

bmad-agent-pm/├── SKILL.md          # Agent 启动器：定义激活流程和运行时行为└── customize.toml    # 可定制表面：人格、原则、菜单、注入点

SKILL.md 是不可编辑的运行时指令，而 customize.toml 是可覆盖的默认配置。

3.3 8 步激活流程（来自 SKILL.md 源码）

Agent 被调用时，执行严格的 8 步激活流程：

1. Resolve the agent block — 调用 Python 脚本 resolve_customization.py，将 customize.toml 与团队/个人覆盖层按结构规则合并

2. Execute prepend steps — 运行 activation_steps_prepend 中配置的预启动步骤

3. Adopt persona — 加载硬编码身份 + 定制的 role、identity、communication_style、principles

4. Load persistent facts — 加载 persistent_facts，支持 file: 前缀引用项目文件（glob 模式）

5. Load config — 读取 _bmad/bmm/config.yaml，解析 user_name、communication_language、planning_artifacts 等变量

6. Greet — 用配置语言、带 icon 前缀向用户打招呼

7. Execute append steps — 运行 activation_steps_append 中的后启动步骤

8. Dispatch or present menu — 若用户意图明确匹配菜单项，直接调度；否则渲染菜单等待输入

3.4 Agent 的三腿凳设计哲学

BMAD 的文档明确将 Agent 模型描述为"三条腿的凳子"：

抽掉任何一条腿，体验就会崩塌：没有 Agent 的 Skills 只是能力列表；没有 Skills 的 Agent 是无事可做的空壳；没有定制化的框架强迫每个用户接受出厂设置。

四、Skills 系统深度解析

4.1 Skills 的本质与生成机制

Skills 在 BMAD 中不是插件或外部工具，而是预构建的提示词目录，由安装器从模块清单动态生成。

生成时机：运行 npx bmad-method install 时，安装器读取每个选中模块的 module.yaml，然后为每个 Agent、Workflow、Task、Tool 写入一个 skill 目录。

落地位置（IDE 特定）：

生成的 Skill 类型：

4.2 Skills 的调用方式

BMAD 提供两种启动工作的机制：

Agent menu trigger 需要活跃的 Agent 会话，而 Skill 可以直接运行。

4.3 Skills 与 Agent 的关系

Skills 和 Agent 的关系是**“能力包"与"角色宿主”**的关系：

• Agent 的 customize.toml 中定义了 [[agent.menu]]，每个菜单项通过 skill = "..." 引用一个 Workflow Skill

• 例如 John（PM Agent）的菜单包含 CP（Create PRD），其背后调用的 skill 是 bmad-create-prd

• 同一个 Workflow Skill 可以被不同 Agent 引用，也可以直接作为独立 Skill 调用

• Agent 的 persistent_facts 和 principles 会贯穿其调用的所有 Skills，确保行为一致性

4.4 Skill 的命名规范

所有 skill 使用 bmad- 前缀 + 描述性名称：

• bmad-agent-dev（Agent）

• bmad-create-prd（Workflow）

• bmad-help（Task）

• bmad-brainstorming（Workflow）

五、定制化工作原理与元素

5.1 核心设计：稀疏覆盖而非 fork

BMAD 定制化的核心设计原则是**“永远不要修改已安装的文件”。所有定制都通过稀疏覆盖文件（sparse override files）**实现，这样既能保留更新兼容性，又避免了 fork 整个框架的维护负担。

5.2 三层覆盖模型（Per-Skill 定制）

对于每个可定制的 skill，存在三层配置，按优先级从低到高：

Priority 1 (最终生效): _bmad/custom/{skill-name}.user.toml   (个人，gitignored)Priority 2:             _bmad/custom/{skill-name}.toml         (团队，提交到 git)Priority 3 (基础):      {skill-root}/customize.toml            (出厂默认)

解析器：_bmad/scripts/resolve_customization.py，使用 Python 3.11+ 标准库 tomllib，零外部依赖（无 pip、无 uv、无 virtualenv）。

5.3 结构化的合并规则

解析器按值的"形状"而非字段名应用四种规则：

重要限制：覆盖层不能删除基础项。若要抑制默认菜单项，需用相同 code 覆盖为无操作描述。

5.4 可定制化元素清单

基于对 customize.toml 源码的直接分析，每个 Agent 的可定制表面包括：

标量字段（直接覆盖）

• icon — Agent 前缀图标（如 "?"）

• role — 角色职责描述

• identity — 身份认同描述

• communication_style — 沟通风格

数组字段（追加）

• persistent_facts — 会话期间持续记忆的事实。支持两种格式：

• 字面句子："Our org is AWS-only."

• 文件引用："file:{project-root}/docs/standards.md"（支持 glob）

• principles — Agent 的价值观系统

• activation_steps_prepend — 问候前执行的启动步骤（预检、合规检查等）

• activation_steps_append — 问候后执行的启动步骤（重上下文加载）

表数组（按 code 合并）

• [[agent.menu]] — 能力菜单。每个项有：

• code — 短代码（如 CP、DS）

• description — 描述

• skill 或 prompt — 要么调用已注册 skill，要么直接执行提示词文本

只读字段

• agent.name 和 agent.title — 硬编码身份，覆盖无效。若确实需要不同名字的 Agent，需复制 skill 文件夹并作为自定义 skill 分发。

5.5 中央配置（Cross-Cutting）

除 per-skill 定制外，BMAD 还有一套中央配置处理跨切面状态：

_bmad/config.toml               (安装器生成，团队范围)_bmad/config.user.toml          (安装器生成，用户范围)_bmad/custom/config.toml        (人工编写，团队覆盖，提交到 git)_bmad/custom/config.user.toml   (人工编写，个人覆盖，gitignored)

四层合并：个人覆盖 → 团队覆盖 → 安装器用户配置 → 安装器团队配置。

用途：

• [agents.{code}] — Agent 名册（轻量描述符），供 bmad-party-mode、bmad-retrospective 等消费

• [modules.{code}] — 模块安装设置（如 planning_artifacts 路径）

• [core] — 核心安装答案

实际用例：

• 在 _bmad/custom/config.toml 中重定义 PM Agent 的 description 和 icon

• 在 .user.toml 中添加虚构 Agent（如 Kirk、Spock）到名册

• 在 _bmad/custom/config.toml 中固定团队级 planning_artifacts 路径

5.6 Workflow 的定制化

Workflow Skills（如 bmad-product-brief）共享相同的覆盖机制，但定制表面在 [workflow] 下：

• activation_steps_prepend / activation_steps_append

• persistent_facts

• on_complete — 工作流完成后的后续动作（标量，覆盖）

激活顺序固定：解析 [workflow] → prepend → 加载 persistent_facts → 加载 config → 问候 → append → 工作流主体开始。

5.7 bmad-customize Skill

BMAD 提供了一个引导式创作助手 skillbmad-customize，它扫描安装中所有可定制的 skill，帮助用户：

• 选择目标 skill

• 选择 Agent 还是 Workflow 范围

• 编写覆盖文件

• 验证合并结果

这意味着大多数用户无需手写 TOML，通过自然语言交互即可完成定制。

六、工作流程（Workflow）体系

6.1 四阶段生命周期

BMM 模块的工作流遵循严格的四阶段结构：

Phase 1: Analysis（分析，可选）

Phase 2: Planning（规划）

Phase 3: Solutioning（方案）

Phase 4: Implementation（实现）

Quick Flow（并行轨道）

6.2 上下文管理

每个阶段的文档自动成为下一阶段的上下文：

• PRD → Architect 知道约束条件

• Architecture → Dev Agent 知道遵循的模式

• Story 文件 → 提供聚焦的完整实现上下文

这种渐进式上下文构建是 BMAD 区别于自由式 AI 编码的核心机制。

七、BMAD Builder（BMB）元能力

BMB 是 BMAD 的"元模块"，代码为 bmb，npm 包 bmad-builder。它让 BMAD 从"使用框架"升级为"生产框架"。

提供的能力：

• Agent Builder — 创建具有自定义专长和工具访问权限的专业 AI Agent

• Workflow Builder — 设计带步骤和决策点的结构化流程

• Module Builder — 将 Agents 和 Workflows 打包为可分享、可发布的模块

• 交互式设置 — 带 YAML 配置和 npm 发布支持

这意味着组织可以基于 BMAD 构建自己的领域特定方法论，并作为 npm 包分发给团队。

八、Agent 与 Skills 的定位与关联总结

8.1 定位对比

8.2 关联机制

Agent 与 Skills 的关联发生在三个层面：

声明层：Agent 的 customize.toml 通过 [[agent.menu]] 声明它能调度哪些 Workflow Skills（如 skill = "bmad-create-prd"）。

运行时层：Agent 被激活时，其 persistent_facts、principles、communication_style 被注入上下文，随后调度的所有 Skills 都在这个"人格场"中运行。

生成层：安装器读取 module.yaml，为每个 Agent 生成 Agent launcher skill，为每个 Workflow 生成 Workflow skill。Agent launcher 的 SKILL.md 硬编码了 8 步激活流程，而 Workflow skill 的 SKILL.md 硬编码了步骤化的执行逻辑。

8.3 与外部 “Agent + Skills” 框架的对比

BMAD 的 Agent/Skills 设计与通用 AI Agent 框架（如 AutoGPT、LangChain Agent）有显著区别：

• 非通用推理：BMAD 的 Agent 不是"给定目标后自主推理"，而是"在预定义工作流中扮演特定角色"

• 人格优先：Agent 的核心价值是人格连续性和角色边界，而非工具调用能力

• Skill 是提示词：BMAD 的 Skills 本质上是结构化的提示词目录，不是外部 API 或函数调用

• 定制化是一等公民：从设计之初就考虑团队级和个人级的覆盖机制

九、安装与使用实例

9.1 基础安装

# 交互式安装npx bmad-method install# 非交互式安装（CI/CD 场景）npx bmad-method install --directory /path/to/project --modules bmm --tools claude-code --yes# 预发布版本npx bmad-method@next install

安装后生成：

• _bmad/ — agents、workflows、tasks、configuration

• _bmad-output/ — 产物输出目录

9.2 调用 Agent

# 直接调用 Skillbmad-helpbmad-create-prdbmad-agent-dev# 调用 Agent 后使用菜单触发器> bmad-agent-pmJohn: Hey! What would you like to work on?> CP    # 直接创建 PRD

9.3 定制化示例

团队级定制（_bmad/custom/bmad-agent-pm.toml）：

[agent]icon = "?"role = "Drives product discovery for a regulated healthcare domain."communication_style = "Precise, regulatory-aware, asks compliance-shaped questions early."principles = [  "Ship nothing that can't pass an FDA audit.",][[agent.menu]]code = "CE"description = "Create Epics using our delivery framework"skill = "custom-create-epics"

个人级定制（_bmad/custom/bmad-agent-pm.user.toml）：

[agent]persistent_facts = [  "Always include a rough complexity estimate (low/medium/high) when presenting options.",]

十、纠偏：网络二手信息的常见偏差

通过源码分析，发现网络流传信息存在以下偏差：

十一、适用场景与评估

优势

1. 流程严谨：YAML/TOML 定义的结构化流程避免 AI 编码的随意性

2. 角色专业化：具名 Agent 提供人格连续性，降低认知负荷

3. 能力可复用：Skills 按模块复用，同一个 Workflow 可被不同 Agent 调度

4. 定制层级丰富：从标量覆盖到创建全新 Module，五层递进

5. 更新兼容：稀疏覆盖机制确保框架更新不破坏定制

6. 生态集成：原生支持 Claude Code、Cursor、Windsurf

局限

1. 仪式感较重：对于一次性脚本或极小改动，四阶段流程显得冗余（Quick Flow 可部分缓解）

2. Python 3.11+ 依赖：macOS 默认或 Ubuntu 22.04 可能需要单独安装

3. IDE 绑定：Skills 需写入 IDE 特定目录，切换 IDE 需重新安装

4. 学习曲线：理解三层覆盖、结构化合并规则、Agent 激活流程需要投入时间

最佳适用场景

• 中大型软件产品的 AI 辅助开发

• 需要多轮迭代、长期维护的代码库

• 团队协作，需要可复现的开发流程和统一规范

• 对架构设计、文档产出、代码质量有较高要求的项目

• 希望建立组织级 AI 开发方法论并内部分发的团队

十二、总结

BMAD Method 是一套经过深思熟虑的 AI 驱动敏捷开发框架。它不是简单地把 AI 当作"更聪明的自动补全"，而是将 AI 定位为结构化的虚拟协作者。通过 6 个具名 Agent 覆盖软件工程全生命周期、34+ Workflows 强制执行敏捷流程、Skills 系统实现能力的模块化复用、以及基于 TOML 的三层覆盖模型实现深度定制，BMAD 在"结构化"与"灵活性"之间取得了精妙的平衡。

其最核心的设计智慧在于：不试图让 AI 替人思考，而是通过结构化流程和角色分工，把人和 AI 的最佳能力结合起来。Agent 提供人格连续性和专业边界，Skills 提供可复用的执行能力，Customization 让团队能把通用框架改造为组织专属的方法论。这三者的组合，使 BMAD 超越了单纯的提示词工程或工具编排，成为一种真正的AI 原生软件工程方法论。

参考来源

本报告所有技术细节均直接来源于对 bmad-code-org/BMAD-METHOD GitHub 仓库源码的分析，核心引用文件包括：

• package.json — 版本、依赖、脚本

• README.md — 项目概述与理念

• src/core-skills/module.yaml — 核心模块清单

• src/bmm-skills/module.yaml — BMM 模块清单与 Agent 名册

• src/bmm-skills/2-plan-workflows/bmad-agent-pm/SKILL.md — Agent 启动器实现

• src/bmm-skills/2-plan-workflows/bmad-agent-pm/customize.toml — Agent 定制表面

• src/bmm-skills/4-implementation/bmad-agent-dev/customize.toml — Dev Agent 定制表面

• src/core-skills/bmad-help/SKILL.md — Help Skill 实现

• docs/how-to/customize-bmad.md — 定制化完整参考

• docs/explanation/named-agents.md — 具名 Agent 设计哲学

• docs/reference/agents.md — Agent 参考

• docs/reference/commands.md — Skills 系统参考

• docs/reference/modules.md — 模块生态

• docs/reference/workflow-map.md — 工作流地图

• docs/tutorials/getting-started.md — 入门教程