Revisão de PR com Claude Code: pré-revisão de diffs mais rápida e segura

Por que o tempo de revisão de PR cresce tanto

Revisões de PR raramente demoram por causa do código ser “difícil”. Elas demoram porque o revisor precisa reconstruir intenção, risco e impacto a partir de um diff que mostra mudanças, não a história completa.

Uma pequena edição pode atingir dependências ocultas: renomear um campo e um relatório quebra, mudar um valor padrão e o comportamento se altera, ajustar um condicional e o tratamento de erro muda. O tempo de revisão aumenta quando o revisor precisa clicar em vários lugares para entender o contexto, rodar a aplicação localmente e fazer perguntas de acompanhamento só para entender o que o PR pretende fazer.

Há também um problema de padrão humano. As pessoas folheiam diffs de maneiras previsíveis: focamos na mudança “principal” e perdemos as linhas chatas onde bugs se escondem (cheques de limite, tratamento de null, logging, limpeza). Também tendemos a ler o que esperamos ver, então erros de copiar/colar e condições invertidas podem passar despercebidos.

Uma boa pré-revisão não é um veredicto. É um segundo par de olhos rápido e estruturado que aponta onde um humano deve desacelerar. O melhor resultado é:

• um resumo em linguagem simples do que mudou
• pontos de risco específicos (arquivos, funções, suposições)
• notas de legibilidade (nomes, fluxo de controle confuso)
• preocupações de correção (lógica, tratamento de erro, consistência de dados)
• casos de borda que valem testar (entradas, tempo, permissões, estados vazios)

O que não deve fazer: “aprovar” o PR, inventar requisitos ou adivinhar comportamento em tempo de execução sem evidência. Se o diff não incluir contexto suficiente (entradas esperadas, restrições, contratos de chamadores), a pré-revisão deve dizer isso e listar exatamente o que falta.

A ajuda de IA é mais forte em PRs de tamanho médio que tocam lógica de negócio ou refatorações onde o significado pode se perder. É mais fraca quando a resposta certa depende de conhecimento organizacional profundo (comportamento legado, peculiaridades de performance em produção, regras internas de segurança).

Exemplo: um PR que “só atualiza a paginação” frequentemente esconde páginas off-by-one, resultados vazios e ordenação incompatível entre API e UI. Uma pré-revisão deve trazer essas perguntas antes que um humano gaste 30 minutos redescobrindo-as.

O que pedir ao Claude numa pré-revisão

Trate Claude como um revisor de primeira passada rápido e exigente, não como a pessoa que decide se o PR deve ser enviado. O objetivo é surfacing de problemas cedo: código confuso, mudanças de comportamento ocultas, testes ausentes e casos de borda que você esquece quando está próximo da mudança.

Dê a ele o que um revisor humano justo precisaria:

• o objetivo do PR (1 a 3 frases)
• o que não pode quebrar (formato da API, compatibilidade retroativa, orçamento de performance, regras de segurança)
• quaisquer restrições ou trade-offs especiais (prazos, rollout parcial)
• os trechos relevantes do diff, com código ao redor suficiente para entender a intenção

Se o PR toca uma área conhecida de alto risco, diga isso desde o início (auth, billing, migrations, concorrência).

Depois peça saídas acionáveis. Um pedido forte fica assim:

• Resuma o que mudou em linguagem simples.
• Aponte problemas de legibilidade (nomes, estrutura, surpresas, padrões inconsistentes).
• Identifique riscos de correção (tratamento de null, caminhos de erro, off-by-one, incompatibilidade de formatos de dados).
• Liste casos de borda e modos de falha (timeouts, retries, entradas vazias, atualizações parciais).
• Sugira testes faltantes e o que cada teste comprova.
• Gere um checklist curto para o revisor e 5 a 10 “perguntas a fazer” antes do merge.

Mantenha o humano no comando forçando clareza sobre incertezas. Peça ao Claude para rotular achados como “certo a partir do diff” vs “precisa de confirmação”, e para citar as linhas exatas que geraram cada preocupação.

Prepare o diff e o contexto antes de mandar o prompt

