BMAD em um projeto que já existe

Você já tem um site, um sistema de pedidos ou uma ferramenta interna. Há telas funcionando, clientes usando, integrações e decisões tomadas antes desta aula. Agora quer usar o BMAD para fazer a próxima mudança com mais clareza.

O ponto de partida é o trabalho existente. O BMAD pode investigar o código, seguir os padrões encontrados e construir uma mudança delimitada. Quando as instruções importantes estão ausentes ou envelheceram, a skill bmad-project-context ajuda a registrar um conjunto pequeno de regras verificadas. Você não precisa replanejar a empresa inteira para corrigir um problema no sistema.

Ao terminar, você terá um ponto de partida salvo, saberá quais instruções a IA lê, terá um caminho para a primeira mudança e uma rotina para corrigir contexto desatualizado. Se a mudança for maior, a Fase 04 mostra como dividir o trabalho sem perder o objetivo.

Antes de começar: tenha a pasta do projeto disponível, o Claude Code funcionando e acesso ao histórico do trabalho. A Aula 04 — Instalação no macOS cobre a preparação da ferramenta; a Aula 05 — Git e GitHub explica como salvar versões. O procedimento de instalação desta aula está escrito para o terminal do macOS. Windows continua dependendo de conferência em uma máquina real, conforme a regra do guia.

Como ler os exemplos. Todo texto depois do nome de uma skill nos blocos de Pedido é um exemplo escrito para esta aula. Não é uma frase obrigatória, um conjunto de opções de terminal nem uma saída observada. Troque o negócio, a mudança e os caminhos pelo seu caso. Os nomes das skills, seus modos e os comportamentos descritos foram conferidos nas fontes indicadas ao lado. As decisões sugeridas pelo guia aparecem como recomendações ou exemplos.

Antes de instalar, separe três coisas: o que o sistema faz hoje, as regras que ele precisa respeitar e o que você quer mudar. Misturar essas três coisas faz a IA tratar uma intenção futura como se já estivesse implementada. O BMAD distingue o contexto usado para trabalhar no código do contexto de planejamento.

O código mostra o presente; você fornece as decisões

Uma IA pode encontrar a tela de cobrança, ler a função que calcula o total e localizar os testes. Isso não revela, por si só, que sua empresa decidiu não mexer no cálculo até o fechamento do mês. Também não prova que uma integração aparentemente antiga pode ser substituída: talvez um parceiro ainda dependa dela.

A proposta de bmad-project-context é registrar fatos que mudam a forma de trabalhar e que seriam caros de redescobrir, ou que só aparecem depois de um erro. Uma regra de negócio ou de equipe pode ser essencial mesmo quando parte dela seria dedutível do código. A skill trata instruções existentes como algo a preservar e avaliar, não como texto descartável.

Considere este exemplo fictício, que acompanha a aula: uma empresa de serviços já usa um sistema de pedidos. O responsável quer melhorar a mensagem exibida quando um filtro não encontra resultados. Depois, pretende acrescentar filtros salvos. O sistema não existe como projeto de teste desta aula; os Pedidos ensinam como descrever a intenção.

A separação da tabela é uma aplicação didática da teoria do contexto e das regras de bmad-spec. Os exemplos não são regras do BMAD para todo projeto.

Quando você pode pular a preparação de contexto

Se o projeto já tem AGENTS.md, CLAUDE.md ou regras da ferramenta mantidas por alguém, você pode começar a mudança sem gerar outro documento. A documentação também permite pular essa etapa quando outra ferramenta já fornece descoberta suficiente. A ausência do bloco não impede, por si só, o uso de bmad-build.

Pular faz sentido quando as instruções estão corretas e chegam à IA. Se ninguém sabe o que está atual, use uma avaliação. Se já existe um bloco gerenciado, escolha refresh ou audit conforme a Fase 05. Se existem instruções sem esse bloco, escolha adopt. Não crie um arquivo concorrente para “organizar depois”.

Quanto desta aula você precisa percorrer

As cinco Fases organizam a leitura; não obrigam toda empresa a executar todas as skills. Escolha pelo trabalho que pretende realizar e pela qualidade do contexto disponível. Um sistema antigo com muitas pastas pode precisar apenas de uma correção delimitada; uma aplicação pequena pode precisar de decisões cuidadosas quando a mudança altera dados ou permissões.

Esta tabela é uma orientação de leitura derivada das fontes, não um sexto modo do BMAD. A escolha pode mudar depois da investigação: se a alteração revelar uma dependência que ninguém conhecia, volte ao planejamento correspondente. Você preserva o objetivo do negócio ao ajustar o percurso, sem transformar cada descoberta numa reconstrução completa do projeto.

Salvar antes é a recomendação prática desta aula, apoiada no controle de versões da Aula 05.

Ao terminar esta etapa

• Você sabe qual é a pasta do projeto.
• Consegue descrever uma primeira mudança sem pedir uma reforma geral.
• Sabe quem mantém as instruções existentes, ou reconhece que elas precisam de avaliação.
• Entende quais partes desta aula foram verificadas por leitura.

Recomendação desta aula: crie um ponto de comparação antes da instalação e outro depois de conferir as instruções. Assim, quando for investigar uma mudança, fica mais fácil separar adoção do BMAD e alteração do sistema.

Se outra pessoa ou outro processo está mexendo na mesma pasta, coordene uma pausa ou use uma cópia de trabalho separada, conforme a prática da equipe. Não acrescente a instalação por cima de alterações cujo dono você desconhece. Essa é uma precaução editorial para trabalho simultâneo; não é uma proteção automática do instalador.

Confira a pasta deste projeto e o estado do Git antes de qualquer instalação.
Leia as instruções existentes e identifique mudanças ainda não salvas.

Mostre quais arquivos pertencem ao trabalho atual, o que já estava alterado
e quais verificações do projeto podem confirmar o comportamento de partida.

Se houver mudanças de outra pessoa ou de outro processo, não as inclua.
Prepare e faça um commit apenas dos arquivos deste trabalho que forem adequados
ao histórico, respeitando as regras do projeto. Não inclua segredos nem dados
privados. Relate o commit criado e qualquer pendência. Se nada mudou,
diga que não foi necessário criar outro commit.

Este Pedido não chama uma skill do BMAD: ele orienta o Claude Code a usar o Git. Os comandos de inspeção e registro são conferidos nas referências git-status, git-diff, git-add e git-commit. O procedimento não foi executado para esta aula.

A mensagem do commit é um exemplo; use a convenção da sua equipe. Se o projeto ainda não usa Git, siga primeiro a Aula 05. Não invente uma política de branches nesta aula: branch é uma linha de trabalho separada no histórico, e a equipe pode ter sua própria regra para usá-la. A política deve vir das instruções do seu projeto, conforme bmad-project-context.

O que você deve conferir

Peça também uma verificação do comportamento atual. Por exemplo, abrir a listagem de pedidos e executar os testes que o próprio projeto já usa. Teste automatizado é uma verificação executada por uma ferramenta para comparar o resultado com o esperado. Não há um comando universal de testes para todos os sistemas. A skill de contexto deve ler os scripts, arquivos que automatizam ações, e verificar qualquer afirmação sobre comandos antes de registrá-la.

Se os testes já falham antes da mudança, registre isso. Não transforme um problema antigo em uma falsa prova de que a instalação causou o defeito. Essa recomendação também segue a separação que bmad-build faz entre a mudança atual e problemas preexistentes.

Se o projeto não tem testes confiáveis

A falta de testes não prova que a adoção do BMAD é impossível, mas limita o que você pode concluir sobre a entrega. O Build prevê investigar como verificar a mudança e registrar os testes e checagens realizados. O procedimento abaixo é uma recomendação desta aula para tornar a comparação inicial concreta; não é um comando nem uma garantia adicional do método.

Antes de pedir a alteração, descreva um percurso curto que alguém consiga repetir. No exemplo fictício: abrir a listagem, aplicar um filtro que encontra pedidos, aplicar outro que não encontra e conferir a ação de voltar à lista. Registre o comportamento observado e quais partes não foi possível verificar. Depois da mudança, repita o mesmo percurso e acrescente os critérios da mensagem nova. Assim, você compara evidências observáveis em vez de depender apenas de “a tela abriu”.

Os exemplos da tabela aplicam a exigência de verificar e relatar evidência do Build e sua triagem de achados. Se a ausência de uma verificação impede decidir se a entrega está correta, trate-a como pendência de aceitação. Criar uma suíte de testes para todo o legado pode ser outro trabalho; primeiro delimite a proteção necessária à mudança em discussão.

Ao terminar esta etapa

• O trabalho relevante tem um ponto de partida recuperável.
• Você sabe quais alterações já existiam.
• Segredos e dados privados não entraram no histórico.
• O comportamento de partida foi observado, ou a falta dessa verificação foi registrada.

O instalador da 6.12 atende tanto projetos novos quanto existentes. Para esta aula, o conjunto básico é o módulo bmm, com a integração claude-code. Módulo é um conjunto de recursos do BMAD; bmm reúne as skills de planejamento e construção usadas aqui. O instalador também cuida da base compartilhada, o core.

1. 1

   Conferir os requisitos e o que já está instalado

   A documentação exige Node.js 20.12 ou posterior para o instalador e uma ferramenta de IA compatível para usar as skills. Node.js é o programa que executa o instalador; npx é o comando usado para executar o pacote. O uv, ferramenta que prepara e executa recursos Python, é necessário para skills como bmad-build. A instalação pode terminar com um aviso de falta de uv, mas isso não torna o Build utilizável. Git é requisito do instalador quando ele busca módulos externos ou personalizados a partir de repositórios Git; nesta aula ele também serve para salvar seu trabalho.

   Pedido — exemplo de conferência, sem instalar ainda

   Pedido — exemplo para o Claude Code

   Confira se esta é a pasta principal do projeto e leia as instruções existentes.
   Verifique os requisitos da instalação do BMAD 6.12.4 para Claude Code.
   
   Veja se já existe _bmad/ e leia o manifesto e a configuração disponíveis.
   Relate a versão instalada, os módulos, a integração com o Claude Code e
   eventuais requisitos ausentes. Não atualize nada nesta conferência.
   Use as fontes da 6.12; não substitua o procedimento pelo da v7.

   O manifesto local de exemplo é _bmad/_config/manifest.yaml; a configuração compartilhada usa _bmad/config.toml. Esses nomes foram conferidos na instalação do guia e no instalador. A versão pinada da próxima linha significa “executar exatamente 6.12.4”, e evita depender de qual versão estiver marcada como mais recente no futuro.

