O que é o BMAD e a filosofia

Uma ferramenta de IA pode escrever código — as instruções que fazem um programa funcionar — e ainda entregar algo diferente do que sua empresa precisa. O ponto central do BMAD é este: quando uma decisão importante fica subentendida, a ferramenta pode transformar uma suposição em parte do sistema. O método ajuda a explicitar essas decisões e preservá-las para o trabalho seguinte.

Imagine que você tem uma oficina e quer uma agenda pela internet. Antes de construir, há escolhas de negócio: quantos carros cabem em cada horário, quem confirma uma reserva e até quando o cliente pode cancelar. Uma tela bonita não responde a essas escolhas por você.

Se o sistema aceitar dois carros no mesmo horário quando só há uma vaga, a oficina terá um problema mesmo que a tela abra e o botão funcione. Escrever antes a regra de uma reserva por horário permite conferir depois se a entrega respeita o combinado.

Exemplo fictício do guia: a oficina será usada ao longo desta aula. As situações e decisões são didáticas; nenhuma agenda foi construída ou testada para produzir este texto.

Usaremos os nomes da página “The method”, da BMad Code: Análise para entender o problema, Plano para decidir a entrega, Implementação para construir e Verificação para conferir o resultado. Análise é opcional; o planejamento acompanha a necessidade do trabalho.

O README.md da 6.12.4 organiza o ciclo com outra ênfase: Esclarecer → Planejar → Construir e verificar → Aprender e ajustar. Ele reúne construção e verificação e destaca o aprendizado na última parte. Os quatro nomes adotados nesta aula vêm da página “The method”; a volta ao plano mantém esse aprendizado visível.

Percorra o exemplo da oficina

1. 01Fase 01 · Análise: descubra por que a equipe confirma duas reservas para a mesma vaga.
2. 02Fase 02 · Plano: combine uma reserva por horário e deixe o pagamento pela internet para depois.
3. 03Fase 03 · Implementação: acompanhe a ferramenta de IA construir a agenda conforme as regras combinadas.
4. 04Fase 04 · Verificação: confira se a agenda bloqueia reservas duplicadas e leve os aprendizados ao plano.

Na Análise, a dona da oficina pode descobrir que as confirmações ocorrem em conversas separadas. Na Verificação, pode perceber que certos serviços ocupam dois horários seguidos. Essa descoberta acrescenta uma regra ao plano antes da próxima mudança.

Esta sequência é uma simulação didática, sem execução. O encadeamento de esclarecimento, plano, construção, revisão e aprendizado está no README.md; a conferência do resultado em relação à intenção está em docs/build/build-a-change.md, “Review the Result”.

Você entra onde o trabalho começa. Na oficina, a dúvida sobre a causa dos conflitos pede Análise. Uma agenda nova com objetivo definido pede Plano. Uma alteração pequena e clara em uma agenda que já existe pode entrar pela Implementação. Mesmo nesse último caso, a construção inclui investigação e revisão: entrar mais adiante não dispensa conferir o resultado.

O tamanho também não decide tudo: dúvida sobre as regras, risco elevado e mudanças que afetam outras partes do negócio podem exigir mais planejamento. A Aula 02 explica como escolher esse caminho.

O que significa ter uma ideia clara

Uma intenção é a descrição do resultado que você quer alcançar. Para orientar a construção, ela precisa dizer o que deverá ser verdade no fim, o que deve permanecer como está e o que fica fora da entrega. Não precisa ser um documento comprido; precisa reduzir as decisões que outra pessoa teria de adivinhar.

Na oficina fictícia, “quero organizar a agenda” ainda deixa várias decisões abertas. Uma descrição mais útil poderia registrar:

1. Resultado esperado: a recepcionista consegue confirmar uma reserva por horário disponível, sem duplicidade.
2. O que preservar: os agendamentos já confirmados continuam válidos.
3. O que fica fora: cobrar pelo serviço e enviar mensagens automáticas aos clientes.

Esse exemplo não é uma especificação pronta. Ainda faltaria decidir, por exemplo, a duração dos serviços e quem pode cancelar uma reserva. Ele mostra como separar a vontade inicial das regras que sustentam a entrega. Quando faltar uma decisão, reconheça a lacuna; uma frase bem escrita não transforma uma suposição em fato.

Porta 01 · Quando ainda falta entender o problema

Na Análise, a primeira escolha é descobrir qual dúvida está impedindo o avanço. A documentação oferece ferramentas independentes; elas não formam uma fila que todos precisam percorrer.

