Customizar o BMAD

Na seção “Make it yours”, a BMad Code resume a proposta em “Customization and modularity, without forking.” Em tradução livre: customização e módulos sem manter uma cópia própria do método. A ideia é guardar suas escolhas ao lado da instalação, em arquivos separados. Esta aula verifica os mecanismos da 6.12.4 no código; a página institucional entra como contexto, não como manual de comandos.

Você não precisa aplicar todos os exemplos. Comece pela repetição que mais atrapalha seu trabalho. Se você sempre pede “escreva para quem não é técnico”, esse é um bom candidato. Se uma regra só serve para o assunto de hoje, deixe-a no Pedido de hoje. Tornar tudo permanente cria instruções que alguém terá de revisar depois. Essa é a recomendação editorial desta aula.

O percurso tem cinco fases: entender as camadas, customizar pelo chat, experimentar exemplos, levar para a equipe e atualizar com cuidado. Os exemplos usam a Rota Clara, uma empresa fictícia de serviços de entrega. Nome de empresa, regras, caminhos de documentos internos e texto dos Pedidos são exemplos autorais; não são arquivos encontrados no seu projeto nem resultados de uma execução.

Como ler as fontes. Referências começando por .claude/ e _bmad/ apontam para a instalação conferida no projeto do guia. Referências docs/, src/ e tools/ apontam para o código-fonte oficial da 6.12, salvo indicação explícita de documento editorial do guia. A lista de fontes no fim oferece os links públicos correspondentes.

Você também verá a palavra script: é um pequeno programa que automatiza uma tarefa, como conferir quais valores de configuração ficaram valendo. Nesta aula, usamos esses programas como alternativa à conferência pedida pelo chat.

Se ainda não instalou o BMAD, faça primeiro a Aula 04 — Instalação no macOS. Para aprender a guardar mudanças no histórico do projeto, consulte a Aula 05 — Git e GitHub. Você pode customizar uma única skill sem percorrer antes todo o fluxo da Aula 06.

Pedido para o Claude Code — exemplo autoral não executado

Confira, sem alterar arquivos, se esta pasta tem BMAD 6.12.4 instalado.
Leia o manifesto da instalação, localize bmad-customize e verifique se existem
os scripts resolve_customization.py e resolve_config.py em _bmad/scripts/.
Liste os arquivos existentes em _bmad/custom/, inclusive os pessoais e os ocultos,
sem exibir informações sensíveis. Diga o que já está customizado e o que é
apenas comentário de exemplo. Não instale nem atualize nada nesta conferência.

O nome bmad-customize, a localização dos scripts e a verificação de _bmad/ vêm do código instalado. O restante do Pedido descreve a conferência desejada, não opções formais de um comando.

Como conferir. Você deve receber a versão, os caminhos encontrados e um inventário do que existe. No projeto usado como fonte desta aula, _bmad/custom/ contém config.toml, config.user.toml e .gitignore; os dois arquivos de configuração contêm somente comentários, sem regras ativas. Não havia personalização por skill nessa pasta durante a leitura. A documentação diz que a pasta começa vazia, mas o instalador da 6.12.4 cria esses arquivos de exemplo quando faltam. Vale o comportamento do código.

• Ao terminar esta etapa: você sabe em qual projeto está, qual versão vai estudar e quais arquivos pode customizar. Pode pular a instalação se já conferiu esses pontos.

Uma sobreposição, também chamada de override na documentação, é um arquivo que guarda somente suas diferenças em relação ao padrão. Pense em um manual de empresa: o BMAD fornece a edição original; a equipe acrescenta suas escolhas; cada pessoa pode acrescentar as próprias preferências. O resultado usado pela skill é a combinação dessas camadas.

Por skill, são três camadas. O exemplo abaixo usa o agente de produto, mas o mesmo nome exato da pasta deve ser usado para qualquer outra skill personalizável.

Na configuração central, são quatro camadas. Ela guarda respostas da instalação, caminhos compartilhados e o cadastro dos agentes. Não confunda esse cadastro com o comportamento de uma skill específica.

Isso explica uma situação aparentemente estranha: uma decisão do time em _bmad/custom/config.toml vence uma resposta pessoal antiga em _bmad/config.user.toml. Porém, uma decisão em _bmad/custom/config.user.toml ainda pode substituí-la. A precedência é uma regra de combinação, não um mecanismo que impede alguém de contrariar a política da empresa. Se uma regra é obrigatória, o time também precisa conferi-la na revisão do trabalho.

Há três consequências práticas. Primeiro, repetir um fato em várias camadas pode deixá-lo repetido no resultado. Segundo, escrever uma frase contrária não apaga a frase antiga: você pode criar um conflito de instruções. Terceiro, misturar itens com code e itens somente com id impede a identificação de uma chave comum e pode transformar uma substituição esperada em acréscimo. Peça ao Claude Code para conferir o conjunto, não apenas o arquivo que acabou de escrever.

O instalador escreve *.user.toml no .gitignore de _bmad/custom/ quando esse arquivo de exclusões ainda não existe. .gitignore é a lista de padrões para arquivos que o Git deve ignorar ao incluir novos arquivos. Ela não retira do histórico arquivos que já estão sendo acompanhados. A recomendação pessoal também se aplica a _bmad/config.user.toml, mas não presuma que o nome sozinho o protege: o projeto do guia versiona esse arquivo de propósito, com um comentário explícito em seu .gitignore. Essa é uma escolha local, não o padrão recomendado para sua equipe. Não coloque senhas ou chaves em nenhum desses arquivos.

• Ao terminar esta etapa: você consegue explicar qual camada venceu e entende que uma lista pode somar, em vez de substituir.

Um exemplo de conflito para reconhecer. Imagine que o padrão de uma skill peça exemplos técnicos, o arquivo do time substitua communication_style por linguagem de negócio e o pessoal substitua o mesmo campo por respostas telegráficas. O estilo pessoal vence inteiro; ele não conserva automaticamente a frase do time. Já três entradas diferentes em persistent_facts são acumuladas. Por isso, “é a última camada” e “é o último item da lista” não significam a mesma coisa. Este é um exemplo autoral do comportamento de structural_merge, não uma execução de agente.

Identificadores também têm formato. Quando uma lista é reconhecida como identificada por code ou id, cada identificador precisa ser um texto não vazio, como "RN" ou "regras-privacidade". Um número ou texto vazio nesse papel causa erro no resolvedor. Copie a chave correta do catálogo da skill e evite inventar um identificador para tentar alterar um item existente: identificador novo acrescenta outro item.

Antes de pedir uma alteração, complete a frase: “Quero que essa regra valha quando…”. A resposta aponta para o arquivo certo. Uma preferência de conversa, um modelo de documento e um nome no cadastro de agentes não são a mesma customização.

Nos exemplos seguintes, PRD significa documento de requisitos do produto; UX significa experiência de uso, isto é, como as pessoas entendem e usam o produto. Uma persona é o jeito de agir e conversar atribuído a um agente. As Etapas 07, 09 e 10 aprofundam esses três assuntos.

Customizar um agente não transforma a regra em uma regra universal de qualquer chamada direta. A documentação descreve a regra acompanhando os fluxos que aquele agente conduz. Se você entrar direto em bmad-prd, trate os campos do próprio PRD como o lugar seguro para exigências daquele documento. Para uma regra universal curta, a documentação recomenda reforçá-la também no arquivo de instruções da ferramenta.

E se o campo não existir? A skill deve avisar que o pedido ultrapassa os pontos de customização disponíveis. Instruções no início do fluxo e fatos persistentes podem aproximar certos comportamentos, mas não prometem reescrever sua lógica. Para uma sequência própria, a documentação sugere criar uma skill própria. Isso é outro trabalho, com manutenção própria; não é necessário para os exemplos desta aula.

Pedido para o Claude Code — exemplo autoral não executado

bmad-customize Quero que os PRDs da Rota Clara sempre expliquem quem responde
pelo resultado e qual evidência comprova a necessidade. Confira o customize.toml
de bmad-prd e indique os campos existentes mais adequados. A regra deve valer
para o time, inclusive quando alguém chamar bmad-prd diretamente. Leia qualquer
customização existente antes de propor mudanças. Mostre o arquivo e a proposta.

Tudo depois de bmad-customize é um exemplo de conversa, não uma lista de parâmetros da skill. A documentação do BMAD admite pedir a skill pelo nome. No Claude Code, a chamada explícita de uma skill disponível pode usar / seguido do nome, como /bmad-customize; o nome sem barra nos Pedidos abaixo funciona como solicitação em linguagem natural para carregá-la. Confira que a skill foi realmente carregada, não apenas mencionada na resposta.