Claude é tão bom quanto o que você mostra. Se você colar um diff gigante sem objetivo ou restrições, receberá conselhos genéricos e perderá os riscos reais.

Comece com um objetivo concreto e critérios de sucesso. Por exemplo: “Este PR adiciona rate limiting ao endpoint de login para reduzir abuso. Não deve alterar o formato da resposta. Deve manter latência média abaixo de 50 ms.”

Em seguida, inclua apenas o que importa. Se 20 arquivos mudaram mas só 3 contêm a lógica, foque nesses. Inclua contexto ao redor quando um trecho isolado seria enganoso, como assinaturas de função, tipos chave ou configuração que altera o comportamento.

Por fim, seja explícito sobre expectativas de teste. Se você quer testes unitários para casos de borda, um teste de integração para um caminho crítico ou uma execução manual na UI, diga isso. Se testes estão ausentes de propósito, explique o porquê.

Um “pacote de contexto” simples que funciona bem:

• Objetivo do PR: o que muda, o que o usuário vê, o que deve melhorar
• Trechos relevantes do diff: arquivos-chave apenas, com código ao redor suficiente
• Restrições duras: orçamentos de performance, requisitos de compatibilidade, regras de segurança/privacidade
• Expectativas de teste: o que deve ser coberto, o que foi adicionado, como rodar
• Itens que “não podem mudar”: contratos públicos da API, esquema do banco, comportamento de UX, formato de logs/auditoria

Passo a passo: um fluxo de pré-revisão repetível

Uma boa revisão Claude Code para PR funciona como um loop curto: forneça contexto suficiente, receba notas estruturadas e transforme-as em ações. Não substitui humanos. Captura deslizes fáceis antes que um colega gaste muito tempo lendo.

O fluxo de 5 passadas

Use as mesmas passadas cada vez para que os resultados sejam previsíveis:

1. Explique a mudança em linguagem simples. Peça ao Claude para resumir o que o PR faz, quais arquivos mudaram e a razão provável da mudança. Se não conseguir explicar de forma simples, o PR provavelmente precisa de descrição mais clara ou escopo menor.
2. Cheque corretude primeiro. Busque erros de lógica, suposições quebradas e mudanças silenciosas de comportamento (padrões padrão, tratamento de erro, permissões, fusos horários, off-by-one).
3. Procure casos faltantes. Pense como o usuário e como produção: entradas vazias, nulls, retries, falhas parciais, concorrência, compatibilidade retroativa.
4. Revise legibilidade e manutenção. Identifique nomes confusos, funções longas, lógica duplicada, comentários pouco claros e pequenas refatorações que reduzem o tempo de revisão futuro.
5. Rascunhe comentários de revisão com apontamentos. Agrupe comentários por arquivo e inclua o nome da função ou trecho citado para que um humano encontre o ponto rapidamente.

Depois de receber as notas, transforme-as em um pequeno gate de merge:

Checklist de merge (mantenha curto):

• Testes cobrem o comportamento novo e pelo menos um caso de borda
• Erros são tratados consistentemente (e logados se necessário)
• Nenhuma mudança breaking sem plano de migração claro
• Nomes e estrutura batem com o código próximo
• Partes arriscadas têm um plano de rollback

Termine pedindo 3 a 5 perguntas que forcem clareza, como “O que acontece se a API retornar uma lista vazia?” ou “Isso é seguro sob requisições concorrentes?”.

Use um rubrica simples (legibilidade, corretude, casos de borda)

Claude é mais útil quando você dá uma lente fixa. Sem rubrica, tende a comentar o que aparecer primeiro (frequentemente nits de estilo) e pode perder o caso limite arriscado.

Uma rubrica prática:

• Legibilidade: nomes claros, fluxo simples, funções pequenas, comentários que expliquem o porquê, sem código morto ou saída de depuração sobrando.
• Corretude: invariantes chave são aplicadas, erros tratados consistentemente, valores null/vazios seguros, limites corretos (off-by-one, arredondamento).
• Casos de borda: entradas vazias/grandes, campos opcionais ausentes, fusos horários e horário de verão, retries que arriscam double-writes, condições de corrida.
• Segurança e privacidade: cheques de autenticação no lugar certo, sem segredos no código/logs, logs não expõem tokens ou payloads sensíveis.
• Compatibilidade e segurança no rollout: clientes antigos e dados armazenados não quebram, migrações são seguras, existe plano de rollback.

