Instalação no macOS

Separe uma pasta nova para este exercício. Abra essa mesma pasta no Claude Code, o assistente de inteligência artificial (IA) que pode trabalhar nos arquivos do seu computador. O BMAD será instalado nela, como orienta a documentação da 6.12 (abre em nova aba).

Precisa ser uma pasta vazia?

Para repetir este exercício, sim. Para usar o BMAD no seu negócio, não: a documentação permite instalá-lo em projetos novos ou existentes. A pasta vazia é uma escolha didática para você conhecer a instalação sem misturá-la com arquivos de um trabalho em andamento.

O instalador detecta uma instalação existente e muda as opções oferecidas. Por isso, copiar o Pedido de instalação nova para uma pasta já configurada exige outro diagnóstico. A conferência dos arquivos e de sua recuperação é uma precaução deste guia para o caminho com trabalho existente, não uma exigência de pasta vazia do BMAD.

Antes de começarmos, mostre o caminho completo da pasta deste projeto e liste o que já existe nela, incluindo pastas ocultas. Não instale nem altere nada. Diga se ela está vazia e se já existe uma instalação do BMAD. Vou usar esta pasta para seguir a aula de instalação do BMAD 6.12.4.

A conferência de Python vem também do arquivo de apresentação da mesma versão, chamado README (abre em nova aba).

Confira antes de seguir:

• O caminho mostrado é o da pasta que você reservou para o projeto.
• A pasta está vazia. Se já tem trabalho seu ou uma instalação do BMAD, escolha outra pasta nova para este exercício.
• Você sabe onde colar um Pedido e onde executar um Comando.

Confira o que já existe no Mac antes de instalar qualquer coisa. O README do BMAD 6.12 declara Node.js 20.12 ou mais novo, Python 3.10 ou mais novo e uv. Há uma diferença dentro da própria versão: o programa que lê a configuração para a bmad-help exige Python 3.11 ou mais novo. Portanto, ver Python 3.10 no terminal não basta para comprovar esse primeiro uso.

O uv pode escolher ou baixar um Python compatível quando executa esse programa. Isso depende de acesso ao download e de essa função estar habilitada. Nesta aula, primeiro conferimos as ferramentas; depois da instalação, a Etapa 05 testa a leitura real da configuração. Se for instalar Python agora, escolha uma versão ainda suportada e que seja pelo menos 3.11.

O Git não é requisito desta instalação com apenas o módulo bmm — um módulo é um conjunto de recursos do BMAD. O instalador exige Git para módulos externos ou personalizados vindos do Git. Se faltar, anote para a Aula 05.

No Mac, a tentativa de executar git --version pode abrir uma oferta de instalação das ferramentas da Apple quando elas estão ausentes. Nesse caso, adie essa instalação para a Aula 05 e registre o Git como pendente. A conferência não é uma ordem para instalar essas ferramentas agora.

Confira os pré-requisitos do BMAD 6.12.4 neste Mac, sem instalar, atualizar ou alterar nada. Execute node --version, npm --version, npx --version, python3 --version, uv --version e git --version. Mostre a saída de cada comando. Compare Node.js com o mínimo 20.12 e Python com o mínimo 3.10 declarado no README. Explique também que o leitor de configuração do BMAD exige Python 3.11+, que o uv pode fornecer, e será testado depois da instalação. Diga se o uv está disponível.

Separe o que impede continuar do que pode ficar para depois: Git será usado na Aula 05, mas não é obrigatório para instalar apenas o bmm. Se o Mac oferecer instalar as ferramentas da Apple durante a consulta do Git, não prossiga com essa instalação. Registre ferramentas ausentes e versões insuficientes. Python 3.10 sozinho não comprova que a bmad-help está pronta; a leitura da configuração e a chamada no chat ainda precisam ser conferidas.

Saída esperada

Esta é a saída real de 15/11/2026, na mesma ordem dos comandos. Os números do seu Mac podem ser diferentes: o que importa é atender aos mínimos e não receber erro de comando ausente.

v22.21.0
10.9.4
10.9.4
Python 3.14.7
uv 0.11.1 (Homebrew 2026-03-24 aarch64-apple-darwin)
git version 2.54.0 (Apple Git-157)

A palavra Homebrew aparece porque o uv deste Mac já havia sido instalado por essa ferramenta. Você não precisa instalar Homebrew para seguir os caminhos da próxima etapa.

Se você usa o Claude Code pelo terminal, também pode conferir sua versão:

Saída real:

2.1.325 (Claude Code)

Essa conferência é opcional para quem usa o app desktop e não verifica a versão incluída no app.

No chat de uma sessão local do app, o Pedido /status permite consultar a versão do Claude Code dessa sessão. Esse Pedido foi conferido na documentação do app (abre em nova aba), mas não foi executado nesta revisão. Não copie para ele a versão obtida por claude --version: são instalações separadas.

Confira antes de seguir:

• Node.js atende ao mínimo, e npm e npx respondem.
• Você identificou a versão do Python e sabe que a leitura de configuração exige 3.11+, diretamente disponível ou fornecido pelo uv.
• uv responde com sua versão.
• Você anotou se Git está disponível. Se não falta ferramenta para a preparação, pule a Etapa 03. A prontidão para usar a skill só será confirmada nas Etapas 05 e 06.

Faça esta etapa somente para as ferramentas ausentes ou abaixo do mínimo. Depois, repita a conferência da Etapa 02.

Use o diagnóstico da etapa anterior e instale apenas os pré-requisitos que faltam ou estão abaixo do mínimo do BMAD 6.12.4. Use os caminhos oficiais: uma versão LTS suportada do Node.js em https://nodejs.org/en/download; uma versão suportada do Python, pelo menos 3.11 para os scripts de configuração, pelo instalador para macOS em https://www.python.org/downloads/macos/; e o instalador independente do uv documentado em https://docs.astral.sh/uv/getting-started/installation/.

Preserve as ferramentas que já atendem aos requisitos. Não altere o Python fornecido pelo macOS. Se uma janela do instalador exigir uma ação minha, explique o próximo passo e aguarde. Não peça que eu cole senhas no chat. Ao terminar, repita os comandos de versão da Etapa 02, mostre as saídas e diga se podemos instalar o BMAD. Ainda não instale o BMAD.

Não há saída de instalação reproduzida nesta etapa porque nenhuma dessas instalações foi executada. O sinal para avançar é a conferência da Etapa 02 passar.

Confira antes de seguir:

• Você instalou só o que precisava.
• Os comandos de versão funcionam no ambiente que o Claude Code está usando.

• Se o terminal reconhece as ferramentas, mas o app não, você consultou este problema comum.

Agora peça a instalação na pasta que você conferiu. Vamos instalar o módulo bmm para o Claude Code, com conversa e documentos configurados em português do Brasil. O módulo básico core acompanha a instalação.

Instale o BMAD 6.12.4 na pasta nova deste exercício. Antes, mostre o caminho completo, confira que ela está vazia e repita a verificação de Node.js, npm, npx, Python e uv. Considere a diferença entre Python 3.10 declarado no README e Python 3.11+ exigido pelo leitor de configuração. Consulte npm view bmad-method dist-tags para informar a versão publicada. Se latest for diferente, explique a diferença, mas não troque automaticamente a versão fixa desta aula.

Se a pasta estiver correta e os requisitos estiverem atendidos, execute nela:
npx --yes bmad-method@6.12.4 install --yes --modules bmm --tools claude-code --directory . --communication-language "Portuguese Brazil" --document-output-language "Portuguese Brazil"

Use as permissões normais do Claude Code. Se houver arquivos anteriores ou outra instalação, não aplique este procedimento de pasta nova: relate o que encontrou. Ao terminar, mostre o trecho final verdadeiro do instalador, leia a versão em _bmad/_config/manifest.yaml e confira _bmad/ e .claude/skills/, incluindo .claude/skills/bmad-help/SKILL.md. Execute a leitura efetiva dos idiomas descrita na Etapa 05. Informe qualquer erro ou aviso. Não crie o produto ainda e não siga o convite do instalador para experimentar a v7.

{ rollback: '4.39.0', latest: '6.12.4', next: '6.12.3-next.1' }

O desenho apresenta a sequência orientada ao leitor; a conversa e a resposta da skill não foram executadas no teste.

Saída esperada

Trecho contínuo copiado do resumo final da execução de 15/11/2026. Mantivemos o texto original do instalador; a mensagem em inglês significa “o BMAD está pronto para usar”. O restante da saída informa o destino e os próximos passos.

◆  claude-code configured: 29 skills → .claude/skills
│ ╭─BMAD is ready to use!──────────────────────────────────────────────────────╮
│ │    ✓  Shared scripts                                                       │
│ │    ✓  BMad Core Module (v6.12.4, installed)                                │
│ │    ✓  BMad Method (v6.12.4, installed)                                     │
│ │    ✓  Module directories                                                   │
│ │    ✓  Configurations (generated)                                           │
│ │    ✓  Help catalog                                                         │
│ │    ✓  claude-code (29 skills → .claude/skills)                             │

