Laboratório: o runbook e o template de PR do seu time
Produzir dois artefatos que o time usa toda semana, validados por alguém que não participou da escrita.
Os dois documentos com melhor relação entre esforço e retorno num time de desenvolvimento: o runbook da rotina que mais dá problema e o template de pull request. Ambos são escritos uma vez e usados toda semana.
Escolha a rotina que mais gera dúvida no seu time — deploy, restauração de backup, rotação de credencial, reprocessamento de fila. Se ela nunca falhou, escolha outra: o valor está no procedimento de falha.
- Reúna as fontes reais: arquivo de CI, scripts, mensagens de incidentes anteriores, comandos do seu histórico de terminal.
- Rode o pedido de fontes fechadas da aula anterior.
- Execute cada comando em ambiente seguro. Marque como NÃO VALIDADO o que não deu para testar.
- Preencha as lacunas NÃO INFORMADO com quem sabe — essa conversa costuma ser a parte mais valiosa do exercício.
- Peça a uma pessoa que não participou da escrita para executar usando apenas o documento.
- Anote cada momento em que ela hesitou, perguntou ou improvisou. Cada um é um defeito do documento.
- Corrija e publique a segunda versão.
- Nenhum comando não testado ficou sem marcação.
- Uma pessoa de fora executou do começo ao fim.
- Todos os pontos de hesitação viraram correção.
- O documento diz o que fazer quando falha, não só quando dá certo.
Se travar: Se ninguém do time tem tempo para executar, peça só a leitura em voz alta com a pergunta "você saberia fazer isso sozinho?" a cada passo. Pega a maior parte dos defeitos e custa dez minutos.
Substitui o "o que este PR faz?" por perguntas que só quem escreveu o código consegue responder — e que o revisor precisa saber.
## O que muda [uma frase: o comportamento observável que passa a existir] ## Por quê [link para a história/decisão · qual problema real isso resolve] ## Como verificar 1. [passo] 2. [passo] Esperado: [resultado observável] ## Decisões que tomei | Decisão | Alternativa descartada | Motivo | Reversível? | |---------|------------------------|--------|-------------| | | | | | ## Risco - Área afetada: [ ] dados [ ] auth [ ] pagamento [ ] integração [ ] nenhuma acima - Precisa de migração? [ ] sim [ ] não - Rollback: [como desfazer] ## Uso de IA nesta mudança - [ ] Não usei - [ ] Usei para planejar/revisar; escrevi o código - [ ] Usei para gerar código, que revisei linha a linha - O que recusei da sugestão e por quê: [texto] ## Testes - [ ] Existe teste que fica vermelho se esta regra quebrar - Comando: `[comando]`
Onde guardar: .github/pull_request_template.md (ou o equivalente do seu Git).
Ela não existe para vigiar ninguém. Existe porque o revisor lê diferente quando sabe a procedência: código gerado tende a esconder erro de premissa em trecho bem escrito, e o revisor calibra a atenção com essa informação.
A linha "o que recusei e por quê" é a que mais diz sobre a qualidade da revisão de quem abriu o PR — e é a que costuma iniciar as melhores conversas técnicas do time.
- O runbook foi executado por alguém de fora.
- Comandos não testados estão marcados.
- O template de PR pergunta sobre decisão, risco e rollback.
- Ambos estão versionados no repositório, não num documento solto.
- Um runbook só está pronto depois que alguém que não o escreveu conseguiu executá-lo sozinho.
Comentários e dúvidas
Inscreva-se grátis para comentar, tirar dúvidas, marcar seu progresso e emitir o certificado ao fim do curso.
Inscrever-se grátis com GoogleAinda não há comentários nesta aula.