Quando pular. Se você já sabe a skill, o campo e o alcance, pode ir direto à proposta na próxima fase. Não existe um comando de terminal que transforme sozinho uma intenção de negócio em uma escolha correta de campos; a alternativa manual é ler o customize.toml, editar somente a sobreposição e executar os verificadores da Etapa 05.

Escolha um percurso proporcional ao trabalho. As linhas abaixo são alternativas, não uma fila de obrigações. A divisão por tamanho é uma recomendação editorial baseada nos alcances separados que a documentação oferece: preferência pessoal, persona, fluxo, modelo e adoção em equipe.

Se a repetição está no jeito de conversar, avance para a Etapa 07. Se está no documento produzido, prefira as Etapas 09–10. Se o problema é revisar uma regra recorrente no código, use a Etapa 08. Trabalhar num projeto já existente não exige renovar o instalador nem percorrer novamente o fluxo completo: primeiro confira o que já está customizado, para não substituir uma regra útil por outra igual.

bmad-customize é a skill que descobre os pontos disponíveis, escolhe o arquivo, propõe o TOML e confere o resultado combinado. Na versão instalada, seu alcance é a customização por skill, em [agent] ou [workflow]. Ela declara a configuração central fora de seu escopo. Por isso, o exemplo de idioma e nome da Etapa 06 usa um Pedido comum ao Claude Code, sem prometer que bmad-customize executa essa parte.

Passo 1. Descubra o que existe. Se você pedir para explorar, a skill lista agentes e fluxos personalizáveis e indica os que já têm arquivos do time ou pessoais. Se já nomear a skill e a mudança, ela pode ir direto à leitura do alvo. Se pedir uma auditoria, ela começa pelos que já foram customizados. Uma solicitação que afeta vários lugares precisa escolher explicitamente o alcance.

bmad-customize Liste as skills personalizáveis desta instalação, separando
agentes e fluxos. Mostre quais já têm customização do time ou pessoal.
Explique as opções de bmad-agent-pm, bmad-code-review, bmad-prd e bmad-ux.
Por enquanto, faça somente a descoberta e não grave arquivos.

Passo 2. Descreva uma mudança concreta. Diga qual skill, qual comportamento e se a regra é do time ou pessoal. “Melhore o BMAD” é vago; “O gerente de produto (John) deve explicar cada opção pelo impacto no prazo, no custo e no cliente” permite uma proposta verificável. A skill deve ler o customize.toml e as sobreposições existentes antes de compor a alteração.

Passo 3. Leia a proposta. A implementação instalada manda mostrar o TOML completo e, se o arquivo já existir, também a comparação com a versão anterior, esperar sua confirmação explícita e só então gravar. Confira o destino, o que entra e o que deixa de valer por substituição. Uma comparação de versões, também chamada de diff, mostra as linhas acrescentadas, alteradas e retiradas.

Passo 4. Confirme o resultado específico. Um exemplo de resposta, quando a proposta estiver correta, é: “Pode gravar a proposta mostrada nesse arquivo e conferir o resultado combinado”. A confirmação faz parte do fluxo instalado da skill; não significa que cada execução futura da skill customizada vai pedir novamente a aprovação da mesma configuração.

Passo 5. Leia a conferência. A skill executa o programa que combina as camadas, aponta os campos alterados e resume o arquivo criado. Se não conseguir executar o programa, deve fazer a combinação por leitura e dizer que foi uma conferência manual. Se a alteração não aparecer, volta à composição. O fluxo considera a tarefa concluída quando você também reconhece o resumo.

• Ao terminar esta etapa: você deve ter uma diferença pequena e compreensível. Para aprender sem alterar seu projeto, pode parar na proposta e continuar lendo os exemplos.

Confira a customização de bmad-agent-pm sem iniciar o agente.
Execute resolve_customization.py com o caminho da skill instalada e a raiz
explícita deste projeto. Mostre o bloco agent combinado e explique de qual
camada vieram os campos alterados. Compare os nomes dos campos com o
customize.toml instalado. Informe arquivos inválidos, referências ausentes
e instruções contraditórias. Não trate essa leitura como teste de comportamento.

Depois vem o teste real. Em uma nova ativação da skill, use um exemplo pequeno e confira se ela adotou o estilo, leu a referência e produziu a seção desejada. As customizações são carregadas na ativação; não prometa que uma conversa já em andamento vai reler o arquivo espontaneamente. Para uma revisão, teste se a camada executa e encontra o tipo de problema que deveria procurar. Para um modelo, produza um documento de amostra e compare sua estrutura. Esses testes são recomendados ao leitor e não foram feitos na preparação desta aula.

Há uma limitação que torna essa separação indispensável. Se o resolvedor falhar, o agente PM e a revisão de código têm instruções para combinar as camadas por leitura. Já PRD e UX mandam recorrer ao customize.toml original, usando os padrões. Portanto, o fluxo pode continuar sem suas regras. Corrija a falha; não interprete “continuou” como “customização aplicada”.

• Ao terminar esta etapa: confira separadamente arquivo correto, campos reconhecidos, resultado combinado e comportamento observado. Só o último exige executar a skill de trabalho.

Ausente e inválido são situações diferentes. Ainda não ter _bmad/custom/bmad-prd.user.toml é normal: a camada opcional é pulada. Ter um arquivo nesse caminho com TOML malformado, sem permissão de leitura ou uma pasta no lugar do arquivo causa erro. Já o customize.toml padrão da skill e _bmad/config.toml central são obrigatórios para os respectivos resolvedores. Corrija a causa indicada; criar uma sobreposição vazia não repara uma instalação incompleta.

Os exemplos desta fase são independentes. Escolha um, confira e só então combine com outro. Todos os Pedidos e conteúdos propostos são exemplos autorais, não executados. Quando dois exemplos usam o mesmo arquivo, peça para integrar os campos à seção existente; não cole vários cabeçalhos [workflow] repetidos nem substitua regras anteriores sem examiná-las. O arquivo deve continuar sendo um TOML válido.

Use esta etapa se o assistente chama você por outro nome, conversa em um idioma indesejado ou explica como se você fosse programador. Separe três decisões: quem é você, em que idioma vocês conversam e em que idioma a equipe entrega os documentos. A instalação mantém campos diferentes para isso.

Os valores de nível definidos no módulo são beginner, intermediate e expert: explicação mais didática, equilíbrio entre detalhe e velocidade, ou comunicação direta e técnica. Esse campo trata da experiência com desenvolvimento; não é uma avaliação da sua experiência como empresário. O exemplo usa beginner e a mesma expressão de idioma encontrada na instalação consultada: Portuguese Brazil.

Limite da preferência de nível. beginner registra a preferência, mas não comprova que toda skill a aplicará da mesma maneira. A revisão de código manda explicitamente carregar user_skill_level; as ativações de PM, PRD e UX consultadas não o enumeram entre os valores utilizados. Se a explicação continuar técnica demais, peça linguagem de negócio e ajuste communication_style ou persistent_facts onde esses campos existirem. Esse limite vem da leitura das instruções; não foi feito um teste comparativo das respostas.

Pedido para o Claude Code — exemplo autoral não executado, sem chamar bmad-customize

Quero ajustar a configuração central do BMAD deste projeto sem editar os
arquivos gerados pelo instalador. Leia as quatro camadas de configuração.
Em _bmad/custom/config.user.toml, defina meu nome como Helena,
communication_language como Portuguese Brazil e, em modules.bmm,
user_skill_level como beginner. Em _bmad/custom/config.toml, defina
document_output_language como Portuguese Brazil para os documentos do time.
Preserve os outros campos. Mostre a proposta com os caminhos, aplique essas
mudanças e confira core e modules.bmm com resolve_config.py.
Explique a origem dos valores finais e qualquer conflito encontrado.

Esse Pedido comum é possível porque os arquivos de custom/ são escritos por quem mantém o projeto. A skill de customização não cobre essa configuração central na versão instalada.

Arquivo pessoal que muda — exemplo

# _bmad/custom/config.user.toml
[core]
user_name = "Helena"
communication_language = "Portuguese Brazil"

[modules.bmm]
user_skill_level = "beginner"

Arquivo do time que muda — exemplo

# _bmad/custom/config.toml
[core]
document_output_language = "Portuguese Brazil"

