ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/docs/tutorials/getting-started/bmad-tutorial.md

9.2 KiB
Raw Blame History

sidebar_label sidebar_position description
BMad v4 1 Install BMAD and create your first planning document

Getting Started with BMad v4

Learn how to build software with BMAD's AI-powered workflows. By the end of this tutorial, you'll have installed BMAD, initialized a project, and created your first planning document.

What You'll Learn

  • How to install and configure BMAD for your IDE
  • How BMAD organizes work into phases and agents
  • How to initialize a project and choose a planning track
  • How to create your first requirements document

:::info[Prerequisites]

  • Node.js 20+ — Required for the installer
  • Git — Recommended for version control
  • AI-powered IDE — Claude Code, Cursor, Windsurf, or similar
  • A project idea — Even a simple one works for learning :::

Step 1: Install BMAD

Open a terminal in your project directory and run:

npx bmad-method install

The interactive installer guides you through setup.

Choose Installation Location — Select current directory (recommended), subdirectory, or custom path.

Select Your AI Tool — Choose Claude Code, Cursor, Windsurf, or other. The installer configures BMAD for your selection.

Choose Modules — For this tutorial, select BMM (BMAD Method):

Module Purpose
BMM Core methodology for software development
BMGD Game development workflows
CIS Creative intelligence and facilitation
BMB Building custom agents and workflows

Accept Default Configuration — For your first project, accept the recommended defaults. Customize later in _bmad/[module]/config.yaml.

Verify Installation — Check your project structure:

your-project/
├── _bmad/
│   ├── bmm/            # Method module
│   │   ├── agents/     # Agent files
│   │   ├── workflows/  # Workflow files
│   │   └── config.yaml # Module config
│   └── core/           # Core utilities
├── _bmad-output/       # Generated artifacts (created later)
└── .claude/            # IDE configuration (if using Claude Code)

:::tip[Troubleshooting] Having issues? See Install BMAD for common solutions. :::

Step 2: Understand How BMAD Works

Before diving in, learn BMAD's core concepts.

Phases

BMAD organizes work into four phases:

Phase Name What Happens
1 Analysis Brainstorm, research (optional)
2 Planning Requirements — PRD or tech-spec (required)
3 Solutioning Architecture, design decisions (varies by track)
4 Implementation Build code story by story (required)

Agents

Agents are specialized AI personas, each expert in their domain:

Agent Role
Analyst Initializes projects, tracks progress, conducts research
PM Creates requirements (PRD or tech-spec)
UX-Designer Designs user interfaces and experiences
Architect Makes technical decisions, designs system architecture
SM Manages sprints, creates stories
DEV Implements code, reviews work

Workflows

Workflows are guided processes that agents run. You tell an agent to run a workflow, and it walks you through the process interactively.

Planning Tracks

Based on your project's complexity, BMAD offers three tracks:

Track Best For Documents Created
Quick Flow Bug fixes, simple features, clear scope Tech-spec only
BMAD Method Products, platforms, complex features PRD + Architecture + UX
Enterprise Compliance, multi-tenant, enterprise needs PRD + Architecture + Security + DevOps

Step 3: Initialize Your Project

Load the Analyst agent in your IDE:

  • Claude Code: Type /analyst or load the agent file directly
  • Cursor/Windsurf: Open the agent file from _bmad/bmm/agents/

Wait for the agent's menu to appear, then run the initialization workflow:

Run workflow-init

Or use the shorthand: *workflow-init

The workflow asks you to describe:

  • Your project and goals — What are you building? What problem does it solve?
  • Existing codebase — Is this new (greenfield) or existing code (brownfield)?
  • Size and complexity — Roughly how big is this? (adjustable later)

Based on your description, the workflow suggests a planning track. For this tutorial, choose BMAD Method.

Once you confirm, the workflow creates bmm-workflow-status.yaml in your project's docs folder to track your progress.

:::warning[Fresh Chats] Always start a fresh chat for each workflow. This prevents context limitations from causing issues. :::

Step 4: Create Your Requirements Document

With your project initialized, create your first planning document — the PRD (Product Requirements Document).

Start a fresh chat and load the PM agent.

Tell the PM agent:

Run prd

Or use shortcuts: *prd, select "create-prd" from the menu, or say "Let's create a new PRD".

The PM agent guides you through creating your PRD interactively:

  1. Project overview — Refine your project description
  2. Goals and success metrics — What does success look like?
  3. User personas — Who uses this product?
  4. Functional requirements — What must the system do?
  5. Non-functional requirements — Performance, security, scalability needs

Answer the agent's questions thoughtfully. The PRD becomes the foundation for everything that follows.

When complete, you'll have a PRD.md file in your _bmad-output/ folder.

Step 5: Check Your Progress

At any point, check what to do next by loading any agent and running:

workflow-status

The agent reads your bmm-workflow-status.yaml and tells you which phase you're in, what's complete, and what the next step is.

:::info[Example Response] Phase 2 (Planning) complete: PRD created

Next recommended steps:

  • UX Design (optional, if your project has a UI)
  • Architecture (required for BMAD Method track) — Agent: architect, Command: create-architecture :::

What You've Accomplished

You've completed the foundation of a BMAD project:

  • Installed BMAD and configured it for your IDE
  • Initialized a project with your chosen planning track
  • Created a PRD that defines your product requirements

Your project now has:

your-project/
├── _bmad/                         # BMAD configuration
├── _bmad-output/
│   ├── PRD.md                     # Your requirements document
│   └── bmm-workflow-status.yaml   # Progress tracking
└── ...

Next Steps

Continue building your project:

  1. Design your system's technical foundation with the Architect agent
  2. Start implementation story by story with SM and DEV agents

Explore related topics:

Quick Reference

Command Agent Purpose
*workflow-init Analyst Initialize a new project
*prd PM Create a Product Requirements Document
workflow-status Any Check progress and next steps

:::tip[Flexible Commands] Agents accept menu numbers, shortcuts (*prd), or natural language ("Let's create a PRD"). :::

Common Questions

Do I need to create a PRD for every project? Only for BMAD Method and Enterprise tracks. Quick Flow projects use a simpler tech-spec instead.

Can I skip Phase 1 (Analysis)? Yes, Phase 1 is optional. If you already know what you're building, start with Phase 2 (Planning).

What if I want to brainstorm first? Load the Analyst agent and run *brainstorm-project before workflow-init.

Why start fresh chats for each workflow? Workflows are context-intensive. Reusing chats can cause the AI to hallucinate or lose track of details. Fresh chats ensure maximum context capacity.

Getting Help

  • During workflows — Agents guide you with questions and explanations
  • Check status — Run workflow-status with any agent
  • Community — Discord (#general-dev, #bugs-issues)
  • Video tutorials — BMad Code YouTube