规范驱动的 Vibe Coding：BMad 实践指南

用 AI Agent 团队和结构化工件，把 Vibe Coding 从"氛围抽卡"变成可控的工程流程。

为什么 Vibe Coding 需要结构？

Vibe Coding 的核心问题是需求在聊天记录里飘着：AI 输出质量看 prompt，开发过程缺乏版本控制，团队协作几乎不可能。

解决方案不是"更好地写 prompt"，而是规范先行（spec-first）——先让人和 AI 就"做什么"达成书面共识，再动手写代码。

BMad 是什么？

BMad（Build More Architect Dreams）是一个 AI 原生的敏捷开发框架，通过专用 AI Agent 团队和结构化工件，覆盖从构思到实现的完整流程。

核心特性

  • AI Agent 团队：内置 12+ 专用 Agent（PM、架构师、开发者、UX、QA 等）
  • 规模自适应：自动根据项目复杂度调整规划深度，小项目走 Quick Flow，大项目走 Enterprise
  • 结构化工件：PRD、架构文档、Epic、Story——每个文档都成为下一阶段的上下文
  • 工具无关：支持 Claude Code、Cursor、Windsurf 等主流 AI 编码工具
  • 可扩展：通过 BMad Builder 可以创建自定义 Agent 和 Workflow

BMad vs OpenSpec

维度 BMad OpenSpec
哲学 AI Agent 团队协作 人类 + AI 协作
工作流 Phase 1-4 完整流程 轻量级 propose → apply
Agent 角色 多角色分工（PM/架构师/开发者） 无 Agent 分工
复杂度适配 自动调整（小功能→企业系统） 手动选择 schema
学习曲线 较陡 较平缓
适用场景 复杂产品、平台、企业系统 中小型功能、Brownfield 项目

两者可以结合使用：BMad 管整体规划和多角色协作，OpenSpec 管单个变更的规范驱动。

核心概念

四阶段开发流程

Phase 1: Analysis    → 头脑风暴、研究、问题定义（可选）
Phase 2: Planning    → 创建 PRD、需求规范
Phase 3: Solutioning → 设计系统架构（BMM/Enterprise 才有）
Phase 4: Implementation → 一个 Epic 接一个 Epic，一个 Story 接一个 Story

三种规划轨道

轨道 适用场景 复杂度 产出文档
Quick Flow Bug 修复、简单功能 1-15 个 Story Tech-spec
BMad Method (BMM) 产品、平台、复杂功能 10-50+ 个 Story PRD + 架构 + UX
Enterprise 合规系统、多租户 30+ 个 Story PRD + 架构 + 安全 + DevOps

工件体系

BMad 的核心是每个文档成为下一阶段的上下文：

PRD → 架构文档 → Epic → Story → 代码
文档 作者 作用
PRD PM Agent 做什么、给谁做、成功标准、非目标
架构文档 架构师 Agent 技术选型、数据结构、边缘情况
Epic PM Agent 一组相关的 Story
Story Scrum Master Agent 可执行的实现单元 + 验收标准
Tech-spec 开发者 Agent 实施计划 + 任务拆解

内置 Agent

BMad 提供 12+ 专用 Agent：

Agent 职责
PM 创建 PRD、Epic、Story
架构师 设计系统架构
开发者 实现代码、代码审查
UX 用户体验设计
QA 质量保证、测试策略
分析师 生成项目背景
Scrum Master Sprint 规划和跟踪

目录结构

BMad 推荐的标准项目结构：

/project-root
  /00_docs              ← 事实来源
    /features           ← 按功能组织的规范
    /architecture       ← 系统文档
  /01_plans             ← 执行计划
    /active             ← 当前进行中
    /completed          ← 已完成
  /02_archive           ← 归档的规范
  /src                  ← 实现代码

工作流命令

Quick Flow（简单项目）

命令 Agent 用途
/quick-spec 开发者 分析代码库，产出技术规范
/dev-story 开发者 实现单个 Story
/code-review 开发者 验证实现质量

BMM 完整流程（复杂项目）

命令 Agent 用途
/product-brief 分析师 定义问题、用户、MVP 范围
/create-prd PM 创建完整需求文档
/create-architecture 架构师 技术决策和系统设计
/create-epics-and-stories PM 拆分为 Epic 和 Story
/sprint-planning Scrum Master 初始化 Sprint 跟踪
/create-story Scrum Master 准备下一个 Story
/dev-story 开发者 实现 Story
/code-review QA 验证实现质量

核心辅助命令

命令 用途
bmad-help 智能向导——任何时候都可以问"下一步做什么"
bmad-quick-dev 统一快速流程：意图澄清 → 规划 → 实现 → 审查 → 交付
bmad-investigate 取证式调查，产出分级证据

完整示例：构建一个笔记应用

Step 1: 启动 Quick Flow

