Como usar o Claude Code para revisar o pull request de outra pessoa antes do merge

Quase todo mundo usa o Claude Code pra ESCREVER código

Aí cai na tua fila aquele PR gigante, de outra pessoa, mexendo em arquivo que tu nem lembrava que existia

E a brincadeira inverte: em vez de pedir código pro agente, tu entrega o diff alheio pra ele ler

O trabalho aqui é outro: achar risco, efeito colateral e teste faltando antes do merge, sem passar duas horas rolando o diff no navegador…

O que você precisa antes de começar

Pouca coisa, na real 🙂

• Claude Code instalado e uma sessão aberta dentro do repositório
• o branch ou o PR alvo acessível localmente
• e só isso: o /code-review roda em qualquer sessão do Claude Code, sem precisar instalar o app do GitHub, e reporta bugs de correção mais limpezas de reuso, simplificação e eficiência

Agora se liga no detalhe que muda tudo neste post

Por padrão, o /code-review cobre os commits do branch que estão à frente do upstream mais as mudanças não commitadas na working tree

Ou seja: sem trabalho no branch e sem nada na working tree, não existe o que reportar

E o PR aqui é de OUTRA pessoa, então teu branch pode estar limpinho e a revisão sair vazia. É por isso que o passo que vira o jogo é apontar um alvo explícito, e não simplesmente rodar o comando e esperar mágica

Se o teu fluxo de versionamento ainda é 100% na unha, vale ver antes como usar o Claude Code com Git pra criar commits e PRs, porque o resto fica bem mais fluido

Um aviso pra não confundir produto: o Code Review integrado ao GitHub é OUTRA coisa

Ele está em research preview e disponível nos planos Team e Enterprise

Não está disponível para Pro ou Max individuais, nem para organizações com retenção zero de dados

Nada do passo a passo abaixo depende dele, beleza? Nos demais planos ainda dá pra revisar um diff localmente com o /code-review

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Passo a passo: revisando o PR de outra pessoa com /code-review

1. Abra a sessão no repositório certo

Parece óbvio, mas é onde mais gente tropeça: o comando lê o repo em que a sessão está

cd caminho/do/seu/repo
claude

2. Rode o /code-review apontando o alvo

Esse é o pulo do gato. O comando aceita um caminho de arquivo, um número de PR, um nome de branch ou um intervalo de refs no formato main...my-feature

/code-review 1234
/code-review feature-do-fulano
/code-review main...feature-do-fulano

O erro comum deste passo é rodar /code-review pelado, sem alvo, e revisar o próprio nada. Como o escopo padrão é o teu branch mais a tua working tree, tu termina revisando o teu trabalho (ou a ausência dele) enquanto acha que está lendo o PR do colega

Detalhe pra quem tem memória muscular do /review: na versão v2.1.223 do Claude Code, o /review virou apelido de /code-review, que revisa o diff atual ou um PR na forma /code-review <nível> <nº do PR>

Se tu gosta de montar teu próprio ferramental, dá pra ir mais longe com slash commands e skills por cima desse fluxo

3. Escolha o nível de esforço conforme o PR

O nível muda o TIPO de achado, não só a quantidade

Níveis mais baixos (low, medium) devolvem menos achados e de confiança mais alta

De high a max a cobertura é mais ampla e pode incluir achados incertos

E ultra roda a revisão mais profunda na nuvem

Se tu não informar nível, ele usa o nível atual da sessão

/code-review medium 1234
/code-review max 1234

O erro comum deste passo é mandar max num PR de três linhas e afogar o autor em ruído. PR trivial pede nível baixo, refactor grande e mudança de contrato pedem cobertura ampla

4. Leia os achados na ordem em que eles chegam

Os achados já vêm deduplicados e ordenados por severidade, então começa por cima

Severidade alta primeiro, nit depois. Se tu ler de baixo pra cima, gasta teu melhor tempo com detalhe cosmético

5. Decida entre --comment e --fix

São duas flags com efeitos MUITO diferentes

--comment publica os achados como comentários inline no PR

--fix aplica os achados na working tree depois da revisão

/code-review high 1234 --comment

O erro comum deste passo é disparar --fix num PR que não é seu. Tu não está revisando, tu está reescrevendo o trabalho do outro na tua máquina e criando um mini fork mental da discussão. Em revisão de PR alheio, o padrão saudável é comentar e devolver pra quem abriu