2. 2

   Instalar quando o projeto ainda não tem BMAD

   Pelo Claude Code

   Pelo Claude Code — Pedido de exemplo

   Pedido — exemplo para o Claude Code

   Instale o BMAD 6.12.4 nesta pasta de projeto, com o módulo bmm e a integração
   claude-code. Configure a comunicação e os documentos em Português do Brasil.
   
   Antes, confirme que não há instalação anterior e que o estado do trabalho
   está salvo. Use meu nome se ele já estiver definido nesta conversa;
   caso contrário, use "Responsável pelo projeto".
   
   Use o instalador oficial da versão 6.12.4 e os parâmetros documentados para
   uma instalação nova sem perguntas. Ao terminar, mostre a pasta usada,
   a versão, os módulos, a integração instalada, os avisos e os arquivos alterados.
   Não faça mudanças no produto como parte desta instalação.

   Pelo terminal

   Pelo terminal — Comando alternativo para instalação nova

   Comando no terminal do macOS

   $npx bmad-method@6.12.4 install --directory . --modules bmm --tools claude-code --user-name "Responsável pelo projeto" --communication-language "Português do Brasil" --document-output-language "Português do Brasil" --yes

   Troque apenas o nome entre aspas se quiser. O ponto de --directory . significa a pasta atual: confirme o local antes de executar. O texto depois de --user-name é um valor de exemplo. Os nomes das opções são os reais do instalador.

   Parte do Comando	O que faz nesta instalação nova
   bmad-method@6.12.4	Escolhe a versão do pacote usada nesta aula
   install	Aciona a instalação
   --directory .	Usa a pasta atual como destino
   --modules bmm	Seleciona o BMM
   --tools claude-code	Seleciona a integração com Claude Code
   --user-name	Define como o BMAD identifica você
   --communication-language	Define o idioma da conversa
   --document-output-language	Define o idioma dos documentos produzidos
   --yes	Usa valores fornecidos e padrões para evitar as perguntas de configuração do instalador

   --yes é uma opção do instalador do BMAD; ela não é uma autorização para ignorar controles do sistema ou da ferramenta de IA. O próprio npx ainda pode pedir confirmação para obter o pacote, conforme seu ambiente; essa confirmação é separada das escolhas do BMAD. Este comando foi conferido por leitura, não executado para esta aula.

3. 3

   Tratar o projeto que já tem BMAD

   Se a 6.12.4 já está instalada e a integração funciona, você pode seguir para o contexto. Não há necessidade de reinstalar só para acompanhar a aula.

   Se precisa atualizar ou mudar a integração, use o caminho interativo depois de salvar o trabalho. Interativo significa que o instalador apresenta escolhas e espera uma resposta. A documentação diferencia atualização da configuração existente e modificação de módulos, ferramentas ou configuração.

   Pelo Claude Code

   Pelo Claude Code — Pedido de exemplo

   Pedido — exemplo para o Claude Code

   Esta pasta já tem BMAD. Leia a versão, os módulos, as ferramentas e a configuração
   atuais antes de propor qualquer alteração.
   
   Quero seguir esta aula na versão 6.12.4. Diga se já está pronta para isso.
   Se houver uma versão posterior, não faça downgrade automaticamente.
   Se precisar atualizar ou reconfigurar uma instalação anterior compatível,
   explique o caminho do instalador e preserve as escolhas atuais que não fazem
   parte da mudança. Não trate o comando de instalação nova como reconfiguração.
   Ao terminar, liste as alterações e os avisos.

   Pelo terminal

   Pelo terminal — alternativa para abrir o instalador dessa versão

   Comando no terminal do macOS

   $npx bmad-method@6.12.4 install --directory .

   Na instalação existente examinada, a escolha Quick Update atualiza com a configuração anterior; Modify BMAD Installation abre o caminho para modificá-la. Leia os módulos e ferramentas selecionados antes de confirmar: mudar a seleção pode remover componentes da instalação anterior. Os nomes e a lógica foram conferidos em ui.js e installer.js. Essas rotas não foram executadas nesta aula.

   Se a instalação veio de uma versão antiga. Leia também os avisos sobre comandos antigos que ficaram nas pastas da ferramenta. A documentação alerta que eles podem aparecer junto das skills novas e produzir duplicatas. No Claude Code, um dos locais examinados pelo instalador é .claude/commands/. O código lista as entradas identificadas; não faz uma limpeza genérica de toda a pasta.

   Antes de remover algo, confira o caminho e o conteúdo de cada entrada apontada, preserve personalizações que ainda tenham uso e siga a política do projeto. Não apague .claude/ nem todo arquivo que comece com bmad: o próprio código explica por que identifica entradas exatas, incluindo recursos personalizados e exceções que devem permanecer. Depois de tratar os avisos, reabra a ferramenta se necessário e confira bmad-help novamente. Essa inspeção e limpeza não foram executadas para a aula.

4. 4

   Entender os arquivos criados

   Local	Papel	O cuidado
   _bmad/	Configuração, manifestos e scripts compartilhados	A atualização pode substituir arquivos geridos pelo instalador
   .claude/skills/	Skills disponíveis para Claude Code	Uma skill de mesmo identificador pode ser apagada e copiada novamente
   _bmad-output/	Destino padrão para os materiais produzidos pelas skills	O caminho é configurável; nem toda subpasta nasce na instalação
   _bmad/custom/	Área prevista para personalizações persistentes	Personalização é outro tema; não edite cópias instaladas para “ensinar” regras do negócio
   AGENTS.md e CLAUDE.md	Instruções do projeto e sua ligação com a ferramenta	O fluxo de contexto, descrito a seguir, propõe as mudanças nesses arquivos

   No caminho core + BMM + Claude Code examinado, não foi encontrada uma etapa de reescrita dos arquivos do produto, do AGENTS.md ou do CLAUDE.md pelo instalador. Isso descreve o código lido; não é uma promessa de que qualquer módulo adicional jamais mexe em outro arquivo. O instalador cria arquivos próprios de exclusão do Git dentro de _bmad/custom/ e _bmad/render/.

   Também não conte com uma cópia de segurança completa feita pelo instalador. Há tratamento de arquivos geridos alterados dentro de _bmad/, inclusive cópias .bak em determinadas atualizações, mas a integração remove e recopia diretórios de skills. Por isso, edições diretas em .claude/skills/ podem desaparecer.

   A pasta de saída existente é preservada quando o caminho continua o mesmo. Se você mudar a configuração desse destino, há lógica que pode mover a pasta anterior ou avisar sobre conflito entre destinos. Não mude esse caminho como detalhe casual da adoção.

5. 5

   Conferir a integração

   A documentação manda conferir o resumo da instalação e invocar bmad-help na ferramenta selecionada. A frase BMAD is ready to use! é descrita na documentação oficial; não é uma saída obtida nesta aula.

   Pelo Claude Code

   Pedido — exemplo

   Pedido — exemplo para o Claude Code

   /bmad-help Estou em um projeto existente. Confira o BMAD instalado e me oriente
   sobre a preparação de contexto antes da primeira mudança. Use a versão local
   6.12.4 e diga quais evidências encontrou; não considere um documento concluído
   só porque o arquivo existe.

   Pelo terminal

   Alternativa pelo terminal para as skills desta aula. Abra o Claude Code interativo na pasta do projeto com o Comando abaixo e cole nele o mesmo Pedido. Os Pedidos com /bmad-... pertencem à conversa com o Claude Code; não são comandos para colar diretamente no terminal do macOS.

   Comando no terminal do macOS

   $claude

   bmad-help usa o catálogo instalado, a configuração e os artefatos encontrados para orientar o próximo passo. Seu código manda distinguir presença de arquivo e conclusão real.

   Nas próximas etapas, “Pelo terminal” significa usar essa conversa interativa. Não há motivo para inventar uma linha de terminal diferente para cada modo de contexto.

Ao terminar esta etapa

• Você conhece a versão e os módulos instalados.
• O Claude Code reconhece bmad-help.
• Avisos de requisitos ausentes foram resolvidos ou ficaram registrados como impedimento.
• Você revisou as mudanças da instalação antes de salvá-las.
• Não alterou o produto junto com a instalação.

O arquivo não substitui seu sistema, seus testes ou o planejamento da mudança. Sua função é colocar as regras importantes no caminho de quem vai trabalhar. Para ferramentas que leem outro arquivo, a skill deve propor e verificar uma forma de carregar essas instruções. No Claude Code, o exemplo usado nesta aula é a importação @AGENTS.md em CLAUDE.md.

A mesma skill atende cinco situações. Você pode dizer a intenção em português; escrever o nome do modo torna a escolha mais explícita. Esses nomes são argumentos reconhecidos pela instrução da skill, não subcomandos do instalador.

A Fase 02 detalha setup e adopt; a Fase 05 detalha os três modos de manutenção.

Como a skill distingue criar de adotar

Um arquivo vazio, só com títulos ou com uma linha de importação, não conta automaticamente como instrução significativa. Porém, se qualquer arquivo de instruções do projeto contém regras relevantes, o modo seguro é adotar. Quando há dúvida, o código manda preferir adopt. Se você pedir setup e a análise encontrar regras existentes, a skill deve mostrar a contradição e confirmar o caminho, em vez de obedecer silenciosamente e perder conteúdo.

Portanto, “o AGENTS.md não existe” não basta para concluir que você começa do zero. O projeto pode ter regras em CLAUDE.md ou em arquivos da ferramenta. O trabalho inicial deve procurar essas fontes.

/bmad-project-context Avalie as instruções desta pasta antes de escolher o modo.
Leia AGENTS.md, CLAUDE.md e outras regras de agentes presentes no projeto.

Se não houver conteúdo significativo, proponha setup.
Se houver instruções sem bloco gerenciado, proponha adopt.
Se o bloco já existir, explique se o caso pede refresh ou audit.

Mostre as evidências e o alcance da proposta antes de escrever.
Não descarte regras existentes apenas porque parecem dedutíveis do código.

Esta avaliação não foi executada para a aula.

Quando há mais de um projeto dentro da pasta

Monorepo é um repositório que reúne mais de um componente ou aplicação. Se a skill encontra unidades separáveis, como pastas com configurações próprias de construção, deve identificar essas unidades e perguntar se o trabalho cobre só a raiz, todas ou algumas. Repositórios vizinhos não são automaticamente filhos do projeto atual.

Não aprove “tudo” por hábito. Uma regra do sistema de pedidos pode não servir ao aplicativo do entregador. A skill só separa instruções em arquivos filhos quando isso reduz de fato o contexto principal e quando verificou que as ferramentas utilizadas carregarão esses arquivos. Essa ramificação reaparece na Etapa 06.

Quando o destino ou a fonte está em outro lugar

Além do modo, a skill aceita um caminho de destino e caminhos ou endereços de fontes adicionais. O padrão é trabalhar no projeto aberto. Se o destino aponta para mais de uma cópia de trabalho, ou para um lugar onde você não pode registrar commits, ela deve esclarecer isso antes de escrever. Não interprete um caminho amplo como autorização para alterar vários projetos de uma vez.

A skill também prevê atuar sobre um projeto sem _bmad/: nesse caso, pula a leitura da configuração central do BMAD. Isso pressupõe que a própria skill já esteja disponível na ferramenta que a executa; digitar o nome não a instala. Nesta aula, mantemos a instalação local da Fase 01 como caminho principal.

Ao terminar esta etapa

• O modo corresponde ao que já existe.
• As regras antigas foram localizadas.
• O alcance é claro: um repositório, sua raiz ou componentes escolhidos.
• Você sabe que a skill conversa e pede aprovação antes de escrever; ela não é uma geração silenciosa de documentação.

A criação de contexto é uma conversa de verificação. Você fornece as regras da empresa; a IA procura evidências no projeto; os dois conferem a proposta antes de ela virar instrução permanente. A skill instalada exige aprovação de cada escrita e não faz commit.