Não acrescente user_name = "Helena" ao arquivo do time para padronizar documentos: isso faria uma preferência individual alcançar outras pessoas. A documentação recomenda deixar nome, idioma de conversa e nível na camada pessoal. Se só você precisa de documentos em português, o campo document_output_language também pode ficar na sua sobreposição pessoal; nesse caso ele não define o padrão compartilhado.

Pelo terminal — alternativa de conferência. Depois de editar os arquivos próprios no editor, execute o comando central da Etapa 05. Não há necessidade de reinstalar para criar essas sobreposições. Os marcadores como {project-root} que aparecem nos exemplos de caminhos do BMAD são substituídos pela skill; o resolvedor apenas combina os valores e pode mostrá-los ainda com os marcadores.

Como conferir. Veja os três campos pessoais e o idioma dos documentos no resultado central. Depois, em uma nova ativação de uma skill que usa resolve_config.py, confira a saudação e o texto produzido. A própria bmad-customize tem uma limitação: sua instrução de ativação lê só os dois arquivos do instalador para nome e idioma. Ela pode saudar de outro jeito mesmo quando PM, PRD, UX e revisão recebem corretamente as quatro camadas. Não “corrija” isso editando a skill instalada.

Quando pular. Se os valores já estão certos, não crie uma sobreposição só para repeti-los. Guarde uma preferência explícita quando quiser que ela continue vencendo respostas futuras da instalação.

Persona é o jeito de agir e conversar atribuído ao agente. O gerente de produto (John) continua sendo a identidade de bmad-agent-pm; você pode ajustar seu papel, suas referências de pensamento, seu estilo e seus princípios. Os campos name e title aparecem no arquivo de referência, mas são identificados como não configuráveis: a ativação adota explicitamente o gerente de produto (John), chamado de Product Manager no código. Mudar esses dois campos na sobreposição não é o caminho para criar uma nova pessoa.

Use esta customização se você quer que as conversas conduzidas pelo gerente de produto (John) considerem uma realidade constante do negócio. No exemplo, a Rota Clara quer discutir valor para cliente e operação antes de escolher funcionalidades. O agente deve ajudar a pensar; não precisa apenas concordar com a direção proposta.

Há dois percursos diferentes. Ao ativar o gerente de produto (John) e depois chamar um fluxo por meio dele, sua instrução mantém a persona e os fatos durante a sessão, até você dispensá-lo. Ao chamar bmad-prd diretamente em outra conversa, o arquivo de customização do agente não é carregado automaticamente como regra do PRD. Para uma exigência permanente do documento, mantenha-a também no fluxo responsável, como mostrado na Etapa 09.

Pedido para o Claude Code — exemplo autoral não executado

bmad-customize Adapte bmad-agent-pm para o time da Rota Clara.
Mantenha o gerente de produto (John) e seu papel. Quero explicações em linguagem de negócio,
com impacto no cliente, na operação e no custo. Ele deve separar fatos de
hipóteses e questionar funcionalidades sem benefício claro. Acrescente o
princípio de validar primeiro a hipótese de maior risco. Não troque o menu
existente. Leia as camadas atuais, proponha somente os campos necessários
em _bmad/custom/bmad-agent-pm.toml e mostre o resultado combinado após gravar.

Arquivo que muda — exemplo ilustrativo

# _bmad/custom/bmad-agent-pm.toml
[agent]
role = "Ajudar a Rota Clara a transformar necessidades de clientes e da operação em decisões de produto verificáveis."
communication_style = "Explique em linguagem de negócio. Relacione opções a cliente, operação e custo. Separe fatos de hipóteses e explique os termos técnicos na primeira ocorrência."
persistent_facts = [
  "A Rota Clara deste exemplo é uma empresa de serviços de entrega.",
  "Uma funcionalidade proposta precisa explicitar qual problema resolve e para quem."
]
principles = [
  "Priorize a validação da hipótese de maior risco antes de ampliar a solução."
]

Aqui, role e communication_style substituem os textos anteriores desses campos. Os fatos e o princípio são acrescentados. Os princípios originais continuam no conjunto, inclusive a orientação de priorizar valor para o usuário. Não acrescente identity por hábito: use esse campo somente se também quiser trocar as referências que orientam o modo de pensar da persona.

Uma regra em arquivo. Em vez de escrever um manual dentro do TOML, você pode acrescentar "file:{project-root}/docs/empresa/glossario.md" a persistent_facts, depois de criar e revisar esse documento. {project-root} significa a pasta principal do projeto. Mesmo que o documento esteja perto da sobreposição, escreva o caminho a partir dessa raiz: caminhos sem esse marcador podem ser interpretados a partir da pasta instalada da skill. No PM, file: carrega o conteúdo; outros valores são fatos literais. Não use skill: nesse campo supondo que o gerente de produto (John) vai automaticamente executar outra skill.

Uma opção nova de menu. Para acrescentar uma conversa de alinhamento, você pode pedir à bmad-customize um item com código ainda não usado. O exemplo abaixo usa um prompt, isto é, uma instrução de conversa. Ele não depende da existência de uma skill nova.

# Trecho adicional de _bmad/custom/bmad-agent-pm.toml
[[agent.menu]]
code = "RN"
description = "Revisar a necessidade de negócio"
prompt = "Antes de propor funcionalidades, ajude a explicitar problema, pessoa afetada, evidência disponível e resultado esperado. Registre o que ainda é hipótese."

O menu original traz PRD para bmad-prd, CE para organizar épicos e histórias de trabalho, IR para conferir a preparação para implementação e CC para avaliar mudanças de direção. Épicos são conjuntos maiores que agrupam histórias de trabalho, cada uma descrevendo uma entrega menor. Os três últimos itens acionam, respectivamente, bmad-create-epics-and-stories, bmad-sprint-planning e bmad-correct-course. Se reutilizar um desses códigos, você substitui aquele item inteiro. Para apenas acrescentar, escolha outro código.

Como conferir e seguir. Resolva o bloco agent com o comando da Etapa 05. Depois ative bmad-agent-pm em uma conversa de ensaio e apresente uma decisão pequena do seu negócio. Confira o estilo e, se criou uma opção, o menu. Se você chamar apenas o agente, sem indicar um trabalho, ele apresenta o menu para sua escolha. Se o Pedido já identificar claramente um trabalho correspondente, o gerente de produto (John) pode iniciá-lo depois da saudação, sem mostrar o menu antes. Se só deseja ajustar o PRD, pule a persona e vá à Etapa 09.

bmad-code-review revisa mudanças no código e organiza os problemas encontrados. Uma camada de revisão é um olhar separado, com uma instrução própria. A skill combina esses olhares; não basta aumentar a quantidade de revisores sem saber o que cada um procura.

O padrão instalado tem quatro camadas. As três primeiras revisam sem receber a especificação como contexto da intenção; a última confronta a mudança com essa intenção. Uma especificação registra o que deve ser construído e como reconhecer o resultado esperado.

O modo no-spec permite revisar sem especificação, mas essa escolha precisa ser explícita. Simplesmente não informar um caminho não obriga a skill a presumir esse modo: ela pede que você forneça a especificação ou escolha continuar sem ela. A revisão também precisa identificar quais mudanças analisar.

bmad-customize Acrescente uma camada de revisão em bmad-code-review para o time.
Ela deve conferir as regras locais de privacidade da Rota Clara no arquivo
docs/empresa/regras-de-privacidade.md e apontar violações concretas nas mudanças.
Primeiro confirme que esse arquivo existe e peça seu conteúdo se estiver ausente;
não invente uma política. Preserve as quatro camadas originais.
Use o id regras-privacidade e mostre a receita inteira proposta em
_bmad/custom/bmad-code-review.toml. Depois de gravar, confira review_layers.

# _bmad/custom/bmad-code-review.toml
[[workflow.review_layers]]
id = "regras-privacidade"
name = "Regras internas de privacidade"
instruction = """
Antes de delegar, resolva o caminho
{project-root}/docs/empresa/regras-de-privacidade.md e {diff_file}
para caminhos absolutos reais deste projeto. Confira se ambos são legíveis.
Se não forem, informe a falha. Caso contrário, inicie um subagente
substituindo as referências abaixo pelos caminhos absolutos já conferidos.

Pedido do subagente:
Política: {project-root}/docs/empresa/regras-de-privacidade.md
Diferenças: {diff_file}
Leia a política e o arquivo de diferenças nos caminhos fornecidos.
Confira somente violações demonstráveis das regras fornecidas.
Para cada achado, informe a regra, o trecho da mudança e a consequência.
Se a referência não estiver acessível, informe a falha; não invente seu conteúdo.
Não execute outras skills nem crie novos subagentes dentro desta revisão.
Retorne os achados como lista Markdown na resposta final. Se não encontrar
violações demonstráveis, declare isso explicitamente, sem inventar problemas.
"""

