Checklist code review: 35 itens para revisar pull requests

Um checklist code review ajuda o time a revisar pull requests com critérios claros. Ele reduz comentários subjetivos, evita retrabalho e deixa mais fácil separar o que precisa bloquear um PR do que pode virar melhoria para depois.

Na prática, um bom checklist não precisa ser enorme. Ele precisa lembrar o revisor de olhar para os pontos que mais costumam escapar: contexto da mudança, legibilidade, testes, segurança, compatibilidade e risco de deploy.

Checklist rápido de code review

• O objetivo do PR está claro?
• A mudança resolve apenas o problema proposto?
• O código é simples de ler e segue os padrões do projeto?
• Há testes cobrindo o caminho principal e os casos de falha?
• Entradas, permissões e dados sensíveis foram tratados?
• A mudança não quebra APIs, contratos ou comportamento existente?
• Logs, métricas e rollback foram considerados quando necessário?

Esse é o resumo. Se você só tem alguns minutos para revisar um PR pequeno, comece por aqui. Para mudanças maiores, use o checklist completo abaixo.

Quando usar um checklist de code review

Checklist de code review faz mais diferença quando o time começa a crescer. Com três ou quatro pessoas, muita coisa ainda fica implícita. O padrão de código, as decisões de arquitetura e o jeito de revisar acabam sendo passados no dia a dia.

Quando o time passa a ter mais squads, mais projetos e mais gente nova entrando, esse modelo começa a falhar. Algumas revisões ficam rápidas demais. Outras entram em detalhes de estilo que o lint já deveria resolver. E discussões maiores, como arquitetura ou escopo da solução, acabam aparecendo tarde demais dentro do PR.

A checklist ajuda porque deixa o review menos dependente da preferência de cada pessoa. Ela cria um combinado simples sobre o que precisa ser avaliado antes de aprovar uma mudança.

Como usar este checklist

O erro mais comum é tratar cada item como obrigatório em qualquer PR. Isso deixa o processo pesado e gera comentários que não mudam muito o resultado.

Use o checklist como guia de atenção. Em um ajuste pequeno de texto, talvez testes, arquitetura e rollback nem façam sentido. Já em autenticação, segurança e compatibilidade viram prioridade. Em uma migration de banco, rollback e impacto em produção precisam ser considerados antes do merge.

Uma boa regra: tudo que pode quebrar o produto, expor dados, gerar retrabalho ou dificultar a manutenção merece atenção. O resto pode virar sugestão, follow-up ou ajuste automático via lint e ferramentas.

Checklist completo de code review

1. contexto da mudança

• O PR explica qual problema está sendo resolvido?
• A mudança está ligada ao ticket, issue ou contexto combinado pelo time?
• O escopo está pequeno o suficiente para ser revisado com cuidado?
• Arquivos alterados fora do escopo foram justificados?
• Existe algum tradeoff importante descrito na descrição do PR?

Um PR sem contexto força o revisor a interpretar a intenção da mudança sozinho. Isso costuma gerar comentários piores, porque a revisão fica limitada ao diff e perde o motivo por trás da decisão.

2. legibilidade e manutenção

• O código é fácil de entender sem explicação verbal do autor?
• Nomes de funções, variáveis e classes deixam clara a intenção?
• A lógica poderia ser menor sem ficar mais difícil de entender?
• Há duplicação que cria risco real de manutenção?
• O código segue os padrões já usados no projeto?
• Comentários explicam decisões ou partes difíceis, sem narrar o óbvio?

Legibilidade não é sobre gosto pessoal. O melhor sinal é simples: alguém do time conseguiria voltar nesse código daqui a três meses e entender o que precisa mudar sem chamar o autor?

3. comportamento e regras de negócio

• A mudança cobre o comportamento esperado pelo produto?
• Casos de erro foram tratados de forma previsível?
• Entradas vazias, inválidas ou inesperadas foram consideradas?
• Regras de negócio antigas continuam funcionando?
• Existe algum caso de borda que deveria estar descrito no PR?

