Skip to content

bmad-context-engineering.md

Latest commit

 

History

History
212 lines (138 loc) · 7.08 KB

bmad-context-engineering.md

File metadata and controls

212 lines (138 loc) · 7.08 KB
Raw

BMAD-METHOD: Context Engineering for AI-Driven Development

Overview

The BMAD Method (Breakthrough Method for Agile AI Driven Development) is a comprehensive framework created by Brian (BMad) that transforms how developers work with AI programming assistants. Unlike traditional "vibe coding" where developers give AI a task and hope for the best, BMAD provides a structured approach that ensures AI agents have complete context throughout the development lifecycle.

The Context Problem

Traditional AI-assisted development suffers from two critical issues:

  1. Planning Inconsistency: AI-generated plans often lack depth and miss critical details
  2. Context Loss: As development progresses, AI loses track of previous decisions and architectural choices

BMAD solves both problems through:

  • Agentic Planning: Specialized AI agents collaborate to create comprehensive specifications
  • Context-Engineered Development: Every development task includes full context, preventing drift

Core Philosophy

"Where the BMad agile flow is different is you can choose to have more upfront planning and architecture specification to ensure the system is built in a sustainable way, not a vibe coded spaghetti mess."

The method elevates casual AI coding to professional software engineering by:

  • Maintaining architectural integrity across sessions
  • Preserving decision history in documented form
  • Ensuring each AI agent has the complete context needed for their specific role

The BMAD Workflow

Phase 1: Planning (Web Interface)

The journey begins in a web-based AI interface (Claude, Gemini, ChatGPT) where specialized planning agents collaborate with you:

The Analyst Agent

  • Role: Investigates and challenges assumptions
  • Output: Market research, feasibility analysis
  • Key Feature: Uses advanced elicitation techniques to uncover hidden requirements

The Product Manager Agent

  • Role: Transforms ideas into structured requirements
  • Output: Comprehensive PRD with epics and user stories
  • Key Feature: Creates stories with enough detail for autonomous implementation

The Architect Agent

  • Role: Designs technical solutions
  • Output: Architecture documents with technology decisions
  • Key Feature: Evaluates trade-offs and provides implementation guidance

Phase 2: Transition to IDE

"Once you have your PRD, Architecture, optional UX and Briefs - it's time to switch over to the IDE to shard your docs, and start implementing the actual code!"

This transition is critical because:

  • Planning documents become the source of truth
  • Context is preserved in markdown files
  • The development phase can reference complete specifications

Phase 3: Development Cycle (IDE)

Development follows a structured agent workflow:

The Scrum Master Agent

  • Primary Function: Transform plans into executable stories
  • Key Innovation: Creates self-contained story files with ALL necessary context
  • Process:
    1. Reads PRD and Architecture documents
    2. Identifies next logical story based on dependencies
    3. Extracts all relevant context into a single story file
    4. Validates completeness with built-in checklists

The Developer Agent

  • Primary Function: Implement one story at a time
  • Key Innovation: Never needs to ask for clarification
  • Process:
    1. Receives complete story file from Scrum Master
    2. Has all architectural decisions embedded
    3. Implements with full awareness of system context
    4. Updates story status upon completion

The QA Agent

  • Primary Function: Ensure quality standards
  • Key Innovation: Tests with full context awareness
  • Process:
    1. Reviews implementation against original requirements
    2. Validates architectural compliance
    3. Ensures testing requirements are met

Context Engineering Techniques

1. Document-Driven Development

  • All decisions captured in markdown
  • Version controlled alongside code
  • Agents reference documents, not memory

2. Story File Architecture

Each story file contains:

  • Complete feature requirements
  • Relevant architectural context
  • Technical implementation details
  • Testing criteria
  • Acceptance conditions

3. Agent Specialization

  • Each agent has deep domain expertise
  • Agents communicate through artifacts, not conversation
  • Role boundaries prevent context confusion

4. Progressive Enhancement

  • Start with high-level planning
  • Progressively add detail through agent collaboration
  • Each phase builds on previous artifacts

Implementation Guide

Getting Started

  1. Clone the BMAD repository:

    git clone https://github.com/bmadcode/BMAD-METHOD.git

  2. Copy agent files to your project:

    cp -r BMAD-METHOD/bmad-agent your-project/

  3. Configure your IDE:

    • Set up custom agent modes
    • Point to PRD and Architecture in /docs
    • Stories will be generated in /docs/template-development/stories

Web Agent Setup

For planning phases, use the BMAD Orchestrator:

  • Upload web-bmad-orchestrator-agent.md as instructions
  • Attach knowledge files from web-build-sample
  • Use /help to see available commands
  • Use /agents to switch between personas

IDE Agent Configuration

For development phases:

  • Cursor: Use custom agent mode with .ide.md files
  • Claude Code: Type /agent-name to activate agents
  • Windsurf: Optimized for <6K character limits

Advanced Features

The Orchestrator

  • Master agent that can become any specialized role
  • Maintains context across persona switches
  • Ideal for smaller teams or solo developers

Expansion Packs

  • Domain-specific agents (game dev, DevOps, etc.)
  • Custom templates for your industry
  • Community-contributed enhancements

Multi-Session Continuity

  • "Continue BMAD planning" picks up where you left off
  • Session state preserved in documents
  • No context loss between work sessions

Benefits Over Traditional Approaches

Versus Task-Based Systems

  • Traditional: Generate task list → Execute blindly
  • BMAD: Deep planning → Contextual execution → Sustainable architecture

Versus Pure Vibe Coding

  • Traditional: Quick prototype → Technical debt → Refactor nightmare
  • BMAD: Thoughtful design → Clean implementation → Maintainable system

Versus Manual Documentation

  • Traditional: Docs drift from code → Become outdated
  • BMAD: Docs drive development → Stay synchronized

Community and Resources

  • GitHub: https://github.com/bmadcode/BMAD-METHOD (2000+ stars)
  • YouTube: BMad Code channel for tutorials and updates
  • Discord: Active community for support and collaboration
  • Creator: Brian (bmadcode) - 20+ year software engineering veteran

Conclusion

The BMAD Method represents a paradigm shift in AI-assisted development. By solving the context problem through specialized agents and comprehensive documentation, it enables developers to build complex applications with AI assistants while maintaining architectural integrity and code quality.

The key insight: AI agents are incredibly capable when given proper context. BMAD ensures they always have it.