Para que serve e onde aplicar

O BMAD ajuda você a decidir o que construir, registrar as escolhas e conduzir o trabalho até a revisão. Ele também serve para pensar e planejar sem chegar a escrever código — o texto de instruções que faz um site ou sistema funcionar. Você pode usar só essa parte do método.

As seis razões abaixo vêm do material oficial. Os exemplos de negócio são fictícios e foram escritos para esta aula; não são projetos executados ou resultados medidos.

Escolha pelo tamanho da mudança que você quer fazer. O nome do produto, sozinho, não resolve: um site pode precisar de uma correção de texto ou de uma área inteira de atendimento. O critério oficial combina tamanho, clareza e risco.

A intenção já está bem definida? Você consegue dizer o que deve ser verdade quando o trabalho terminar, o que precisa continuar como está e o que fica de fora? Essa é a pergunta central do planejamento no BMAD. Uma intenção completa permite preparar o acordo escrito sobre a construção; se faltam decisões, primeiro você esclarece o que falta.

No aplicativo de agendamento, “quero organizar melhor os horários” ainda deixa muita coisa aberta. Uma intenção mais clara seria: “O cliente escolhe um horário livre, recebe a confirmação e pode cancelar até a véspera. A duração dos serviços continua igual. Cobrança on-line fica fora desta entrega.” Este é um exemplo de decisão de negócio, não uma descrição técnica pronta para qualquer aplicativo.

Antes da tabela, conheça os nomes que aparecem no caminho:

• Skill é um conjunto de instruções do BMAD identificado por um nome, que a ferramenta de IA carrega para executar uma tarefa, conduzir um trabalho ou assumir um papel.
• Sessão de construção é uma rodada de trabalho voltada a um objetivo. Não significa um prazo fixo em minutos ou horas.
• Spec, ou especificação, é o documento que registra o acordo sobre o que será construído.
• Épico é um resultado completo que exige várias sessões de construção.
• Story é uma parte do trabalho, pequena o suficiente para ser construída em uma sessão. Um épico pode ser dividido em várias stories.

Os quatro tamanhos

Esses exemplos pressupõem as condições descritas. O campo do formulário pode deixar de ser pequeno se também mudar contratos com outros sistemas. As 500 linhas e as 20 sessões são referências aproximadas, não limites rígidos, estimativas de preço ou promessas de prazo. Você não precisa saber contar linhas para começar: bmad-help orienta quando houver dúvida.

Risco também pesa. Uma alteração curta que muda cobranças, acessos ou informações usadas por outras áreas pode exigir mais planejamento. O caminho deve considerar o impacto, as regras ainda pouco claras e a coordenação entre pessoas.

Siga as decisões de cima para baixo. No desenho, “muitas sessões” retoma a referência aproximada de 20 ou mais. Uma mudança pequena pode entrar diretamente em bmad-build; a checagem de intenção aparece antes do planejamento do trabalho maior, como orienta a fonte.

Para simular a escolha, volte ao agendamento de uma unidade. Ele muda o funcionamento do negócio, então não é edição trivial. Suponha que reservar e cancelar exijam várias sessões, mas ainda formem um resultado único: a primeira versão da agenda. Com as regras definidas, o caminho é épico → bmad-spec → divisão em stories com você → bmad-build por story → conferência conjunta → bmad-retrospective. Se você acrescentar gestão de várias unidades, cobrança e relatórios independentes, reavalie o tamanho como projeto. Esta é uma aplicação didática dos critérios da fonte de planejamento (abre em nova aba), não uma medição de um aplicativo construído.

O que foi conferido: os caminhos, os limites aproximados e os nomes das skills foram conferidos na documentação da 6.12.4 e nos arquivos da instalação local. As skills e os exemplos desta aula não foram executados. Não há saída de execução simulada.

O que acontece no caminho de uma sessão

Entrar por bmad-build não exige que você escreva uma spec antes. A skill aceita uma descrição da mudança, um arquivo ou uma story já planejada. Primeiro examina o projeto e os documentos disponíveis. A orientação oficial é começar em uma conversa nova, para não misturar o contexto de outro trabalho.