Ao pedir, solicite um parágrafo curto por categoria e peça “maior risco primeiro.” Essa ordem mantém os humanos focados.

Templates de prompt que geram notas úteis de revisão

Use um prompt-base reutilizável para que os resultados sejam uniformes entre PRs. Cole a descrição do PR e depois o diff. Se o comportamento for voltado ao usuário, adicione o comportamento esperado em 1–2 frases.

You are doing a pre-review of a pull request.

Context
- Repo/service: <name>
- Goal of change: <1-2 sentences>
- Constraints: <perf, security, backward compatibility, etc>

Input
- PR description:
<...>
- Diff (unified diff):
<...>

Output format
1) Summary (max 4 bullets)
2) Readability notes (nits + suggested rewrites)
3) Correctness risks (what could break, and why)
4) Edge cases to test (specific scenarios)
5) Reviewer checklist (5-10 checkboxes)
6) Questions to ask the author before merge (3-7)

Rules
- Cite evidence by quoting the relevant diff lines and naming file + function/class.
- If unsure, say what info you need.

Para mudanças de alto risco (auth, pagamentos, permissões, migrações), acrescente pensamento explícito sobre falha e rollback:

Extra focus for this review:
- Security/privacy risks, permission bypass, data leaks
- Money/credits/accounting correctness (double-charge, idempotency)
- Migration safety (locks, backfill, down path, runtime compatibility)
- Monitoring/alerts and rollback plan
Return a “stop-ship” section listing issues that should block merge.

Para refactors, torne “sem mudança de comportamento” uma regra rígida:

This PR is a refactor. Assume behavior must be identical.
- Flag any behavior change, even if minor.
- List invariants that must remain true.
- Point to the exact diff hunks that could change behavior.
- Suggest a minimal test plan to confirm equivalence.

Se quiser uma revisão rápida, acrescente um limite como “Responda em menos de 200 palavras.” Se quiser profundidade, peça “até 10 achados com justificativa.”

Transforme a saída em um checklist de revisor

As notas do Claude viram úteis quando você as converte num checklist curto que um humano pode fechar. Não repita o diff. Capture riscos e decisões.

Separe itens em dois grupos para a thread não virar debate de preferência:

Must-fix (bloqueia merge)

• Corretude: resultado esperado está escrito em uma frase e bate com o ticket
• Casos de borda: entradas null/vazias e caminhos de erro são tratados (ou rejeitados) claramente
• Segurança de dados: escritas e migrações são seguras para dados existentes e código antigo
• Testes: ao menos um teste cobre o comportamento principal e outro cobre a falha mais arriscada
• Observabilidade: logs/metrics suficientes para debugar rapidamente (request id, user id, job id)

Nice-to-have (seguimento)

• Legibilidade: renomear o identificador mais confuso ou adicionar um comentário curto explicando o “porquê”
• Consistência: alinhar padrões existentes para erros, nomes e layout de arquivos
• Performance: notar mudanças em hot-paths e se importam na escala atual
• Docs: atualizar docs inline se uma nova opção/flag foi adicionada

Também capture prontidão para rollout: ordem de deploy mais segura, o que monitorar após o lançamento e como desfazer a mudança.

Perguntas a fazer antes do merge

Uma pré-revisão só ajuda se terminar com um pequeno conjunto de perguntas que forcem clareza.

Comportamento e corretude

• Que mudança visível ao usuário acontece, e o que deve permanecer igual?
• Se isso é “sem mudança de comportamento”, qual evidência mostra que as saídas são idênticas?
• Qual é a falha mais provável em produção, e onde ela apareceria (UI, API, dados)?
• Quais suposições o código faz sobre entradas, ordenação, tempo ou chamadas de rede?
• Há erros engolidos ou transformados em defaults silenciosos?

Casos de borda, testes e operações

