Existe uma forma de medir a maturidade técnica de um engenheiro que vai além do código que escreve: como ele escreve pull requests. Um PR bem feito não é só código: é comunicação, documentação e respeito pelo tempo das pessoas que vão revisá-lo.

PRs ruins chegam à tarde de sexta com 47 arquivos modificados, uma descrição de três palavras ("fix bug") e nenhum contexto sobre o que mudou, por que mudou, e o que o revisor deve prestar atenção. A maioria das pessoas nessa situação aprova o PR por cansaço — e isso é um risco técnico real.

O que faz um PR ser difícil de revisar

Antes de falar sobre o que funciona, vale entender o que não funciona:

  • Escopo grande demais. Um PR que toca 15 arquivos em 3 contextos diferentes é quase impossível de revisar com profundidade. Revisores não têm contexto suficiente para avaliar tudo — e acabam aprovando superficialmente.
  • Descrição ausente ou genérica. "Refactor" ou "Update logic" não dizem nada. O revisor tem que ler todo o diff para entender o que foi feito.
  • Mudanças de estilo misturadas com mudanças de lógica. Reformatações e reindentações no mesmo PR que muda lógica de negócio dificultam encontrar o que realmente importa revisar.
  • Sem contexto de teste. "Como eu valido que isso funciona?" é a pergunta que todo revisor tem — e que um bom PR responde antes de ser feita.

A anatomia de um PR bem feito

Título descritivo com tipo

Siga Conventional Commits no título: feat(auth): add JWT refresh token rotation é muito melhor que "Update auth". O tipo, o escopo e o que muda devem estar visíveis sem abrir o PR.

Descrição estruturada

Uma descrição de PR eficiente responde a três perguntas: O que foi feito? Por que foi necessário? Como o revisor deve abordá-lo?

## O que
Adiciona rotação automática de refresh tokens ao fazer login.
Tokens anteriores são invalidados na mesma requisição.

## Por que
Resolve CVE-2024-XXXX — tokens de longa duração sem rotação
são vulneráveis a ataques de session fixation após logout.

## Como revisar
- Comece pelo middleware em `auth/refresh.ts`
- A lógica de invalidação fica em `token-store.ts:47`
- Testes de integração cobrem o fluxo completo em `auth.test.ts`

Escopo focado

A regra prática: um PR deve ser revisável em menos de 20 minutos por alguém com contexto do domínio. Se vai passar disso, quebre em PRs menores. Isso não é burocracia — é respeito pelo processo de revisão.

Separe reformatação de lógica

Se você vai reformatar um arquivo, faça num PR separado. Assim o revisor do PR de lógica consegue focar no que realmente importa — e o histórico do git fica limpo.

Screenshots e evidências

Para mudanças de UI, screenshots antes/depois são obrigatórios. Para mudanças de performance, números antes/depois. Para mudanças de comportamento, um vídeo curto ou GIF do fluxo.

Isso não é opcional — é parte da responsabilidade de quem abre o PR provar que a mudança funciona como esperado.

Auto-revisão antes de abrir

Uma prática que transforma a qualidade dos PRs: revise seu próprio PR antes de marcar alguém como revisor. Abra o diff como se fosse outra pessoa. Você entenderia o que foi feito? Tem algum debug statement esquecido? Algum comentário TODO que deveria ter sido resolvido?

Dois minutos de auto-revisão evitam ciclos de revisão que demoram dias.

O checklist de PR que funciona

  • O título segue Conventional Commits?
  • A descrição responde: o quê, por quê, como revisar?
  • O PR toca uma única responsabilidade?
  • Reformatações estão separadas de mudanças de lógica?
  • Testes cobrem os casos adicionados/modificados?
  • Screenshots/evidências incluídas para mudanças visíveis?
  • Sem console.log, debugger, ou TODO esquecidos?
  • Você leu o próprio diff uma vez antes de abrir?

Esse checklist parece óbvio escrito assim. Mas aplicá-lo consistentemente é o que separa engenheiros que aceleram o time de engenheiros que criam gargalos no processo de revisão.