Depois dessa investigação, o caminho se divide. Quando o desenho da mudança não deixa lacunas importantes na intenção, ações irreversíveis ou uma extensão de alterações que exija mais cuidado, a skill segue o caminho leve: registra uma especificação mínima, implementa e revisa na mesma sessão. Quando identifica algum desses pontos, prepara um plano escrito mais completo. As decisões ainda abertas precisam ser resolvidas antes da aprovação. Portanto, “uma sessão” não significa “nenhuma decisão sua”.

No exemplo do campo “Empresa”, reutilizar o formulário existente pode caber no caminho leve. Se a investigação mostrar que esse campo muda quem pode ver os dados de clientes, a decisão deixou de ser apenas visual. O exemplo ilustra os critérios de risco; não antecipa qual caminho a skill escolheria em um sistema real.

Ao implementar, a skill revisa a mudança com revisores independentes e corrige os problemas que pertencem a ela. Questões anteriores e sem relação com o pedido ficam separadas para trabalho futuro em deferred-work.md. Você ainda confere o resultado. Se o código não corresponder ao objetivo, o processo pode voltar ao plano ou à intenção, em vez de acumular correções sobre uma decisão errada. Essa é a conduta descrita pela fonte; não é uma garantia de ausência de defeitos.

Como conduzir um épico sem perder o conjunto

O épico pede decisões antes, durante e depois das stories. O caminho documentado tem estes cuidados:

1. Registrar o acordo. Leve a intenção definida a bmad-spec. A spec registra por que fazer, o que o produto deve permitir, as restrições, o que fica de fora e como reconhecer o sucesso. No agendamento, “não permitir duas reservas no mesmo horário” precisa aparecer como regra verificável.
2. Dividir com você. O recurso Story Breakdown, ou divisão em stories, propõe partes que podem ser conferidas separadamente. Você revê a ordem e decide quais precisam de uma parada para avaliar o plano, o resultado ou ambos. A saída é stories.yaml, ao lado de SPEC.md.
3. Dar atenção às primeiras decisões. Stories importantes, arriscadas ou que estabelecem o padrão das próximas devem passar por bmad-build com sua participação. Na agenda, a maneira de impedir horários duplicados pode afetar várias entregas posteriores. O exemplo é didático; a regra sobre stories que estabelecem padrões vem de “Establish the implementation pattern”.
4. Rever a divisão quando aprender algo. A lista é um plano de execução, não uma promessa de que nada mudará. Se surgir uma restrição esquecida ou uma dependência entre stories, atualize a spec por bmad-spec e solicite novamente a divisão quando necessário. Atualizar SPEC.md não reescreve automaticamente stories.yaml.
5. Conferir a entrega integrada. Reservar pode funcionar sozinho e cancelar também, mas cancelar precisa liberar o horário para uma nova reserva. Este exemplo explica por que conferir cada parte não basta. A documentação pede verificação conjunta e depois bmad-retrospective com a pasta da spec.

A divisão em stories tem uma condição importante. Na 6.12.4, bmad-spec só executa Story Breakdown no modo interativo, isto é, em conversa com a pessoa. No modo headless, uma execução sem essa interação, ela pula a divisão mesmo quando o pedido menciona stories. A skill também pode identificar esse modo quando outro programa a chama, ou quando recebe todos os dados e um pedido para apenas devolver o caminho do artefato. Para obter stories.yaml por esse recurso, use a conversa interativa. O comportamento foi conferido nas instruções instaladas e no código oficial; não foi testado em uma execução da skill.

As paradas de conferência registradas na lista precisam ser respeitadas por quem coordena e inicia as stories. O arquivo não executa esse acompanhamento sozinho, e a skill de construção não lê por conta própria os campos que definem essas paradas. Se você delegar a coordenação, inclua essa responsabilidade no Pedido, o texto para colar no chat do Claude Code, a ferramenta de IA usada neste guia para trabalhar no projeto.

No fechamento, bmad-retrospective lê os documentos e registros do que foi construído. Ela apresenta um veredito: accepted significa aceito; accepted-with-open-items, aceito com pendências; rejected, rejeitado. No caminho da spec, o relatório fica em RETROSPECTIVE.md, dentro da mesma pasta. A skill propõe ações e você decide o que executar. O relatório não aplica sozinho as correções de código ou as mudanças na spec.