• Quais são as piores entradas reais (vazias, gigantes, malformadas, duplicadas) e o que deve acontecer?
• Qual fluxo comum pode acionar isso duas vezes (retries, double-click, jobs de background) e é seguro?
• Qual teste prova o comportamento principal, e qual cobre o caso de borda mais arriscado?
• Se faltar um teste, é difícil de escrever ou o código é difícil de testar?
• O que ops precisará: logs úteis, métricas, alertas, defaults de config e passos de rollback?

Se você não consegue responder isso em palavras simples, pause o merge e enxugue o escopo ou adicione provas.

Armadilhas comuns (e como evitá-las)

A maioria das falhas são problemas de processo, não do modelo.

• Colar diffs enormes sem foco. Peça revisão em 1 a 3 áreas de risco e cole só os hunks relacionados mais as assinaturas que dependem deles.
• Pular intenção e comportamento esperado. Sem objetivo, a revisão deriva. Adicione duas linhas: o que muda e o que não pode mudar.
• Confiar em palpites confiantes. Exija citações ao diff. Se não puder citar evidência, trate como hipótese a ser testada.
• Bikeshedding em estilo. Peça “Must-fix” vs “Nice-to-have” e limite notas de estilo.
• Ignorar padrões da equipe. Se seu time tem convenções (returns cedo, tipos de erro, formato de logging), inclua-as.

Se um PR adiciona um endpoint de checkout novo, não cole todo o serviço. Cole o handler, validação, escrita no DB e qualquer mudança de schema. Depois diga: “Objetivo: prevenir cobranças duplas. Não é objetivo: refatorar nomes.” Você receberá menos comentários e os que vierem serão mais fáceis de verificar.

Um exemplo realista: pré-revisão de um PR pequeno

Um PR pequeno: adicionar um campo “display name” a uma tela de configurações. Toca validação (server) e texto na UI (client). É pequeno, mas ainda cheio de lugares onde bugs se escondem.

Aqui estão os trechos de diff que você colaria (mais 2–3 frases de contexto como comportamento esperado e tickets relacionados):

- if len(name) == 0 { return error("name required") }
+ if len(displayName) < 3 { return error("display name too short") }
+ if len(displayName) > 30 { return error("display name too long") }

- <TextInput label="Name" value={name} />
+ <TextInput label="Display name" value={displayName} helperText="Shown on your profile" />

Exemplos de achados que você quer receber:

• Legibilidade: “displayName” vs “name” está misturado entre arquivos. Escolha um termo para evitar tradução mental em mudanças futuras.
• Corretude: o servidor valida comprimento, mas o cliente não. Usuários podem digitar 1 ou 2 caracteres e só ver o erro no submit.
• Caso de borda: strings com apenas espaços passam em len(displayName) mas ainda parecem vazias. Faça trim antes da validação.

Transforme isso num checklist:

• Nomes consistentes na API, campos do banco e rótulos da UI.
• Validações cliente correspondem às regras do servidor (min/max, required).
• Entrada é trimada (e comportamento com Unicode/emoji é aceitável).
• Mensagens de erro são claras e alinhadas entre servidor e UI.

Verificações rápidas, métricas e próximos passos

Uma revisão Claude Code funciona melhor quando termina com algumas checagens rápidas:

• Comportamento: o que muda para o usuário e o que não pode mudar
• Testes: o que está coberto, o que falta, o que pode flutuar
• Logs e erros: falhas são claras e mensagens são úteis
• Performance: novos loops, queries N+1, payloads grandes, chamadas de rede extras
• Segurança: validação, cheques de auth, segredos, defaults arriscados

Para ver se está funcionando, acompanhe duas métricas simples por 2–4 semanas: tempo de revisão (aberto até primeira revisão significativa e aberto até merge) e retrabalho (commits de follow-up após revisão, ou quantos comentários exigiram mudanças de código).

Padronização vence prompts perfeitos. Escolha um template, exija um bloco de contexto curto (o que mudou, por que, como testar) e combine o que significa “pronto”.

Se seu time desenvolve por chat, pode aplicar o mesmo fluxo no Koder.ai: gere mudanças, exporte o código-fonte e anexe o checklist de pré-revisão ao PR para que a revisão humana foque nas partes de maior risco.