As quatro decisões possíveis sobre uma camada. Você pode acrescentar uma usando um id novo; substituir uma usando o id existente; condicionar uma usando when; ou desativar uma usando instruction = "". when é uma condição descrita em texto para a skill interpretar, não uma expressão Python. instruction é a receita inteira, podendo inclusive chamar uma ferramenta externa quando isso estiver corretamente configurado. Nosso exemplo fica em arquivos locais.

Se a decisão consciente for desligar uma camada específica, o mecanismo documentado é este exemplo isolado:

# Exemplo opcional, não necessário para acrescentar a camada da empresa.
# _bmad/custom/bmad-code-review.toml
[[workflow.review_layers]]
id = "blind-hunter"
name = "Blind Hunter"
instruction = ""

A camada permanece identificada no resultado, mas a revisão a ignora. Não desligue todas esperando um relatório de revisão concluída: se não sobrar nenhuma ativa, o código interrompe com no active review layers. Isso é diferente de apagar a etapa de revisão do fluxo. Embora a documentação discuta dispensar revisão em certos trabalhos, a execução instalada não permite continuar essa skill com zero camadas ativas.

Outras opções da revisão. Além das camadas, esse customize.toml oferece activation_steps_prepend, activation_steps_append, persistent_facts e on_complete. Os dois primeiros acrescentam preparação antes e depois da saudação. Os fatos mantêm contexto durante a revisão e aceitam texto ou file:. on_complete é a instrução de encerramento após a apresentação dos achados e a sincronização do acompanhamento aplicável. Não assuma que campos avançados do PRD, como external_sources, também existem aqui.

Quando uma camada falha. O fluxo registra camadas com falha, demora excedida ou resultado vazio e continua com os achados das demais. Isso não equivale a uma aprovação pela camada que falhou. Se uma receita exige subagentes e o ambiente não os oferece, o código instalado manda preparar instruções completas para sessões separadas e parar até os resultados voltarem. A documentação descreve alternativas mais permissivas; nesta versão, siga o código.

Como conferir e seguir. Confirme que as quatro camadas antigas permanecem, que a nova tem receita e que a política existe. Depois faça uma revisão pequena, com o conjunto de mudanças e a presença ou ausência de especificação explicitados. Confirme quais camadas rodaram e quais falharam ou foram puladas. A aula não executou esse teste. Se você ainda não tem regras internas específicas para revisar, pode manter o padrão e pular a camada adicional.

Se a mudança for grande. A coleta de contexto considera grande uma diferença acima de aproximadamente 3.000 linhas e oferece dividir a revisão por grupos lógicos de arquivos; a pessoa pode aceitar ou continuar com o conjunto completo. Uma mudança pequena pode seguir com as camadas padrão. Em uma mudança extensa, separar por assunto ajuda a discutir o alcance antes de acrescentar novos revisores. O limite é uma orientação da skill, não uma medida de risco do negócio: uma alteração de uma linha também pode afetar uma cobrança.

Se usar sessões separadas. O caminho alternativo sem subagentes só funciona se cada sessão receber as referências necessárias. A instrução instalada torna o conjunto de diferenças autossuficiente porque a sessão separada pode não acessar o mesmo disco. Para a camada autoral de privacidade, confira também como a política ficará disponível naquela sessão; copiar apenas o nome de um arquivo local não entrega seu conteúdo. Esse caso não foi executado na aula.

Use esta etapa quando a empresa já tem exigências recorrentes para aprovar um produto ou mudança. No exemplo, a Rota Clara quer acrescentar responsável pelo resultado, indicador de sucesso e restrições operacionais. A proposta começa pelo modelo instalado e preserva suas convenções úteis, em vez de trocar requisitos por um formulário apenas administrativo.

Pedido para o Claude Code — exemplo autoral não executado

bmad-customize Quero adaptar o modelo de bmad-prd para o time da Rota Clara.
Leia o modelo instalado e copie-o para
_bmad/custom/templates/prd-rota-clara.md, sem alterar a instalação.
Adapte a cópia para incluir responsável pelo resultado, indicador de sucesso,
restrições operacionais e evidências da necessidade. Preserve as convenções
de requisitos e referências entre jornadas, requisitos e métricas.
Aponte prd_template em _bmad/custom/bmad-prd.toml para essa cópia usando
{project-root}. Acrescente uma instrução explícita para não inventar evidências
nem preencher decisões desconhecidas como se estivessem aprovadas.
Mostre as diferenças do modelo e do TOML antes de gravar; depois confira o resultado.

Arquivos que mudam. O TOML guarda o endereço e a regra; _bmad/custom/templates/prd-rota-clara.md guarda o modelo completo adaptado. Esses nomes de arquivos próprios são escolhas do exemplo. O campo real é prd_template.

# _bmad/custom/bmad-prd.toml
[workflow]
prd_template = "{project-root}/_bmad/custom/templates/prd-rota-clara.md"
persistent_facts = [
  "Todo PRD da Rota Clara deve explicitar responsável pelo resultado, indicador de sucesso, restrições operacionais e evidências da necessidade. Se algo for desconhecido, registre a lacuna; não invente evidências nem aprovação."
]

O que preservar e o que adaptar no modelo. O arquivo original contém a finalidade do documento, visão, público e jornadas, glossário, funcionalidades com requisitos identificados, limites do produto, escopo inicial, métricas, perguntas abertas e índice de suposições. Também sugere seções adicionais conforme o contexto. Para iniciativas de empresa, há sugestões de responsáveis e aprovações, riscos, retorno esperado, operação, integrações, implantação e governança de dados. Use o que o produto exige e explique por que uma seção relevante não se aplica.

O modelo instalado organiza jornadas com identificadores UJ, requisitos funcionais com FR e métricas com SM. São códigos para ligar a necessidade, o comportamento esperado e a medição. O cabeçalho do documento, chamado de front-matter, guarda metadados como título e datas entre linhas ---; na criação, a skill também registra status: draft. A cópia da empresa deve preservar o sentido dessas referências e metadados, mesmo quando traduz títulos e acrescenta seções.

Um acréscimo possível ao modelo da Rota Clara seria este trecho. Ele não substitui o modelo inteiro:

## Responsabilidade pelo resultado

- Responsável de negócio: nome ou lacuna a resolver.
- Pessoa que valida o resultado na operação: nome ou papel.
- Decisão que este PRD permite tomar: descrição concreta.

## Evidências e restrições da operação

- Problema observado: descreva o caso e a fonte.
- Evidência disponível: documento, entrevista ou medição identificada.
- Hipótese ainda não confirmada: registre como hipótese.
- Restrição operacional: explique o limite e quem o confirmou.
- Indicador de sucesso: relacione às métricas e aos requisitos do PRD.

Modelo não é garantia de cumprimento. A skill instalada trata o modelo como referência adaptável: pode reorganizar e combinar seções conforme o produto. Para um requisito obrigatório da empresa, combine o modelo com instrução explícita, critérios de qualidade e revisão do documento. validation_checklist_template, apesar do nome, aponta para uma rubrica, um conjunto de critérios para julgar a qualidade do conteúdo; não é apenas uma lista de caixas de “sim ou não”.

Todas as opções expostas pelo PRD. Você não precisa configurar todas; a tabela explica qual problema cada uma resolve. Todos os campos estão sob [workflow]. Quando aparecer HTML, entenda o formato usado para apresentar um relatório como página no navegador.

A ramificação de on_complete. Se a camada do time usa um texto e a pessoal usa outro texto, o pessoal substitui o texto inteiro. Se as duas usam listas, os itens são acrescentados. Se uma usa texto e a outra lista, o valor posterior substitui o anterior, pois os formatos são diferentes. Não use a troca de formato como truque para esconder uma política: alinhe com a equipe o que deve acontecer no encerramento.

Cadastrar um revisor não o torna obrigatório. No PRD, o ponto de escolha dos revisores varia com o impacto do trabalho: um projeto pessoal pode usar os padrões sem uma escolha detalhada ou pular a revisão; trabalhos de maior impacto oferecem todos, alguns ou nenhum. Se a empresa exige uma revisão específica, registre essa exigência e confira que ela realmente foi executada. A simples presença de uma entrada em finalize_reviewers não é uma trava de aprovação.