6. Rode o /security-review pra camada de segurança

O Claude Code tem um comando separado só pra isso: o /security-review roda a análise de segurança direto do terminal antes do commit

/security-review

Ele checa padrões como injeção de SQL e de comando, XSS, falhas de autenticação e autorização, exposição de dados, problemas de criptografia e validação de entrada

É uma passada diferente da revisão de correção e limpeza, então roda as duas quando o PR toca input de usuário, permissão ou dado sensível

Roteiro de perguntas para fazer ao agente sobre o diff

Antes das perguntas, entende COMO a revisão funciona por dentro, porque isso muda o jeito de perguntar

Vários agentes analisam o diff e o código ao redor em paralelo, cada um procurando uma classe diferente de problema

Depois uma etapa de verificação confere os resultados contra o comportamento real do código, pra filtrar falso positivo

Traduzindo: quanto mais tu nomear a CLASSE de problema que te preocupa, melhor o retorno. Pergunta genérica ("esse PR está bom?") devolve resposta genérica

Esse é o roteiro que eu usaria depois da primeira rodada de achados

Risco: o que quebra fora do diff

• "Quais comportamentos existentes mudam por causa deste diff, mesmo em arquivos que não foram tocados?"
• "Tem alguma suposição implícita aqui que o resto do código não garante?"
• "Qual é o pior cenário se essa mudança for pro ar sexta à noite?"

Efeito colateral: quem mais chama isso

• "Liste todos os pontos do repositório que chamam as funções alteradas neste PR"
• "Alguma dessas chamadas depende do formato de retorno antigo?"
• "Essa mudança altera contrato de API, schema ou formato de evento consumido por outro serviço?"

Aqui vale a tática de pedir prova: exigir que a afirmação de comportamento venha com citação file:line no código-fonte, em vez de inferência a partir de nomes de função

Teste faltando

• "Quais caminhos de código introduzidos neste PR não têm teste cobrindo?"
• "Qual é o caso de borda mais provável de quebrar e não está testado?"
• "Se eu só pudesse pedir UM teste novo pro autor, qual seria e por quê?"

Dado antigo e migração

• "O que acontece com registros criados ANTES desta mudança?"
• "Essa alteração precisa de migração ou backfill? Se sim, o PR inclui?"
• "Tem algum estado intermediário durante o deploy em que código novo lê dado velho (ou o contrário)?"

Quando escalar o nível de esforço

Regra prática simples

• correção de bug pequena, ajuste de texto, config: low ou medium resolvem e o sinal vem limpo
• refactor amplo, mudança de contrato, código crítico de pagamento ou permissão: high ou max, aceitando que vai vir achado incerto no meio
• PR daqueles que ninguém quer revisar sozinho: ultra, que roda a revisão mais profunda na nuvem

A lógica é a mesma de sempre: subir esforço aumenta cobertura E ruído junto, então tu escolhe qual dor prefere naquele PR

A revisão está apontando coisa demais? Como calibrar o ruído

Sintoma: a revisão volta com uma parede de achados incertos, nit em código gerado, reclamação de lockfile e de dependência vendorizada. O PR fica com mais comentário de robô do que de gente

Causa: quase sempre são duas coisas somadas. Nível de esforço alto demais pro tamanho do PR, e ausência de regra dedicada dizendo o que interessa naquele repositório

Solução: um REVIEW.md na raiz do repositório

Esse arquivo é injetado como bloco de instrução de prioridade máxima no system prompt de TODO agente do pipeline de revisão, acima da orientação padrão

Com ele tu muda o que é flagrado, em que severidade e como os achados são reportados, incluindo regras de skip pra código gerado, lockfiles e dependências vendorizadas

# REVIEW.md

## Não revisar
- arquivos gerados automaticamente
- lockfiles
- dependências vendorizadas

## Severidade
- quebra de contrato de API: alta
- caminho sem teste em código de cobrança: alta
- preferência de estilo: não reportar

## Evidência
- toda afirmação sobre comportamento precisa vir com citação file:line
- sem citação, não postar o achado

Essa última regra é a tática antifalso positivo mais barata que existe: exigir evidência antes de postar uma classe de achado, ou seja, pedir citação file:line no código-fonte em vez de inferência a partir de nomes

E o CLAUDE.md, não serve pra isso?

Serve, mas não é a mesma coisa