Boa parte dos bugs que passam em review não aparece na sintaxe. Aparece em comportamentos que pareciam óbvios para quem escreveu, mas não ficaram claros para quem revisou.

4. testes

• Há testes para o caminho principal da mudança?
• Há testes para falhas, permissões ou entradas inválidas?
• Os testes validam comportamento em vez de detalhes frágeis de implementação?
• Algum teste existente precisou ser alterado? Se sim, o motivo faz sentido?
• Os testes rodam de forma confiável no CI?

Nem todo PR precisa de uma bateria nova de testes. Mas mudanças em regra de negócio, autorização, pagamento, dados ou APIs públicas quase sempre precisam de alguma cobertura. Se o autor decidiu não testar, essa decisão deveria estar clara.

5. segurança

• Entradas do usuário foram validadas no lugar certo?
• Permissões e autorização foram verificadas no backend?
• Dados sensíveis não aparecem em logs, respostas de API ou mensagens de erro?
• Secrets, tokens e credenciais ficaram fora do código?
• Novas dependências foram avaliadas quanto a risco e necessidade?
• A mudança evita problemas comuns como SQL injection, XSS e acesso indevido?

Segurança em review não precisa virar uma auditoria completa. O revisor precisa avaliar os riscos mais prováveis para aquele tipo de mudança. Autenticação, autorização, dados sensíveis e dependências novas merecem um olhar mais cuidadoso.

6. performance

• A mudança adiciona queries, loops ou chamadas externas em pontos sensíveis?
• Existe risco de N+1, consulta pesada ou processamento desnecessário?
• O código lida bem com volume real de dados?
• Operações demoradas foram movidas para o lugar certo?
• Cache, paginação ou processamento assíncrono foram considerados quando fazem sentido?

O review não precisa prever todo gargalo futuro. Ainda assim, é importante verificar se aquele código continua razoável quando sai do exemplo local e passa a lidar com dados de produção.

7. compatibilidade e contratos

• A mudança quebra alguma API pública ou contrato usado por outros serviços?
• Clientes antigos continuam funcionando?
• Migrations são compatíveis com deploy gradual?
• Flags, versões ou fallback são necessários?
• Documentação de API, eventos ou payloads foi atualizada quando necessário?

Esse ponto é fácil de esquecer quando o PR parece pequeno. Uma alteração em campo, status, enum ou payload pode quebrar outro serviço sem parecer perigosa no diff.

8. logs, métricas e observabilidade

• Há logs suficientes para investigar falhas em produção?
• Os logs têm contexto útil, como IDs e etapa do fluxo?
• Dados sensíveis ficaram fora dos logs?
• Métricas ou alertas precisam ser atualizados?
• Erros importantes são capturados de forma visível para o time?

Nem todo PR precisa mexer em observabilidade. Mas se a mudança cria um fluxo novo ou altera algo crítico, alguém precisa conseguir entender o que aconteceu quando der errado.

9. deploy e rollback

• O PR depende de variável de ambiente, migration ou configuração externa?
• O deploy pode ser feito sem interromper usuários?
• Existe uma forma clara de voltar atrás se algo falhar?
• A mudança precisa de feature flag?
• O CI passou com testes, lint e checks relevantes?

Review também é olhar para o caminho até produção. Uma mudança pode estar correta no código e ainda assim ser arriscada se o deploy exigir passos manuais que ninguém documentou.

O que deve bloquear um PR

Nem todo comentário precisa impedir merge. Para manter o review saudável, o time precisa concordar sobre o que realmente deve ser bloqueado.

Em geral, o PR deve ser bloqueado quando há:

• bug funcional claro
• falha de segurança
• risco de perda ou vazamento de dados
• quebra de contrato público sem plano de migração
• teste ausente em fluxo crítico
• mudança que não resolve o problema descrito
• deploy sem rollback em área sensível

Esses pontos justificam pedir mudanças antes do merge. Quando há risco real, o revisor precisa ser claro sobre o que deve ser ajustado.

O que pode virar uma sugestão

Alguns comentários são úteis, mas não precisam impedir o merge.