Como conferir e seguir. Peça que o resolvedor mostre workflow.prd_template e que o Claude Code abra o arquivo apontado. Depois, faça uma criação ou atualização pequena com bmad-prd e veja o documento, não só o endereço do modelo. No padrão, o prd.md fica em {prd_output_path}/{run_folder_pattern}/; a execução também mantém registros próprios e pode produzir material complementar. Alterar o modelo não reescreve PRDs antigos automaticamente. Para um documento existente, use a intenção de atualização da skill.

Pedido de ensaio, depois da configuração — exemplo autoral não executado

bmad-prd Crie um PRD de ensaio para a Rota Clara registrar o motivo de uma
entrega atrasada. Use o modelo resolvido da empresa. Marque todos os dados
fictícios e as decisões ainda não confirmadas. Ao apresentar o documento,
mostre onde aparecem responsável, indicador, restrições e evidências.
Não envie o resultado a sistemas externos nesta execução.

Pode pular a troca do modelo se você só precisa de um critério adicional: uma instrução específica em persistent_facts ou um revisor adicional pode bastar. Quanto mais você substitui, mais precisa comparar com a evolução do padrão em atualizações futuras.

O modelo também precisa caber no tamanho do trabalho. A disciplina do PRD orienta dimensionar o documento pelo impacto: aproximadamente duas páginas para projeto pessoal, cinco a oito para ferramenta interna e o necessário para cobrir requisitos e preocupações em um lançamento maior. São referências de proporção, não limites obrigatórios. Uma empresa pequena pode ter uma mudança crítica; uma empresa grande pode precisar de um ajuste simples.

Na Rota Clara, registrar o motivo de um atraso pode exigir poucas jornadas e critérios claros. Criar uma nova operação de entregas pode exigir responsáveis, integrações, dados, implantação e acompanhamento mais detalhados. Preserve as convenções de identificação e acrescente somente as seções pertinentes. O modelo oficial inclusive prevê histórias no próprio PRD para escopos pequenos; a customização não deve transformar toda necessidade em um formulário corporativo extenso. Esses dois casos de negócio são ilustrativos.

Aqui a decisão é quando uma informação deve entrar. Ler um glossário na abertura, pesquisar uma base quando surgir uma dúvida, revisar a escrita ao terminar e publicar o documento pronto são quatro momentos diferentes. O PRD e o fluxo de UX expõem campos próprios para eles. UX, ou experiência do usuário, descreve como as pessoas entendem e usam o produto, incluindo seus caminhos, respostas e situações de erro.

Comece por fontes locais. No exemplo, a empresa já mantém um glossário, um documento de regras do produto e um padrão de escrita. Esses arquivos são conteúdo da empresa; a customização só indica quando ler e como usar. Se não existem, prepare-os antes com o responsável pelo assunto. Não transforme conhecimento inventado pelo assistente em política interna aprovada. Essa é uma recomendação editorial para aplicar o mecanismo de referências file: documentado nas skills.

Pedido para o Claude Code — exemplo autoral não executado

bmad-customize Acrescente ao bmad-prd do time três referências locais existentes:
docs/empresa/glossario.md como contexto persistente;
docs/empresa/regras-do-produto.md como fonte a consultar quando surgir
uma decisão operacional; e docs/empresa/padrao-de-escrita.md como padrão
de acabamento. Confira os três arquivos antes de propor. Preserve o modelo
e as regras que já estão em _bmad/custom/bmad-prd.toml.
Não configure envio externo. Mostre o TOML integrado e a conferência final.

Arquivo que muda — trecho ilustrativo a integrar, não a sobrescrever

# _bmad/custom/bmad-prd.toml
[workflow]
persistent_facts = [
  "file:{project-root}/docs/empresa/glossario.md"
]
external_sources = [
  "Quando surgir uma decisão sobre a operação, consulte {project-root}/docs/empresa/regras-do-produto.md e cite a regra relevante. Se não houver resposta, registre a lacuna."
]
doc_standards = [
  "file:{project-root}/docs/empresa/padrao-de-escrita.md",
  "Diferencie observações verificadas, estimativas e hipóteses em todo o documento."
]

O padrão de escrita é acrescentado ao acabamento já previsto, que inclui skill:bmad-review lenses=structure,prose. Essa chamada pede duas lentes editoriais da skill de revisão: estrutura e prosa. Os dois pontos e lenses=structure,prose são parte da instrução instalada desse campo; não são uma sintaxe que serve para qualquer referência. O campo doc_standards = [] não removeria esse padrão, pois as listas somam.

Quando a fonte está em outro sistema. MCP, sigla de Model Context Protocol, é um padrão de conexão entre aplicativos de IA, ferramentas e fontes externas. external_sources pode conter instruções com o nome de uma ferramenta conectada, a situação em que deve ser consultada e os dados de que precisa. A documentação usa bases internas e sistemas corporativos como exemplos. Esses nomes de exemplo não são prova de que a ferramenta existe na sua sessão. Escrever um nome no TOML não instala uma conexão nem concede acesso.

Antes de configurar uma fonte remota, peça ao Claude Code para listar as ferramentas realmente disponíveis e identificar qual permite a consulta desejada. Depois descreva uma condição concreta: “quando surgir dúvida sobre prazo operacional, consultar a base de procedimentos”. Inclua como citar a origem e o que fazer se a consulta falhar. No PRD, uma ferramenta indisponível leva ao comportamento padrão com registro da lacuna; não autoriza inventar o conteúdo da fonte.

Você também pode usar on_complete para um encerramento local simples, como “apresente três decisões tomadas e as pendências restantes”. A receita oficial de adoção mostra on_complete publicando em Confluence e oferecendo trabalho posterior em Jira. É uma receita que pressupõe integrações e uma decisão de publicação; não é uma regra de que qualquer documento deva ser enviado automaticamente. Para o primeiro ensaio, mantenha a entrega local.

Em UX, a revisão também é uma escolha explícita. Ao finalizar, a skill pergunta se você quer validar; na intenção Validate, esse interesse já foi declarado. Nos dois caminhos, apresenta as perspectivas de revisão para selecionar todas, algumas ou nenhuma. Portanto, finalize_reviewers oferece revisores; o campo, sozinho, não obriga sua execução.

A skill explica essa escolha pelo consumo adicional de cada perspectiva de revisão. Para um ensaio pequeno, escolha a análise que consegue responder à dúvida concreta, como a recuperação após erro. Para um fluxo importante da operação, examine também os critérios de qualidade que a equipe exige antes de escolher os revisores. Nenhuma quantidade de revisores ou custo em dinheiro foi medida nesta aula.

Os recursos visuais padrão incluem instruções para temas de cores, direções de design, rascunhos de telas e exemplos de telas em HTML. O cadastro design_handoffs apresenta Google Stitch como uma opção instalada. Isso não comprova que uma conta, ferramenta externa ou conexão esteja disponível no seu ambiente. Uma referência visual também não substitui decisões sobre quem usa o produto e o que acontece em cada situação.

Pedido para o Claude Code — exemplo autoral não executado para UX

bmad-customize Adapte bmad-ux para consultar as referências existentes da empresa.
Acrescente docs/empresa/referencia-DESIGN.md em design_md_examples e
docs/empresa/referencia-EXPERIENCE.md em experience_md_examples, com caminhos
file:{project-root}/... completos. Acrescente como fato persistente que o
produto precisa explicar erros e indicar como a pessoa pode se recuperar.
Confira se os arquivos existem e use _bmad/custom/bmad-ux.toml do time.
Preserve os exemplos instalados. Não configure ferramentas nem envios externos.

Arquivo que muda — exemplo ilustrativo

# _bmad/custom/bmad-ux.toml
[workflow]
design_md_examples = [
  "file:{project-root}/docs/empresa/referencia-DESIGN.md"
]
experience_md_examples = [
  "file:{project-root}/docs/empresa/referencia-EXPERIENCE.md"
]
persistent_facts = [
  "O produto deve explicar os erros em linguagem compreensível e indicar uma ação de recuperação para a pessoa."
]

Como conferir e seguir. Use o resolvedor por skill da Etapa 05, trocando a pasta para bmad-ux e a chave para workflow. Depois confira a leitura dos arquivos e uma pequena entrega de UX: observe tanto o uso da referência visual quanto a explicação dos erros e das ações de recuperação pedidas. Espera-se que a referência acrescente orientação; a lista vazia não retiraria os exemplos originais. Se você ainda não tem uma referência aprovada, pode pular essa customização e começar pela regra textual de comportamento.