O que se acrescenta quando vira projeto

Num projeto com vários épicos, cada parte precisa seguir decisões comuns. Compras e estoque, por exemplo, precisam concordar sobre o significado de um produto e sobre quando uma compra altera a quantidade disponível. A fonte pede planejamento proporcional ao risco de decisões incompatíveis. Arquitetura é o conjunto de decisões técnicas que mantém as partes coerentes. Uma alteração local que segue padrões já estabelecidos normalmente dispensa um novo trabalho de arquitetura; partes construídas separadamente precisam de decisões compartilhadas quando poderiam escolher caminhos conflitantes.

Há duas formas documentadas de organizar e acompanhar as partes. Na tabela, PRD significa documento de requisitos do produto: o acordo sobre o que construir e por quê. Sprint, neste contexto, é o termo mantido pelo BMAD para o acompanhamento das entregas; o nome do arquivo não fixa um prazo em dias.

Os arquivos e caminhos foram conferidos por leitura, sem execução.

As duas formas mantêm a mesma regra: construir uma unidade de cada vez com bmad-build. O projeto acrescenta coordenação. Não crie dois controles concorrentes para o mesmo épico sem saber qual caminho está usando. A página de planejamento manda usar bmad-spec por épico; a página de acompanhamento distingue o épico organizado por spec do projeto acompanhado por sprint. Use os documentos reais do projeto para decidir, com a orientação de bmad-help quando faltar clareza.

Em bmad-sprint-planning, PASS indica que o plano passou pela avaliação; CONCERNS apresenta ressalvas para você decidir se prossegue; FAIL interrompe a passagem e lista os problemas. Faltar um tipo de documento só é problema quando as stories dependem de decisões que deveriam estar nele. Interface é o conjunto de telas e controles que as pessoas usam para interagir com o produto. Um trabalho sem interface de uso, por exemplo, não precisa de um documento visual apenas para preencher uma lista.

Essa skill também tem caminhos para consultar o andamento, verificar se o arquivo de acompanhamento está válido e reparar um arquivo que deixou de refletir a realidade. A reparação mostra uma proposta de estados antes de escrever e exige confirmação. Consultar o andamento não fornece estimativas de prazo: mostra estados, riscos e a próxima ação recomendada.

Épicos independentes podem avançar em paralelo quando as dependências e os pontos de integração estão explícitos. Cada frente precisa de um responsável, e todas devem respeitar o mesmo objetivo de produto e as mesmas decisões de arquitetura. O paralelo não elimina a conferência conjunta nem a retrospectiva de cada épico.

Quando o plano muda ou a execução pode ser automática

Se uma mudança ultrapassar uma story — uma regra de negócio estava errada ou uma decisão de arquitetura precisa mudar —, bmad-correct-course avalia o impacto e propõe a nova organização do trabalho. Depois de aplicar a proposta, refaça a divisão ou o acompanhamento dos épicos afetados. Trabalho concluído não deve virar pendente só porque o plano foi atualizado.

Quando as decisões importantes e os padrões de implementação já estiverem estáveis, existe bmad-build-auto. Ela constrói e revisa uma unidade sem esperar respostas durante a execução. Não escolhe a próxima story, não percorre sozinha toda a lista e não faz a retrospectiva do épico. Alguém ou uma ferramenta de coordenação precisa selecionar a unidade e examinar o resultado.

A execução automática depende de subagentes, assistentes auxiliares que fazem partes do trabalho, como as revisões. Sem esse recurso, a skill registra um bloqueio. Também pode bloquear quando falta uma decisão indispensável ou a verificação falha. blocked significa bloqueado; não significa entrega concluída. É preciso ler o registro e resolver a causa. Este é um caminho avançado, apenas apresentado aqui e não testado nesta aula. O módulo opcional BMad Loop, que pode coordenar execuções, permanece fora do guia.

Você não precisa usar todas as skills. Escolha a que resolve a lacuna de agora. As ferramentas de planejamento são independentes; a fonte oficial não exige uma sequência única para todos os projetos.

Três termos ajudam a ler a tabela:

• Briefing é um resumo do produto e do problema que ele resolve. No exemplo da agenda, explica para quem o serviço existe e por que organizar os horários é importante.
• PRD, do inglês Product Requirements Document, é o documento de requisitos do produto. Registra o que as pessoas envolvidas precisam acordar. Na agenda, detalha as capacidades que a entrega deve oferecer e as regras que precisam ser respeitadas.
• UX, do inglês User Experience, significa experiência de uso: como alguém encontra informações e realiza tarefas no produto. Na agenda, inclui o percurso entre escolher um serviço e receber a confirmação.

Nos caminhos maiores, bmad-spec transforma uma intenção já definida em um acordo de construção. Ela não substitui a decisão sobre o que você quer. Um PRD não é obrigatório só porque o produto parece grande: prepare os documentos que faltam para esclarecer e compartilhar as decisões.

Se a ideia ainda não está firme

Gerar possibilidades, testar uma proposta e pesquisar uma decisão são necessidades diferentes. Elas não formam uma sequência obrigatória. Se você já sabe o que quer, pode pular a exploração de ideias. Se ainda não sabe, escrever documentos posteriores sem esclarecer a ideia apenas carrega a mesma dúvida adiante.

Em bmad-brainstorming, você escolhe como quer participar. No papel de facilitador, o assistente conduz técnicas e perguntas, mas as ideias vêm de você. No papel de parceiro criativo, também oferece ideias. Na opção Ideate for me, ou “gere ideias para mim”, conduz a sessão e apresenta o resultado. Depois da exploração, você pode pedir para priorizar as possibilidades. Isso ajuda, por exemplo, quando uma empresa sabe que perde reservas, mas ainda não escolheu entre lembretes, confirmação antecipada ou mudança na política de cancelamento. O exemplo é fictício.

Em bmad-forge-idea, você já tem uma proposta e quer esclarecê-la, testar se ela se sustenta ou melhorá-la. A sessão pode terminar com a ideia suficientemente definida, com a ideia descartada ou apenas com um entendimento melhor. Só o primeiro resultado gera o documento de passagem forged-idea.md; o relatório forge-report.html é previsto em todas as execuções. Descartar uma proposta fraca também é um resultado útil. “Testar a ideia” aqui significa examinar a consistência e as decisões; não promete comprovar demanda ou vendas no mundo real.

Se o que falta é evidência, bmad-deep-recon tem três modalidades. Draft prepara um Pedido de pesquisa para você levar a outra ferramenta; essa modalidade sozinha não entrega a pesquisa concluída. Process recebe um relatório pronto, verifica suas afirmações conforme o tipo de pesquisa e organiza a síntese. Run faz a pesquisa na própria sessão, após a aprovação do plano. A pesquisa concluída ou processada gera research.md, com fontes. Você também pode começar com Draft, trazer o resultado por Process e pesquisar apenas as lacunas restantes. A operação nas ferramentas externas não foi testada nesta aula.

Se você precisa escrever ou questionar a proposta

bmad-product-brief ajuda a registrar a visão quando o conceito já está relativamente claro. bmad-prfaq oferece outro caminho: PRFAQ combina Press Release e Frequently Asked Questions, isto é, um comunicado de lançamento e perguntas frequentes. Você descreve o benefício do produto como se ele já estivesse pronto e enfrenta perguntas de clientes e das pessoas responsáveis por viabilidade e execução. Na agenda, isso obriga a explicar qual dificuldade do cliente realmente será resolvida.

Briefing e PRFAQ podem alimentar um PRD, e o resumo do PRFAQ pode seguir diretamente para bmad-spec quando o PRD não for necessário. Nenhum desses documentos precisa existir antes de começar bmad-prd; a skill aceita a explicação inicial do produto. Uma lista curta de decisões também pode bastar para definir a intenção.

Em bmad-prd, deixe claro se quer criar, atualizar ou validar. Criar conduz a descoberta e escreve o documento. Atualizar confronta uma mudança com as decisões anteriores. Validar examina o que já existe e produz um relatório, sem alterar o PRD. Na criação orientada, há ainda duas entradas: começar pelas capacidades do produto, útil para ferramentas internas, ou pelos percursos das pessoas, útil quando diferentes públicos participam do serviço.