/bmad-project-context setup Prepare as instruções deste projeto existente.
Confira primeiro se realmente não há regras significativas que precisem ser
adotadas. Leia as configurações e o código relevante antes de afirmar
como o projeto funciona.

Quero um bloco pequeno no AGENTS.md, com regras verificadas e orientações que
evitem erros reais. Pergunte o que depende das decisões da empresa.
Mostre o bloco completo e a forma de carregamento no Claude Code antes
de escrever. Não faça commit.

/bmad-project-context adopt Melhore as instruções existentes deste projeto.
Trate o que já está escrito como regras a preservar e avaliar.

Mostre o destino de cada instrução: manter, reescrever, mover, automatizar
ou excluir, com motivo e evidência. Se uma reescrita perder parte de uma regra,
mostre essa perda separadamente. Confira contradições entre AGENTS.md,
CLAUDE.md e as demais regras.

Apresente o bloco completo, a tabela de decisões e qualquer mudança em outros
arquivos antes de escrever. Não faça commit.

Os textos dos Pedidos são exemplos editoriais; não foram executados.

Não troque a conversa por uma execução automática esperando que ela aprove as próprias mudanças.

1. 1

   Avaliar o que já existe

   A skill lê instruções, documentos e anotações relevantes. Se houver conteúdo anterior, abre um registro de decisões, chamado ledger no código. Pense nele como uma tabela de prestação de contas: para cada regra, ela deve mostrar o que vai acontecer, por quê, qual é a evidência e qual é o risco de perdê-la.

   Não basta entregar um AGENTS.md novo e mais elegante. Você precisa saber, por exemplo, para onde foi a regra que proibia alterar uma integração antiga. A skill pode agrupar regras mantidas ou reescritas sem perda; mudanças de destino, automatizações e exclusões precisam ficar individualizadas.

   Decisão interna	Leitura prática	O que conferir
   retain	Manter	A regra continua inteira
   rewrite	Reescrever	A redação mudou, mas a obrigação não foi enfraquecida
   relocate	Mover	O novo arquivo será carregado quando necessário
   automate	Automatizar	Uma verificação real passará a impedir a violação
   delete	Excluir	Existe um fundamento válido e visível para a remoção

   Mover uma regra também exige evidência. Se a proibição de alterar a exportação sair de CLAUDE.md e for parar num documento que nenhuma ferramenta carrega nem consulta por uma condição concreta, ela deixou de proteger o trabalho. A skill trata essa mudança como exclusão, sujeita aos fundamentos e aprovações correspondentes. Na tabela de decisões, confira tanto o caminho novo quanto a explicação de como a regra chegará à próxima sessão.

   No exemplo fictício, “Ao alterar a exportação de pedidos, leia o contrato do parceiro” dá uma condição reconhecível para a consulta. “Documentação adicional em outra pasta” apenas informa que existe um arquivo. Se a regra precisa valer antes de qualquer investigação, mantê-la no contexto principal pode ser necessário mesmo quando há uma documentação detalhada em outro lugar.

2. 2

   Trazer o que o código não consegue decidir

   A skill deve perguntar sobre regras de segurança, padrões internos, áreas congeladas e documentos externos. “Área congelada” é uma parte do projeto que a equipe decidiu não modificar naquele trabalho. Um manual interno ou uma decisão da empresa pode ser fonte; isso não torna automaticamente verdadeiro tudo que estiver nele. Contradições com o projeto precisam ser mostradas.

   No exemplo da empresa de serviços, você poderia informar: “A exportação usada pelo financeiro precisa continuar com as mesmas colunas até concluirmos a adaptação do parceiro”. A IA pode ler as colunas existentes. Só a empresa pode explicar esse compromisso e quando ele deixa de valer.

   Não cole credenciais ou dados de clientes para explicar a regra. Descreva a obrigação e indique a fonte acessível à equipe. Essa é uma orientação de segurança do guia; políticas sobre segredos são um dos tipos de contexto admitidos pela skill.

3. 3

   Conferir em vez de copiar

   A skill lê arquivos como package.json, Makefile e pyproject.toml quando eles existem. São arquivos que podem declarar dependências, os pacotes externos usados pelo projeto, ou maneiras de executá-lo. Ela também lê a configuração das verificações automáticas e o histórico necessário para entender restrições. Não exige que todos esses arquivos existam no seu sistema.

   O objetivo não é transcrever cada comando para o AGENTS.md. É descobrir o que o arquivo já explica e o que ainda falta dizer. “Use o teste do pacote de cobrança, porque o comando da raiz não executa esses testes” pode ser útil; uma lista copiada de todos os scripts tende a envelhecer junto com os scripts.

   Cada caminho mencionado precisa existir. Para cada afirmação sobre um comando, a skill deve ler o script ou alvo executado e conferir o que ele faz. Isso é verificação por leitura; não significa que todos os comandos foram executados. Quando a conclusão depender de execução, peça que o relatório distinga o que foi lido do que foi rodado. A distinção no relatório é recomendação desta aula.

4. 4

   Responder apenas ao que falta

   A entrevista vem depois da investigação. A skill não deve perguntar a você o nome de uma pasta que ela pode localizar. Deve perguntar o que o código não responde: por que uma área está congelada, qual erro os agentes repetem, o que significa um termo do negócio. O código limita cada rodada a no máximo oito perguntas e recomenda menos quando possível.

   Se a IA descobrir algo estranho, isso é motivo para uma pergunta, não para inventar uma regra. Uma função antiga não prova que é proibido substituí-la. Um caminho complicado não prova que agentes já erraram ali. Armadilhas precisam de erro observado.

5. 5

   Conferir a proposta e aprovar a escrita

   A proposta precisa mostrar o bloco inteiro, os eventuais blocos dos componentes e a tabela de decisões sobre instruções anteriores. Quando a mudança inclui correção em outro arquivo, ela também deve aparecer.

   Há quatro fundamentos para excluir uma instrução existente:

   1. Ela está desatualizada ou incorreta, com evidência.
   2. Uma verificação automática já impede aquela violação específica.
   3. Ela é prejudicial ou contraditória e a conciliação mostrou qual regra deve prevalecer.
   4. Você aprovou explicitamente a exclusão daquele item.

   “Ficou longo”, “a IA consegue descobrir” ou “está em algum lugar do repositório” não bastam, por si só, para apagar uma regra humana. Quando a justificativa depende apenas do quarto fundamento, aprovar o bloco completo não equivale a aprovar a exclusão. A remoção precisa ser apresentada como um item específico.

   Uma automação prometida também não basta. Se a regra vai ser substituída por uma verificação, mantenha a instrução até a verificação estar funcionando. Hook é uma ação automática disparada em um momento do trabalho; linter é uma ferramenta que verifica regras no código; CI é a execução automática de verificações do projeto. A skill pode propor esses recursos quando impedem melhor o erro do que uma frase.

   Ver em texto

   1. Você pede setup ou adopt ao Claude Code.
   2. O Claude Code carrega bmad-project-context.
   3. A skill lê as instruções e as evidências do projeto.
   4. Apresenta o que encontrou e as lacunas que precisam de informação humana.
   5. Você informa as regras da empresa.
   6. A skill confere os caminhos e as afirmações sobre comandos.
   7. Apresenta o bloco completo e as decisões sobre as instruções anteriores.
   8. Se você pedir ajustes, a skill reapresenta o bloco e as decisões corrigidos. Repita essa revisão enquanto houver ajustes necessários; a escrita continua pendente.
   9. Você aprova a proposta final; só então a skill escreve as mudanças apresentadas.
   10. Explica o resultado e deixa os arquivos para revisão; não faz commit.

   O diagrama resume a conversa; não representa uma execução feita nesta aula.

Ao terminar esta etapa

• Cada regra antiga tem um destino explicado.
• Afirmações verificáveis têm evidência.
• Regras novas da empresa foram confirmadas por quem pode defini-las.
• A escrita corresponde ao que você aprovou.
• Os arquivos ainda serão revisados e salvos no Git.

Leia o resultado como alguém que vai delegar o próximo trabalho. A pergunta útil é: “Se uma nova sessão receber estas instruções, o que ela fará de forma diferente?”. Esse é o teste de utilidade usado pelas boas práticas da skill.

O formato do bloco

A skill escreve entre os marcadores <!-- bmad:context --> e <!-- /bmad:context -->. A linha de procedência informa a data e o identificador do commit conferido. Esse identificador, chamado SHA, serve como referência para comparar mudanças futuras.

O template prevê uma orientação breve e, quando houver conteúdo útil, seções de política, localização de entradas relevantes, execução e verificação, convenções diferentes do padrão e armadilhas conhecidas. Se uma seção não tem nada que justifique sua presença, ela fica de fora. Não há número universal obrigatório de linhas.

A orientação pode identificar o projeto e suas tecnologias em poucas frases. O que a skill rejeita são inventários extensos, árvores completas de pastas e descrições copiadas do que o código mostra melhor. Essa nuance importa: “manter curto” não significa proibir uma frase que ajude a reconhecer o projeto.

O que merece entrar

As frases são exemplos; a skill precisa substituí-las por instruções específicas e verificadas do seu projeto.

Repare no último item. “Leia o manual quando achar necessário” deixa a consulta a critério da IA. “Ao alterar a exportação, leia o contrato do parceiro” define um gatilho observável, isto é, uma condição concreta que a tarefa permite reconhecer.

O que deve ficar fora

Não peça um catálogo de todas as pastas, uma cópia dos scripts, o histórico inteiro de decisões ou um manual de todas as bibliotecas. Biblioteca é um conjunto de código reutilizável usado pelo projeto. O contexto carregado em cada sessão precisa justificar seu custo e continuar verificável.

O desejo de acrescentar filtros salvos pertence à spec da mudança, não a uma frase afirmando que o sistema já tem filtros salvos. Uma preferência pessoal que vale em todos os seus projetos pertence à sua configuração global; uma regra da equipe sobre este repositório pertence ao contexto compartilhado.

O objetivo não é alcançar uma quantidade mínima de texto. Um bloco curto, com três regras decisivas e verificadas, pode servir melhor do que páginas que repetem o código. Isso é o princípio de seleção da skill, não uma promessa numérica de ganho de produtividade.

O exemplo real deste guia

O AGENTS.md do guia contém um bloco gerenciado. Nele há regras de política, convenções próprias e uma armadilha sobre buscas. O arquivo CLAUDE.md, na leitura feita para esta aula, contém apenas:

@AGENTS.md

Esse é um trecho real de arquivo, não uma saída simulada de execução.

Um exemplo de regra registrada no bloco é:

Excluir .claude/skills/, .agents/skills/ e _bmad/ das buscas: são a instalação do BMAD (quase todos os arquivos rastreados), não conteúdo do guia.

É uma instrução para as buscas normais do trabalho no guia. Nesta aula, a leitura dessas pastas foi expressamente necessária para conferir a instalação. Não copie a regra sem avaliar seu próprio projeto.

O bloco também registra uma política de commit direto na main. Isso é uma escolha deste guia, não uma regra geral do BMAD. O template oficial da skill traz outro exemplo, com revisão por solicitação de mudança. A skill existe justamente para acolher a política local.