# 告诉 BMad 你的想法
npx bmad-method

# 选择 Quick Flow 开始

Step 2: 创建 Tech-spec

/quick-spec 构建一个笔记应用，支持创建、编辑、删除笔记

BMad 会：

  1. 理解意图——通过对话澄清模糊需求
  2. 调查代码——检查现有代码库（如有）
  3. 生成 Tech-spec——包含完整实现计划

Step 3: Tech-spec 示例

# 笔记应用 Tech-spec

## 概述
用户需要一个本地笔记应用，支持创建、编辑、删除笔记。

## 用户故事

### Story: 创建笔记
- **作为** 笔记应用用户
- **我想要** 创建新笔记
- **以便于** 记录我的想法

#### 验收标准
- **GIVEN** 用户在笔记列表页面
- **WHEN** 用户点击"新建笔记"按钮
- **THEN** 创建空白笔记并打开编辑界面
- **AND** 笔记标题默认为"新笔记"
- **AND** 自动保存已启用

### Story: 编辑笔记
- **作为** 笔记应用用户
- **我想要** 编辑已有笔记
- **以便于** 更新我的想法

#### 验收标准
- **GIVEN** 用户已有一篇笔记
- **WHEN** 用户点击笔记进入编辑页面
- **THEN** 显示笔记当前内容
- **AND** 编辑后自动保存（防抖 1 秒）

### Story: 删除笔记
- **作为** 笔记应用用户
- **我想要** 删除不需要的笔记
- **以便于** 保持笔记列表整洁

#### 验收标准
- **GIVEN** 用户在笔记列表页面
- **WHEN** 用户点击删除按钮并确认
- **THEN** 笔记从列表中移除
- **AND** 本地存储同步更新

## 技术方案

### 技术栈
- **前端**：React + TypeScript
- **存储**：localStorage（IndexedDB 扩展）
- **样式**：Tailwind CSS

### 目录结构
```
src/
├── components/
│   ├── NoteList.tsx      # 笔记列表组件
│   ├── NoteEditor.tsx    # 编辑器组件
│   └── DeleteConfirm.tsx # 删除确认弹窗
├── hooks/
│   ├── useNotes.ts       # 笔记 CRUD 操作
│   └── useAutoSave.ts    # 自动保存逻辑
├── types/
│   └── note.ts           # 类型定义
└── App.tsx               # 入口
```

## 实施任务

### 任务 1: 项目初始化
- [ ] 创建 React + TypeScript 项目
- [ ] 安装 Tailwind CSS
- [ ] 配置 ESLint + Prettier

### 任务 2: 类型定义
- [ ] 创建 `src/types/note.ts`
- [ ] 定义 Note 接口（id, title, content, createdAt, updatedAt）

### 任务 3: 存储层
- [ ] 实现 `useNotes` Hook
- [ ] CRUD 操作挂接 localStorage
- [ ] 实现 useAutoSave 防抖

### 任务 4: 组件
- [ ] 实现 NoteList 组件
- [ ] 实现 NoteEditor 组件
- [ ] 实现 DeleteConfirm 弹窗

### 任务 5: 集成
- [ ] App.tsx 组装所有组件
- [ ] 路由：列表页 / 编辑页

Step 4: 实现与审查

/dev-story story-1  # 实现第一个 Story
/code-review        # 审查代码质量
# 重复直到所有 Story 完成

关键原则

1. 文档是资产，代码是负债

BMad 有一个核心理念：代码是负债，规范是资产。改动代码成本高，改动规范成本低。

层次 Bug 修复成本 时间
Prompt $0.01 1 分钟
规范 $0.10 5-10 分钟
代码 $1.00 30-60 分钟

2. 每个文档驱动下一个

PRD → 架构文档 → Epic → Story → 代码

PRD 告诉架构师什么约束重要。架构文档告诉开发者遵循什么模式。Story 提供完整的上下文。

3. 规模自适应

BMad 会根据项目规模自动调整流程：

  • 小功能：走 Quick Flow，2-3 个文档就够了
  • 复杂产品：走 BMM，PRD + 架构 + Epic + Story
  • 企业系统：走 Enterprise，加上安全和 DevOps

4. 人类只在高价值时刻介入

Quick Flow 的设计哲学：把人类介入点减少到最小。

人类参与的时机：

  • 意图澄清——把模糊的需求压缩成一个清晰目标
  • 规范审批——确认理解是正确的
  • 最终审查——验收最终产物

中间过程由 AI Agent 自主执行。

多角色如何协调？

BMad 的多角色协调核心是文档驱动，不是直接调用。Agent 之间不直接通信，而是通过共享的规范文档传递上下文。

协调流程

PM Agent                    架构师 Agent
    │                            │
    ├─ 创建 PRD ─────────────────→│  读取 PRD 作为约束
    │                            │
    │                     生成 architecture.md
    │                            │
    │←───────────────────────────┤
    │
