264 lines
7.1 KiB
Markdown
264 lines
7.1 KiB
Markdown
# 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](https://claude.ai/code))
|
|
- Existing BMAD-Method project
|
|
|
|
### 2. Generate Claude Subagents
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
1. Create agent definition in `bmad-core/agents/new-agent.md`
|
|
2. Add agent ID to `integration/claude/src/build-claude.js`
|
|
3. 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
|
|
|
|
```yaml
|
|
# .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
|
|
```bash
|
|
# Rebuild agents
|
|
npm run build:claude
|
|
|
|
# Verify generation
|
|
ls .claude/agents/
|
|
```
|
|
|
|
### Memory Issues
|
|
```bash
|
|
# 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](https://discord.gg/gk8jAdXWmj)
|
|
- **Issues**: [GitHub Issues](https://github.com/24601/BMAD-AT-CLAUDE/issues)
|
|
- **Claude Code Docs**: [docs.anthropic.com/claude-code](https://docs.anthropic.com/en/docs/claude-code/overview)
|