Há um limite importante nesse exemplo real. O bloco informa que foi verificado em 14/11/2026, contra o commit 8048e5c, e sua orientação ainda afirma “Ainda não há código”. Na leitura desta aula já existem, entre outros, src/pages/index.astro e src/lib/aulas.ts. Portanto, ele demonstra o formato produzido pela skill e também uma razão concreta para refresh. Não foi corrigido nesta tarefa, que só podia ler o repositório.

O que acontece fora dos marcadores

Consequência prática: colocar algo fora do bloco impede que a simples substituição o sobrescreva. Não transforma a instrução em uma regra que nunca possa ser discutida ou atualizada. Confira o conjunto de mudanças, inclusive arquivos externos ao bloco.

Se você editar dentro dos marcadores por conta própria, a próxima atualização pode substituir essa edição. Prefira pedir a alteração à skill, para que a regra seja verificada e faça parte da proposta.

Conferir o carregamento no Claude Code

Não basta os dois arquivos existirem. A importação precisa estar no arquivo certo e o conteúdo não deve aparecer duplicado em dois arquivos carregados. A skill deve verificar o mecanismo das ferramentas que você usa antes de propor a adoção ou divisão.

A sintaxe @AGENTS.md importa o arquivo referenciado a partir de CLAUDE.md. A documentação atual do Claude Code confirma a importação por @; o procedimento desta aula usa essa forma explícita, sem presumir que toda versão e configuração descubra todos os arquivos automaticamente.

A documentação atual também prevê leitura direta de AGENTS.md desde o Claude Code 2.1.277. No padrão, isso depende de não haver CLAUDE.md, .claude/CLAUDE.md nem CLAUDE.local.md na pasta de trabalho ou nos diretórios acima; configurações podem mudar essa seleção. A importação usada aqui continua suportada. Na sessão seguinte, /context all, dentro do Claude Code, permite conferir CLAUDE.md na relação de arquivos de memória. Essa orientação foi conferida na documentação, sem executar o comando nem observar sua tela nesta revisão.

Confira o contexto recém-escrito sem alterá-lo.
Mostre quais instruções do projeto você está usando nesta sessão e por quais
arquivos elas chegam. Verifique a ligação entre CLAUDE.md e AGENTS.md,
eventuais duplicações e regras contraditórias.

Compare as mudanças com a proposta aprovada. Diga o que foi conferido por
leitura e o que exigiria uma execução para comprovar. Não conclua que o contexto
está atual apenas por encontrar os marcadores.

Esse Pedido é uma conferência editorial apoiada nas exigências de carregamento e verificação da skill; não é um sexto modo.

Quando separar regras em subpastas

Só vale criar um arquivo próprio para um componente quando as regras forem exclusivas dele, tiverem volume suficiente, reduzirem de verdade o bloco principal e tiverem carregamento verificado em todas as ferramentas usadas. A divisão também precisa de aprovação.

Uma regra que precisa valer antes de entrar naquela pasta, ou cuja violação afeta o restante do sistema, continua na raiz. Quando a leitura do arquivo filho não está comprovada, mantenha a regra na raiz com seu alcance explícito. Um exemplo editorial é “Na importação de pedidos, valide todas as linhas antes de gravar”.

Cada arquivo filho criado deve aparecer como referência, com seu caminho, no bloco pai. Se a análise de um componente não revelar regras próprias, não há motivo para criar um arquivo vazio ou repetir o conteúdo da raiz.

Se há um project-context.md antigo, a skill atual deve lê-lo e oferecer absorver seu conteúdo. Não deve apagá-lo sem acordo nem deixá-lo como uma segunda fonte esquecida.

Ao terminar esta etapa

• As regras descrevem o presente e os compromissos vigentes.
• Caminhos e ressalvas foram conferidos.
• O carregamento foi verificado, sem duplicação desnecessária.
• Nenhuma instrução importante sumiu sem explicação.
• O contexto e a instalação foram revisados e salvos antes da primeira mudança de produto, conforme a Aula 05.

bmad-build transforma uma intenção delimitada em código, com investigação, implementação, revisão e verificação. Ela aceita uma mudança descrita diretamente ou uma unidade já planejada. Uma correção mecânica óbvia e de baixo risco pode dispensar o BMAD; uma alteração que exige entender o comportamento do sistema já pode se beneficiar do fluxo.

No exemplo fictício, a primeira mudança será melhorar a mensagem de lista vazia quando nenhum pedido corresponde aos filtros. O objetivo é pequeno e observável. “Aproveite e refaça a cobrança, as permissões e o painel” reúne outros objetivos e perde essa delimitação.

1. 1

   Deixar a conversa e os arquivos prontos

   Comece uma nova conversa para esta execução da skill, mantendo aberta a pasta correta. Passe os caminhos dos documentos que realmente fazem parte da mudança. O catálogo de ajuda recomenda um contexto novo para cada skill; a documentação do Build também recomenda uma conversa nova.

   Antes, revise e salve as mudanças de instalação e contexto. No código instalado, se o Git mostra alterações pendentes ou uma linha de trabalho claramente incompatível, o Build deve parar e perguntar como lidar com a situação. Ele não deve misturar silenciosamente esse trabalho com a sua mudança.

2. 2

   Escrever intenção, preservação e verificação

   Pelo Claude Code

   Pelo Claude Code — Pedido de exemplo para o projeto fictício

   Pedido — exemplo para o Claude Code

   /bmad-build Na listagem de pedidos, melhore o estado em que nenhum pedido
   corresponde aos filtros escolhidos.
   
   Quando não houver resultados, exiba uma mensagem que explique a situação
   e oriente a pessoa a revisar os filtros. Siga os componentes, a redação e
   os recursos de acessibilidade que o projeto já usa.
   
   Preserve os filtros existentes, o cálculo dos totais, as permissões de acesso
   e o comportamento quando há resultados. Não acrescente notificações,
   relatórios ou novas dependências só para esta mudança.
   
   Leia as instruções do projeto, encontre a implementação e os testes relevantes
   e diga o que será reutilizado. Verifique os cenários com e sem resultados.
   Quero revisar o resultado local antes de qualquer envio ou publicação.

   Pelo terminal

   Pelo terminal, abra a conversa interativa da Etapa 03 e cole o mesmo Pedido.

   O texto é um exemplo de intenção, não um teste executado. Acessibilidade significa permitir que pessoas com diferentes formas de interação consigam usar a interface. Dependência é um pacote externo usado pelo projeto. Os limites do Pedido são escolhas do exemplo, não restrições universais do BMAD.

3. 3

   Observar a investigação antes de discutir soluções

   O Build deve ler o código primeiro. Ele identifica onde a mudança entra, o que pode reutilizar e o que precisa preservar. Em um projeto existente, seguir os padrões encontrados é o comportamento normal; não há uma etapa obrigatória perguntando se você quer combinar com o código atual.

   Se você quer mudar um padrão, diga qual e por quê. Por exemplo: “Hoje a tela mostra uma mensagem genérica; esta mudança estabelece uma mensagem específica para listas vazias e deve continuar usando o componente atual”. Se a mudança de padrão afetar várias sessões, registre a decisão na spec, para a próxima sessão não voltar ao padrão antigo.

   Modernizar é uma intenção que precisa de alcance. “Melhore tudo que encontrar” não informa o que preservar, qual risco aceitar nem como reconhecer a entrega. A recomendação desta aula é transformar esse desejo em uma mudança separada quando houver um objetivo concreto.

4. 4

   Entender as duas rotas do Build

   O código instalado decide a rota depois da investigação:

   Situação encontrada	Caminho	Sua participação
   Mudança clara, pequena e reversível	Registra um plano mínimo e segue pela rota oneshot	Pode implementar e revisar sem uma aprovação geral prévia do plano
   Há dúvida de intenção, irreversibilidade ou tamanho que pede mais cuidado	Escreve um plano completo, resolve perguntas e apresenta a proposta	Você aprova para continuar, aprova para retomar depois ou pede revisão
   A rota curta encontra dificuldade maior durante o trabalho	Volta ao planejamento completo	Você participa das decisões que surgiram

   oneshot é o nome interno de uma rota curta; não significa ausência de revisão.

   Poucas linhas também podem ter efeito difícil de desfazer. O roteamento considera migração de banco de dados, alteração destrutiva de dados, efeito externo e publicação como sinais de irreversibilidade. Migração de banco é uma mudança na organização dos dados; um efeito externo pode ser uma ação realizada em outro serviço. Esses exemplos vêm do planejamento do Build, que os separa do simples tamanho da implementação.

   Para o empresário, a consequência é concreta: trocar a mensagem da lista e apagar pedidos antigos podem exigir pouco código, mas têm consequências diferentes. O commit guarda a versão dos arquivos selecionados; ele não é uma cópia automática dos dados do sistema nem desfaz por si só uma ação já realizada em outro serviço. Se a mudança exige esse tipo de ação, descreva-a no Pedido e trate sua preparação e verificação no plano. Não conclua que a rota curta serve apenas porque a alteração parece pequena.

   A documentação de Build também menciona pedir uma execução curta ou pular revisão. Porém, o fluxo instalado manda não obedecer a instruções para pular etapas e escolhe a rota por evidência. Por isso, a aula não oferece “pular revisão” como atalho garantido.

   Na rota completa, há ainda uma decisão de tamanho: se o plano ultrapassar 1.600 tokens, a skill apresenta a contagem e oferece dividir objetivos secundários ou manter o plano inteiro, com os riscos explicados. Token é uma unidade de texto processada pela IA; não corresponde exatamente a uma palavra. Esse número pertence ao plano de uma execução do Build, não a um limite para toda a pasta produzida por bmad-spec e muito menos ao tamanho desta aula.

   Se houver perguntas de intenção em aberto, a rota completa espera respostas antes do checkpoint. Depois, as escolhas são aprovar e continuar, aprovar e parar, ou revisar o plano. Aprovar e parar deixa o registro em ready-for-dev, isto é, pronto para desenvolvimento numa nova sessão.

5. 5

   Saber quando interromper o crescimento do pedido

   Se a investigação mostrar que a mensagem vazia depende de uma reforma nas permissões, a mudança deixou de ser tão simples quanto parecia. O Build pode voltar ao plano. Se aparecerem objetivos independentes, pode separar o que fica para depois. O arquivo deferred-work.md registra trabalho adiado no destino configurado para artefatos de implementação. Artefato, aqui, é um arquivo produzido pelo método para registrar o trabalho.

   Adiar um problema descoberto não é o mesmo que afirmar que ele não importa. Significa separar a entrega atual da próxima. Se o problema afeta a segurança ou a validade da mudança que você está fazendo, ele não deve ser escondido como um assunto sem relação; precisa entrar na decisão sobre continuar. Essa distinção acompanha a classificação de achados prevista no passo de revisão.

Se precisar retomar em outra conversa

Informe o caminho real do registro de implementação já produzido. O Build usa o estado registrado para retomar: draft volta ao planejamento; ready-for-dev e in-progress seguem à implementação; in-review segue à revisão. Um registro done, concluído, serve de contexto para o novo trabalho, não como uma implementação pendente a repetir.

Pedido — exemplo de retomada

/bmad-build Retome o trabalho a partir deste registro de implementação:
[substitua pelo caminho real informado na execução anterior].
Leia o estado e as decisões já registradas antes de definir o próximo passo.

