BMAD Method - Developer Guide
The BMAD Method is an AI-driven agile development framework that layers structured planning, named agents, reusable skills, and phased workflows on top of coding assistants such as Claude Code, Cursor, and Codex. This guide explains what BMAD is, where it helps, where it is overkill, and how to use it well without turning your workflow into ceremony theater.
1. What is BMAD?​
BMAD stands for Build More Architect Dreams. It is not "just another coding assistant" and not merely a prompt pack. The better mental model is:
| Layer | Role |
|---|---|
| Your AI IDE / coding agent | Does the actual reading, editing, command execution, and implementation |
| BMAD Method | Adds workflow structure, planning phases, named personas, and reusable skills |
| Project artifacts | PRDs, architecture docs, stories, UX specs, and context files that accumulate across the process |
The official BMAD docs describe it as a framework that helps teams move from idea and analysis through planning and architecture into implementation, while adapting the amount of rigor to the size of the task.
The key idea​
Most AI coding sessions fail for boring reasons:
- the prompt is vague
- the agent has no stable project context
- the task is too big for one chat
- nobody wrote down the decisions that the next step depends on
BMAD tries to fix that by making the agent work through a progressive context pipeline instead of a single oversized prompt.
2. Why developers use it​
BMAD is attractive when you want the AI to act more like a structured collaborator than a raw autocomplete engine.
The main advantages​
| Advantage | Why it matters |
|---|---|
| Phased workflow | You can move from idea to implementation without improvising every step |
bmad-help guidance | The system inspects project state and recommends the next sensible action |
| Named agents | Different roles such as PM, architect, UX designer, and engineer have clearer responsibilities |
| Generated skills | Workflows are invoked by name instead of rewritten from scratch every time |
| Scale-adaptive tracks | A bug fix does not need enterprise ceremony, but a platform build probably does |
| Project context files | The AI can align with your stack, conventions, and constraints across sessions |
What makes it different from a plain coding agent​
A normal coding agent is optimized for:
- one repo
- one session
- one prompt
- one implementation loop
BMAD is optimized for:
- repeatable planning
- artifact-driven handoffs
- multi-role collaboration
- large or ambiguous projects
- staying organized across many chats
3. The most important thing to understand​
BMAD is best when the problem is underspecified or large enough that planning quality changes the outcome.
It is not primarily about generating code faster. It is about improving the quality of:
- problem framing
- requirements shaping
- architecture decisions
- story decomposition
- implementation handoff
If your task is "rename three methods and fix one test", BMAD can be too much. If your task is "turn this idea into a product with requirements, architecture, and a sane build order", BMAD starts to make a lot more sense.
Use BMAD when the missing piece is usually clarity, not just typing speed.
4. How BMAD is structured​
The official workflow map organizes BMAD into four phases plus a lighter quick path.
| Phase | What happens |
|---|---|
| Analysis | Brainstorming, research, product brief, PRFAQ, pressure-testing the idea |
| Planning | PRD creation and optional UX design |
| Solutioning | Architecture work and implementation-readiness checks |
| Implementation | Sprint planning, story execution, review, and delivery |
| Quick Flow | Condensed path for smaller work where the full method would be overkill |
The tracks​
BMAD currently frames three planning tracks:
| Track | Best for | Typical output |
|---|---|---|
| Quick Flow | Bug fixes, small features, clear scope | Lightweight spec plus implementation |
| BMad Method | Product work, larger features, meaningful planning needs | PRD, architecture, stories, optional UX |
| Enterprise | Large systems, stricter controls, more cross-cutting concerns | Deeper planning, architecture, security, operational considerations |
The BMAD docs explicitly say to choose a track by planning needs, not by obsessing over a story count threshold.
5. The pieces you will actually touch​
5.1 bmad-help​
This is the most important entry point. It is BMAD's context-aware guide:
- it inspects what artifacts already exist
- it checks which modules and workflows are available
- it recommends the next required step first, then optional ones
If you install BMAD and do not know where to start, start here.
5.2 Skills​
BMAD generates skills at install time. These are pre-built prompts that your IDE can invoke directly, for example:
bmad-helpbmad-prdbmad-quick-devbmad-create-architecturebmad-sprint-planning
The generated skills live in an IDE-specific directory such as:
| IDE / CLI | Skills directory |
|---|---|
| Claude Code | .claude/skills/ |
| Cursor | .agents/skills/ |
| Windsurf | .agents/skills/ |
5.3 Named agents​
BMAD also ships named agent personas such as:
- Mary for analysis
- John for product management and planning
- Sally for UX
- Winston for architecture
- Amelia for implementation
These are not just mascots. The docs describe them as a layer that wraps related skills in a more stable role and interaction style.
5.4 Output folders​
A standard install creates:
_bmad/for agents, workflows, tasks, and configuration_bmad-output/for generated artifacts
This separation is useful. It keeps the framework bits away from the documents that become part of your project process.
6. How to use BMAD well​
This is where most of the real value lives.
6.1 Start with the core module, not the whole universe​
Install BMAD, choose the core BMad Method module first, and learn the flow before adding specialized modules or web bundles.
npx bmad-method install
If you pile on extra modules before you understand the baseline workflow, you will create complexity faster than clarity.
6.2 Use bmad-help as your front door​
The best BMAD habit is simple:
- install it
- open the repo in your AI IDE
- run
bmad-help - follow the next recommended workflow
This is better than memorizing commands or trying to outsmart the system too early.
6.3 Use one fresh chat per workflow​
The official getting-started guide explicitly recommends a fresh chat for each workflow. That is one of the highest-signal habits in the whole system.
Why it matters:
- you reduce context drift
- you avoid polluting one step with leftovers from another
- you make artifacts, not chat history, carry the project forward
6.4 Pick the smallest track that still protects quality​
This is the main adoption mistake: people either over-BMAD a tiny task or under-BMAD a complex one.
Good default:
- use Quick Flow for small, contained changes
- use the full BMad Method when requirements or architecture are still fuzzy
- use the Enterprise mindset only when the system actually has that level of risk or coordination burden
6.5 Treat artifacts as the source of truth​
BMAD works because each phase produces documents that feed the next one. If you ignore the artifacts and keep steering from ad-hoc chat messages, you lose the point of the method.
The important mindset is:
- decisions go into documents
- later workflows consume those documents
- implementation should reflect the written plan unless you intentionally revise it
6.6 Use project context early on existing codebases​
For established projects, the BMAD docs recommend generating project-context.md so the agents align with your current conventions.
bmad-generate-project-context
That is especially valuable when the repo already has strong patterns for:
- architecture
- naming
- testing
- framework conventions
- deployment constraints
6.7 Re-run the installer when your module setup changes​
BMAD generates skills from the currently installed modules. If you add or remove modules later, re-run the installer so the skill set stays in sync.
This is easy to overlook and can make the environment feel "broken" when it is actually just stale.
7. Recommended workflows​
7.1 New product or major feature​
This is where BMAD is strongest.
Recommended path:
- Run
bmad-help - Use analysis workflows if the idea is still fuzzy
- Create the PRD with
bmad-prd - Add UX work if the feature has meaningful interface complexity
- Create architecture with
bmad-create-architecture - Generate epics and stories
- Run the implementation-readiness check
- Move into sprint planning and implementation
This path gives the coding agent better constraints, better decomposition, and fewer "rewrite half the feature" surprises later.
7.2 Existing product with a small change​
Do not force the full method.
The official established-project guidance recommends bmad-quick-dev for smaller additions or updates. That lets you clarify intent, plan lightly, implement, and review in one tighter loop.
7.3 Existing product with a major change​
Use BMAD more deliberately:
- generate or refine project context
- point the planning workflows at your real docs and codebase constraints
- ensure PRD and architecture work against the current system, not a greenfield fantasy
BMAD is useful here because existing systems usually fail on integration assumptions, not on code generation.
8. Where BMAD is overkill​
BMAD is probably too much when:
- you just want a fast coding loop
- you are still learning your base agent
- the task is a single bug fix or tiny refactor
- your project does not benefit from formal artifacts
- you dislike working through explicit phases
It can also become counterproductive if you use it performatively, for example:
- generating a PRD nobody will read
- writing architecture docs for trivial changes
- invoking multiple roles when one focused workflow would do
BMAD can make weak teams feel organized without actually improving decisions. The method only helps if the produced artifacts are better than what you would otherwise do.
9. Web bundles and cost-aware planning​
One useful BMAD idea is the web bundle approach. The project packages selected planning workflows for web LLM surfaces such as ChatGPT Custom GPTs and Gemini Gems.
The practical reason is smart:
- do large planning work in a flat-rate web subscription
- bring the polished artifacts into your coding IDE afterward
- spend metered IDE agent tokens on implementation instead of open-ended ideation
This will not fit every team, but it is a sensible pattern if planning is long and implementation tokens are expensive.
10. A realistic adoption strategy​
If you want the benefits without drowning in surface area, use this order:
Phase 1 - Learn the baseline​
- install the core BMad Method module
- run
bmad-help - try one small but meaningful feature
- keep the flow limited to PRD, architecture, and implementation
Phase 2 - Adapt for your real codebase​
- generate
project-context.md - see whether BMAD actually respects your conventions better
- decide when Quick Flow is enough and when the full method helps
Phase 3 - Expand only where there is pain​
- add specialized modules if you genuinely need them
- use web bundles if planning cost is the bottleneck
- customize only after you understand the default behavior
That sequence gives you signal before ceremony.
11. Bottom line​
BMAD is a strong fit for developers and teams who already use AI coding assistants but want a repeatable planning and execution method around them. It is most valuable when the work is ambiguous, cross-functional, or large enough that architecture and decomposition matter.
It is not the best choice for every task. For small, obvious changes, a normal coding agent loop is usually better. But when the problem is bigger than a prompt and smaller than a full human process department, BMAD occupies a very useful middle ground.