O CLAUDE.md são as instruções gerais do projeto, usadas em TODAS as tarefas, e violações novas dele entram como nits

O REVIEW.md é só de revisão e, por ser prioridade máxima, faz as regras pegarem de forma mais confiável do que as mesmas regras enterradas dentro de um CLAUDE.md longo

Se tu já tentou colocar "não reclame de lockfile" no meio de um CLAUDE.md de 300 linhas e mesmo assim veio reclamação, é exatamente esse o problema 😀

Como prevenir: começa em nível baixo, lê os achados de severidade alta, e só sobe o esforço quando sentir que ficou raso. Criar o REVIEW.md no primeiro sinal de ruído recorrente, não antes

Comando local, Code Review no GitHub ou GitHub Action: qual usar

São três formas diferentes de colocar o Claude pra revisar PR, e elas não competem tanto quanto parece

No integrado, quem manda no gatilho é a organização: pode ser automático na abertura do PR, a cada push, ou só sob pedido manual

E comentar @claude review no PR inicia uma revisão, funcionando independentemente do gatilho configurado no repositório

Com gatilho automático, o sinal chega rápido: aparece em poucos minutos um check run chamado Claude Code Review

Sobre permissões do integrado, pra tu já chegar com a resposta na conversa com o time de infra: o app de Code Review pede acesso de leitura ao conteúdo do repositório e de escrita a pull requests e checks

No lado das Actions existem duas peças oficiais que valem conhecer

A claude-code-action tem dois modos de operação: o interativo, que responde a menções @claude, e o de automação, que roda direto com um prompt. O parâmetro claude_args aceita argumentos da CLI do Claude Code

E tem um detalhe que economiza uma tarde de debug: ao configurar revisão de PR pela Action, o prompt precisa incluir o repositório e o número do PR, senão o Claude não sabe qual PR revisar

Pra vulnerabilidade tem peça dedicada: o anthropics/claude-code-security-review é uma GitHub Action da Anthropic que usa o Claude pra analisar mudanças de código em busca de vulnerabilidades

Minha leitura, sem enrolação: o comando local é o que resolve pra maior parte de quem lê este post, porque não depende de plano de organização nem de aprovação de admin. Os outros dois entram quando o time quer revisão automática no fluxo, não sob demanda de uma pessoa

O que continua sendo trabalho do revisor humano

Aqui vem o veredito honesto, porque tem gente vendendo isso como "revisor automático" e não é

A revisão do Claude não decide o merge

Quando os achados vão parar no PR, eles chegam marcados por severidade e em comentários inline nas linhas específicas, mas a revisão não aprova nem bloqueia o PR. O teu fluxo de revisão humana existente continua valendo inteirinho

E o posicionamento oficial sobre segurança é literal nesse ponto: as revisões automáticas devem COMPLEMENTAR, e não substituir, as práticas de segurança existentes e a revisão manual de código

O que sobra pra pessoa, então

• Intenção do produto: o código pode estar impecável e resolver o problema errado. O agente lê o diff, não a conversa que gerou a demanda
• Decisão de arquitetura: se aquilo devia ser um novo serviço, uma coluna nova ou nem existir, é chamada de quem carrega o sistema no médio prazo
• Contexto de negócio: o que é aceitável quebrar, o que tem cliente grande dependendo, o que já foi combinado com outro time
• Julgamento de severidade real: o achado é técnico correto e irrelevante na prática? Só tu sabe
• A conversa com quem abriu o PR: revisão também é ensinar, alinhar padrão e não humilhar ninguém com 40 comentários automáticos de nit

O agente é excelente pra tirar de você a parte mecânica: ler tudo, cruzar chamadas, lembrar do caso de borda que tu esqueceu às 18h

A parte de decidir continua na cadeira

Próximo passo

Caminho mínimo pra tu sair daqui e fazer, hoje mesmo

Abre a sessão no repo, pega o próximo PR da fila e roda em nível baixo apontando o alvo

/code-review low 1234

Lê só os achados de severidade alta e vê se algum deles te pouparia tempo

Se ficou raso, sobe o esforço na segunda passada. Se veio ruído demais, aí sim tu cria o REVIEW.md com as regras de skip e a exigência de citação file:line

E quando o PR tocar input de usuário, permissão ou dado sensível, passa o /security-review por cima

No fim, o agente entrega o mapa dos riscos, mas quem clica no merge continua sendo você =)

até o próximo post!