Não renomeie estados por conta própria para fazer a skill avançar. O Pedido deve apontar para a evidência real do trabalho.

Ao terminar esta etapa

• Há um objetivo observável e limites claros.
• O Build localizou o código relevante e os padrões a preservar.
• As decisões pendentes foram tratadas conforme a rota.
• Você sabe o que ficou para depois e onde isso foi registrado.

O fim da implementação não substitui sua conferência do resultado. A skill deve apresentar o que mudou, quais verificações foram realizadas, o resultado das revisões e o trabalho adiado. Você precisa comparar essa entrega com a intenção original.

1. 1

   Entender os registros produzidos

   Há dois tipos de “spec” nesta aula, com papéis diferentes:

   Registro	Quem produz	Papel
   Registro da implementação de uma unidade	bmad-build	Guarda plano, execução, revisão e estado daquele trabalho
   Pasta com SPEC.md e eventuais documentos complementares	bmad-spec	Define o contrato compartilhado do que construir, inclusive quando exige várias unidades

   Para um Pedido direto, o Build usa um arquivo com o padrão spec-{slug}.md no destino de implementação configurado; slug é um nome curto usado no caminho, como mensagem-lista-vazia. Para uma story identificada em uma pasta de spec, o registro fica sob stories/{id}-{slug}.md nessa pasta. Story é uma unidade de mudança que pode ser implementada e revisada separadamente. Esses padrões não autorizam você a supor o caminho real: leia o caminho informado no resultado da execução.

   A distinção evita uma confusão comum: receber um plano do Build não significa que você criou toda a pasta de contrato e divisão de trabalho da Fase 04.

2. 2

   Ler as verificações e os achados

   Na rota completa, a revisão do Build separa problemas que podem ser corrigidos localmente, erros no plano, lacunas na intenção e trabalho sem relação com o objetivo atual. Dependendo do caso, corrige, volta ao planejamento, consulta você ou registra o que ficou para depois. Na rota curta, um problema da mudança cujo conserto não é simples faz a skill parar e consultar você; não é a mesma triagem da rota completa.

   Voltar ao planejamento pode significar mais do que corrigir uma frase. Na rota completa, a skill prevê desfazer as alterações de implementação daquela execução e construir novamente a partir do plano corrigido. Quando o problema está no plano, registra também o que funcionou e precisa ser preservado. Isso diz respeito ao trabalho daquela execução, não a apagar o projeto ou desfazer alterações alheias. O fluxo manda interromper e consultar a pessoa quando os retornos ultrapassam cinco; não promete insistência ilimitada até dar certo.

   Revisor automático não é prova de que qualquer mudança está correta. Confira quais testes realmente rodaram e quais situações foram observadas. “Parece correto pela leitura” e “o teste foi executado e passou” são evidências diferentes. O Build exige confrontar o resultado com a diferença real dos arquivos e com os critérios da mudança.

   Se a ferramenta não oferece os subagentes necessários, o fluxo prevê preparar pedidos de revisão para sessões separadas. Subagente é outra execução de IA encarregada de uma parte do trabalho. Isso exige que as revisões sejam de fato realizadas; uma lista de pedidos não equivale a pareceres concluídos. Essa alternativa não foi testada nesta aula.

3. 3

   Conferir o comportamento como dono do negócio

   No nosso exemplo, a conferência manual deve observar a lista sem resultados, a lista com resultados e a preservação dos filtros. O que observar vem da intenção descrita no Pedido. Não copie esses cenários para uma mudança completamente diferente.

   Se precisar de ajuda para olhar a entrega, use bmad-walkthrough. Essa skill conduz uma revisão humana: explica para que serve a mudança, onde olhar com atenção e como testá-la.

   Pelo Claude Code

   Pelo Claude Code — Pedido de exemplo

   Pedido — exemplo para o Claude Code

   /bmad-walkthrough Guie minha conferência da mudança de mensagem na listagem
   de pedidos. Use o registro de implementação que acabou de ser produzido
   e o diff da mudança.
   
   Mostre como observar o caso sem resultados e o caso com resultados.
   Destaque onde conferir que filtros, totais e permissões continuam respeitados.
   Separe o que já foi testado do que ainda depende da minha observação.

   Pelo terminal

   Pelo terminal, use a conversa interativa da Etapa 03.

   O texto é exemplo editorial. A skill não foi executada para esta aula.

   A origem do procedimento está na skill de walkthrough.

   Se o resultado não corresponde ao que você queria, descreva a diferença concreta. “O botão para limpar filtros sumiu” ajuda a investigar; “não gostei” ainda precisa virar um critério observável. Para ajustes do mesmo trabalho, a documentação permite continuar a conversa; para uma nova unidade, inicie outra execução bem delimitada.

4. 4

   Separar commit, envio e publicação

   O fluxo padrão instalado do Build cria um commit local ao terminar quando existe Git e há alterações a registrar. Ele não faz push automaticamente. Push é o envio dos commits para um repositório remoto. Publicar o produto é outra operação, que depende de como o sistema é colocado em uso.

   Isso é diferente de bmad-project-context, que nunca faz commit. Também significa que o exercício oficial que pede deixar mudanças na pasta de trabalho não deve ser lido como uma garantia universal de ausência de commit. O padrão instalado precisa ser considerado.

   Recomendação da aula: antes de enviar ou publicar, confira o resumo, o comportamento e os arquivos incluídos. Se a organização exige aprovação, siga essa regra. A Aula 05 explica o envio do histórico; a Aula 06 diferencia construção e publicação.

Quando uma regra nova aparece durante a revisão

O código instalado do Build orienta adiar propostas de mudança em AGENTS.md ou CLAUDE.md em vez de incluí-las silenciosamente na correção do produto. Leve o aprendizado para bmad-project-context record, na Fase 05.

Também não espere que toda execução chame bmad-help sozinha. A página de projetos existentes generaliza essa chamada no fim de cada fluxo, mas o Build instalado só executa a ação de conclusão configurada, e o padrão de on_complete está vazio. Você pode chamar /bmad-help manualmente quando precisar de orientação.

Ao terminar esta etapa

• A entrega atende à intenção da mudança.
• Você conhece as verificações executadas e as lacunas.
• O diff está dentro do alcance combinado.
• Sabe se houve commit local e qual foi ele.
• O trabalho adiado está registrado.
• Aprendizados sobre instruções foram encaminhados para manutenção de contexto.

Use esse caminho quando a mudança precisa de várias sessões, quando decisões têm de sobreviver entre conversas ou quando várias partes precisam obedecer ao mesmo contrato. Um épico, no vocabulário do BMAD, reúne várias unidades de trabalho para alcançar um resultado coerente. Um projeto maior pode reunir vários épicos.

O tamanho do código existente não decide sozinho. Um sistema grande pode receber uma mudança pequena diretamente pelo Build. Uma mudança aparentemente curta pode merecer planejamento porque mexe em dados, permissões, integrações ou decisões difíceis de reverter.

O contexto acompanha o plano, mas não vira um catálogo do sistema

Dê à skill os documentos necessários e peça que leia a implementação relevante. O contrato deve nomear o comportamento existente que precisa continuar, as regras vigentes e o que será alterado. A documentação alerta que requisitos de projeto existente, quando ignoram o que já funciona, tendem a exigir retrabalho na construção.

Ao mesmo tempo, não entregue todo o arquivo histórico da empresa por hábito. Planejamento antigo pode explicar decisões importantes, mas não é automaticamente uma descrição correta do produto atual. A documentação de projetos existentes recomenda manter o histórico disponível para as sessões que precisam dele e fora da descoberta habitual de uma mudança pequena. Isso é organização do acesso, não uma ordem para apagar documentação.

A skill diferencia documentos complementares e fontes já absorvidas. Complementares, declarados em companions:, fazem parte do contrato que o próximo trabalho precisa ler. Fontes em sources: servem à rastreabilidade quando seu conteúdo importante já foi incorporado. Rastreabilidade é conseguir apontar de onde veio uma decisão. Não esconda uma regra necessária apenas em uma fonte que o implementador não vai carregar.

1. 1

   Dar uma intenção suficientemente definida

   Vamos ampliar o exemplo fictício: a empresa quer permitir que cada usuário salve filtros pessoais na listagem. O resultado exige decidir o comportamento, a persistência e a integração com a tela existente. Persistência é a forma de guardar informação para continuar disponível depois da sessão.

   Pelo Claude Code

   Pelo Claude Code — Pedido de exemplo

   Pedido — exemplo para o Claude Code

   /bmad-spec Crie uma spec chamada filtros-salvos para acrescentar filtros pessoais
   à listagem de pedidos deste projeto existente.
   
   Leia as instruções do projeto, a implementação da listagem, os filtros atuais
   e os testes relevantes antes de escrever. Use os documentos atuais necessários
   como referências verificáveis.
   
   Quero que cada usuário possa salvar um nome e a combinação de filtros,
   reaplicar um filtro salvo e excluir os próprios filtros salvos.
   Preserve a autorização de acesso aos pedidos, o cálculo dos totais e os filtros
   que já funcionam. Não inclua compartilhamento entre usuários, notificações
   ou um novo sistema de login.
   
   Registre as lacunas e suposições sem inventar regras de negócio.
   Quero revisar a proposta nesta conversa antes de decidir a divisão em stories.

   Pelo terminal

   Pelo terminal, use o Claude Code interativo da Etapa 03.

   O nome filtros-salvos e os requisitos são exemplos. A saída padrão correspondente seria a pasta _bmad-output/specs/spec-filtros-salvos/, caso a configuração de saída mantenha o padrão. A skill usa o mesmo nome curto para voltar à mesma pasta em atualizações.

   Este Pedido não foi executado, e a aula não contém uma spec gerada desse sistema fictício.

2. 2

   Entender o que a spec organiza

   Campo real	Pergunta de negócio que ele responde	Aplicação ao exemplo
   Why	Por que fazer isso?	Evitar que o usuário refaça filtros frequentes
   Capabilities	O que será possível e como verificar?	Salvar, aplicar e excluir filtros próprios
   Constraints	Quais limites influenciam a solução?	Respeitar a autorização e o funcionamento existente
   Non-goals	O que fica explicitamente fora?	Compartilhamento e notificações
   Success signal	Qual demonstração concreta indica sucesso?	Salvar um filtro e reaplicá-lo no uso previsto

   A aplicação é editorial e ainda depende das decisões reais do projeto.

   Cada capacidade precisa de intenção e critério de sucesso. Dizer apenas “ter filtros melhores” não informa como aceitar a entrega. Quando detalhes essenciais não cabem no núcleo, a skill cria complementos. Diagramas, quando usados na spec, ficam em um complemento, não dentro do núcleo de SPEC.md.