Você pode usar uma, combinar algumas ou pular esse trabalho quando a intenção já estiver definida. Uma sessão de questionamento também pode terminar com a decisão de abandonar a ideia ou com uma compreensão melhor, ainda sem material suficiente para construir. A documentação de bmad-forge-idea admite esses resultados; avançar para código não é o único desfecho útil. Estas funções foram conferidas por leitura, sem execução.

Na oficina, pode fazer mais sentido combinar que uma única pessoa confirme as reservas antes de pagar por uma agenda nova. Essa é uma possibilidade didática, não uma conclusão da pesquisa: o método ajuda a examinar a ideia, mas a decisão depende do seu negócio.

Porta 02 · Quando a intenção já existe e precisa virar plano

Especificação, ou spec, é o registro do que deve ser construído e das condições que a entrega deve cumprir. A skill bmad-spec organiza a intenção nesse contrato de trabalho. Ela não substitui a descoberta do que você quer: se a entrada estiver insuficiente, ficam perguntas a resolver ou é necessário voltar ao trabalho de definição.

O arquivo central se chama SPEC.md. Ele registra cinco campos: por que fazer, quais capacidades entregar, quais restrições respeitar, o que fica fora e como reconhecer o sucesso. Outros arquivos guardam os detalhes que precisam acompanhá-lo. Na oficina, isso permite manter a regra de uma reserva por horário e a decisão de adiar o pagamento visíveis para quem construir cada parte. O exemplo é fictício; os cinco campos e o nome do arquivo são documentados.

O que muda conforme o tamanho: há quatro termos úteis para entender a divisão do trabalho.

• Uma sessão de implementação trata de uma unidade de trabalho.
• Uma story é uma fatia da entrega que pode ser construída e conferida separadamente.
• Um épico reúne várias dessas fatias para alcançar um resultado coerente.
• Um projeto pode reunir vários épicos.

A quantidade de documentos aumenta quando é preciso manter essas partes alinhadas, enquanto a construção continua sendo feita uma unidade por vez.

• Se cabe em uma sessão: uma mudança clara pode ir diretamente para bmad-build. Se você já tem uma especificação, ela serve de entrada. Não é obrigatório produzir um documento de produto completo antes de toda correção.
• Se precisa de várias sessões para um resultado: bmad-spec pode dividir a especificação em stories. No modo de conversa com a pessoa, essa opção se chama Story Breakdown, isto é, divisão em stories. Ela escreve stories.yaml ao lado de SPEC.md. Você examina a ordem e escolhe quais partes precisam de conferência humana antes ou depois da implementação. Em seguida, há uma execução de bmad-build por story.
• Se envolve vários resultados ou equipes: prepare os documentos compartilhados necessários, mantenha uma especificação por épico e confira também o funcionamento das partes juntas. A documentação usa vários épicos ou cerca de vinte sessões como sinais de trabalho do tamanho de um projeto; isso é uma referência de planejamento, não um limite automático.

O nome e a condição de criação de stories.yaml foram conferidos também no SKILL.md de bmad-spec: a divisão é opcional e interativa; não acontece no modo sem interação humana. Nenhum desses arquivos foi gerado nesta revisão.

Quando o projeto pede mais preparação, cada documento resolve uma necessidade diferente:

Essas escolhas não impõem uma ordem única. PRD, experiência do usuário e arquitetura podem ser trabalhados em ordens diferentes e alimentar a mesma especificação. Nos projetos que precisam de um planejamento mais amplo, bmad-create-epics-and-stories faz a decomposição em épicos e stories; bmad-sprint-planning verifica a prontidão antes de criar o acompanhamento do trabalho. Sprint é o nome usado para um ciclo de trabalho. O caminho de um épico baseado em SPEC.md e stories.yaml pode funcionar sem esse acompanhamento separado. A Aula 06 detalha os procedimentos; aqui, o objetivo é reconhecer por que cada alternativa existe.

Porta 03 · Quando a mudança é pequena e clara

Entrar pela Implementação significa dispensar uma preparação separada quando ela não faz falta. Dentro de bmad-build, ainda há investigação dos arquivos e das decisões existentes. Depois, a skill avalia três pontos: decisões de intenção que faltam, ações irreversíveis e alcance da mudança. Se o desenho estiver livre desses sinais, ela pode seguir por uma rota leve, com especificação mínima e implementação na mesma sessão. Se algum ponto exigir cuidado, produz um plano completo e apresenta as perguntas que precisam de resposta antes da aprovação.

Por isso, “pequena” não significa “sem risco”. Na oficina fictícia, trocar uma frase explicativa e alterar a regra de cancelamento podem parecer pedidos curtos. A segunda mudança afeta compromissos com clientes e exige decisões mais cuidadosas. A fonte orienta aumentar o planejamento conforme o risco e o efeito sobre outras partes do sistema.