PM Agent / Scrum Master
    │
    ├─ 读取 PRD + architecture ──→ 生成 Epic 和 Story
    │                            Story 继承所有上游约束
    │
开发者 Agent
    │
    ├─ 读取 Story ──────────────→ 实现代码
    │    （Story 包含 PRD + 架构的完整上下文）
    │
QA Agent
    │
    ├─ 读取 Story 的验收标准 ───→ 验证代码是否符合

关键机制

机制 说明
上下文继承 Story 文件自动继承 PRD 和架构的约束。开发者不需要重新理解产品意图，Story 里已经写清楚了
无直接调用 Agent 之间不直接通信。通过文件系统中共享的文档协调——文档写好了，开发者就能拿到完整上下文
Party Mode 可以把多个 Agent 拉进同一个会话，让他们同时讨论、协作。适合复杂决策需要多方输入的场景
bmad-help 任何时候可以问"下一步做什么"，智能向导会告诉你应该调用哪个 Agent、应该读取什么文档

具体例子：构建一个电商后台

Step 1: PM 创建 PRD

# 电商后台 PRD

## 目标
团队需要一个电商后台系统，管理商品、订单、用户。

## 用户角色
- 管理员：管理商品、查看订单
- 运营：管理库存、查看报表

## 成功标准
- 管理员可以在 3 分钟内完成商品上架
- 系统支持日均 1000 订单处理

## 非目标
- 不需要支付集成（第三方负责）
- 不需要移动端支持

Step 2: 架构师读取 PRD，生成架构文档

# 电商后台架构

## 技术选型
- 后端：Node.js + Express
- 数据库：PostgreSQL
- 前端：React + Ant Design

## 约束（来自 PRD）
- 需要支持日均 1000 订单 → 数据库需要索引优化
- 管理员快速上架 → 后台需要支持富文本编辑器
- 多角色 → RBAC 权限模型

Step 3: Scrum Master 读取 PRD + 架构，拆分为 Epic

# Epic 1: 商品管理

## 包含 Stories
- story-01: 管理员登录
- story-02: 商品列表
- story-03: 商品上架
- story-04: 商品编辑

## 技术约束（继承自架构）
- 使用 React + Ant Design
- 使用 RBAC 权限模型

Step 4: 开发者读取 Story，实现代码

# story-03: 商品上架

## 上下文继承
- 用户角色：管理员（来自 PRD）
- 技术栈：React + Ant Design（来自架构）
- 权限：需要管理员角色（来自架构 RBAC）

## 验收标准
- **GIVEN** 管理员已登录
- **WHEN** 填写商品信息并提交
- **THEN** 商品出现在商品列表
- **AND** 数据库写入成功

## 实施任务
- [ ] 创建 ProductForm 组件
- [ ] 调用 POST /api/products
- [ ] 成功后跳转到商品列表

开发者不需要重新问"商品上架需要哪些权限"——Story 里已经写了。

Step 5: QA 读取 Story 验收标准，验证代码

# story-03 验收检查

## 需要验证
1. 商品表单字段完整（名称、价格、库存、描述）
2. 提交后数据库有对应记录
3. 非管理员用户无法访问上架页面（权限验证）
4. 表单提交有防抖，防止重复提交

Party Mode：多 Agent 协作讨论

当某个决策需要多个角色的视角时，可以用 Party Mode 把他们拉到一起：

用户：我想把订单处理速度提升 10 倍，怎么改？

架构师 Agent：需要引入消息队列和异步处理
PM Agent：这会改变订单确认的流程，需要告知用户吗？
QA Agent：异步处理会导致测试复杂度上升，需要增加集成测试

→ 最终决策：分阶段实施，先做队列，再做异步

协调总结

问题 BMad 的解法
Agent A 怎么知道 B 做了什么？ 通过文档继承——Story 包含完整上游上下文
开发者需要重新理解 PRD 吗？ 不需要，Story 已经继承了一切
多个 Agent 意见冲突怎么办？ Party Mode，拉到一起讨论
不知道下一步该调用谁？ bmad-help 告诉你

安装

# 标准安装
npx bmad-method install

# 非交互式 CI/CD
npx bmad-method install --yes --modules bmm --tools claude-code

# 前置要求
# - Node.js v20+
# - Python 3.10+
# - uv

与 OpenSpec 的对比选择

场景 推荐
小团队，简单功能迭代 OpenSpec
复杂产品，多角色协作 BMad
已有代码库的功能增强 OpenSpec（Brownfield）
从零构建新产品 BMad
需要 AI Agent 团队 BMad
快速原型验证 OpenSpec

两者并不互斥——可以在 BMad 管理整体规划和 Epic 拆分，在 OpenSpec 管理单个 Story 的规范。

参考资源