• preferência de nome quando o nome atual já é claro
• formatação coberta por lint
• refactor fora do escopo da mudança
• troca de padrão sem impacto prático naquele PR
• melhoria pequena de documentação
• discussão arquitetural que precisa de uma conversa maior

Nesses casos, deixe claro que o comentário é uma sugestão. Algo como “poderia ficar mais claro se…” costuma funcionar melhor do que tratar todo ajuste como obrigatório.

Checklist para quem abriu o PR

O autor também deveria usar a checklist antes de pedir review. Isso economiza tempo de todo mundo.

• Eu expliquei o objetivo do PR?
• Eu revisei meu próprio diff antes de pedir review?
• Eu removi código de debug, logs temporários e alterações sem relação?
• Eu rodei testes, lint e checks locais quando faz sentido?
• Eu deixei comentários no PR onde o revisor precisa de contexto?
• Eu expliquei decisões que podem parecer estranhas olhando só o diff?
• Eu avisei se existe risco de deploy, migration ou compatibilidade?

Um bom self-review evita aquele tipo de comentário que o próprio autor encontraria em dois minutos olhando o diff com calma.

Checklist para quem está revisando

• Eu entendi o problema antes de revisar a solução?
• Eu olhei o comportamento, não só estilo de código?
• Eu diferenciei bloqueio de sugestão?
• Eu expliquei o motivo dos comentários mais importantes?
• Eu evitei pedir refactors grandes que fogem do escopo do PR?
• Eu deixei claro quando algo precisa mudar antes do merge?

Um bom review não se mede pela quantidade de comentários. Ele ajuda o autor a melhorar o PR sem transformar cada ajuste em uma discussão longa.

Template de checklist para GitHub pull request

Você pode colocar este modelo em .github/pull_request_template.md e adaptar para o jeito do seu time.

## O que mudou?

Descreva em poucas linhas o que este PR muda e por quê.

## Contexto

Link do ticket, issue ou discussão relacionada:

## Tipo de mudança

- [ ] Bugfix
- [ ] Feature
- [ ] Refactor
- [ ] Alteração de API
- [ ] Migration ou mudança em banco
- [ ] Segurança
- [ ] Performance
- [ ] Documentação

## Checklist do autor

- [ ] Revisei meu próprio diff antes de pedir review
- [ ] Removi código de debug, logs temporários e alterações fora do escopo
- [ ] Expliquei decisões que podem não ficar claras olhando só o diff
- [ ] Rodei testes, lint e checks relevantes
- [ ] Atualizei documentação, exemplos ou contratos quando necessário
- [ ] Avisei sobre riscos de deploy, migration ou compatibilidade

## Testes

Descreva como a mudança foi testada.

- [ ] Testes automatizados
- [ ] Teste manual
- [ ] Não se aplica

## Pontos para o revisor olhar com mais atenção

Liste arquivos, decisões ou partes do fluxo que precisam de um olhar mais cuidadoso.

## Riscos e rollback

Existe algum risco conhecido? Como voltar atrás se algo der errado?

## Checklist de review

- [ ] O objetivo do PR está claro
- [ ] O escopo está coerente com o problema
- [ ] O código está legível e consistente com o projeto
- [ ] Casos de erro e edge cases foram considerados
- [ ] Testes cobrem os cenários relevantes
- [ ] Segurança, permissões e dados sensíveis foram tratados
- [ ] APIs, eventos e contratos continuam compatíveis
- [ ] Deploy e rollback foram considerados quando necessário

Como adaptar esse checklist ao seu time

Copiar uma checklist pronta é um bom começo, mas o melhor checklist é aquele que reflete os problemas reais do time.

Olhe para os últimos bugs que chegaram em produção. Veja quais passaram por review. Depois pergunte: qual item teria ajudado alguém a perceber isso antes?

Esse exercício costuma ser mais útil do que montar uma lista enorme com todos os princípios possíveis de engenharia. Se o time vive sofrendo com migrations, coloque migrations na checklist. Se o problema aparece em autorização, dê mais espaço para segurança. Se PRs ficam grandes demais, coloque limite de escopo e contexto logo no topo.