3. 3

   Escolher o que fazer com lacunas

   A documentação recomenda chegar com uma intenção definida. O código instalado também trata entradas menos completas: se há material suficiente, oferece um caminho express, que organiza o que existe e registra lacunas, ou guided, que percorre os cinco campos com você. São opções da conversa, não flags do comando de terminal.

   Se a ideia é vaga demais para virar contrato, a skill deve parar e sugerir outro trabalho de definição, como bmad-prd. Ela não deve preencher o vazio inventando como seu negócio funciona. A Fase 04 não transforma a spec em uma máquina de descobrir a estratégia da empresa.

   Há também o modo sem interação, chamado headless. A skill pode detectá-lo quando não há terminal interativo, quando recebe uma chamada programática de outra ferramenta ou skill, ou quando a primeira mensagem já fornece todas as entradas e pede apenas o caminho do artefato de volta. Portanto, o modo depende também da forma de chamada e do Pedido, não só da janela que você abriu. Na versão instalada, esse modo usa o caminho expresso por padrão e devolve uma resposta estruturada. Ele não faz Story Breakdown, mesmo que o texto peça isso. Story Breakdown é a divisão da spec em unidades de trabalho. Nesta aula, mantenha uma conversa de fato interativa, com revisão das decisões, para essa divisão.

4. 4

   Conferir coerência e preservação

   A skill verifica se o contrato está coerente e se preservou os pontos relevantes das fontes. Você deve conferir sobretudo o que não pode desaparecer entre sessões: permissões existentes, integrações, formatos de dados e limites aprovados. Os exemplos variam por projeto; a exigência de preservar o que muda decisões vem da própria skill.

   A pasta também contém .memlog.md, o registro acumulado das decisões usado para derivar a spec. “Derivar” significa reconstruir o documento a partir desse registro e das fontes. Por isso, a skill instalada não considera a edição manual de SPEC.md por fora o caminho de atualização suportado: a próxima derivação pode sobrescrevê-la.

   Pedido — exemplo para corrigir uma decisão na spec

   Pedido — exemplo para o Claude Code

   /bmad-spec Atualize a spec em _bmad-output/specs/spec-filtros-salvos/.
   Esclarecimento do exemplo: nomes iguais são permitidos entre usuários diferentes,
   mas não entre os filtros salvos da mesma pessoa.
   
   Registre a decisão, confira as capacidades e as restrições afetadas e valide
   a preservação do contrato. Se já houver stories.yaml, diga quais stories
   precisam ser revistas; não presuma que a lista ficou atualizada sozinha.

   O esclarecimento é fictício. A atualização precisa vir de uma decisão real sua.

Ao terminar esta etapa

• O contrato descreve a mudança, sem reescrever toda a documentação do produto.
• O que deve continuar funcionando está explícito.
• Lacunas e suposições continuam visíveis.
• A pasta e os complementos necessários foram identificados.
• Você sabe como pedir atualização sem criar uma segunda fonte conflitante.

Uma spec que exige várias sessões precisa de uma ordem de execução. Na 6.12, você pode pedir à própria bmad-spec a divisão interativa em stories. Ela escreve stories.yaml ao lado de SPEC.md. YAML é um formato de arquivo estruturado; aqui ele organiza os dados da lista de trabalho.

1. 1

   Dividir com critérios de revisão

   Pelo Claude Code

   Pelo Claude Code — Pedido de exemplo

   Pedido — exemplo para o Claude Code

   /bmad-spec Faça Story Breakdown da spec em
   _bmad-output/specs/spec-filtros-salvos/ nesta conversa interativa.
   
   Proponha unidades que possam ser implementadas e revisadas separadamente,
   na ordem necessária para chegar ao resultado completo. Não fixe uma quantidade
   de stories antes de ler o contrato.
   
   Explique a dependência entre as partes e proponha, para discutirmos,
   as paradas de revisão antes e depois da implementação.

   Pelo terminal

   Pelo terminal, mantenha o Claude Code interativo.

   O Pedido é exemplo editorial.

   Não use um executor sem interação esperando o mesmo resultado, porque o código de Story Breakdown o proíbe nessa modalidade.

   A skill pede decisões sobre spec_checkpoint e done_checkpoint. O primeiro identifica uma parada para conferir o plano daquela unidade; o segundo, uma parada para conferir sua entrega. invoke_dev_with pode guardar uma orientação adicional para quem iniciar a implementação. Esses campos orientam quem organiza a execução; não são uma garantia de que colar qualquer Pedido no Build vai aplicar sozinho todas as paradas.

   No percurso manual desta aula, você organiza a sequência. Antes de iniciar uma unidade, leia esses campos e cumpra as paradas escolhidas. Se houver texto em invoke_dev_with, inclua essa orientação no Pedido que entrega a story ao Build. Ao receber a pasta e o identificador, o roteamento do Build usa o título e a descrição da story como intenção inicial; não descreve uma leitura automática dos campos de controle para organizar todo o trabalho.

   Por exemplo, se a orientação escolhida pede revisão do plano antes de construir, acrescente essa exigência ao Pedido daquela unidade e confira que ela foi respeitada. Se o combinado é revisar a entrega, mantenha a próxima story pendente até terminar a conferência. Esse exemplo é uma aplicação editorial dos campos; não acrescenta um modo novo nem exige um orquestrador, programa que coordena várias execuções automaticamente. A presença do YAML, por si só, não conduz a sequência.

   Recomendação desta aula: acompanhe as primeiras unidades, principalmente quando estabelecem padrões que as demais vão repetir. A própria documentação recomenda dar atenção humana às histórias iniciais, arriscadas ou fundamentais.

2. 2

   Executar uma story por vez

   Leia o identificador real em stories.yaml antes de copiar. O número abaixo é ilustrativo; não garante que a primeira story do seu projeto terá esse identificador.

   Pedido — exemplo

   Pedido — exemplo para o Claude Code

   /bmad-build Implemente a story de id "1" da pasta
   _bmad-output/specs/spec-filtros-salvos/.
   
   Use stories.yaml para identificar a unidade e leia SPEC.md com seus
   complementos necessários. Respeite as instruções atuais do projeto.
   Explique o que será reutilizado e o que será preservado.
   Quero conferir esta unidade antes de iniciar a próxima.

   Texto e caminho concreto são exemplos editoriais; o fluxo não foi executado para a aula.

   Conclua a revisão de uma unidade antes de iniciar a seguinte quando houver dependência entre elas. A lista em stories.yaml define a ordem. O arquivo não guarda um campo geral de status de cada execução; os registros de implementação carregam o andamento do trabalho.

   O Build executa uma unidade; não assume a gestão de toda a lista nem escolhe automaticamente qual story deve vir depois. Essa distinção evita que você interprete “concluído” como “toda a funcionalidade está pronta”.

   Ver em texto

   1. Descreva o resultado da mudança maior.
   2. Leia as regras vigentes e o código relevante.
   3. Use bmad-spec para criar o contrato.
   4. Se o contrato não está suficientemente definido, resolva as lacunas e atualize a spec. Confira novamente antes de continuar.
   5. Com o contrato definido, faça a divisão interativa em stories.
   6. Execute bmad-build para uma unidade e confira sua entrega local.
   7. Se o trabalho revelar uma mudança no contrato, atualize a spec e reveja as stories antes de continuar a implementação apropriada.
   8. Se não houve mudança no contrato e faltam unidades, execute a próxima, respeitando a ordem e as dependências.
   9. Quando todas estiverem concluídas, verifique o resultado conjunto.
   10. Decida se executará a retrospectiva recomendada. Se sim, use bmad-retrospective para revisar o épico; se não, siga ao registro das evidências e pendências da conferência. O caminho de planejamento recomenda essa skill; a introdução a projetos existentes a apresenta como opcional.
   11. Registre evidências e pendências do fechamento. Esse registro final é uma recomendação editorial; não promete um novo arquivo automático quando você opta por não executar a retrospectiva.

   O diagrama é uma simulação do percurso, não um registro de execuções.

3. 3

   Atualizar o plano quando o trabalho ensinar algo novo

   A divisão não é uma promessa de que o plano nunca muda. Uma story pode revelar uma restrição que altera outra. A documentação manda atualizar a spec e refazer a divisão quando necessário.

   Há uma diferença importante: atualizar a spec não reescreve automaticamente stories.yaml. Se a skill perceber incompatibilidade, oferece refazer a divisão. Revise isso explicitamente antes de entregar o próximo Pedido ao Build.

   Também não espalhe a correção só por conversas antigas. Se a decisão deve orientar o restante do trabalho, ela precisa entrar no contrato. Se passou a ser uma regra duradoura do projeto, use ainda a manutenção de contexto da Fase 05, com a verificação correspondente.

4. 4

   Verificar as partes funcionando juntas

   No exemplo fictício, não basta conseguir salvar um filtro em uma story e listar nomes em outra. É preciso salvar, reencontrar, aplicar e excluir no uso real previsto, preservando o acesso de cada usuário. Uma integração pode falhar mesmo quando cada unidade isolada passou. A documentação pede verificações conjuntas no fechamento do épico.

   Depois disso, o caminho de planejamento recomenda executar bmad-retrospective a partir da pasta da spec. A introdução a projetos existentes apresenta essa retrospectiva como opcional; nesta aula, recomendamos usá-la no fechamento de uma mudança maior. Retrospectiva é a revisão do resultado e das evidências do trabalho, incluindo o que foi aceito e o que ficou pendente. No caminho de spec, a skill usa stories.yaml como inventário e escreve RETROSPECTIVE.md na mesma pasta.

   Pelo Claude Code

   Pedido — exemplo

   Pedido — exemplo para o Claude Code

   /bmad-retrospective Revise o épico em
   _bmad-output/specs/spec-filtros-salvos/.
   
   Use stories.yaml, os registros de implementação e o contrato de SPEC.md.
   Avalie o resultado integrado e diferencie evidência observada, pendência
   e suposição. Mostre o veredito de aceitação e os próximos trabalhos propostos.

   Pelo terminal

   Pelo terminal, use a conversa interativa da Etapa 03.

   O Pedido é exemplo; a retrospectiva não foi executada nesta aula.

   Esse fechamento não publica a aplicação nem elimina a necessidade de conferir o produto.

   Veredito registrado	Como interpretar
   accepted	Critérios demonstrados, sem impedimento e com todas as unidades concluídas
   accepted-with-open-items	Critérios atendidos e unidades concluídas, mas há pendências identificadas que continuam acompanhadas
   rejected	Há falha nos critérios, impedimento ou unidade ainda inacabada

   A decisão humana pode divergir do veredito da avaliação, mas a divergência precisa ficar registrada. No modo baseado na pasta de spec, a retrospectiva propõe reconciliações; não reescreve automaticamente SPEC.md, stories.yaml ou os registros das unidades.

Ao terminar esta etapa

• Cada unidade foi identificada e implementada com o contrato correto.
• Mudanças de escopo voltaram à spec.
• A lista de stories foi revista quando necessário.
• O comportamento conjunto foi verificado.
• O fechamento distingue resultado aceito e pendências.

Pule esta etapa se a intenção está definida, a spec cobre as decisões e a mudança cabe em um único resultado dividido em unidades. Use-a quando ainda falta um acordo sobre o produto, a experiência de uso ou a organização técnica. A documentação trata os recursos de planejamento como ferramentas escolhidas conforme a lacuna, não como uma fila obrigatória para toda mudança.

Criar, atualizar ou validar um documento existente

As três skills de PRD, UX e arquitetura distinguem criar, atualizar e validar. Criar produz o documento; atualizar incorpora decisões ao trabalho existente; validar examina a qualidade e aponta problemas sem transformar a avaliação em uma reescrita silenciosa. Diga qual intenção você tem.

