BMAD Method: AI-Driven Agile Development
The BMAD Method (Breakthrough Method for Agile AI-Driven Development) is a revolutionary methodology that tackles one of the most critical problems of AI-assisted software development: how do you manage complex projects that exceed the capabilities of a single conversation session? The answer lies in a concept as simple as it is powerful: Document Sharding, the fragmentation of project documentation into atomic pieces optimized for consumption by AI agents.
BMAD is not simply a set of prompts or a collection of templates: it is a complete framework that includes 21 specialized agents, over 50 guided workflows, templates for every project phase, and an adaptive intelligence system that scales complexity based on project size. In this article we will explore every aspect of the method, from theory to practice, with concrete implementation examples.
What You'll Learn
- Understand the context overflow problem and how BMAD solves it
- Master the concept of Document Sharding and its importance
- Learn about the 21 specialized agents and their roles
- Use the 50+ guided workflows for every project phase
- Apply BMAD's scale-adaptive intelligence
- Configure BMAD in your own project with Claude Code
- Compare BMAD with traditional methodologies
- Avoid common implementation mistakes
Series Overview
| # | Article | Focus |
|---|---|---|
| 1 | Claude as Technical Partner | Setup and first steps |
| 2 | Context and Project Setup | CLAUDE.md and configuration |
| 3 | Ideation and Requirements | MVP and user personas |
| 4 | Backend and Frontend Architecture | Spring Boot and Angular |
| 5 | Code Structure | Organization and conventions |
| 6 | Advanced Prompt Engineering | Advanced techniques |
| 7 | Testing and Quality | Strategies and test generation |
| 8 | Professional Documentation | README, API, ADR |
| 9 | Deploy and DevOps | Docker, CI/CD, monitoring |
| 10 | Evolution and Maintenance | Refactoring and scalability |
| 11 | Real Project Integration | Claude Code in production |
| 12 | Claude Code CLI | Command line mastery |
| 13 | Agent Skills | Extending Claude Code |
| 14 | Specialized Subagents | Orchestrating specialized agents |
| 15 | Hooks and Automation | Event-driven automation |
| 16 | Ralph Wiggum Method | Iterative autonomous development |
| 17 | BMAD Method (you are here) | AI-driven agile methodology |
| 18 | Multi-Agent Orchestration | Coordinating agent teams |
| 19 | Claude Cowork | Working together with Claude |
| 20 | Security and Privacy | Protecting the workflow |
| 21 | Monitoring and Productivity | Metrics and performance |
1. The Context Overflow Problem
To understand why BMAD exists, you need to understand the fundamental problem it solves. Language models like Claude have a limited context window: the maximum amount of text they can "remember" during a conversation. Even the most advanced models with 200K token windows have significant practical limits when it comes to managing complex software projects.
A typical enterprise project includes hundreds of source files, dozens of specification documents, architecture, test plans, deployment guides, and API documentation. Fitting all of this into a single conversation is impossible, and even inserting significant portions degrades response quality because the model must "dilute" its attention across too much material.
The Problem in Numbers
| Element | Typical Size | % Context Window (200K) |
|---|---|---|
| Complete requirements specification | 20K-50K tokens | 10-25% |
| Architecture document | 15K-30K tokens | 7-15% |
| Database schema (20 tables) | 5K-10K tokens | 2-5% |
| API documentation | 30K-80K tokens | 15-40% |
| Complete test plan | 10K-25K tokens | 5-12% |
| Existing codebase (100 files) | 100K-500K tokens | 50-250% |
| Typical medium project total | 200K-700K tokens | 100-350% |
As you can see, even a medium-complexity project generates more documentation than a single context window can contain. Traditional solutions to this problem are unsatisfactory:
- Summarize everything: Critical implementation details are lost
- Separate sessions: Coherence between different parts of the project is lost
- Selective copy-paste: Requires constant manual management and is error-prone
- RAG (Retrieval Augmented Generation): Good for specific questions, but insufficient for complex implementation tasks
2. Document Sharding: The Key Innovation
Document Sharding is the central concept of BMAD. The idea is simple yet profound: instead of creating monolithic documentation that attempts to describe the entire project in long documents, BMAD breaks down every aspect of the project into atomic, self-contained, and interconnected fragments that can be provided to the AI agent exactly when needed, without wasting context.
Document Sharding Principles
- Atomicity: Each shard describes a single concept, component, or decision. It is not necessary to read other shards to understand it completely.
- Self-containment: Each shard includes all the context necessary for its use. If a shard describes an API endpoint, it contains input/output schema, validation, possible errors, and dependencies.
- Interconnection: Shards contain explicit references to other related shards, allowing the agent to navigate documentation like a graph.
- Optimal size: Each shard is sized to occupy a manageable portion of the context window (typically 2K-8K tokens), leaving room for reasoning and code generation.
BMAD Directory Structure
bmad-agent/
├── agents/ # 21 specialized agents
│ ├── pm-agent.md # Product Manager
│ ├── architect-agent.md # System Architect
│ ├── developer-agent.md # Developer
│ ├── ux-agent.md # UX Designer
│ ├── sm-agent.md # Scrum Master
│ ├── qa-agent.md # Quality Assurance
│ ├── devops-agent.md # DevOps Engineer
│ ├── data-agent.md # Data Engineer
│ ├── security-agent.md # Security Specialist
│ ├── tech-writer-agent.md # Technical Writer
│ ├── analyst-agent.md # Business Analyst
│ ├── design-agent.md # System Designer
│ ├── frontend-agent.md # Frontend Specialist
│ ├── backend-agent.md # Backend Specialist
│ ├── mobile-agent.md # Mobile Developer
│ ├── ml-agent.md # ML Engineer
│ ├── performance-agent.md # Performance Engineer
│ ├── migration-agent.md # Migration Specialist
│ ├── review-agent.md # Code Reviewer
│ ├── release-agent.md # Release Manager
│ └── orchestrator-agent.md # Agent Orchestrator
│
├── tasks/ # 50+ guided workflows
│ ├── analysis/
│ │ ├── gather-requirements.md
│ │ ├── competitive-analysis.md
│ │ ├── user-persona-creation.md
│ │ └── risk-assessment.md
│ ├── planning/
│ │ ├── create-roadmap.md
│ │ ├── sprint-planning.md
│ │ ├── resource-allocation.md
│ │ └── milestone-definition.md
│ ├── architecture/
│ │ ├── system-design.md
│ │ ├── api-contract.md
│ │ ├── database-schema.md
│ │ └── integration-patterns.md
│ ├── implementation/
│ │ ├── feature-implementation.md
│ │ ├── code-generation.md
│ │ ├── refactoring-guide.md
│ │ └── testing-strategy.md
│ └── delivery/
│ ├── deployment-plan.md
│ ├── release-checklist.md
│ ├── monitoring-setup.md
│ └── post-mortem.md
│
├── templates/ # Reusable templates
│ ├── prd-template.md # Product Requirements Document
│ ├── adr-template.md # Architecture Decision Record
│ ├── epic-template.md # Epic/Feature template
│ ├── story-template.md # User Story template
│ └── test-plan-template.md # Test Plan template
│
├── personas/ # Persona configurations
│ ├── startup-mode.md # Lean startup mode
│ ├── enterprise-mode.md # Rigorous enterprise mode
│ └── solo-dev-mode.md # Single developer mode
│
└── checklists/ # Quality checklists
├── code-review.md
├── security-audit.md
├── accessibility.md
└── performance.mdShard Example: API Endpoint
# API Shard: Create Booking
## Endpoint
POST /api/v1/bookings
## Description
Creates a new booking for a registered user.
## Authentication
Bearer JWT Token (roles: USER, ADMIN)
## Input Schema
{
"roomId": "string (UUID, required)",
"checkIn": "string (ISO 8601, required)",
"checkOut": "string (ISO 8601, required)",
"guests": "number (1-10, required)",
"notes": "string (max 500 char, optional)"
}
## Validations
1. checkOut must be after checkIn
2. Minimum duration is 1 night
3. Maximum duration is 30 nights
4. The room must exist and be available for the period
5. The user must not have overlapping bookings
## Responses
- 201 Created: booking created successfully
- 400 Bad Request: validation failed
- 401 Unauthorized: missing or invalid token
- 404 Not Found: room not found
- 409 Conflict: room not available for the period
## Dependencies
- Shard: room-availability-service
- Shard: user-validation-middleware
- Shard: booking-entity-schema
## Required Tests
- Happy path with valid data
- Date validation (checkOut before checkIn)
- Room not available (conflict)
- Unauthenticated user
- Overlapping bookingThis shard contains everything needed to implement the endpoint: input schema, validations, responses, dependencies, and required tests. An AI agent receiving this shard has the necessary context to produce a complete implementation without needing to read the entire project documentation.
3. The 21 Specialized BMAD Agents
The operational core of BMAD is composed of 21 specialized agents, each configured with specific competencies, system prompts, and workflows for a particular aspect of software development. These agents are not independent entities but Claude Code configurations that activate specific expertise through system prompts and selective access to documentation shards.
Agent Map by Project Phase
| Phase | Agents Involved | Responsibilities |
|---|---|---|
| Analysis | PM Agent, Analyst, UX Agent | Requirements, personas, competitive analysis |
| Planning | SM Agent, PM Agent | Roadmap, sprint planning, resources |
| Architecture | Architect, Designer, Security | System design, API contract, security |
| Implementation | Developer, Frontend, Backend, Mobile, ML | Code, tests, integration |
| Quality | QA Agent, Review Agent, Performance | Testing, code review, performance |
| Delivery | DevOps, Release, Tech Writer | Deploy, documentation, release notes |
| Coordination | Orchestrator, Data Agent, Migration | Orchestration, data, migration |
Agent Profile: PM Agent (Product Manager)
The PM Agent is responsible for gathering and managing product requirements. It is the first agent to be invoked in most projects and produces the fundamental artifacts that guide all subsequent development.
# PM Agent - Product Manager
## Identity
You are an experienced Product Manager with 15+ years of experience in B2B
and B2C software products. You excel at requirements gathering, stakeholder
needs analysis, and strategic roadmap definition.
## Specific Competencies
- Requirements elicitation techniques (interviews, workshops, surveys)
- Prioritization frameworks (MoSCoW, RICE, Kano)
- Product Requirements Document (PRD) creation
- Success metrics definition (KPI, OKR)
- Competitive analysis and positioning
## Available Workflows
1. gather-requirements: Structured requirements gathering
2. competitive-analysis: Competitive landscape analysis
3. user-persona-creation: Detailed user persona creation
4. prd-creation: Product Requirements Document drafting
5. roadmap-planning: Product roadmap planning
## Templates
- prd-template.md: Requirements document template
- epic-template.md: Epic/feature template
- story-template.md: User stories template
## Interaction Rules
1. Always ask clarifying questions before proceeding
2. Quantify requirements when possible (numbers, metrics, SLA)
3. Identify and document risks for each critical requirement
4. Always distinguish between MUST, SHOULD, COULD and WON'T (MoSCoW)
5. Produce artifacts in shard format for consumption by other agentsAgent Profile: Architect Agent
The Architect Agent transforms the PM Agent's requirements into concrete architectural decisions. It produces architecture shards that guide implementation, defining technologies, patterns, interfaces, and trade-offs.
# Architect Agent - System Architect
## Identity
You are a senior System Architect with experience in distributed architectures,
microservices, event-driven and serverless. You balance pragmatism and technical
rigor in architectural decisions.
## Specific Competencies
- Scalable architecture design (vertical and horizontal)
- Architectural patterns (DDD, CQRS, Event Sourcing, Hexagonal)
- API Design (REST, GraphQL, gRPC)
- Database selection (SQL vs NoSQL vs NewSQL)
- Trade-off analysis (CAP theorem, performance vs consistency)
- Security by design
## Expected Output
For each architectural decision, produce:
1. ADR (Architecture Decision Record) in shard format
2. Component diagram (textual description for mermaid)
3. API contract shard for each interface
4. Database schema shard
5. List of constraints and assumptions
## Rules
1. Every decision must have an ADR with alternatives considered
2. Prefer simple solutions over elegant solutions
3. Document trade-offs explicitly
4. Define interfaces before implementations
5. Always consider scalability, security, and maintainabilityAgent Profile: Developer Agent
The Developer Agent is the agent that produces actual code. It consumes the shards produced by the PM Agent and the Architect Agent to implement features, write tests, and produce code that respects architectural constraints.
# Developer Agent - Full-Stack Developer
## Identity
You are an experienced full-stack developer with mastery of TypeScript,
Java, Python and Go. You write clean, testable and maintainable code.
You follow community best practices and SOLID principles.
## Specific Competencies
- TypeScript/JavaScript (Node.js, Angular, React, Next.js)
- Java (Spring Boot, Hibernate)
- Python (FastAPI, Django)
- Database (PostgreSQL, MongoDB, Redis)
- Testing (Jest, JUnit, pytest)
- Clean Code and Design Patterns
## Workflow
1. Read the shard for the feature/endpoint to implement
2. Read the relevant architecture shard
3. Implement the code following project conventions
4. Write unit tests with coverage > 80%
5. Run lint and type check
6. Update the module STATUS.md
## Rules
1. Never use `any` in TypeScript without a justification comment
2. Every public function must have JSDoc/JavaDoc
3. Explicit error handling, never empty catches
4. Follow the naming convention defined in CLAUDE.md
5. Respect the interfaces defined by the Architect AgentAgent Profile: QA Agent
The QA Agent is responsible for testing strategy and code quality validation. It operates in parallel with the Developer Agent, producing test cases, performing coverage analysis, and identifying gaps in implementation quality.
Agent Profile: Scrum Master Agent
The SM Agent coordinates the development process, manages sprint planning, facilitates retrospectives, and removes impediments. In the BMAD context, it is responsible for creating and maintaining the shard backlog and task prioritization.
The Other Agents
Complete Overview of All 21 Agents
| # | Agent | Role | Primary Output |
|---|---|---|---|
| 1 | PM Agent | Product Manager | PRD, User Stories, Backlog |
| 2 | Architect Agent | System Architect | ADR, API Contract, Schema |
| 3 | Developer Agent | Full-Stack Developer | Code, Unit Tests |
| 4 | UX Agent | UX Designer | Wireframes, User Flows |
| 5 | SM Agent | Scrum Master | Sprint Plan, Retrospective |
| 6 | QA Agent | Quality Assurance | Test Plan, Bug Report |
| 7 | DevOps Agent | DevOps Engineer | Pipeline, Infrastructure |
| 8 | Data Agent | Data Engineer | Schema, Migration, ETL |
| 9 | Security Agent | Security Specialist | Threat Model, Audit |
| 10 | Tech Writer Agent | Technical Writer | Docs, API Guide, README |
| 11 | Analyst Agent | Business Analyst | Analysis, Metrics, KPI |
| 12 | Designer Agent | System Designer | Component Design, Patterns |
| 13 | Frontend Agent | Frontend Specialist | UI Components, State |
| 14 | Backend Agent | Backend Specialist | Services, APIs, DB |
| 15 | Mobile Agent | Mobile Developer | App, Native Features |
| 16 | ML Agent | ML Engineer | Models, Pipelines, Eval |
| 17 | Performance Agent | Performance Engineer | Benchmarks, Optimization |
| 18 | Migration Agent | Migration Specialist | Migration Plan, Scripts |
| 19 | Review Agent | Code Reviewer | Review Notes, Suggestions |
| 20 | Release Agent | Release Manager | Release Notes, Changelog |
| 21 | Orchestrator Agent | Agent Coordinator | Task Routing, Sync |
4. The 50+ Guided Workflows
Each BMAD agent has predefined workflows: structured sequences of steps that guide the agent through complex tasks in a systematic and reproducible way. Workflows eliminate ambiguity and ensure that every aspect of a task is addressed, regardless of complexity.
Workflow by Phase: Analysis
Analysis phase workflows are designed to gather and structure the information needed before any design or implementation activity.
# Workflow: Structured Requirements Gathering
## Prerequisites
- Access to the client/stakeholder (or brief document)
- PRD template (prd-template.md)
- Standard questions checklist
## Steps
### Step 1: Context Understanding
- What problem does the product solve?
- Who are the target users?
- What are the business constraints (budget, timeline, compliance)?
- Are there legacy systems to integrate?
### Step 2: Functional Elicitation
For each identified macro-feature:
1. Define the main use case (happy path)
2. Identify edge cases
3. Define acceptance criteria (Given/When/Then)
4. Classify priority (MoSCoW)
5. Estimate relative complexity (S/M/L/XL)
### Step 3: Non-Functional Requirements
- Performance: expected response times (p50, p95, p99)
- Scalability: expected concurrent users (now, 6 months, 1 year)
- Availability: target SLA (99.9%? 99.99%?)
- Security: compliance requirements (GDPR, SOC2, PCI-DSS)
- Accessibility: target WCAG level (A, AA, AAA)
### Step 4: Artifact Production
Generate the following shards:
1. shard-prd-overview.md (project overview)
2. shard-personas.md (user personas)
3. shard-requirements-functional.md (functional requirements)
4. shard-requirements-nonfunctional.md (non-functional requirements)
5. shard-constraints.md (constraints and assumptions)
6. shard-risks.md (identified risks)
### Step 5: Validation
- Review each shard for completeness
- Verify that every requirement is testable
- Confirm priorities with the stakeholderWorkflow by Phase: Architecture
# Workflow: System Design
## Required Input
- shard-prd-overview.md
- shard-requirements-functional.md
- shard-requirements-nonfunctional.md
- shard-constraints.md
## Steps
### Step 1: Component Identification
Read the functional requirements and identify:
- Bounded contexts (DDD)
- Main services
- External integrations
- Persistence layers
### Step 2: Architectural Pattern Selection
Evaluate and document in ADR:
- Monolith vs Microservices vs Modular Monolith
- Sync vs Async communication
- SQL vs NoSQL for each bounded context
- Hosting: Cloud vs On-premise vs Hybrid
### Step 3: Interface Design
For each service/module:
1. Define API contract (OpenAPI/Protobuf)
2. Define event schema (for async communication)
3. Define database schema
4. Document in separate shards
### Step 4: Security Design
- Authentication: method and flow
- Authorization: model (RBAC, ABAC, ReBAC)
- Encryption: at rest and in transit
- Threat model (STRIDE)
### Step 5: Architectural Shard Production
1. shard-architecture-overview.md
2. shard-adr-{decision}.md (one per decision)
3. shard-api-{service}.md (one per API)
4. shard-db-{context}.md (schema per bounded context)
5. shard-security-model.mdWorkflow by Phase: Implementation
# Workflow: Feature Implementation
## Required Input
- shard-api-{endpoint}.md (endpoint contract)
- shard-db-{context}.md (database schema)
- shard-architecture-overview.md (architectural constraints)
## Steps
### Step 1: Shard Analysis
1. Read the shard for the endpoint/feature to implement
2. Identify dependencies on other shards
3. Verify that all interfaces are defined
### Step 2: Scaffolding
1. Create the necessary files following the project structure
2. Define TypeScript/Java interfaces for the types
3. Create stubs for the main methods
### Step 3: TDD Implementation
For each feature in the shard:
1. Write the test that verifies expected behavior
2. Implement the minimum code to pass the test
3. Refactor while keeping tests green
4. Repeat for the next feature
### Step 4: Integration
1. Verify compatibility with defined interfaces
2. Run integration tests
3. Verify compliance with the architecture shard
### Step 5: Quality
1. Run linter and type checker
2. Verify coverage > 80%
3. Document API with JSDoc/JavaDoc
4. Update STATUS.md5. Scale-Adaptive Intelligence
One of BMAD's most significant innovations is Scale-Adaptive Intelligence: the ability to automatically adapt the level of complexity, formality, and rigor of the process based on the size and nature of the project. Not all projects need 21 agents and 50 workflows; a personal side project requires a radically different approach from an enterprise system.
BMAD Scale Levels
| Level | Project Type | Active Agents | Workflows | Formality |
|---|---|---|---|---|
| Nano | Script, utility, single tool | 1 (Developer) | Minimal | No formal documentation |
| Micro | Side project, prototype, MVP | 3 (PM, Dev, QA) | Essential | README + basic tests |
| Small | Startup, small team (2-5) | 6 (PM, Arch, Dev, QA, DevOps, Writer) | Standard | PRD + ADR + API docs |
| Medium | Business product, medium team (5-15) | 12 | Complete | Full documentation + compliance |
| Large | Enterprise, large team (15+) | All 21 | All + custom | Full formal + audit trail |
Solo Developer Mode
For solo developers, BMAD offers the Solo Dev mode that condenses the responsibilities of multiple agents into a lean but effective workflow:
# BMAD Solo Developer Mode
## Active Agents
1. PM Agent (lightweight): only user stories and acceptance criteria
2. Developer Agent: implementation + testing
3. DevOps Agent: only deployment configuration
## Simplified Workflow
1. Define the problem in 1 paragraph
2. List the main features (max 10)
3. For each feature, write 1 user story with acceptance criteria
4. Implement with TDD
5. Deploy
## Minimum Shards
- overview.md: what the project does, for whom, why
- features.md: feature list with priorities
- tech-stack.md: chosen technologies with rationale
- For each feature: 1 shard with interface + test criteria
## Rules
- No formal ADRs for obvious decisions
- Unit tests only for complex business logic
- Inline documentation (JSDoc) instead of separate documents
- Continuous deployment without formal releases6. The 4 Phases of the BMAD Workflow
Regardless of the project scale, BMAD organizes the development process into four distinct phases, each with specific objectives, responsible agents, and output artifacts. The phases are sequential for the first execution but become iterative once the project is underway.
Phase 1: Analysis
The analysis phase is dedicated to deep understanding of the problem to be solved. The PM, Analyst, and UX agents collaborate to gather requirements, define personas, analyze the competitive landscape, and identify constraints and risks.
Agents involved: PM Agent, Analyst Agent, UX Agent
Artifacts produced: PRD (Product Requirements Document), User Personas, Competitive Analysis, Risk Assessment, Functional and Non-Functional Requirements in the form of atomic shards.
The output of the analysis phase is a set of shards that completely describes what needs to be built and for whom, without yet defining how. This separation is fundamental to avoid premature implementation decisions.
Phase 2: Planning
The planning phase transforms requirements into a concrete work plan. The Scrum Master Agent and the PM Agent collaborate to define the roadmap, organize the backlog, plan sprints, and allocate resources (agents) to tasks.
Agents involved: SM Agent, PM Agent
Artifacts produced: Project Roadmap, Sprint Backlog, Milestone Definition, Resource Allocation Matrix. Every task in the backlog is associated with one or more requirement shards and one or more agents responsible for implementation.
Phase 3: Architecture
The architecture phase defines how the system will be built. The Architect Agent and the Designer Agent analyze the requirements and produce documented architectural decisions, API contracts, database schemas, and security models.
Agents involved: Architect Agent, Designer Agent, Security Agent
Artifacts produced: Architecture Overview, ADR (Architecture Decision Records), API Contracts, Database Schemas, Security Model, Integration Patterns. Every decision is documented with the alternatives considered and the reasons for the choice, creating a complete audit trail of design decisions.
Phase 4: Implementation
The implementation phase is where code gets written. The Developer Agents (with Frontend, Backend, Mobile variants) consume the shards produced in previous phases to implement features, write tests, and produce deploy-ready code. In parallel, the QA Agent validates quality and the DevOps Agent prepares infrastructure.
Agents involved: Developer Agent, Frontend Agent, Backend Agent, QA Agent, DevOps Agent, Tech Writer Agent
Artifacts produced: Source code, Test suite, API Documentation, CI/CD Pipeline, Release Notes, User Guide.
┌─────────────────────────────────────────────────────────────────┐
│ PHASE 1: ANALYSIS │
│ PM Agent ──→ Analyst Agent ──→ UX Agent │
│ Output: PRD shards, Personas, Requirements, Risks │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ PHASE 2: PLANNING │
│ SM Agent ──→ PM Agent │
│ Output: Roadmap, Sprint Backlog, Milestones │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ PHASE 3: ARCHITECTURE │
│ Architect Agent ──→ Designer Agent ──→ Security Agent │
│ Output: ADR shards, API contracts, DB schemas, Security model │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ PHASE 4: IMPLEMENTATION │
│ Developer ──→ QA ──→ DevOps ──→ Tech Writer │
│ Output: Code, Tests, Pipeline, Documentation │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌──────────────┐
│ DELIVERY │
│ Release + │
│ Monitoring │
└──────────────┘7. Comparison with Traditional Methodologies
BMAD was not born in a vacuum: it positions itself at the intersection between traditional agile methodologies and the emerging capabilities of AI agents. Understanding the differences and complementarities with established approaches helps evaluate when and how to apply BMAD.
BMAD vs Traditional Methodologies
| Aspect | Scrum | Kanban | BMAD |
|---|---|---|---|
| Iterations | Fixed sprints (2-4 weeks) | Continuous flow | Adaptive loops (minutes-hours) |
| Roles | 3 human roles | No fixed roles | 21 configurable AI agents |
| Documentation | User stories, backlog | Cards on the board | Interconnected atomic shards |
| Feedback | End of sprint (retrospective) | Continuous (flow metrics) | Every iteration (automated tests) |
| Scalability | SAFe, LeSS for large-scale | Natively scalable | Scale-adaptive intelligence |
| Human cost | Full team required | Flexible team | 1 operator + API cost |
| Speed | Weeks per feature | Days per feature | Hours per feature (with loops) |
It is important to emphasize that BMAD does not replace agile methodologies but enhances them. A team using Scrum can adopt BMAD to accelerate the implementation phase of each sprint, maintaining Scrum ceremonies for human coordination and using BMAD agents for individual task execution.
8. Configuring BMAD in Your Own Project
Integrating BMAD into an existing project requires an initial setup that prepares the directory structure, configuration files, and base shards. The process is designed to be incremental: you can start with minimal configuration and add complexity as the project grows.
Step 1: Installation
# Clone the BMAD template
git clone https://github.com/bmad-method/bmad-agent.git .bmad
# Create the base structure in the project
mkdir -p .bmad/{agents,tasks,templates,shards}
# Copy the agents needed for the chosen scale level
# Example: "Small" level (6 agents)
cp .bmad/agents/{pm-agent,architect-agent,developer-agent,qa-agent,devops-agent,tech-writer-agent}.md \
.bmad/agents/
# Copy the relevant workflows
cp -r .bmad/tasks/{analysis,architecture,implementation} .bmad/tasks/
# Configure CLAUDE.md to integrate BMAD
cat >> CLAUDE.md << 'EOF'
## BMAD Configuration
- Agents directory: .bmad/agents/
- Tasks directory: .bmad/tasks/
- Shards directory: .bmad/shards/
- Active scale: Small (6 agents)
When starting a new task, always:
1. Check which shard is relevant in .bmad/shards/
2. Follow the appropriate workflow in .bmad/tasks/
3. Produce output as new shards when generating documentation
EOFStep 2: Creating Initial Shards
# .bmad/shards/project-overview.md
# Project Overview Shard
## Project Name
BookingAPI - Online Booking System
## Problem
Small hotels and B&Bs lack a modern, affordable, and easily
embeddable booking system for their websites.
## Solution
REST API + Embeddable widget for booking management with
availability calendar, payments, and notifications.
## Technology Stack
- Backend: Node.js + Express + TypeScript
- Database: PostgreSQL
- Cache: Redis
- Auth: JWT + OAuth2
- Deploy: Docker + Railway
## Target Users
1. Small hotel/B&B owners (admin)
2. Guests who book (end user)
3. Developers who integrate the widget (developer)
## Constraints
- Budget: $0 infrastructure (free tier)
- Timeline: MVP in 2 weeks
- Compliance: GDPR for user data
- Accessibility: WCAG 2.1 AA
## Related Shards
- shard-personas.md
- shard-requirements-functional.md
- shard-architecture-overview.mdStep 3: Invoking an Agent
Once configured, you invoke a BMAD agent by providing Claude Code with the agent context and the relevant shard:
# Method 1: Direct prompt with agent context
claude "Read .bmad/agents/architect-agent.md to assume the architect role.
Then read .bmad/shards/project-overview.md and .bmad/shards/requirements-functional.md.
Follow the workflow in .bmad/tasks/architecture/system-design.md to produce
the architectural design. Save each output as a separate shard in .bmad/shards/"
# Method 2: Custom slash command
# In .claude/commands/bmad-architect.md:
# Assume the Architect Agent role from .bmad/agents/architect-agent.md
# Read relevant shards and produce architecture design shards
/bmad-architect "Booking system design"
# Method 3: Combination with Ralph Wiggum
# PROMPT.md with BMAD instructions + autonomous loop
cat PROMPT.md | claude --print --dangerously-skip-permissions9. Best Practices and Common Mistakes
BMAD adoption brings significant benefits when applied correctly, but can introduce unnecessary complexity if used inappropriately. This section collects lessons learned from the community and identifies success patterns and anti-patterns to avoid.
Best Practices
- Start small: Begin at the Micro or Small scale level and add complexity only when needed. It is much easier to add agents and workflows than to remove them once integrated into the process.
- Shards before code: Resist the temptation to write code before having clear shards. The investment in structured documentation pays off enormously during the implementation phase.
- One shard = one concept: If a shard requires more than 8K tokens, it is probably trying to cover too many concepts. Split it into smaller, interconnected shards.
- Update shards: Shards are not static documents. When implementation reveals that an assumption was wrong, update the corresponding shard to maintain coherence.
- Combine with Ralph Wiggum: For the implementation phase, the BMAD + Ralph Wiggum pairing is extremely effective: BMAD provides the structure and shards, Ralph Wiggum executes the iterative implementation.
Common Mistakes
BMAD Anti-Patterns
| Anti-Pattern | Problem | Solution |
|---|---|---|
| Over-engineering | Using all 21 agents for a todo list | Choose the appropriate scale level |
| Monolithic shards | 20K+ token shards containing everything | Split into atomic shards of 2-8K tokens |
| Orphan shards | Shards without references to other shards | Every shard must have a "Related Shards" section |
| Infinite analysis | Producing shards without ever implementing | Define a time-box for each phase |
| Ignoring feedback | Not updating shards when implementation diverges | Review and update shards at end of sprint |
| Copy-paste agents | Using agents without customizing them for the project | Adapt prompts and rules of each agent to the context |
10. Integration with Claude Code CLI
BMAD integrates natively with Claude Code through several mechanisms: CLAUDE.md for persistent context, slash commands for agent invocation, hooks for automation, and sub-agents for parallel execution.
CLAUDE.md as BMAD Hub
# CLAUDE.md
## Project
BookingAPI - Online Booking System
## BMAD Configuration
Scale: Small (6 agents active)
### Directory Structure
- `.bmad/agents/` - Agent configurations
- `.bmad/tasks/` - Guided workflows
- `.bmad/shards/` - Project documentation shards
- `.bmad/templates/` - Reusable templates
### Active Agents
1. PM Agent: requirements and product decisions
2. Architect Agent: system design and ADRs
3. Developer Agent: code implementation
4. QA Agent: testing strategy and execution
5. DevOps Agent: deployment and infrastructure
6. Tech Writer Agent: documentation
### Conventions
- Every new feature must start with a shard
- Every architecture decision needs an ADR shard
- Implementation follows TDD within BMAD workflows
- Shards are updated when implementation diverges
### Current Sprint
Read `.bmad/shards/sprint-current.md` for active tasks
## Development Commands
- `npm run dev` - Start development server
- `npm test` - Run test suite
- `npm run build` - Production build
- `npm run lint` - Lint checkSlash Commands for BMAD Agents
# .claude/commands/bmad-pm.md
# Assume the PM Agent role from .bmad/agents/pm-agent.md
# Gather requirements and produce shards
Read .bmad/agents/pm-agent.md to understand your role.
Then follow the workflow in .bmad/tasks/analysis/gather-requirements.md.
Save all outputs as shards in .bmad/shards/.
Ask clarifying questions before proceeding.
---
# .claude/commands/bmad-architect.md
# Assume the Architect Agent role from .bmad/agents/architect-agent.md
# Design system architecture based on requirement shards
Read .bmad/agents/architect-agent.md to understand your role.
Read all shards in .bmad/shards/ that start with "requirements-".
Follow the workflow in .bmad/tasks/architecture/system-design.md.
Produce architecture shards and ADRs.
---
# .claude/commands/bmad-implement.md
# Assume the Developer Agent role from .bmad/agents/developer-agent.md
# Implement the next feature based on architecture shards
Read .bmad/agents/developer-agent.md to understand your role.
Read .bmad/shards/sprint-current.md to identify the next task.
Read the relevant API and architecture shards.
Follow the workflow in .bmad/tasks/implementation/feature-implementation.md.
Use TDD: write tests first, then implement.11. Practical Case: BMAD for a Booking API
To make the presented concepts concrete, let's see how BMAD is applied to building a real hotel booking API, from the analysis phase through to implementation of the first endpoint.
Analysis Phase: PM Agent Output
After invoking the PM Agent with the project brief, the following requirement shards are produced:
- project-overview.md: Context, problem, solution, and constraints
- personas-hotel-owner.md: Hotel owner profile
- personas-guest.md: Booking guest profile
- requirements-booking-crud.md: Booking CRUD requirements
- requirements-availability.md: Availability calculation requirements
- requirements-auth.md: Authentication/authorization requirements
- constraints-budget-timeline.md: Budget and timeline constraints
Architecture Phase: Architect Agent Output
The Architect Agent consumes the requirement shards and produces architectural decisions:
- architecture-overview.md: Layered modular architecture
- adr-001-modular-monolith.md: Decision to use a modular monolith
- adr-002-postgresql.md: PostgreSQL choice as database
- api-bookings.md: Complete booking API contract
- db-schema-bookings.md: Database schema for the bookings module
- security-model.md: JWT + RBAC for authentication
Implementation Phase: The Developer Agent at Work
The Developer Agent receives the api-bookings.md shard and follows the
TDD workflow to implement the first endpoint. The output is working code with
complete tests, produced iteratively through the development loop.
// src/bookings/booking.service.ts
// Generated by the Developer Agent following the api-bookings.md shard
import { Injectable, ConflictException, NotFoundException } from '@nestjs/common';
import { BookingRepository } from './booking.repository';
import { RoomService } from '../rooms/room.service';
import { CreateBookingDto, BookingResponse } from './booking.dto';
@Injectable()
export class BookingService {
constructor(
private readonly bookingRepo: BookingRepository,
private readonly roomService: RoomService,
) {}
/**
* Creates a new booking after verifying availability.
* @shard api-bookings.md - POST /api/v1/bookings
*/
async createBooking(
userId: string,
dto: CreateBookingDto,
): Promise<BookingResponse> {
// Verify room existence
const room = await this.roomService.findById(dto.roomId);
if (!room) {
throw new NotFoundException('Room not found');
}
// Verify availability for the period
const isAvailable = await this.roomService.checkAvailability(
dto.roomId,
dto.checkIn,
dto.checkOut,
);
if (!isAvailable) {
throw new ConflictException('Room not available for the requested period');
}
// Create booking
const booking = await this.bookingRepo.create({
userId,
roomId: dto.roomId,
checkIn: dto.checkIn,
checkOut: dto.checkOut,
guests: dto.guests,
notes: dto.notes,
status: 'CONFIRMED',
});
return this.toResponse(booking);
}
private toResponse(booking: any): BookingResponse {
return {
id: booking.id,
roomId: booking.roomId,
checkIn: booking.checkIn,
checkOut: booking.checkOut,
guests: booking.guests,
status: booking.status,
createdAt: booking.createdAt,
};
}
}Conclusion
The BMAD Method represents a mature and systematic approach to AI-assisted software development. Through Document Sharding, BMAD solves the fundamental problem of context overflow, allowing you to manage projects of any complexity without sacrificing the quality or coherence of documentation and implementation.
The true strength of BMAD lies in its adaptability: from Solo Dev mode for personal side projects to enterprise configuration with all 21 agents, the framework scales naturally with the project's needs. Combined with techniques like the Ralph Wiggum loop for autonomous implementation and hooks for automation, BMAD becomes the core of a complete and effective AI-driven development system.
Key Takeaways
- Document Sharding solves context overflow: Atomic, self-contained fragments enable managing complex projects
- 21 agents cover the entire cycle: From requirements analysis to deployment, every aspect has a dedicated agent
- 50+ workflows eliminate ambiguity: Structured sequences ensure completeness and reproducibility
- Scale-adaptive intelligence: The framework adapts from Nano to Large scale without over-engineering
- 4 iterative phases: Analysis, Planning, Architecture, and Implementation in a continuous cycle
- Complementary to agile methodologies: BMAD enhances Scrum and Kanban, it does not replace them
- Native integration with Claude Code: CLAUDE.md, slash commands, and hooks for a fluid workflow
In the next article we will explore Multi-Agent Orchestration: how to coordinate multiple Claude Code instances working simultaneously on different aspects of a project, managing synchronization, conflict resolution, and convergence toward a common goal.