7.1 KiB

Raw Blame History

BMAD-Method Claude Code Integration

This document describes the Claude Code subagents integration for BMAD-Method, allowing you to use BMAD's specialized agents within Claude Code's new subagent system.

Overview

The Claude Code integration transforms BMAD's collaborative agent framework into Claude Code subagents while maintaining clean separation from the original codebase. This enables:

Native Claude Code Experience: Use BMAD agents directly within Claude Code
Context Management: Each agent maintains its own context window
Tool Integration: Leverage Claude Code's built-in tools (Read, Grep, codebase_search, etc.)
Workflow Preservation: Maintain BMAD's proven agent collaboration patterns

Quick Setup

1. Prerequisites

Node.js 20+
Claude Code installed (claude.ai/code)
Existing BMAD-Method project

2. Generate Claude Subagents

# From your BMAD project root
npm run build:claude

This creates .claude/agents/ with six specialized subagents:

Analyst (Mary) - Market research, competitive analysis, project briefs
Architect - System design, technical architecture
PM - Project management, planning, coordination
Dev - Development, implementation, coding
QA - Quality assurance, testing, validation
Scrum Master - Agile process management

3. Start Claude Code

# In your project root (where .claude/ directory exists)
claude

Usage Patterns

Explicit Agent Invocation

Request specific agents for specialized tasks:

# Market research and analysis
> Use the analyst subagent to help me create a competitive analysis

# Architecture planning  
> Ask the architect subagent to design a microservices architecture

# Implementation
> Have the dev subagent implement the user authentication system

# Quality assurance
> Use the qa subagent to create comprehensive test cases

Automatic Agent Selection

Claude Code automatically selects appropriate agents based on context:

# Analyst will likely be chosen
> I need to research the market for AI-powered project management tools

# Architect will likely be chosen  
> How should I structure the database schema for this multi-tenant SaaS?

# Dev will likely be chosen
> Implement the JWT authentication middleware

Agent Capabilities

Analyst (Mary) 📊

Market research and competitive analysis
Project briefs and discovery documentation
Brainstorming and ideation facilitation
Strategic analysis and insights

Key Commands: create-project-brief, perform-market-research, create-competitor-analysis, brainstorm

Architect 🏗️

System architecture and design
Technical solution planning
Integration patterns and approaches
Scalability and performance considerations

PM 📋

Project planning and coordination
Stakeholder management
Risk assessment and mitigation
Resource allocation and timeline management

Dev 👨‍💻

Code implementation and development
Technical problem solving
Code review and optimization
Integration and deployment

QA 🔍

Test planning and execution
Quality assurance processes
Bug identification and validation
Acceptance criteria definition

Scrum Master 🎯

Sprint planning and management
Agile process facilitation
Team coordination and communication
Impediment resolution

Workflow Integration

BMAD Story-Driven Development

Agents can access and work with BMAD story files:

> Use the dev subagent to implement the user story in stories/user-auth.story.md

Task and Template Access

Agents can read BMAD dependencies:

> Have the analyst use the project-brief template to document our new feature

Cross-Agent Collaboration

Chain agents for complex workflows:

> First use the analyst to research the market, then have the architect design the solution, and finally ask the pm to create a project plan

Technical Architecture

Directory Structure

./
├── bmad-core/           # Original BMAD (untouched)
├── integration/claude/  # Claude integration source
└── .claude/            # Generated Claude subagents
    ├── agents/         # Subagent definitions
    │   ├── analyst.md
    │   ├── architect.md
    │   └── ...
    └── memory/         # Agent context memory

Context Management

Lightweight Start: Each agent begins with minimal context (~2-4KB)
On-Demand Loading: Agents use tools to read files when needed
Memory Files: Rolling memory maintains conversation context
Tool Integration: Access BMAD files via Read, Grep, codebase_search

Tool Permissions

Each agent has access to:

Read - File reading and content access
Grep - Text search within files
glob - File pattern matching
codebase_search_agent - Semantic code search
list_directory - Directory exploration

Advanced Usage

Custom Agent Development

To add new agents:

Create agent definition in bmad-core/agents/new-agent.md
Add agent ID to integration/claude/src/build-claude.js
Rebuild: npm run build:claude

Memory Management

Agents maintain context in .claude/memory/{agent}.md:

Automatically created on first use
Stores key decisions and context
Truncated when exceeding limits
Can be manually edited if needed

Integration with CI/CD

# .github/workflows/claude-agents.yml
name: Update Claude Agents
on:
  push:
    paths: ['bmad-core/agents/**']
jobs:
  build-claude:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm run build:claude
      - # Commit updated .claude/ directory

Best Practices

Agent Selection

Analyst: Early project phases, research, market analysis
Architect: System design, technical planning, solution architecture
PM: Project coordination, planning, stakeholder management
Dev: Implementation, coding, technical execution
QA: Testing, validation, quality assurance
Scrum Master: Process management, team coordination

Context Optimization

Start conversations with clear agent requests
Reference specific BMAD files by path when needed
Use agent memory files for important decisions
Keep agent contexts focused on their specialization

Workflow Efficiency

Use explicit agent invocation for specialized tasks
Chain agents for multi-phase work
Leverage BMAD story files for development context
Maintain conversation history in agent memory

Troubleshooting

Agent Not Found

# Rebuild agents
npm run build:claude

# Verify generation
ls .claude/agents/

Memory Issues

# Clear agent memory
rm .claude/memory/*.md

Context Problems

Keep agent prompts focused
Use tools to load files on-demand
Reference specific sections rather than entire documents

Support

BMAD Community: Discord
Issues: GitHub Issues
Claude Code Docs: docs.anthropic.com/claude-code

7.1 KiB Raw Blame History