Esse trecho também aparece na repetição com versão fixa feita pela revisão. A mensagem de sucesso está descrita na documentação oficial (abre em nova aba). As 29 skills são o resultado destes testes com bmm, não uma promessa de quantidade para qualquer combinação de módulos.

Confira antes de seguir:

• O resumo mostra BMAD 6.12.4 e Claude Code.
• O destino é a pasta do seu projeto.
• A instalação terminou; você leu eventuais avisos, mesmo que a mensagem de sucesso apareça.

Confira os arquivos além da mensagem de sucesso. O BMAD guarda a configuração compartilhada e os programas de apoio em _bmad/. Para o Claude Code, as skills ficam em .claude/skills/, cada uma com seu arquivo SKILL.md.

Confira a instalação do BMAD nesta pasta, sem editar arquivos do projeto. Mostre se existem _bmad/, .claude/skills/ e .claude/skills/bmad-help/SKILL.md. Leia a versão em _bmad/_config/manifest.yaml e confirme se é 6.12.4. Liste as skills instaladas e diga se a bmad-help está entre elas.

Execute uv run _bmad/scripts/resolve_config.py --project-root . --key core.communication_language --key core.document_output_language e mostre a saída verdadeira. O uv pode obter um Python compatível para rodar esse programa. Confira se os dois valores são Portuguese Brazil. Se houver diferença, identifique em qual camada de configuração ela foi definida, sem corrigir automaticamente. Se algo faltar ou falhar, mostre exatamente o que ocorreu. Não considere a integração com o chat testada apenas porque os arquivos existem ou o programa de configuração funcionou.

_bmad/
.claude/skills/
.claude/skills/bmad-help/SKILL.md

{
  "core.communication_language": "Portuguese Brazil",
  "core.document_output_language": "Portuguese Brazil"
}

Confira antes de seguir:

• _bmad/ existe na pasta certa.
• .claude/skills/ existe na mesma pasta.
• .claude/skills/bmad-help/SKILL.md existe.
• A versão registrada é 6.12.4.
• O programa de configuração terminou sem erro e mostrou os dois idiomas como Portuguese Brazil. Falta agora conferir o uso no chat.

Peça orientação à bmad-help. Ela examina o projeto e os módulos instalados para recomendar o próximo passo. Você não precisa decorar o catálogo de skills.

/bmad-help Acabei de instalar o BMAD neste projeto. Quero organizar os pedidos de clientes da minha empresa, mas ainda não defini o que vou construir. Responda em português do Brasil. Explique o que você encontrou no projeto, recomende o próximo passo e diga o que é opcional. Por enquanto, só me oriente; não comece a construir.

Como reconhecer que funcionou

O Claude Code reconhece a skill, explica a situação do projeto e sugere próximos passos com os nomes das skills que você pode chamar. A resposta depende dos arquivos e da pergunta; não existe uma frase final única para copiar e comparar. Esse comportamento foi conferido nas instruções oficiais da bmad-help (abre em nova aba), que também existem na instalação local do guia.

A resposta da bmad-help não foi testada nesta aula. O teste confirmou seu arquivo instalado e executou a leitura da configuração que ela utiliza. Isso não equivale a rodar a skill no Claude Code; por isso não há bloco de saída de conversa nesta etapa.

O que muda conforme o tamanho do projeto?

A instalação de bmm desta aula é a mesma. O que muda é o caminho escolhido depois dela. Instalar o método não obriga você a produzir todos os documentos nem a usar todas as skills. A documentação orienta escolher o menor caminho que comporte o trabalho com segurança, considerando clareza, tamanho, risco e pessoas envolvidas.

Os nomes e usos dessas skills também foram conferidos nos respectivos SKILL.md da instalação local. Elas não foram executadas para produzir exemplos nesta aula; a tabela descreve caminhos documentados, não respostas observadas.

Por exemplo, “quero organizar os pedidos da minha empresa” ainda não define uma solução. Você pode precisar explorar opções. Já “quero acrescentar um filtro por data à lista de pedidos existente, preservando as regras atuais” dá mais elementos para avaliar uma mudança delimitada. “Quero integrar vendas, estoque e entregas de várias unidades” provavelmente exige divisão e decisões compartilhadas. Esses exemplos são fictícios; a avaliação deve considerar os arquivos reais, as restrições e o risco, como orienta a documentação de planejamento (abre em nova aba).

