Como instalar e rodar o BMAD Method em um editor de IA

Seu agente de código é bom em escrever código e ruim em admitir o que supôs. Ele escolhe um formato de estado, uma convenção de erro, uma fronteira — em silêncio — e você descobre a escolha três arquivos depois, quando algo a contradiz.

O BMAD Method ataca isso colocando as decisões em disco antes de o código existir. Ele se instala como um conjunto de skills de agente, dá a você personas com nome para conversar e escreve briefs e documentos de arquitetura que a sua próxima sessão pode ler em vez de deduzir de novo.

Este guia instala o método do zero, roda dois workflows de planejamento de ponta a ponta e então faz o que a maioria dos textos pula: confere a saída com o linter que o BMAD inclui exatamente para isso. Medido em 23 de setembro de 2026 contra a versão 6.13.0-next.

Prefere assistir?

A mesma ideia em vídeo: o que é o método, por que várias personas especializadas superam um assistente genérico e como é trabalhar com elas.

Watch it instead BMAD Method - A completely new way to develop Software.

Que problema o BMAD resolve, de fato?

Ele preserva o raciocínio que produziu o seu código, em vez de jogá-lo fora no fim do chat. Um agente de código é eficaz na implementação e indiferente à procedência: peça uma funcionalidade e você recebe a funcionalidade, mais uma dúzia de decisões que ninguém registrou.

A resposta do BMAD é um conjunto de skills, cada uma um workflow especializado, que gravam a saída em arquivos no seu repositório. Um brief de produto é um arquivo. Um documento de arquitetura é um arquivo. O raciocínio por trás de cada um é anexado a um log de memória ao lado.

Esse formato é o argumento inteiro. A próxima sessão, o próximo agente ou o colega que herdar o projeto lê a decisão em vez de adivinhá-la — e como os artefatos são Markdown puro, nada fica preso no histórico de chat de um fornecedor.

O que você precisa antes de instalar?

Três coisas, e uma delas é nova desde o vídeo: Node.js com npm, Git e uv. Os workflows do BMAD são guiados por scripts Python, e o uv é como eles rodam — sem ele as skills param e mandam você instalá-lo.

node --version   # v22.21.1
git --version    # 2.54.0
uv --version     # 0.11.6

Seu editor também precisa suportar skills de agente. A skills CLI detecta o que você está usando e instala de acordo; nesta máquina ela encontrou o Claude Code e instalou sem fazer uma única pergunta.

Como instalar?

Um comando no seu projeto, e a skills CLI faz o resto. Você pode ver primeiro o que está disponível — o repositório publica 32 skills, e a ideia não é instalar todas.

npx skills add bmad-code-org/BMAD-METHOD --list

Para instalar, nomeie as skills que quer. A base do README é o hub mais os dois registros de módulo; acrescente as personas e os workflows que você pretende usar.

npx skills add bmad-code-org/BMAD-METHOD \
  --skill bmad --skill bmod-core-tools --skill bmod-method \
  --skill bmad-build --skill bmad-agent-analyst \
  --skill bmad-agent-architect --skill bmad-brainstorming

Sete skills chegaram em 3,7 segundos. Elas ficam em .agents/skills/ na raiz do projeto, com symlinks em .claude/skills/ para o Claude Code e copiadas para um layout universal que outras 20 ferramentas leem — Codex, Cursor, Copilot e o resto — então a mesma instalação serve para qualquer editor que você abrir em seguida.

Como saber o que está faltando?

Peça o status antes de qualquer outra coisa. A skill bmad é um hub: ela lê a instalação, reporta em que estado está e nomeia o único comando a rodar em seguida.

O primeiro status numa instalação nova voltou com current: false e next: "bmad setup" — e, mais útil, seis recomendações. Cada persona declara as skills de workflow em que se apoia, e as que você pulou são listadas com o comando exato para adicioná-las.

{
  "skill": "bmad-agent-architect",
  "requires": "bmad-architecture",
  "state": "missing",
  "install": "npx skills add bmad-code-org/BMAD-METHOD --skill bmad-architecture"
}

São recomendações, não defeitos — uma analista sem a skill de deep-recon ainda funciona, só tem menos recursos à mão. Instalar as seis levou mais 3,3 segundos e levou o projeto a 13 skills.

O que o setup cria?

Rode o setup e o BMAD grava uma pasta _bmad/: 19 arquivos, 288 KB, e nada que você precise preencher à mão. É um upsert, então é também o que você roda depois de cada atualização.

_bmad/
  config.toml           # project name and where artifacts go
  scripts/              # shared Python the skills call
  core-tools/scripts/   # per-module copies
  method/scripts/
  custom/.gitignore     # keeps personal answers out of commits

A config é curta e vale a leitura, porque decide onde tudo o que você produzir vai parar — _bmad-output/planning-artifacts para planejamento, _bmad-output/implementation-artifacts para trabalho de código, docs para conhecimento do projeto.

O setup só faz as perguntas que os módulos instalados declaram. Nesta execução não houve nenhuma, e o segundo status voltou com current: true, next: null, zero problemas e zero requisitos não atendidos.

O que os workflows de planejamento produzem, de fato?

Arquivos, numa pasta de execução, com um log de memória ao lado. Apontado para um produto pequeno — um registro de empréstimos para uma biblioteca comunitária mantida por voluntários — o workflow de brief produziu brief.md numa pasta datada.

O arquivo é estruturado em resumo executivo, problema, solução, a quem serve, critérios de sucesso, escopo e questões em aberto.