A checklist também deve mudar com o tempo. Quando um item deixa de gerar valor, ele pode sair. Quando um problema aparece mais de uma vez, ele pode virar parte da lista. O documento precisa acompanhar o código e a forma como o time trabalha.

O que automatizar no code review

Quem revisa não deveria gastar tempo com tudo. Formatação, lint, testes, vulnerabilidades conhecidas e padrões repetidos podem ser checados por ferramentas.

Isso libera o time para olhar o que exige contexto: decisão de produto, impacto em usuário, desenho da solução, risco de deploy e clareza do código.

Na Kodus, por exemplo, a ideia por trás da Kody é justamente ajudar times a automatizar parte desse trabalho repetitivo dentro do fluxo de pull request. Regras do time, padrões de código e problemas recorrentes podem ser revisados com mais consistência, enquanto os engenheiros focam nas decisões que precisam de julgamento.

Se o seu time já tem padrões claros, esses padrões podem virar regras. Se ainda não tem, o checklist pode ser o primeiro passo para descobrir quais regras realmente fazem sentido.

Exemplos de bons comentários de code review

Um checklist funciona melhor quando o feedback também é claro. Comentários vagos deixam o autor na defensiva. Comentários específicos mostram qual é o problema e o que pode ser feito.

🫠 Exemplo ruim:

Esse código está confuso. 

😎 Exemplo melhor:

A regra de desconto ficou dividida entre o controller e o service. Acho que vai ser mais fácil manter se essa decisão ficar só no service, porque é lá que os outros descontos já são tratados.

🙄 Exemplo ruim:

Falta teste.

😉 Exemplo melhor:

Consegue adicionar um teste para o caso de usuário sem permissão? Esse fluxo mexe em autorização e é fácil quebrar sem perceber.

😪 Exemplo ruim:

Melhorar nome.

👍 Exemplo melhor:

Eu trocaria data por invoiceDueDate. Do jeito atual, precisei voltar algumas linhas para entender qual data estava sendo usada.

O padrão é simples: diga o problema, explique o risco e sugira um caminho quando tiver um.

Perguntas frequentes sobre checklist de code review

O que é um checklist de code review?

É uma lista de pontos que autores e revisores usam para avaliar um pull request antes do merge. Ela ajuda o time a revisar contexto, qualidade do código, testes, segurança, compatibilidade e riscos de deploy.

Quantos itens um checklist de code review deve ter?

O suficiente para cobrir os riscos mais comuns do time. Para uso diário, algo entre 10 e 20 itens costuma funcionar melhor do que uma lista enorme. Para PRs maiores, vale ter seções extras por tipo de mudança.

Todo item do checklist deve bloquear o PR?

Não. Alguns itens são bloqueadores, como falha de segurança, bug claro ou quebra de contrato. Outros são sugestões, como pequenas melhorias de nome, documentação ou organização interna.

O que revisar em um pull request?

Comece pelo objetivo da mudança. Depois olhe comportamento, legibilidade, testes, segurança, compatibilidade e risco de deploy. Estilo e formatação deveriam ser automatizados sempre que possível.

Qual a diferença entre code review manual e automatizado?

O review automatizado verifica padrões que uma ferramenta consegue detectar, como lint, testes, secrets, vulnerabilidades e regras recorrentes. O review manual olha contexto, intenção, impacto no produto e decisões que dependem de julgamento.

Como adaptar um checklist de code review para meu time?

Use bugs reais, incidentes recentes e comentários repetidos em PRs como base. Se um problema aparece várias vezes, ele provavelmente merece virar item da checklist ou regra automatizada.

Para fechar

Um bom checklist de code review não transforma a revisão em burocracia. Ele cria um alinhamento simples sobre o que o time precisa avaliar antes do merge.

Comece pequeno. Coloque o checklist no template de pull request. Revise alguns PRs usando os itens principais. Depois ajuste com base no que realmente aparece no trabalho do time.

O melhor sinal de que a checklist está funcionando é quando os comentários ficam mais claros, os PRs chegam mais preparados e o time discute menos preferência pessoal em cada review.