Pedido alternativo — já existe um produto:

/bmad-help Já existe um produto nesta pasta. Quero acrescentar um filtro por data à lista de pedidos, preservando as regras atuais. Antes de indicar a próxima skill, confira o que está documentado e o que ainda precisa ser entendido. Explique se isso pode caber em uma sessão ou precisa ser dividido. Não implemente ainda.

Use esse Pedido somente na pasta do produto existente; numa pasta vazia, mantenha o exemplo inicial. A bmad-help lê o catálogo, a configuração e as evidências do projeto para orientar o caminho. Um arquivo de planejamento encontrado não prova, sozinho, que aquela etapa foi concluída: a skill deve examinar o conteúdo e reconhecer a incerteza quando faltar evidência.

Quando escolher a próxima skill, abra uma conversa nova na mesma pasta, como recomenda a bmad-help, e informe o objetivo e os documentos pertinentes. “Conversa nova” não significa instalar o BMAD outra vez. A Aula 02 explica os tamanhos de trabalho; a Aula 06 desenvolve os fluxos. Aqui, a meta é concluir a instalação e receber orientação, sem começar o produto por acidente.

Confira antes de seguir:

• O Claude Code reconhece a bmad-help.
• Você recebe orientação ligada ao que contou sobre o projeto.
• Você entende qual é o próximo passo. Se a skill não respondeu, a instalação dos arquivos terminou, mas a integração ainda precisa ser conferida.

Você pode pular esta etapa na primeira instalação. Mais adiante, o caminho oficial para atualizar o BMAD ou rever módulos e ferramentas é executar o instalador novamente na pasta que já contém _bmad/. Ele detecta a instalação e oferece os caminhos aplicáveis.

Quero revisar a instalação do BMAD nesta pasta. Primeiro, leia a versão, os módulos e as ferramentas instaladas e consulte npm view bmad-method dist-tags. Leia também os idiomas efetivos e verifique se há ajustes em _bmad/custom/. Mostre o que está instalado e qual versão está marcada como latest. Não atualize nem migre automaticamente.

Quando eu tiver indicado o ajuste, use npx --yes bmad-method@6.12.4 install nesta mesma pasta para seguir o caminho de atualização ou reconfiguração da 6.12.4. Distinga renovar a instalação de mudar módulos, ferramentas ou respostas de configuração. Não acrescente o --yes do BMAD para tentar pular a escolha de modificação. Mostre as escolhas necessárias e o resumo final verdadeiro. Ao terminar, confira manifesto, pastas e idiomas e peça que eu teste a bmad-help novamente. Uma versão mais nova em latest deve ser explicada, sem substituir automaticamente a versão fixa.

Usa outra ferramenta de IA? — Opcional, não testado

O BMAD também configura outras ferramentas. A lista de identificadores aceitos é fornecida pelo próprio instalador. Se esse for seu caso, peça ao Claude Code para mostrar a lista com o Comando abaixo, sem mudar a instalação; no terminal, você pode executá-lo diretamente:

Esse Comando de consulta foi executado na revisão de 15/11/2026; ele lista as ferramentas e encerra sem instalar. A consulta sem versão fixa também havia sido executada pelo autor. O identificador escolhido é o valor usado em --tools; o local das skills depende da ferramenta. Não suponha que outra ferramenta leia .claude/skills/ ou use a mesma forma de chamada no chat. A instalação e o uso com outras ferramentas não foram testados e não fazem parte deste passo a passo.

Você terminou quando os arquivos estão na pasta certa e a bmad-help responde no Claude Code. Na próxima aula, vamos cuidar do histórico do projeto com Git e GitHub.

1. A bmad-help não aparece. O que conferir?

   Confira se a sessão está na pasta em que você instalou o BMAD e se existe .claude/skills/bmad-help/SKILL.md. Abra uma nova sessão nessa pasta e tente o Pedido da Etapa 06. A documentação atual do Claude Code também orienta usar o Pedido /reload-skills no chat se a pasta das skills foi criada depois do início da sessão; essa alternativa não foi testada aqui. A orientação do BMAD é reabrir a ferramenta quando necessário. Não assuma que ver a pasta no disco já prova a integração. Situação documentada; não reproduzida neste teste.