Uma customização pessoal que funcionou não vira automaticamente uma boa regra para todos. Antes de compartilhá-la, descreva o problema que resolve, quem precisa dela e como reconhecer que funcionou. A documentação oficial organiza a adoção por alcance: comportamento do agente, resultado de um fluxo, fontes e publicações, modelos, cadastro de agentes e configuração compartilhada. Os arquivos do time ficam no repositório para que os colegas os recebam ao atualizar suas cópias.

Não comece por todas as receitas ao mesmo tempo. A sequência sugerida nesta aula é um ensaio com uma entrega recorrente, como o PRD, seguido da revisão da equipe. Acrescente integrações depois que a regra local estiver clara. É uma recomendação de adoção, não uma etapa obrigatória do BMAD.

A desenvolvedora de software sênior (Amelia) é carregada pela skill bmad-agent-dev; o fluxo bmad-product-brief prepara, atualiza ou valida o documento de visão do produto. Eles aparecem na tabela para mostrar as outras receitas oficiais. Você não precisa ativar a desenvolvedora de software sênior (Amelia) nem criar um documento de visão para compartilhar a customização de PRD desta aula.

1. 1

   Passo 1. Separe política e preferência.

   “Usar o glossário aprovado” pode ser do time. “Responder primeiro em três frases” pode continuar pessoal. Evite colocar o nome de uma pessoa ou um caminho que só existe no computador dela dentro do padrão compartilhado. A documentação mantém nome do usuário, idioma da conversa e nível de explicação como preferências pessoais.

2. 2

   Passo 2. Leve o conjunto completo.

   Um modelo, um glossário e uma rubrica que a configuração referencia também precisam estar disponíveis. Use caminhos a partir de {project-root} para documentos do próprio repositório. Se a fonte for remota, documente qual ferramenta deve estar conectada e como a ausência dela será informada. Não compartilhe acesso por meio de senhas escritas nos arquivos.

3. 3

   Passo 3. Leia como outra pessoa.

   Peça a alguém do time, ou faça uma conferência em uma cópia sem suas preferências pessoais, para verificar se o resultado depende de um .user.toml. O que funciona só no seu computador pode depender de uma referência pessoal que ficou invisível na entrega. Essa conferência decorre das camadas de precedência; é uma recomendação editorial de teste, não um ensaio realizado para esta aula.

Um padrão compartilhado continua sujeito à camada pessoal posterior: ela pode substituir textos, campos de tabelas e itens identificados. Se a política da empresa exige determinada análise, confira sua execução no resultado de cada pessoa. O TOML compartilhado distribui a orientação; o resolvedor não é um controle de permissão que impeça alterações pessoais.

Pedido para o Claude Code — exemplo autoral não executado

Prepare para a equipe as customizações de PRD aprovadas neste projeto.
Leia os arquivos do time e os pessoais e liste somente as regras compartilháveis.
Confira todas as referências de arquivos, a versão do BMAD e os campos usados.
Mostre quais arquivos do time e modelos precisam entrar no histórico do Git,
e quais preferências devem continuar pessoais. Confira também o que já está
rastreado pelo Git; não presuma que o sufixo .user.toml basta para ignorar.
Não copie credenciais, não inclua arquivos pessoais e não envie nada ao remoto.
Mostre um resumo com o problema resolvido, arquivos envolvidos e teste de ensaio.

Arquivo ou entrega que muda. Este Pedido de preparação pode produzir só uma lista de revisão. Quando a equipe aceitar a regra, os arquivos compartilhados são os <skill>.toml, o config.toml de custom/ e seus documentos de apoio. O processo de salvar e enviar versões está na Aula 05. Não há necessidade de copiar sua instalação pessoal inteira para explicar uma mudança de modelo.

Vários times no mesmo repositório. A documentação admite que pessoas apontem para modelos diferentes usando .user.toml. Isso é útil para uma escolha local, mas não cria automaticamente uma configuração compartilhada e separada para cada departamento. Se a distinção é uma regra da organização, documente quem usa qual modelo e como essa seleção é conferida. Não invente nomes de pastas de “camadas departamentais” esperando que o resolvedor as procure: o código lê os caminhos fixos da Etapa 02.

• Ao terminar esta etapa: outra pessoa deve conseguir entender a regra, encontrar os arquivos e executar o ensaio sem depender da sua conversa anterior. Se você trabalha sozinho, pode pular a distribuição e manter o cuidado de documentar a intenção para o seu próprio futuro.

Algumas decisões são de organização do projeto. A configuração central permite definir caminhos comuns e descritores do cadastro de agentes. Um descritor é a ficha que apresenta uma persona a outras skills: nome, título, descrição, grupo e símbolo. Ele não é o código de um novo fluxo.

Caminhos comuns. planning_artifacts identifica a pasta de documentos de planejamento; implementation_artifacts, a de registros ligados à implementação. Na instalação do guia, são pastas dentro de _bmad-output/. A equipe pode fixar outros caminhos em [modules.bmm] de _bmad/custom/config.toml. Mudar o endereço da configuração não é uma instrução para migrar automaticamente todos os arquivos existentes; planeje a localização dos documentos anteriores antes de trocar.

Pedido para o Claude Code — exemplo autoral não executado, configuração central

Prepare uma proposta de configuração central compartilhada do BMAD.
Em _bmad/custom/config.toml, quero os documentos de planejamento em
{project-root}/docs/planejamento e os registros de implementação em
{project-root}/docs/implementacao. Leia as quatro camadas e mostre
quais valores venceriam. Antes de mudar caminhos, liste os documentos já
existentes nas pastas antigas e como continuariam acessíveis.
Não mova arquivos nem altere os caminhos até apresentar essa proposta.

Arquivo que mudaria — exemplo ilustrativo

# _bmad/custom/config.toml
[modules.bmm]
planning_artifacts = "{project-root}/docs/planejamento"
implementation_artifacts = "{project-root}/docs/implementacao"

Os campos e sua combinação são reais; os dois destinos são escolhas ilustrativas. Se o padrão _bmad-output/ atende à equipe, mantenha-o. Não há benefício em trocar caminhos apenas para demonstrar que é possível.

A apresentação do gerente de produto (John) nas conversas coletivas. bmad-party-mode reúne perspectivas de agentes em uma conversa. A documentação também indica o cadastro central para skills como bmad-retrospective, que revisa um conjunto de trabalho concluído, e bmad-advanced-elicitation, que aprofunda uma análise com métodos de questionamento. Na instalação conferida, a retrospectiva abre a discussão coletiva quando ela é solicitada; a elicitação consulta o cadastro quando o método escolhido envolve personas. Alterar a descrição do gerente de produto (John) muda a ficha disponível a essas conversas; a persona ativada por bmad-agent-pm continua vindo da própria skill e de sua sobreposição.

Pedido para o Claude Code — exemplo autoral não executado, configuração central

Adapte a descrição de bmad-agent-pm no cadastro central do BMAD para o time.
Em _bmad/custom/config.toml, na seção agents.bmad-agent-pm, descreva o gerente de produto (John)
como responsável por ligar necessidades dos clientes, operação e decisões
de produto da Rota Clara. Preserve o nome e o título originais e os demais
campos. Mostre a diferença e confira essa ficha com resolve_config.py.
Explique que essa mudança não substitui a persona de bmad-agent-pm.

Arquivo que muda — trecho ilustrativo

# _bmad/custom/config.toml
[agents.bmad-agent-pm]
description = "O gerente de produto (John) liga necessidades dos clientes, restrições da operação e decisões de produto da Rota Clara. Expõe hipóteses e procura evidências antes de ampliar a solução."

A tabela central combina campos recursivamente, então mudar só description preserva os outros campos. Isso difere das listas de itens de menu e de revisão, em que um identificador igual troca o item inteiro. A distinção é o formato dos dados.

Uma perspectiva adicional sem criar uma skill. Você pode acrescentar uma persona fictícia ao cadastro com um novo código e um descritor. Isso disponibiliza uma perspectiva para uma conversa coletiva; não cria automaticamente uma skill chamável com aquele nome, nem ferramentas, nem um especialista humano. O campo team registra um rótulo de equipe na ficha. Apesar de a documentação descrevê-lo como filtro de grupos, o programa instalado o carrega como metadado: os grupos selecionáveis do party mode usam workflow.party_groups e suas definições de participantes. Não presuma que preencher team cria sozinho um grupo selecionável. Configurar grupos completos fica fora deste exemplo.

