BMAD com Claude Code: Tutorial Completo 2026

Claude Code e o ambiente onde o BMAD brilha mais. Sem distracao de GUI, com acesso direto ao filesystem e a capacidade de criar, editar e executar arquivos sem sair do terminal. Parece pouco, mas essa diferenca de ambiente muda completamente a qualidade do que o agente consegue entregar.

Neste tutorial vou mostrar como configurar o BMAD no Claude Code do zero, criar a estrutura de agentes, e desenvolver um SaaS real com o metodo. Se ainda nao conhece o BMAD em detalhes, recomendo ler primeiro o artigo sobre agile coding com IA que explica a metodologia completa.

Por que Claude Code e ideal para BMAD

Vantagens do terminal sobre GUI

A diferenca principal e controle. No terminal com Claude Code, voce ve exatamente o que o agente esta fazendo: quais arquivos ele esta lendo, quais esta editando, quais comandos esta executando. Na GUI de IDEs como Cursor, parte desse processo fica escondido em abstractions que parecem convenientes mas dificultam o debug quando algo da errado.

Outra vantagem: o Claude Code tem janela de contexto grande e consistente. Com o Claude 3.5 Sonnet ou Claude 3 Opus via API, voce tem 200k tokens de contexto. Isso significa que o agente pode ler todos os documentos do projeto, o codigo atual, e o historico de decisoes sem perder informacao.

CLAUDE.md como base dos agentes

O CLAUDE.md e um arquivo especial que o Claude Code le automaticamente quando voce inicia uma sessao em um repositorio. E o equivalente ao system prompt persistente do projeto. No contexto do BMAD, o CLAUDE.md e onde voce registra qual agente esta ativo, quais sao as convencoes do projeto e onde estao os documentos de contexto.

A sacada e que o CLAUDE.md pode referenciar outros arquivos. Entao em vez de colocar o prompt completo de cada agente no CLAUDE.md, voce mantém o arquivo principal enxuto e referencia arquivos em /agents/. Isso facilita a manutencao e permite que voce evoluia os prompts sem baguncar o arquivo principal.

Instalacao e configuracao

# Estrutura de diretorios do projeto BMAD
mkdir -p meu-saas/{docs,agents,src}
cd meu-saas
git init

# Criar arquivos de prompt dos agentes
touch agents/po.md
touch agents/arch.md
touch agents/dev.md
touch agents/qa.md

# Criar documentos de contexto (serao preenchidos pelos agentes)
touch docs/prd.md
touch docs/tech-spec.md
touch docs/dev-log.md
touch docs/qa-report.md

# Criar CLAUDE.md
touch CLAUDE.md

# Iniciar Claude Code
claude

Criando o workflow BMAD no Claude Code

Estrutura de diretorios

A estrutura de diretorios nao e arbitraria. Ela reflete a separacao de responsabilidades dos agentes e facilita o gerenciamento de contexto. Cada agente sabe exatamente onde buscar informacao e onde depositar seus outputs.

meu-saas/
├── CLAUDE.md              # Configuracao dos agentes
├── agents/
│   ├── po.md              # Prompt do Product Owner
│   ├── arch.md            # Prompt do Arquiteto
│   ├── dev.md             # Prompt do Desenvolvedor
│   └── qa.md              # Prompt do QA
├── docs/
│   ├── prd.md             # Output do PO
│   ├── tech-spec.md       # Output do Arquiteto
│   ├── dev-log.md         # Log do Desenvolvedor
│   └── qa-report.md       # Relatorio do QA
└── src/
    ├── app/               # Codigo da aplicacao
    ├── lib/               # Utilitarios compartilhados
    └── tests/             # Testes

Configurando personas via markdown

O CLAUDE.md principal deve ser enxuto e funcionar como um menu de agentes. Os detalhes de cada persona ficam nos arquivos separados em /agents/.

# Projeto: [Nome do Projeto]

## BMAD Workflow
Este projeto usa o metodo BMAD. Sempre pergunte qual agente deve ser ativado antes de comecar.

## Ativar agentes
Quando o usuario digitar um dos comandos abaixo, leia o arquivo correspondente e adote aquela persona completamente:

- `/po` → leia agents/po.md e aja como Product Owner
- `/arch` → leia agents/arch.md e aja como Arquiteto
- `/dev` → leia agents/dev.md e aja como Desenvolvedor
- `/qa` → leia agents/qa.md e aja como QA Engineer