2. Algumas skills estão faltando. A instalação falhou?

   Nem sempre. O instalador grava as skills dos módulos selecionados. Este guia seleciona bmm, com o módulo básico core, e o teste criou 29 skills. Uma instalação com módulos adicionais pode ter mais. Confira o módulo escolhido e, se precisar mudá-lo, siga a Etapa 07. A quantidade de 29 foi observada no teste; a falta de skills não foi reproduzida.

3. O Node.js é antigo. Posso continuar?

   Se estiver abaixo de 20.12, não avance: esse é o mínimo declarado para o instalador da 6.12. Instale uma LTS suportada pela página oficial, abra um novo terminal e repita node --version. Se o app ainda enxergar a versão antiga, confira a pergunta sobre ferramentas não encontradas abaixo. Situação prevista pelo requisito oficial; não reproduzida no teste.

4. O BMAD terminou de instalar, mas falta uv. Está pronto?

   Ainda falta completar a preparação. A documentação da 6.12 diz que a ausência de uv gera aviso, mas não impede o instalador de terminar. As skills que precisam dele não funcionarão até sua instalação; a bmad-help usa uv para ler a configuração. Faça o Passo 03 da Etapa 03, confira uv --version e tente a skill novamente. No teste, uv já estava disponível.

5. As ferramentas funcionam no Terminal, mas o app não as encontra. E agora?

   O app pode ter iniciado antes de o ambiente reconhecer as ferramentas instaladas. Encerre e reabra o app, selecione de novo a pasta e repita a conferência. Se persistir, peça ao Claude Code para diagnosticar o PATH, a lista de pastas em que o computador procura programas. A documentação do app registra esse problema com ferramentas como Node.js e npm. Problema documentado; o app não foi testado.

6. O Python mostra 3.10, mas a leitura da configuração falha. O que faço?

   O mínimo do README e a exigência desse programa são diferentes. Use o Comando com uv run da Etapa 05; não o substitua por uma chamada direta de Python 3.10. Se o uv não conseguir fornecer um Python compatível, confira a mensagem: downloads de Python podem estar desabilitados ou indisponíveis no ambiente. Nesse caso, use o caminho oficial da Etapa 03 para disponibilizar uma versão suportada de pelo menos 3.11 e repita a consulta. A combinação com somente Python 3.10 não foi testada aqui.

7. Pedi português, mas o BMAD ainda usa inglês. Preciso reinstalar tudo?

   Primeiro execute a consulta de idiomas da Etapa 05. Se os valores efetivos não forem os pedidos, confira as quatro camadas de configuração antes de escolher o ajuste. Se forem Portuguese Brazil, leve ao Claude Code o resultado e a resposta em inglês para diagnosticar o uso da skill. A bmad-help é instruída a responder no idioma configurado; um valor correto no arquivo não comprova que ela foi chamada. Esse problema de conversa não foi reproduzido.

8. Depois de mudar módulos, aparecem comandos duplicados ou skills antigas. Posso apagar a pasta?

   Não apague a pasta inteira. Confira o manifesto, os módulos escolhidos e os avisos sobre entradas legadas. A documentação de atualização prevê limpeza de comandos antigos; a documentação de skills também alerta para possíveis resíduos. Entretanto, há rotinas de limpeza no código da 6.12.4, então não se pode afirmar que toda atualização deixa arquivos antigos. Peça uma lista dos itens encontrados, de sua origem e do motivo para remover cada um. A limpeza de uma instalação antiga não foi testada nesta aula.

9. O npx fez uma pergunta mesmo com --yes. Por quê?

   Há duas ferramentas envolvidas. O --yes depois de install é uma opção do BMAD. Antes disso, o npx pode pedir autorização para baixar o pacote. Confira se o pacote solicitado é bmad-method na versão 6.12.4 antes de aceitar o download.

   A variante recomendada na Etapa 04 já inclui os dois: npx --yes bmad-method@6.12.4 install --yes, seguido das demais opções. Ela foi testada na revisão, mas o cache do npm — os arquivos de pacotes guardados no computador para reutilização — não foi deliberadamente esvaziado. A confirmação de download continua sendo uma função diferente das permissões do Claude Code.

10. O instalador convidou para experimentar a v7. Eu errei?

    Não necessariamente. Esse convite apareceu na instalação real da 6.12.4, antes e depois do resumo de sucesso. Confira as linhas com a versão instalada e as pastas da Etapa 05. Para acompanhar esta aula, permaneça no caminho da 6.12; o anúncio da prévia não comprova que você instalou a v7.