Briefing, PRD e UX oferecem um caminho rápido e um caminho orientado. No rápido, o assistente reúne lacunas e redige o documento, marcando suposições com [ASSUMPTION] para você corrigir. No orientado, aprofunda as decisões por partes. As sessões podem ser pausadas e retomadas. Escolher rapidez não transforma suposição em fato: leia as marcações antes de tratar o documento como uma decisão do negócio.

Se faltam decisões de experiência ou de arquitetura

Use bmad-ux quando a aparência e o comportamento da interface influenciam o resultado. Ela separa o registro visual, DESIGN.md, do registro de funcionamento, EXPERIENCE.md. Também permite um caminho de preparação para outra ferramenta de design, com a posterior incorporação do que ela produzir. Esse uso externo não foi testado. Você pode pular um novo trabalho de UX quando a mudança não tem interface ou apenas segue padrões já definidos no produto.

Use bmad-architecture quando partes construídas separadamente precisam respeitar escolhas técnicas comuns. Ela pode partir de uma ideia, de uma spec, de um documento anterior ou do código existente. O caminho orientado apresenta alternativas para você decidir; o rápido prepara o documento e marca suposições. Numa mudança pequena e local, com padrões já estabelecidos, normalmente não é necessário produzir uma nova arquitetura. Num projeto com vários épicos, registre as decisões que evitam incompatibilidades entre as partes.

PRD, UX e arquitetura podem alimentar a mesma spec em ordens diferentes. Antes de passar pesquisas extensas e várias conversas a bmad-spec, consolide as decisões relevantes: o objetivo é entregar uma intenção compreensível, não uma pilha de material sem conclusão. Se o material for insuficiente, a skill pode oferecer um rascunho com questões abertas ou percorrer os campos com você. Se for vago demais para produzir um acordo útil, ela encaminha para a descoberta de requisitos.

Nesta aula, os nomes identificam as portas de entrada; não são uma sequência para executar agora. Nas aulas de aplicação, Pedido é o texto para colar no chat do Claude Code, a ferramenta de IA usada neste guia para trabalhar no projeto. Comando é a linha para o terminal, a janela que recebe instruções escritas para o computador. O uso do BMAD dentro de ferramentas como o Claude Code está descrito em docs/index.md (abre em nova aba).

Você pode usar o BMAD para uma única necessidade e parar quando tiver o resultado: pensar, documentar, construir ou revisar. As ferramentas de planejamento são independentes, e uma mudança pequena pode entrar diretamente pela construção. Não é preciso percorrer todos os caminhos.

A tabela é um panorama das onze ramificações. O passo a passo completo de cada uma, com situações de negócio, entradas, Pedidos de exemplo, condições das saídas e próximos destinos, está na Aula 08 — “Usar só uma parte do BMAD”. O brainstorm e o módulo opcional CIS são aprofundados na Aula 07 — “Brainstorm e criatividade: o módulo CIS”. As saídas abaixo são previstas nas instruções; nenhuma skill foi executada para produzir este panorama.

Ideias geradas, opiniões de personas e hipóteses organizadas não comprovam demanda nem substituem evidências do negócio. Você pode encerrar com o material útil para a decisão de hoje; só escolha outro ramo quando surgir outra necessidade.

Este é o mapa resumido: escolha um grupo e consulte as ramificações da tabela. O mapa completo e os Pedidos ficam na Aula 08. Não há sequência obrigatória entre os grupos.

Um agente do BMAD é um papel especializado que a IA assume, com orientações e um menu de tarefas. O método principal oferece cinco agentes com nome. Eles ajudam a examinar o trabalho por perspectivas diferentes; as decisões do negócio continuam com você.

Os cinco nomes de skill foram conferidos também em .claude/skills/<nome>/SKILL.md na instalação local do guia. Os exemplos de atuação são ilustrações desta aula, não sessões executadas.

Você tem duas formas de começar. Chamar uma skill diretamente, como bmad-build, inicia o trabalho correspondente. Carregar um agente, como Amelia por bmad-agent-dev, abre aquele papel e permite escolher uma tarefa pelo menu. Não é necessário carregar um agente antes de usar uma skill.

O BMAD também tem módulos extras, conjuntos adicionais de recursos, como BMad Builder, Creative Intelligence Suite, Test Architect, BMad Loop e Game Dev Studio. Eles existem, mas ficam fora deste guia.