A parte interessante é o companheiro. Todo workflow grava decisões por um script compartilhado, então a pasta acumula um registro do porquê separado do o quê:

uv run _bmad/scripts/memlog.py append --workspace "$W" \
  --type decision \
  --text "Scope fixed to loans and returns only; borrower accounts, reservations and fines explicitly out of v1."

Essa linha é a promessa de contexto durável tornada concreta. O brief diz o que o produto é; o memlog diz quais alternativas foram fechadas e quando — que é justamente a parte que normalmente evapora quando a janela do chat fecha.

Em que a skill de arquitetura difere de simplesmente pedir um design?

Ela se recusa a escrever a maior parte do que você esperaria. A skill de arquitetura do BMAD produz um spine: só os invariantes que permitiriam que duas partes construídas de forma independente divergissem. Todo o resto é explicitamente adiado.

Cada decisão é um bloco pequeno com três campos — o que ela vincula, que divergência ela impede e a regra aplicável. O formato é o que a torna verificável depois.

### AD-1 — A loan's returned state is a timestamp, never a boolean

- **Binds:** all
- **Prevents:** two builders modelling the same fact differently — one as
  `isReturned: true`, one as `returnedAt` — making the overdue query and the
  history view disagree.
- **Rule:** the `Loan` entity carries `returnedAt` as a nullable timestamp.
  Open means `returnedAt == null`. No boolean mirror may be stored.

A skill também exige que qualquer tecnologia nomeada tenha a versão checada na web, em vez de lembrada, e é por isso que a tabela de stack na saída traz versões fixas em vez de nomes vagos. Para este spine, isso significou confirmar React 19.3.0, Vite 8.3.0, TypeScript 7.0.2 e o Parse JS SDK 8.6.0 antes de vinculá-los.

Dá para verificar a saída, ou é preciso confiar?

Dá para verificar uma parte real, o que é raro em qualquer coisa desta categoria. A skill de arquitetura inclui scripts/lint_spine.py, e rodá-lo sobre o spine produzido é um único comando.

uv run .agents/skills/bmad-architecture/scripts/lint_spine.py \
  --workspace "_bmad-output/planning-artifacts/architecture/architecture-bmad-demo-2026-09-23"

O spine voltou limpo: "ok": true, "total_findings": 0. Sozinho isso prova pouco — um linter que nunca dispara não vale nada — então o mesmo arquivo foi corrompido de propósito e rodado de novo.

{"ok": false, "total_findings": 3, "findings": [
  {"detail": "AD-2 missing required field(s): rule", "severity": "high"},
  {"detail": "AD-1 id reused (also at line 32)", "severity": "high"},
  {"detail": "AD-1 is non-monotonic (follows AD-4)", "severity": "high"}
]}

Três achados de severidade alta, cada um nomeando a linha. As verificações são estruturais, não semânticas — nenhuma ferramenta vai dizer que uma decisão está errada — mas “toda decisão carrega sua regra, e ids nunca colidem” é exatamente o tipo de deriva que torna um documento pouco confiável seis meses depois.

O que acontece quando você passa para o código?

A skill de build se compila para a execução em vez de entregar ao agente um prompt estático. Invocá-la renderiza um snapshot em _bmad/render/, e o snapshot contém só os passos de que a rota escolhida precisa.

Pedir a rota oneshot com uma revisão rápida produziu um snapshot de 92 KB e 12 arquivos — os passos clarify, plan e oneshot, os prompts de revisão e um manifesto — enquanto os passos da rota mais longa ficaram de fora.

O workflow que ela renderiza traz padrões explícitos, incluindo uma régua “Ready for Development” que exige que toda tarefa nomeie um caminho de arquivo e que todo critério de aceitação seja escrito como Given/When/Then.

Com o que você deve tomar cuidado?

Três coisas, nenhuma delas impeditiva. A primeira é a diferença de versão: npx skills add puxa da branch main do repositório, então as skills reportaram 6.13.0-next enquanto o bmad-method do npm está em 6.12.0. Se você precisa de uma release fixa, instale do npm ou de um marketplace de plugins.

A segunda são as permissões. Skills executam com todos os direitos do seu agente, e o instalador diz isso. O script de setup do próprio BMAD é limpo — sem execução de shell, acesso à rede limitado a buscar um manifesto de versão, escritas confinadas à pasta que você passa — mas isso é uma propriedade deste projeto, não de skills em geral.

A terceira é o inchaço de escopo na direção oposta à habitual: com 32 skills disponíveis, é tentador instalar tudo. O status diz o que as suas personas realmente querem. Pegue essas e deixe o resto.

Onde isso deixa o seu backend?

Exatamente onde o spine o colocou, e esse é o ponto. O documento de arquitetura que esta execução produziu fixou um backend gerenciado atrás de uma única camada de gateway — um só módulo autorizado a importar o SDK, devolvendo objetos simples ao domínio.

Essa é uma fronteira que vale escrever antes de qualquer código existir, seja qual for a plataforma atrás dela. É também o que torna a decisão reversível: a regra nomeia a camada, não o fornecedor, então trocar a fonte de dados depois mexe em um diretório em vez de em todos os componentes.

Ferramentas de planejamento não constroem nada sozinhas. O que o BMAD muda é que as razões sobrevivem à sessão — e razões em disco são a coisa mais barata que você vai ter quando o projeto fizer seis meses e quem tomou a decisão já tiver saído.