## Contexto do projeto
Sempre leia os documentos abaixo antes de iniciar qualquer tarefa:
- docs/prd.md (se existir)
- docs/tech-spec.md (se existir)

## Regras gerais
- Commits atomicos, um por feature
- Testes obrigatorios para logica de negocio
- Zero TODO no codigo — ou implementa ou cria uma issue

Projeto pratico: SaaS do zero com BMAD + Claude Code

Vamos construir um SaaS de gestao de projetos simplificado. Nada complexo demais, mas com o suficiente para mostrar o BMAD em acao: autenticacao, criacao de projetos, tarefas e um dashboard basico.

Sprint 1: Discovery

Voce abre o Claude Code no repositorio e digita: '/po Preciso de um SaaS para pequenas equipes gerenciarem projetos. Usuarios podem criar projetos, adicionar tarefas, atribuir membros e acompanhar progresso.'

O agente PO vai fazer perguntas antes de sair escrevendo: Quantos membros por equipe? Tem integracao com outras ferramentas? Qual e o modelo de cobranca? Essas perguntas sao o que diferencia um bom agente PO de um que aceita qualquer coisa. Depois de voce responder, ele produz o PRD em /docs/prd.md com user stories priorizadas e criterios de aceite.

Sprint 2: Arquitetura

Com o PRD aprovado, voce ativa o Arquiteto: '/arch'. Ele le o PRD e produz o Tech Spec. No caso do nosso SaaS, ele vai propor algo como: Next.js 16 com App Router, Convex como banco de dados reativo, Clerk para autenticacao, Stripe para pagamentos. Cada decisao com justificativa.

O Tech Spec tambem define a estrutura de componentes, os padroes de nomenclatura e as fronteiras entre modulos. Quando o agente Dev comecar a codar, ele tem esse documento como referencia — sem precisar inventar padrao.

Sprint 3: Implementacao

Ativa o Dev: '/dev Implemente a autenticacao conforme o Tech Spec.' O agente le os documentos, configura o Clerk, cria as rotas de login e callback, integra com o Convex para armazenar o perfil do usuario. Tudo seguindo os padroes definidos pelo Arquiteto.

Depois de cada feature, voce ativa o QA: '/qa Revise a implementacao de autenticacao.' O agente olha o codigo, verifica os criterios de aceite do PRD e reporta o que encontrou. Em geral, ele encontra pelo menos dois ou tres casos que o Dev nao cobriu.

Dicas avancadas e troubleshooting

Depois de usar BMAD em varios projetos, aqui estao os problemas mais comuns e como resolver:

Um truque que economiza muito token: faca o agente PO produzir o PRD em formato extremamente conciso. Stories longas e detalhadas sao mais dificeis de seguir do que stories curtas com criterios de aceite objetivos. O Arquiteto e o Dev vao pedir clarificacao se precisarem de mais detalhe.

Para aprofundar em tecnicas de prompt que melhoram a qualidade do codigo gerado pelos agentes, confira o artigo sobre templates de prompt engineering para coding.

Quanto custa usar BMAD com Claude Code

Transparencia total aqui porque todo mundo pergunta. Em um projeto SaaS de complexidade media (autenticacao, CRUD, pagamentos, dashboard), o custo de tokens para um sprint de uma semana com BMAD fica em torno de $20 a $40 usando Claude Sonnet. Se usar Claude Haiku para os agentes PO e QA e so o Sonnet para o Dev, da pra cair para $12-25.

Comparando com o Cursor Pro que custa $20/mes com requests limitados, ou com um freelancer que cobra $50-100/hora, o custo do BMAD com Claude Code e extremamente competitivo. A diferenca e que no BMAD voce esta comprando capacidade de desenvolvimento, nao uma assinatura de editor.

Conclusao

BMAD com Claude Code e atualmente a combinacao mais poderosa para desenvolvedores que querem usar IA de forma estruturada. O terminal da controle, o CLAUDE.md da persistencia, e a metodologia de agentes da qualidade.

O investimento de configurar os agentes e o CLAUDE.md no inicio do projeto paga rapido. A partir do segundo sprint, o fluxo e fluido e o codigo que sai tende a ser muito mais consistente do que qualquer abordagem sem estrutura.

Se voce quer entender a visao macro por tras do BMAD e como o AI coding mudou o desenvolvimento em 2025-2026, volte para o artigo hub sobre agile coding com IA. Ele tem o contexto historico e estrategico que faz tudo isso fazer sentido.