📘 Entenda o que é um playbook
Playbook é um procedimento reutilizável para uma tarefa recorrente. Não é um princípio ("teste bem"), é uma sequência de passos com ordem, entradas, saídas e critério de conclusão.
Como ler: os quatro playbooks tratam de situações diferentes, mas convergem para o mesmo formato. Se você aprender esse esqueleto, escreve qualquer playbook novo em quinze minutos — e todos ficam consumíveis pelo mesmo agente.
🆕 Novo aqui?
Playbook é o procedimento escrito para humanos e agentes. Skill (módulo 5.2) é esse mesmo procedimento empacotado para o agente executar direto. Rule é um limite que vale em todas as tarefas, independente de playbook. Um descreve o caminho, o outro o encurta, o terceiro cerca a estrada.
Sequência
Não conselho
Recorrente
Tarefa que se repete
Repetível
Entre pessoas e agentes
Esqueleto
Igual para todos
✨ Playbook de nova funcionalidade
O caminho padrão do trabalho novo. Ter isso escrito elimina a diferença de qualidade entre a tarefa feita na segunda de manhã e a feita na sexta às 18h.
Ler a especificação → confirmar escopo → mapear impacto → criar plano → implementar mudança mínima → criar testes → executar quality gates → revisar → documentar → preparar pull request
✓ Onde o playbook salva
- ✓"Confirmar escopo" pega o mal-entendido antes do código existir
- ✓"Mapear impacto" revela o consumidor que ia quebrar
- ✓"Plano antes de implementar" permite corrigir rumo barato
✗ Os atalhos que custam caro
- ✗Pular o plano "porque é rápido"
- ✗Deixar documentação para depois (nunca chega)
- ✗Escrever os testes só depois de tudo pronto
Confirmar
Antes de codar
Impacto
Quem quebra?
Mínima
A mudança certa
Documentar
Faz parte do pronto
🐞 Playbook de correção de bug
Aqui a ordem é tudo. Sem reprodução, você conserta o que imagina; sem teste que falha antes, não existe prova de que o bug foi embora.
Reproduzir o erro → registrar evidência → identificar causa → criar teste que falha → implementar correção → executar regressão → revisar impacto → documentar
💡 Dica prática
Se o bug não reproduz, o playbook muda: a tarefa passa a ser "conseguir reproduzir" — com mais logs, mais dados, ambiente mais parecido. Corrigir sem reproduzir é chute com aparência de trabalho.
Reproduzir
Primeiro passo, sempre
Teste que falha
É a prova
Regressão
Fecha o ciclo
Não reproduz?
Essa vira a tarefa
🏚️ Playbook de modernização
É a trilha 4 condensada em procedimento — o formato em que ela realmente é usada.
Mapear dependências → criar testes de caracterização → definir fronteira → criar adaptador → migrar pequeno módulo → executar em paralelo → comparar resultados → liberar gradualmente
🧪 Exercício copiável — gerar seus playbooks a partir do que o time já faz
Objetivo: escrever o primeiro playbook do seu repositório sem partir do zero, usando o histórico real.
Analise os últimos 30 pull requests deste repositório (use git log e os arquivos alterados). Não altere nada. 1. agrupe os PRs por TIPO de tarefa (feature, bug, dependência, refatoração, infra, outros) e diga quantos caíram em cada grupo; 2. para o grupo mais frequente, descreva os passos que as pessoas de fato seguiram — inclusive os passos que ficaram FALTANDO em alguns PRs (ex.: sem teste, sem documentação, escopo estourado); 3. escreva um PLAYBOOK desse tipo de tarefa, no formato: quando usar · entradas · passos numerados · critério de pronto · ações proibidas · o que anexar como evidência; 4. aponte quais passos poderiam virar verificação automática. Salve a proposta em docs/playbooks/<nome>.md e me mostre o conteúdo.
Como verificar: use o playbook na próxima tarefa desse tipo e anote onde ele travou ou ficou vago. A segunda versão — escrita depois do primeiro uso real — é a que vale.
Do histórico
Não da imaginação
O que faltou
Vira passo explícito
Evidência
Parte do playbook
Automatizável
Marque desde já
🚨 Playbook de incidente
Sob pressão ninguém improvisa bem. Este playbook existe principalmente para impedir que a primeira reação apague a evidência do que aconteceu.
Coletar logs → classificar gravidade → preservar evidências → identificar causa provável → criar mitigação → validar → aplicar correção → registrar aprendizado
⚠️ Atenção
Reiniciar o serviço costuma resolver o sintoma e destruir a evidência. Se você precisa reiniciar para restabelecer o serviço, capture antes: logs, estado, métricas, dump. Sem isso, o mesmo incidente volta e você recomeça do zero.
🔁 O passo mais esquecido: registrar aprendizado
Todo incidente resolvido deve terminar com uma decisão: isso vira teste, vira rule, vira gate ou vira alerta? Incidente que termina só com o serviço no ar volta a acontecer.
Preservar
Antes de agir
Mitigar
Não é corrigir
Gravidade
Define a resposta
Aprendizado
Vira teste ou gate
♻️ Mantenha os playbooks vivos
Playbook desatualizado é pior que playbook ausente: o agente segue um procedimento que já não descreve o sistema — com toda a confiança do mundo.
Falhou na prática? atualize na hora
O melhor momento de corrigir um playbook é logo depois de ele ter falhado — enquanto você lembra exatamente onde travou.
Versionado no repositório
Em /docs/playbooks/, revisado como código. Mudança de playbook é mudança de processo e merece revisão.
Poucos e bons
Cinco playbooks usados valem mais que trinta arquivados. Se um deles não foi consultado em seis meses, apague ou funda com outro.
Checagem rápida: qual é o melhor ponto de partida para escrever o primeiro playbook do time?
Atualize
Quando falhar
Versionado
Revisado como código
Poucos
E realmente usados
Morto
Apague sem dó
📌 Resumo do Módulo
Próximo Módulo:
5.2 - Skills e Rules: empacotar capacidades e fixar limites permanentes.