Os caminhos completos dependem da configuração e são informados na execução. HTML é o formato de uma página visualizável no navegador; Markdown é o formato de texto usado neste rascunho.

No PRD, o caminho rápido prepara um rascunho com suposições; o acompanhado discute as decisões com você. Em UX, também há caminhos rápido e acompanhado, além do encaminhamento para uma ferramenta externa quando essa for a escolha do trabalho. No caminho rápido de UX, a skill pula os recursos criativos opcionais. Esses atalhos não transformam suposições em decisões aprovadas.

Para esta aula, prefira acompanhar os pontos que dependem do conhecimento da empresa. Os modos sem interação dessas skills pertencem a outro tipo de execução e podem terminar com perguntas, suposições ou impedimentos. Eles não dispensam decidir corretamente o que deve mudar.

Se falta acordo sobre o produto

bmad-prd tem as intenções de criar, atualizar e validar. Em um projeto existente, começar por uma atualização ou avaliação do documento atual pode ser mais adequado do que produzir outro concorrente. A escolha depende do que existe e de quem precisa aprová-lo.

Pedido — exemplo

/bmad-prd Quero atualizar os requisitos desta iniciativa no projeto existente.
Localize e leia o PRD atual e os documentos relevantes antes de propor mudanças.
Diferencie o que já funciona, o que deve continuar e o que a iniciativa acrescenta.
Se não encontrar um PRD aplicável, mostre a lacuna antes de criar outro documento.

O Pedido é exemplo e não foi executado. Não entregue requisitos antigos como se sua simples existência provasse que eles continuam vigentes.

Se a mudança altera a experiência de uso

A documentação recomenda trabalho de UX quando a mudança cria ou altera telas, fluxos ou padrões. Você pode dispensar essa etapa para uma atualização simples de uma tela cuja organização já está adequada.

Pedido — exemplo

/bmad-ux Defina a experiência da mudança de filtros salvos no projeto existente.
Leia as telas, os componentes e os documentos de experiência atuais.
Mostre o que será reutilizado e quais estados novos precisam ser definidos.
Preserve o contrato da spec e registre as decisões que as próximas stories
precisam seguir.

O texto é exemplo editorial. A skill registra decisões de aparência e comportamento em DESIGN.md e EXPERIENCE.md; esses documentos pertencem ao fluxo de UX e podem ser referências necessárias da spec.

Se falta uma decisão técnica compartilhada

A skill de contexto não deve escolher sozinha entre desenhos técnicos realmente disputados, com alternativas viáveis e consequências diferentes. Esse trabalho pertence a bmad-architecture.

Pedido — exemplo

/bmad-architecture Avalie as decisões técnicas necessárias para esta mudança
no projeto existente. Leia a arquitetura documentada, a spec e o código atual.

Explique quais mecanismos já atendem à necessidade, onde há uma decisão nova
e quais consequências cada alternativa traz. Não proponha substituir
a organização atual sem relacionar a proposta a uma necessidade da mudança.

O texto é exemplo. A saída padrão é ARCHITECTURE-SPINE.md, o documento principal das decisões de arquitetura. Confira o caminho informado pela skill e as opções do projeto.

Se UX ou arquitetura vieram depois da spec

Volte à bmad-spec para incorporar as decisões e adotar os documentos necessários como complementos do contrato, quando aplicável. Apenas criar DESIGN.md, EXPERIENCE.md ou ARCHITECTURE-SPINE.md em alguma pasta não significa que a próxima story receberá todas essas decisões. A spec usa companions: para indicar os documentos que fazem parte do contrato; a skill de arquitetura recomenda levar seu documento principal para essa adoção ou atualização.

/bmad-spec Atualize a spec da mudança com as decisões de UX e arquitetura
que acabamos de concluir. Use a pasta real da spec e os caminhos reais
dos documentos produzidos nesta iniciativa.

Confira quais documentos precisam ser adotados em companions e quais fontes
já foram absorvidas. Preserve as restrições do sistema existente e mostre
conflitos antes de resolver decisões de negócio por conta própria.
Se a mudança afetar stories.yaml, proponha rever a divisão nesta conversa.
Relate os documentos incorporados e as pendências que permaneceram.

Esse Pedido é ilustrativo, não foi executado e pressupõe que você forneça os caminhos reais ou que eles estejam disponíveis na conversa.

A adoção dos complementos e a revisão de stories são ações previstas na skill de spec; não significam aprovação automática de toda decisão produzida em outra sessão.

Quando a iniciativa vira um projeto maior

Vários resultados independentes, coordenação entre equipes e decisões que atravessam sistemas pedem planejamento compartilhado. A documentação usa cerca de vinte ou mais sessões como um sinal de escala de projeto, não como um limite automático. Risco e coordenação podem justificar planejamento antes disso.

A Aula 06 — Fluxo completo aprofunda requisitos, experiência, arquitetura e organização do trabalho. A Aula 07 — Brainstorm e criatividade ajuda quando o problema ainda pede exploração de alternativas. Volte à spec quando houver uma intenção suficientemente definida.

Ao terminar esta etapa

• Cada documento pedido resolve uma lacuna identificada.
• Os responsáveis sabem o que precisa de decisão.
• O plano cita o sistema existente e as restrições atuais.
• Você não confundiu tamanho do repositório com tamanho da mudança.

Use refresh quando o projeto mudou desde a última verificação do bloco. O modo lê a procedência registrada, reconfere caminhos e ressalvas e compara exclusões e renomeações desde o commit de referência. Ele não deve repetir toda a entrevista inicial: pergunta o que mudou na forma de trabalhar.

Não confunda atualizar contexto com atualizar o BMAD. Atualizar o BMAD troca componentes da instalação; atualizar contexto revê o que as instruções dizem sobre o seu projeto.

Quando vale revisar

Recomendação prática, baseada nas verificações previstas pela skill: faça um refresh depois de mover uma área importante, mudar a maneira correta de testar, alterar uma integração, estabelecer uma convenção ou concluir uma mudança que invalida uma instrução anterior. Não é necessário abrir uma sessão de manutenção para cada correção de vírgula.

O exemplo real do guia mostra o motivo. A orientação “Ainda não há código” deixou de descrever o projeto quando o site passou a existir. A data e o commit antigos ajudam a localizar o que precisa ser reconferido. A solução é revisar a instrução com evidência; acrescentar outra frase dizendo o contrário criaria duas ordens simultâneas.

/bmad-project-context refresh O projeto mudou desde a última verificação
do bloco. Releia a procedência, confira caminhos, comandos e ressalvas
e compare com o estado atual.

Mostre quais instruções continuam corretas, quais perderam a evidência
e quais precisam de atualização. Não repita perguntas já resolvidas.
Apresente o bloco completo e as decisões sobre qualquer alteração ou remoção
antes de escrever. Não faça commit.

O texto é exemplo; o procedimento não foi executado para a aula.

O que conferir na atualização

Um arquivo renomeado pode exigir corrigir o caminho. Uma regra pode continuar válida mesmo que o arquivo que a exemplificava tenha mudado. A skill precisa verificar a evidência e o compromisso, não apenas substituir nomes por aproximação. Quando a fonte de uma afirmação desaparece, a teoria do método manda corrigir ou remover a afirmação de modo justificado, sem apontá-la silenciosamente para outro texto parecido.

Também confira a nova linha de procedência. Ela precisa corresponder à verificação realizada. Se havia mudanças ainda não salvas, a apresentação deve deixar isso claro; o exemplo real do guia registra essa ressalva.

A atualização pode acrescentar contexto quando há evidência nova. Não use essa abertura para transformar o bloco em um diário de tudo que aconteceu. A instrução deve dizer a regra atual; o histórico já tem outro lugar.

Ao terminar esta etapa

• Caminhos e ressalvas apontam para o projeto atual.
• Regras aposentadas têm justificativa.
• Não ficaram instruções contraditórias em arquivos carregados.
• A procedência informa o que foi conferido.
• Você revisou e salvou a mudança conforme a política do projeto.

Quando a IA erra a mesma coisa duas vezes, vale investigar por que o processo não está impedindo a repetição. A skill oferece record para tratar um erro observado: recebe a tarefa, o erro, a correção e a evidência. Antes de criar uma regra, confere se já existe uma que cobre o caso.

Isso não significa esperar uma segunda ocorrência de um erro caro. O código instalado diz que um erro recorrente ou caro já pode merecer uma linha. Uma ocorrência isolada pode ser anotada sem virar imediatamente instrução permanente.

1. 1

   Trazer evidência suficiente

   No exemplo fictício, imagine que duas sessões tentaram criar um componente novo para uma mensagem que já tinha um componente padrão. A correção não é necessariamente “jamais crie componentes”. Pode ser “nas listas deste produto, use o componente de estado vazio existente; proponha outro só quando ele não atender ao estado necessário”.

   Antes de gravar essa frase, a skill precisa localizar o componente, conferir seu uso e entender o erro. Os caminhos e ocorrências abaixo são campos para você preencher, não arquivos reais desta aula.

   Pelo Claude Code

   Pelo Claude Code — Pedido de exemplo

   Pedido — exemplo para o Claude Code

   /bmad-project-context record Quero registrar um erro observado.
   
   Tarefa: melhorar a mensagem de lista vazia.
   Erro: em duas sessões, a IA criou um componente novo apesar de já existir
   um componente adequado no projeto.
   Correção: reutilizar o componente existente quando ele atender ao estado
   necessário e justificar qualquer exceção.
   Evidência: [substitua pelos arquivos, commits ou registros reais das ocorrências].
   
   Confira se uma instrução atual já cobre o caso e se ela chega à IA.
   Proponha a menor correção útil ou uma verificação automática que evite o erro.
   Mostre a mudança antes de escrever. Não faça commit.

   Pelo terminal

   Pelo terminal, use a conversa interativa da Etapa 03.

   O exemplo foi criado para a aula e não descreve um erro observado no sistema fictício. Substitua a evidência antes de usar.

2. 2

   Descobrir se falta regra ou se falta carregamento

   Se a regra já existe, acrescentar uma cópia não resolve a causa. Verifique se ela está num arquivo carregado, se há uma instrução concorrente ou se a frase é vaga. “Siga os padrões” pode não dizer qual padrão está em disputa; um apontamento concreto pode ajudar.

   Se o erro envolve um comando, a correção pode entrar na seção de execução e verificação com a chamada correta. Para outros erros, a skill pode propor uma armadilha. Não crie um comando universal nesta aula: a forma certa deve ser conferida no projeto do leitor.