Este exemplo opcional ficaria na camada pessoal, para explorar o ponto de vista da operação antes de decidir se ele deve virar padrão do time:

# _bmad/custom/config.user.toml
[agents.olhar-operacao]
team = "rota-clara"
name = "Olhar da operação"
title = "Perspectiva operacional"
icon = "OP"
description = "Persona fictícia que pergunta quem executa cada tarefa, quanto esforço ela exige e como recuperar uma entrega quando algo falha. Não representa uma pessoa real nem substitui validação da equipe."

Os campos são os documentados; nome, código, grupo, símbolo textual e descrição são exemplos autorais. Para conferir a ficha, o resolvedor central aceita --key agents.olhar-operacao. Para verificar se ela participa como esperado, seria necessário um ensaio com bmad-party-mode; esse ensaio não foi realizado.

Há uma consequência a conferir antes de gravar: quando não há grupo padrão resolvido por default_party, o programa do party mode inclui as entradas da tabela central agents no elenco padrão. Portanto, acrescentar a perspectiva ali pode torná-la disponível já na entrada da conversa coletiva, mesmo que não exista uma skill correspondente. Novos participantes definidos em party_members seguem outro mecanismo e não entram automaticamente nesse elenco. “Pessoal” indica quem mantém a configuração; não significa que a perspectiva ficará invisível até receber convite.

Regras que precisam valer fora do BMAD. Se uma regra deve valer até numa conversa comum, a documentação recomenda registrá-la também no arquivo de instruções que a ferramenta carrega, como CLAUDE.md no ambiente correspondente ou AGENTS.md em ferramentas que o adotam. Mantenha esse texto curto e aponte para o documento completo quando necessário. Evite manter cópias divergentes do mesmo manual em cada skill. No Claude Code, a documentação oficial confirma CLAUDE.md para instruções do projeto e lembra que essas instruções são contexto para o assistente, não uma imposição técnica infalível.

Um exemplo de regra curta, escrito para esta aula, seria: “Separe fatos verificados, hipóteses e decisões aprovadas; consulte docs/empresa/glossario.md para os termos do negócio”. O nome desse arquivo é ilustrativo. A escolha de arquivo de instruções depende da ferramenta e do projeto; esta aula não instala integração nem altera os arquivos globais da sua máquina.

• Ao terminar esta etapa: você distingue regra universal, comportamento de agente, configuração de um fluxo e ficha no cadastro. Se não precisa alterar caminhos nem elenco, mantenha os padrões e siga para a manutenção.

As sobreposições ficam separadas para sobreviver à atualização dos arquivos instalados. O instalador recria as configurações que administra e preserva os arquivos próprios em _bmad/custom/. Isso protege o conteúdo dos seus ajustes; não garante que qualquer campo continuará existindo para sempre em versões futuras. Depois da atualização, você ainda precisa conferir compatibilidade e comportamento.

Passo 1. Identifique o ponto de partida. Confira a versão do manifesto, os módulos e ferramentas instalados, os arquivos do time, os pessoais e seus modelos. Não use esta atualização como oportunidade de remover módulos sem perceber. O manifesto é o registro da instalação, com versão e módulos, em _bmad/_config/manifest.yaml.

Passo 2. Guarde o que é seu. Os arquivos do time e documentos de apoio devem ter uma versão recuperável no histórico. Guarde os pessoais de forma apropriada para você: estar fora do Git não os torna menos importantes. O instalador pode manter cópias de certas alterações detectadas, mas isso não transforma edição de skill instalada em uma estratégia confiável de customização.

Passo 3. Escolha conscientemente a versão de destino. O comando com @6.12.4 abaixo executa o instalador dessa versão. Se você já usa 6.12.4, é uma reinstalação ou renovação controlada da mesma versão, não a busca automática de uma versão mais nova. Para migrar no futuro, confira a documentação e o código da versão escolhida antes de trocar o número. Esta aula não valida a migração para a v7.

Módulos externos têm versão própria. Um módulo é um conjunto adicional de recursos do BMAD. A versão no comando fixa o instalador e os módulos que vêm com ele, core e bmm. Os módulos externos seguem suas próprias fontes e escolhas de atualização; o comando não congela toda extensão na versão usada antes. Confira os módulos e as versões no resumo. No caminho Quick Update, uma versão externa fixada permanece fixada, enquanto a seleção estável pode receber correções e versões menores conforme a política do instalador.

As outras ramificações de Quick Update. Um módulo registrado no canal next continua nesse canal. Para módulos registrados no canal stable com versão e repositório conhecidos, a detecção de uma nova versão principal conserva a versão atual em vez de aceitar silenciosamente esse salto; uma falha na consulta de versões também mantém a versão registrada. Módulos instalados sem fonte disponível são pulados e preservados. Assim, “o comando terminou” não prova que todos os módulos avançaram para uma versão nova. Leia os avisos e compare o manifesto resultante com o inventário anterior. Essas decisões foram conferidas no código, sem executar atualização.

Pedido para o Claude Code — exemplo autoral de preparação, sem executar o instalador

Prepare a renovação da instalação BMAD 6.12.4 deste projeto.
Leia _bmad/_config/manifest.yaml, liste módulos e ferramentas existentes
e inventarie as customizações, incluindo arquivos pessoais e modelos.
Confira se alguém editou arquivos instalados que deveriam estar em _bmad/custom/.
Mostre o que precisa ser preservado, a versão de destino e o comando proposto.
Não execute o instalador nesta preparação e não envie arquivos pessoais ao Git.

Passo 4. Renove a instalação preparada. Depois de revisar o inventário e guardar os arquivos, peça a execução com a versão definida. O caminho de atualização da interface se chama Quick Update; Modify BMAD Installation serve quando você quer mudar módulos, ferramentas ou respostas de configuração. Não confunda “atualizar o que existe” com “reconfigurar o conjunto”.

Renove a instalação deste projeto usando o instalador bmad-method@6.12.4,
conforme o inventário e a preservação que acabamos de conferir.
Execute na pasta que contém _bmad e use o caminho de atualização da instalação
existente, sem alterar intencionalmente os módulos e ferramentas selecionados.
Mostre qualquer decisão adicional do instalador, o resumo final, as versões
resultantes e as mudanças nos arquivos. Depois compare as customizações
com os campos instalados e execute os resolvedores, sem iniciar publicações externas.

O que muda e o que você deve reencontrar. Os arquivos instalados e as configurações administradas pelo instalador podem ser renovados. Seus arquivos de custom/ e modelos próprios devem continuar disponíveis; depois você confere se ainda apontam para campos e caminhos corretos. Evite usar um comando sem versão só porque é mais curto: ele não expressa a escolha de permanecer na versão ensinada.

Quando pular. Se você só acrescentou uma sobreposição e não precisa renovar a instalação, não rode o instalador. A próxima ativação da skill é o momento de carregar as camadas. Atualização e customização são operações diferentes.

Depois de uma atualização, compare três coisas: se o arquivo foi preservado, se o campo continua disponível e se o comportamento continua adequado. O resolvedor ajuda com a combinação, mas o teste pequeno da Etapa 05 continua necessário. Essas três conferências são a recomendação de manutenção desta aula, baseada na separação entre arquivos próprios, campos expostos e execução da skill.

Pedido para o Claude Code — exemplo autoral não executado

Confira as customizações depois da renovação do BMAD.
Compare o inventário anterior com os arquivos atuais de _bmad/custom/ e os modelos.
Para cada sobreposição, confira os campos no customize.toml instalado e resolva
o resultado com a raiz explícita deste projeto. Mostre campos desconhecidos,
caminhos ausentes, itens duplicados e substituições de camadas completas.
Proponha um ensaio pequeno para cada comportamento alterado.
Não diga que está funcionando somente porque o TOML foi lido sem erro.

O que ajustar primeiro. Se você copiou o customize.toml inteiro, reduza sua sobreposição aos campos que realmente pretende fixar. Uma cópia antiga pode continuar vencendo melhorias do padrão novo. Para um item identificado de menu ou revisão, contudo, preserve a receita completa desse item quando o substituir: “arquivo mínimo” não significa “item incompleto”.

Se o problema começou após mudar o caminho de saída, procure os documentos no caminho antigo antes de concluir que desapareceram. Se começou após uma troca de modelo, confirme a existência da cópia e o campo que aponta para ela. Se começou após adicionar uma fonte externa, confira a disponibilidade da ferramenta e o acesso ao destino. Essas são verificações orientadas pelos campos das Etapas 09–10; nenhum desses testes foi realizado para a aula.