Ampliação do escopo do guia: a exclusão dos módulos extras mencionada no parágrafo anterior passa a ter uma exceção. O CIS — Creative Intelligence Suite agora integra o guia, com o panorama da ramificação 11 na tabela desta Aula, os usos completos na Aula 08 — Usar só uma parte do BMAD e o aprofundamento na Aula 07 — Brainstorm e criatividade: o módulo CIS. Os demais módulos citados continuam fora do escopo. Esta é uma atualização editorial do guia, não uma mudança na composição do BMAD.

O planejamento produz arquivos que o trabalho seguinte pode consultar. bmad-spec gera SPEC.md; quando você pede a divisão em stories em uma conversa interativa, ela gera stories.yaml ao lado dele. No modo sem interação, essa divisão não é executada. Assim, o objetivo e a lista de partes ficam disponíveis para as próximas sessões quando você usa o caminho correspondente.

Cada arquivo guarda uma parte do trabalho

Como ler esta tabela junto dos usos avulsos: ela resume os nomes; as condições de geração estão detalhadas nas ramificações da Aula 08. No brainstorm, os artefatos finais dependem da postura e da sua escolha; no brief, addendum.md depende de haver conteúdo de apoio. Consulte as Etapas 02 e 06 da Aula 08 antes de interpretar esses nomes como entregas obrigatórias.

Os nomes abaixo são os previstos na documentação e nas skills da 6.12.4. A tabela descreve saídas documentadas; nenhum desses arquivos foi gerado por uma execução de exemplo nesta revisão. Eles não são uma lista obrigatória de tudo o que seu projeto precisa produzir.

SPEC.md é o acordo derivado das decisões registradas; .memlog.md guarda o histórico dessas decisões. Para mudar a spec, volte a bmad-spec com a alteração. A própria skill informa que uma edição manual em SPEC.md não é suportada e pode ser substituída na próxima geração. Arquivos de apoio que vieram de outra skill continuam sob responsabilidade da skill que os produziu. Isso preserva a diferença entre mudar uma decisão na origem e apenas trocar uma frase no documento final.

O que fica local e o que passa pela ferramenta de IA

Neste guia, repositório é a pasta do projeto acompanhada por um histórico de versões no Git, a ferramenta que registra versões do trabalho. Essa explicação prática será desenvolvida na Aula 05.

Segundo a BMad Code, os documentos, as configurações e as skills ficam no repositório. O BMAD não oferece armazenamento hospedado próprio. A página “The method” declara que o método não exige conta nem mantém um serviço próprio em execução ou telemetria — coleta automática de informações de uso. Ela também informa que a instalação faz consultas externas.

Limite dessa conferência: a declaração de governança da página oficial está marcada como auditada na v6.12.0. Aqui ela foi conferida por leitura; não foi feita uma auditoria de rede ou de telemetria da 6.12.4.

O Claude Code tem suas próprias regras de dados. A documentação da Anthropic informa que ele usa conexões de rede para interagir com o modelo e que o tratamento dos dados depende da conta e das configurações. Portanto, guardar os documentos na pasta não significa que tudo usado pela IA permanece apenas no computador.

Antes de usar informações de clientes ou documentos internos, confira as regras da sua empresa e as configurações da ferramenta de IA. Para acompanhar os exemplos do guia, use dados fictícios.

Uma edição trivial pode ir direto ao assistente quando é óbvia, tem baixo risco e você consegue revisar o resultado. Corrigir uma palavra na página de contato é um exemplo. Se o erro puder afetar o uso real do produto, a própria documentação recomenda considerar bmad-build.

Um protótipo descartável é uma versão feita só para experimentar uma ideia e depois abandonar. Imagine uma tela com horários fictícios, usada numa conversa para descobrir se o cliente entende a proposta. A fonte oficial permite dispensar o processo nesse tipo de trabalho.

Se aquela tela passar a receber reservas reais, reavalie a escolha. No exemplo, entram regras e consequências que antes não existiam. Esse é o critério a levar para o seu negócio: escolha o menor caminho que permita construir e conferir a mudança com segurança.

Instalação no macOS

Na Aula 04, você instala o BMAD na pasta do projeto e confere se ele está pronto para começar.