3. 3

   Preferir uma prevenção verificável quando ela serve

   Alguns erros podem ser detectados por uma verificação automática. Se uma importação proibida pode fazer o teste falhar, esse impedimento pode ser mais confiável do que depender de uma frase lida corretamente. A skill deve propor a verificação; a equipe decide como incorporá-la ao projeto.

   Não remova a regra no momento em que alguém apenas concorda em criar essa verificação. Ela só pode sair por esse fundamento quando a verificação está implementada e reprova a violação específica. Uma ferramenta que verifica “o mesmo assunto” não necessariamente impede o mesmo erro.

   Ver em texto

   1. Observe o erro e corrija o trabalho afetado.
   2. Reúna a tarefa, a ocorrência, a correção e sua evidência.
   3. Chame bmad-project-context no modo record.
   4. Se a regra já existe, confira se ela é carregada e se há contradições. Se não existe, avalie diretamente a correção duradoura.
   5. Avalie se uma verificação automática pode impedir o erro.
   6. Se puder, proponha essa verificação. Caso contrário, confira se o erro é recorrente ou caro: se for, proponha uma instrução útil; se for uma ocorrência isolada que não justifica a regra, anote a evidência e observe a próxima execução.
   7. Quando houver mudança proposta, revise e aprove antes da escrita. Uma regra existente continua até a prevenção automática estar funcionando.
   8. Se houve revisão do contexto, salve-a conforme a política do projeto.
   9. Observe a execução seguinte para conferir se a causa foi tratada.

   A observação da próxima execução é recomendação prática desta aula; não há promessa de que uma regra textual elimine todo erro.

Ao terminar esta etapa

• O erro foi descrito com evidência.
• Você sabe se o problema era ausência de regra, carregamento ou contradição.
• A solução não duplicou instruções.
• A automação proposta, quando houver, tem uma violação concreta para impedir.
• O registro é útil para a próxima sessão.

Use audit para reexaminar o contexto quando ele parecer extenso, contraditório ou pouco confiável. Auditar significa conferir afirmações e suas evidências. A skill deve revisar cada ressalva, caminho, referência e afirmação sobre comandos, além de buscar contradições com outros arquivos de instrução.

A diferença para refresh está no objetivo. refresh acompanha mudanças reais do projeto e pode crescer com evidência nova. audit faz revisão e redução: o bloco termina menor ou igual. Se a auditoria revelar a necessidade de novo conteúdo, trate essa inclusão em uma manutenção apropriada; não use “auditoria” como justificativa para acrescentar páginas.

/bmad-project-context audit Audite as instruções deste projeto.
Confira cada caminho, referência e afirmação sobre comandos.
Procure contradições e duplicações entre os arquivos que a ferramenta carrega.

Mostre o que está desatualizado, o que falta, o que continua bom
e o destino proposto para as instruções afetadas.
Não exclua uma política ou armadilha só porque não houve erro recente.
Apresente a proposta e as justificativas antes de escrever. Não faça commit.

O texto é exemplo e não foi executado.

Quando uma regra não deve sair

Uma regra pode estar funcionando justamente porque ninguém voltou a cometer o erro. A ausência de falhas recentes não é evidência de inutilidade. Política e armadilha só saem quando o que protegem deixou de existir ou quando a pessoa responsável as aposenta, respeitando as decisões de revisão.

Também não retire uma regra humana só porque ela é longa ou porque a IA consegue localizar parte do assunto em outro lugar. Reescrever, mover para um documento realmente consultado ou automatizar pode ser melhor. Se a remoção não tem fundamento, a decisão deve ser exposta, não escondida dentro de um bloco mais curto.

Uma rotina simples para a empresa

Esta é uma recomendação editorial, baseada nos três modos de manutenção:

1. Depois de uma mudança significativa, avalie refresh.
2. Quando um erro relevante acontecer, registre a ocorrência e avalie record.
3. Quando o contexto ficar contraditório ou difícil de usar, execute audit.
4. Revise e salve as instruções junto do trabalho, seguindo a política da equipe.
5. Na próxima mudança, confira que as regras relevantes foram consideradas.

O método não fixa uma frequência de calendário para essas ações; os acontecimentos do projeto ajudam a escolher o momento.

Outras aulas para apoiar este trabalho

• Para preparar o ambiente: Aula 04 — Instalação no macOS.
• Para salvar e compartilhar o trabalho: Aula 05 — Git e GitHub.
• Para aprofundar uma iniciativa maior: Aula 06 — Fluxo completo, da ideia ao go-live.
• Para escolher outro ponto de partida: Ver todas as aulas.

A sequência desta parte do guia é Aula 08 — Usar só uma parte do BMAD → Aula 09 — BMAD em um projeto que já existe → Aula 10 — Customizar o BMAD. A Aula 11 — Módulos avançados: Builder, Test Architect e Loop vem depois da customização; esses módulos não são requisito para cumprir esta aula, cujo caminho de contexto, spec e Build já está coberto por core e BMM.

Ao terminar esta etapa

• O contexto continua pequeno o suficiente para ser útil.
• O que saiu tem uma justificativa verificável.
• As regras importantes continuam chegando à IA.
• A equipe sabe quando atualizar, registrar e auditar.
• Você consegue iniciar outra mudança sem reconstruir toda a história do projeto.

1. Já tenho CLAUDE.md. Preciso apagá-lo?

   Não. Use adopt para avaliar seu conteúdo. A skill pode propor que ele passe a importar AGENTS.md, mas precisa mostrar o destino das regras anteriores e verificar o carregamento. Se alguma instrução precisa ficar onde está, isso deve aparecer na proposta. Não substitua um arquivo valioso por uma importação sem a avaliação.

2. Pedi setup, mas a skill quer adotar. Ela entendeu errado?

   Pode ter entendido corretamente. O código manda detectar conteúdo significativo nos arquivos de instrução e preferir adoção quando há dúvida. setup não é uma ordem para apagar regras encontradas. Confira o que ela identificou e siga o modo que preserva o material útil.

3. Não encontrei as skills antigas de documentar o projeto. Minha instalação está incompleta?

   Não necessariamente. A documentação informa que bmad-document-project e bmad-generate-project-context foram substituídas por bmad-project-context. A disponibilidade dos encaminhadores antigos depende da instalação. O manifesto do guia registra installShims: false; por isso a aula ensina diretamente o nome atual. Se houver project-context.md antigo, a skill deve oferecer adoção do conteúdo.

4. O instalador terminou, mas bmad-build reclama de uv. Posso mandar pular isso?

   Não trate a instalação concluída como prova de que os requisitos de todas as skills estão atendidos. O instalador pode apenas avisar que falta uv. A entrada instalada do Build exige preparar seu fluxo por meio do script previsto e parar se essa preparação falhar. Corrija o requisito conforme a Aula 04; não peça à IA que execute os arquivos internos por um caminho improvisado.

5. Colei /bmad-project-context no terminal e não funcionou. O nome está errado?

   O Pedido pertence à conversa com o Claude Code. Abra a ferramenta na pasta do projeto e cole o Pedido ali. A alternativa pelo terminal é iniciar essa conversa com claude, conforme a Etapa 03. Se a skill não é reconhecida dentro da ferramenta, confira a integração e o resumo do instalador antes de tentar outra versão.

6. Usei --yes numa instalação antiga e o idioma não mudou. Por quê?

   Na rota instalada examinada, --yes encaminha normalmente a instalação existente para atualização rápida. Essa rota reaproveita a configuração anterior e não reaplica os parâmetros comuns de instalação nova. Volte à Etapa 03 e use o caminho de modificação com as escolhas conferidas. Não repita o mesmo comando esperando um efeito diferente.

7. O bloco ficou enorme. Devo mandar reduzir pela metade?

   Peça uma auditoria com justificativas por regra, não um corte por porcentagem. Um inventário copiado do código pode sair; uma proibição decisiva não deve desaparecer para cumprir uma meta estética. Se houver instruções que só valem numa parte do sistema, a divisão depende de carregamento verificado.

8. A IA citou um arquivo que não existe. Aprovo e corrijo depois?

   Peça que verifique o caminho antes de gravá-lo como regra. A skill deve conferir toda afirmação que nomeia arquivo e ler o que sustenta afirmações sobre comandos. Um caminho inventado vira uma instrução inútil para as próximas sessões.

9. AGENTS.md e CLAUDE.md dizem coisas diferentes. Qual deles vence?

   Não use uma aposta sobre precedência como manutenção. A skill deve localizar a contradição, mostrar seu efeito e propor uma correção explícita nos arquivos envolvidos. A forma de carregamento também precisa ser conferida. Duas instruções ativas e incompatíveis são um defeito do contexto.

10. A IA continua repetindo o erro mesmo com uma regra escrita. Acrescento outra?

    Comece por record com a ocorrência e confira se a regra já cobre o caso. Verifique carregamento, clareza e contradições. Se for uma violação que uma ferramenta pode impedir, proponha a verificação automática. Repetir a mesma frase em mais arquivos pode aumentar o custo sem resolver a causa.

11. O Build começou sem pedir aprovação do plano. Isso é previsto?

    Sim, quando a investigação escolhe a rota curta: mudança pequena, clara e reversível. Quando os fatores exigem mais cuidado, há plano completo e escolhas de aprovação. Se seu processo exige uma parada específica, ela precisa estar expressa nas instruções aplicáveis e no Pedido. Veja a divergência entre o exercício oficial e o código na Etapa 07.

12. O Build parou porque há mudanças pendentes. Preciso apagar tudo?

    Não. Confira quem produziu os arquivos e salve ou organize o trabalho conforme a política do projeto. A parada existe para não misturar uma tarefa nova com alterações já presentes. O código manda perguntar como prosseguir; não manda apagar os arquivos.

13. A spec mudou, mas stories.yaml continua igual. É um defeito?

    Não é atualização automática faltando: o código diz que atualizar a spec não reescreve a lista. Peça à bmad-spec que reveja as stories e faça Story Breakdown novamente na conversa interativa quando a mudança do contrato exigir.

14. Cada story passou nos testes. Posso considerar o conjunto pronto?

    Ainda precisa conferir a integração entre as partes. O planejamento da 6.12 pede verificações do resultado conjunto e recomenda executar a retrospectiva para avaliar o épico contra o contrato. Um sucesso isolado não demonstra que o percurso inteiro funciona.

15. Preciso instalar módulos avançados para trabalhar em um projeto antigo?

    O caminho desta aula usa bmm e as skills já incluídas nele, além da base compartilhada. Ser um projeto existente não cria, por si só, uma exigência de módulo adicional. Escolha outros módulos quando uma necessidade concreta justificar, como nos recursos criativos da Aula 07.

16. O tutorial oficial usa Django. Preciso copiar aquele projeto?

    Não. “Getting Deeper” é um exercício opcional em Django 5.2.4, com uma versão de código fixada, para demonstrar uma mudança pequena e depois uma spec com três stories. Você pode estudá-lo como laboratório. Ele não é um pré-requisito para adotar BMAD no seu sistema.

    A exclusão de pastas do BMAD em .git/info/exclude também é uma escolha daquele exercício, não uma política universal para sua empresa. Não copie esse trecho sem decidir o que sua equipe precisa compartilhar e versionar.

17. Encontrei instruções diferentes na documentação da internet. Qual sigo?

    Para reproduzir esta aula, use a instalação 6.12.4 e os links do branch V6.12 listados a seguir. O contrato editorial deste guia registra que docs.bmad-method.org já descreve a v7 e não deve fundamentar os fatos da 6.12. Quando documentação e código instalado divergem, esta aula informa a diferença e segue o instalado.

18. Posso aprovar tudo no automático e nunca mais revisar o contexto?

    A skill de contexto desta versão é sempre conversacional e exige aprovação das escritas. Além disso, regras podem perder validade quando o projeto muda. Use os modos de manutenção para conservar o que é verdadeiro e útil. A versão do método não transforma um documento antigo em uma descrição permanentemente correta.