Como desfazer uma customização com precisão. Você pode retirar a regra do arquivo em que a criou. Se todo aquele arquivo só existia para o ajuste que deseja desfazer, pode remover apenas essa sobreposição. Antes, examine o que existe nas camadas abaixo e acima: remover a pessoal revela a do time; remover a do time não apaga uma pessoal ainda ativa. Para voltar ao padrão de um campo, retire as sobreposições desse campo em todas as camadas que o alteram, preservando as demais regras.

Uma lista vazia não restaura uma lista original nem remove uma regra herdada. Para retirar um fato que você acrescentou, edite a lista na camada que o introduziu. Para reativar uma camada de revisão que você desativou, retire a substituição que esvaziou instruction, ou restaure a receita completa desejada. Em seguida resolva novamente. Não apague _bmad/custom/ inteiro para desfazer um único ajuste.

Pedido para o Claude Code — exemplo autoral não executado de reversão

Quero desfazer somente a customização pessoal do estilo de bmad-agent-pm.
Leia as três camadas e mostre em qual arquivo communication_style foi alterado.
Retire apenas esse campo da camada pessoal, preservando outros campos e o
arquivo do time. Mostre qual estilo passará a valer e confira com o resolvedor.
Se a camada pessoal não alterar esse campo, explique isso antes de propor outra ação.

Por fim, reabra a ferramenta se as skills renovadas não aparecerem e use bmad-help, que orienta o próximo passo a partir da instalação e do projeto. Isso confere o reconhecimento da integração; não substitui o ensaio da customização.

• Ao terminar esta etapa: registre a versão conferida, o motivo dos ajustes e o resultado do ensaio. Você deve conseguir manter o que a empresa precisa sem congelar todos os padrões da instalação.

Continue no guia. Volte à Aula 06 — Fluxo completo, da ideia ao go-live para aplicar uma customização no trabalho que ela deve apoiar. Use a Aula 05 — Git e GitHub para guardar e compartilhar os arquivos do time. Se faltar a instalação, comece pela Aula 04 — Instalação no macOS. Para escolher um caminho proporcional ao seu projeto, consulte a Aula 02 — Para que serve e onde aplicar. Você também pode ver todas as aulas.

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

   Confirme a pasta do projeto e a existência de .claude/skills/bmad-customize/SKILL.md. Confira também qual integração foi escolhida na instalação. Se o problema surgiu após instalar ou atualizar, reabra a ferramenta quando necessário. A lista instalada é a referência para os nomes disponíveis; não troque por um nome encontrado em documentação de outra versão.

2. A skill aparece, mas não está na lista de personalizáveis.

   O inventário procura um customize.toml válido com [agent] ou [workflow]. Uma pasta de skill sem esse arquivo não oferece esse caminho de customização. Se as skills estiverem fora da raiz examinada, use --extra-root na descoberta e confira scanned_roots e errors. O programa pode terminar com código de sucesso e ainda listar erros de leitura de algumas pastas; leia o conteúdo, não apenas o fato de que o comando terminou.

3. Gravei o arquivo, mas nada mudou.

   Confira o nome exato da pasta da skill, o destino em _bmad/custom/, a seção [agent] ou [workflow] e o campo exposto no customize.toml. Procure uma sobreposição pessoal que ainda esteja vencendo. Execute o resolvedor com --project-root explícito e ative a skill novamente para conferir o comportamento. Não presuma que uma sessão já aberta relê a configuração.

4. O idioma mudou no PRD, mas não na saudação de bmad-customize.

   Isso pode ser a limitação da própria skill de customização: sua ativação lê os dois arquivos centrais do instalador, enquanto PRD, UX, PM e revisão usam o resolvedor de quatro camadas. Confira o resultado central e a skill que efetivamente realizará seu trabalho. Não edite a instalação para compensar essa diferença.

5. O comando acusa erro de TOML. O que costuma estar errado?

   Textos precisam de aspas; listas precisam de colchetes e separação entre itens; [workflow] é uma tabela, enquanto [[workflow.review_layers]] inicia um item de uma lista de tabelas. Também importa a posição: um campo escrito depois de iniciar um item pertence àquela tabela, não automaticamente ao [workflow] anterior. Peça para integrar os campos simples antes das subtabelas e conferir se não repetiu uma seção indevidamente. Um arquivo presente e inválido gera erro no carregamento.

6. O JSON está correto. Posso considerar a regra funcionando?

   Ainda falta verificar se o campo é consumido pela skill, se o arquivo referenciado existe e se a execução seguiu a intenção. O resolvedor não valida o esquema completo de cada skill, não abre automaticamente todos os arquivos citados nas strings e não faz uma revisão da qualidade da resposta. Faça o ensaio pequeno da Etapa 05.

7. Um arquivo referenciado existe, mas a skill procura em outro lugar.

   Use o caminho a partir de {project-root} para documentos próprios. Caminhos simples dos padrões, como assets/prd-template.md, são relativos à pasta instalada da skill. No terminal, substitua os caminhos de exemplo pelo caminho real: {project-root} não é uma variável que o terminal entende automaticamente. O resolvedor pode devolver esse marcador sem expandir, porque a expansão pertence à skill consumidora.

8. Tentei limpar uma lista com [], mas o padrão continuou.

   Esse é o comportamento da combinação: listas comuns acrescentam, e acrescentar zero itens preserva os anteriores. Retire a regra na camada em que foi criada. Quando quiser mudar um item identificado de menu ou revisão, use a chave existente e forneça o item completo desejado. Não misture uma regra de lista com a expectativa de substituição de um texto simples.

9. Alterei só when e uma camada de revisão sumiu.

   Uma camada com o mesmo id substitui o item inteiro. Se você não preservou instruction, a camada fica sem receita e é desativada. Leia o item instalado completo e refaça a proposta com a condição e a instrução desejadas. Essa é uma divergência concreta entre um exemplo abreviado da documentação e a combinação executada pelo código.

10. Desativei todas as camadas e a revisão parou.

    Na 6.12.4 instalada, a ausência de camadas ativas bloqueia o fluxo com no active review layers. Reative pelo menos a revisão adequada ao trabalho. Um resultado produzido sem os revisores não deve ser apresentado como revisão concluída por eles.

11. Tentei renomear o gerente de produto (John), mas o nome não mudou.

    agent.name e agent.title são metadados não configuráveis dessa identidade. A skill continua adotando o gerente de produto (John). Ajuste papel e estilo para moldar seu comportamento; use a configuração central para a ficha de apresentação; trate uma identidade executável totalmente nova como uma skill própria.

12. O fluxo continuou depois de um erro no resolvedor. Está tudo bem?

    Não necessariamente. PM e revisão têm combinação manual como alternativa. PRD e UX podem seguir com os padrões instalados, sem suas regras. Corrija o erro e confira novamente antes de confiar em um documento que dependia de exigências específicas da empresa.

13. Escrevi uma ferramenta externa na configuração, mas ela não funciona.

    Confirme o nome exato disponível na sessão, a conexão e os dados exigidos. Os nomes de ferramentas de Confluence, Jira ou outras bases mostrados na documentação são exemplos de receitas. Eles não tornam o serviço disponível. Se a ferramenta não estiver acessível, os campos de fontes e encaminhamentos preveem informar a lacuna ou pular a ação, conforme o caso. Não preencha credenciais dentro do TOML para tentar resolver.

14. Meu colega não recebeu a customização.

    Veja se a regra ficou em .user.toml, se o arquivo do time foi compartilhado e se os documentos de apoio também estão disponíveis. Confira se ele está no mesmo projeto e ativou a skill correta. Uma regra no agente não se torna automaticamente uma regra de todos os fluxos chamados diretamente.

15. Depois da atualização, o arquivo existe, mas o comportamento mudou.

    Compare os campos usados com o novo customize.toml, verifique as substituições de itens inteiros e confirme se a sobreposição está fixando um padrão antigo desnecessariamente. Refaça o ensaio e ajuste somente o que pertence ao projeto. A preservação do arquivo não é uma promessa de compatibilidade eterna entre versões.

16. Apaguei uma sobreposição. Por que não voltou ao original?

    Ainda pode existir outra camada alterando o mesmo campo. Remover a pessoal revela a do time; remover a do time pode deixar a pessoal ativa. Execute o resolvedor e examine as três camadas da skill ou as quatro da configuração central antes de apagar mais arquivos.