Quando pode dispensar o BMAD: a documentação admite pedir diretamente uma edição trivial, de baixo risco, que você esteja disposto a conferir, ou trabalhar sem o processo em um protótipo descartável — uma versão feita só para experimentar uma ideia. Se um defeito puder chegar ao uso real, a documentação recomenda considerar bmad-build. A escolha não depende apenas de quantas palavras há no Pedido.

A Verificação acompanha todos os caminhos de construção

O desenho separa as fases para facilitar o entendimento. Na execução documentada, bmad-build já inclui revisão e correção dos problemas pertencentes à mudança. Portanto, a Fase 04 não quer dizer que o trabalho só será conferido depois de todo o projeto pronto. A revisão acontece por entrega; em um épico, também é necessário conferir o resultado combinado.

Para entender uma mudança pronta, bmad-walkthrough conduz uma revisão humana: explica a intenção, organiza o que foi alterado e sugere observações manuais. Você decide aceitar, pedir retrabalho ou discutir mais. Essa skill não executa a suíte de testes — o conjunto de verificações automáticas do projeto — nem substitui a revisão feita por bmad-build. A função foi conferida na documentação e na instalação, sem executar a skill.

Se não souber por onde começar, bmad-help examina o contexto disponível no projeto e recomenda próximas skills. Ela oferece orientação; você continua responsável por dizer qual resultado importa. Também foi conferida por leitura, sem execução.

O BMAD organiza a colaboração para que você preserve o julgamento e consiga conferir a entrega. A documentação orienta a descrever o resultado esperado, o que deve ser preservado e o que fica fora do trabalho. Essas escolhas dão uma referência para construir e revisar.

Na oficina, a ferramenta pode verificar se duas reservas ocupam o mesmo horário. Você confirma se uma reserva por horário é a regra certa para aquela operação. Ao encontrar uma regra esquecida, registre a mudança no plano e confira o resultado de novo.

Diferencie defeito, decisão errada e trabalho novo

Ao conferir a agenda fictícia, você pode encontrar três situações diferentes:

• A regra foi registrada, mas o sistema não a respeita. O plano diz uma reserva por horário, porém duas são confirmadas. É preciso corrigir a implementação e verificar novamente.
• O sistema respeita uma regra que estava incompleta. A reserva ocupa um horário, mas certos serviços precisam de dois. Corrija a decisão no plano e depois ajuste a implementação.
• Apareceu outro objetivo. A agenda atende ao combinado, mas agora você quer controlar o estoque de peças. Registre esse objetivo para um trabalho próprio, em vez de tratá-lo como um defeito da agenda.

Esses casos são exemplos didáticos da distinção documentada em bmad-build: problemas da mudança são corrigidos; quando a causa está no plano ou no objetivo, a revisão volta a essa camada; assuntos independentes podem ser adiados. Quando a skill registra trabalho adiado, usa deferred-work.md na pasta configurada para os registros de implementação. Esse arquivo não é uma saída obrigatória de toda execução. A existência e a função foram conferidas nas instruções; o arquivo não foi produzido nesta revisão.

Se o plano estiver em SPEC.md, a orientação é pedir a atualização por bmad-spec, que preserva os identificadores das capacidades, em vez de editar esse arquivo diretamente. Se a mudança alterar a divisão do trabalho, a lista de stories também precisa ser revista. A seta de volta ao Plano no D01-A representa esse aprendizado: corrigir o que orienta a próxima entrega.

Confira se ficou claro

Explique o BMAD em voz alta, como se estivesse conversando com um sócio. Use suas palavras para dizer o que ele é, qual problema resolve e quais são as quatro fases. Depois escolha uma das três entradas para a agenda da oficina e justifique sua escolha.

Sua explicação está completa se distingue a decisão de negócio da execução, menciona o risco de construir com suposições e percorre Análise, Plano, Implementação e Verificação, incluindo o aprendizado que volta ao plano. Se ainda faltar uma dessas partes, retome a seção correspondente antes da próxima aula.

Conferência em 15/11/2026: os arquivos do BMAD foram lidos na versão 6.12.4, e as duas páginas da BMad Code foram consultadas diretamente. Essas páginas exibiam a versão 6.12.0; foram usadas para filosofia e apresentação das fases. Os detalhes da 6.12.4 foram conferidos no código, na documentação da própria versão e nos arquivos das quinze skills citadas, presentes na instalação local. A apresentação do Claude Code e o funcionamento de suas skills foram conferidos na documentação oficial da ferramenta. Esta aula não testa instalação nem execução no Claude Code. A única validação executável do conteúdo foi a análise de sintaxe do D01-A; ela não comprova sua aparência no site.