Revisão de código com o Claude Code: encontre bugs antes de irem para produção

O que é o Claude Code Review?

O Claude Code Review é um sistema multiagente de revisão de código que examina um PR no contexto do repositório e relata potenciais bugs, problemas de segurança e regressões. O GitHub Code Review executa esses agentes em um PR do GitHub, enquanto o /code-review local oferece uma revisão do seu diff atual diretamente no Claude Code.

A palavra importante aqui é contexto. Uma revisão tradicional de diff pede para alguém inspecionar as linhas que mudaram. Os agentes de revisão do Claude analisam essas mudanças dentro do contexto do repositório. O fluxo do GitHub tem vários agentes especializados trabalhando em paralelo, seguidos de verificação, deduplicação e ranqueamento por severidade.

Por exemplo, uma mudança de 10 linhas em uma transformação com pandas pode depender do schema criado por um modelo dbt upstream, da granularidade de uma tabela no Snowflake e de suposições embutidas em um dashboard downstream.

O Claude nem aprova nem bloqueia um PR. O GitHub Code Review relata uma conclusão neutra no check, então suas regras atuais de proteção de branch permanecem inalteradas, a menos que você construa sua própria lógica de CI em cima da saída do check.

Três superfícies de revisão

Atualmente existem 3 formas principais de revisar código com o Claude Code.

O comando local /code-review examina os commits da sua branch. Você também pode informar um arquivo específico, branch, número de PR ou um intervalo de refs do Git.

O GitHub Code Review é desenhado em torno do próprio PR. Dependendo da configuração do repo, ele pode revisar uma vez após a criação do PR, a cada push, ou apenas quando alguém solicita a revisão com @claude review.

/code-review ultra é a opção mais pesada. A Anthropic chama o recurso de ultrareview, e /ultrareview funciona como um alias quando o recurso está disponível para sua conta. Ele executa uma frota de agentes revisores em um sandbox remoto, e cada bug relatado é reproduzido e verificado antes de aparecer nos achados. Atualmente é uma prévia de pesquisa, e uma revisão típica leva de 5 a 10 minutos.

O que o Claude sinaliza vs. o que ele ignora

O Claude Code Review prioriza correção. A documentação da Anthropic diferencia explicitamente bugs que impactam produção de preferências de formatação e cobertura de testes ausente.

Os achados usam 3 níveis de severidade:

Essa distinção é útil porque cientistas de dados costumam ter opiniões bem diferentes sobre o que merece tempo de revisão. Uma sugestão de nomenclatura sobre revenue_df versus weekly_revenue não está na mesma categoria que multiplicar a receita por 2 por causa de um join muitos-para-muitos que escorregou em uma transformação.

Como configurar o Code Review no Claude Code?

Configurar o Claude Code Review exige passos diferentes dependendo se você quer uma revisão local ou revisão de código em PR do GitHub. O /code-review local não requer o App do GitHub e pode ser feito antes mesmo de você abrir um PR. 

O GitHub Code Review requer que um Owner ou Primary Owner da organização configure o App do GitHub do Claude e selecione os repositórios. Ao fazer revisões de PR, você vai querer criar um arquivo especializado chamado REVIEW.md que contenha regras específicas apenas para revisão.

CLAUDE.md vs. REVIEW.md

CLAUDE.md e REVIEW.md têm propósitos diferentes, e misturá-los é um jeito fácil de criar revisões barulhentas.

CLAUDE.md contém instruções gerais do projeto que o Claude usa em várias tarefas. A revisão de código também lê essas instruções, e violações recém-introduzidas são reportadas como nits.  Já o REVIEW.md é específico para o comportamento de revisão e diz aos agentes o que seu time quer sinalizar, pular ou tratar como Importante.

Para um repositório de dados em Python, eu manteria o CLAUDE.md focado em coisas como a estrutura do repo, como rodar pytest, se as transformações usam pandas ou polars, e onde ficam os modelos SQL. 

Eu colocaria regras de revisão no REVIEW.md. Alguns exemplos de regras possíveis:

• "Verifique se toda transformação nova tem um teste correspondente."
• "Nunca faça log de credenciais."
• "Ignore arquivos gerados."

Um pequeno  REVIEW.md poderia ser assim:

# Review instructions

## Important findings

Report as Important:
- Incorrect joins or filters that can change dataset grain
- Missing tenant or customer scoping
- Secrets or credentials written to logs
- Silent changes to revenue or customer metrics

## Do not report
- Formatting already enforced by Ruff
- Generated files
- *.lock files

## Always check
- New transformations have tests
- Joins use the intended keys
- Datetime operations specify timezone assumptions
- Missing values are handled explicitly

Recomendo manter seu REVIEW.md focado porque instruções longas podem diluir regras importantes. A implementação atual também lê o arquivo como instruções simples, então você deve colocar as regras diretamente nele em vez de usar o atalho com @. 

Ah, e quando você está desenvolvendo localmente, o /code-review não lê o  REVIEW.md. Ele segue o CLAUDE.md, enquanto o pipeline do GitHub Code Review usa o  REVIEW.md para instruções específicas de revisão.

Se você quiser as mesmas regras de revisão localmente e no GitHub, coloque as regras gerais no CLAUDE.md e repita as regras específicas de revisão no REVIEW.md quando necessário.

Para se aprofundar, recomendo ler nosso guia sobre como escrever o melhor arquivo CLAUDE.md.

App do GitHub e modo de disparo

O GitHub Code Review é configurado por um Owner ou Primary Owner da organização pelas configurações de admin do Claude. O admin precisa instalar o App do GitHub do Claude, conceder acesso ao repo, selecionar os repositórios a revisar e então atribuir um comportamento de revisão para cada repo.

Existem 3 modos de disparo:

Uma exceção aos 3: o Claude nunca revisa automaticamente um pull request vindo de um fork. Alguém precisa comentar @claude review nele.

A partir da atualização de julho de 2026, os comandos manuais também mudaram: 

• @claude review inicia uma única revisão e não inscreve o PR para futuras revisões por push. 

• @claude review always inicia uma revisão e inscreve o PR para revisões acionadas por push no futuro.

• @claude review once se comporta igual ao comando simples.

Se você aprendeu o Claude Code Review no início de 2026, tutoriais antigos podem ter dito que @claude review inscreve o PR para futuras revisões, mas esse comportamento mudou em julho de 2026 e continua valendo em setembro de 2026.

Usuários Pro e Max que não têm acesso ao GitHub Code Review da organização podem pular totalmente o App e usar /code-review localmente, com /code-review ultra para uma revisão mais profunda.

Como revisar um diff localmente com /code-review?

O comando local /code-review revisa sua branch atual antes de você abrir um PR. Eu sempre começo por aqui porque ele pega problemas enquanto ainda estou trabalhando e pode evitar falhas no CI.

O caso a revisar

Vamos imaginar um repo de e-commerce com uma tabela de pedidos contendo order_id, customer_id, order_date, status e revenue, e criamos o weekly_revenue.py para calcular a receita semanal:

orders = load_orders()
customers = load_customers()

# Derive the reporting week from the order date
orders["week"] = orders["order_date"].dt.to_period("W").dt.start_time

weekly_revenue = (
    orders
    .merge(customers, on="customer_id", how="inner")
    .groupby("week", as_index=False)["revenue"]
    .sum()
)

À primeira vista, nada estranho. O merge() é explícito, o agrupamento é legível e a receita é agregada após o join.

O problema é que a tabela de clientes contém vários registros históricos para alguns clientes. Um cliente com 2 registros agora produz 2 linhas após o join, dobrando a receita atribuída a esse cliente. Esse é exatamente o tipo de bug fácil de passar batido quando você lê a transformação localmente sem checar a granularidade da tabela.

Delimite o diff

Na sua sessão do Claude Code, rode /code-review.

O comando revisa os commits da branch atual à frente da sua branch upstream, junto com mudanças não comitadas. Você também pode mirar um arquivo, branch, PR ou intervalo específico, como main...feature/weekly-revenue.

Por exemplo:

/code-review weekly_revenue.py

ou:

/code-review main...feature/weekly-revenue

Você também pode passar um nível de esforço, como /code-review high. Em low e medium, a revisão reporta apenas os achados com maior confiança, enquanto de high a max amplia a cobertura ao custo de mais possíveis falsos positivos. 

Use flags para direcionar a revisão

Quando você se acostumar com o fluxo, duas flags começam a ajudar bastante: 

• --fix aplica os achados na sua working tree após a revisão.

• --comment publica os achados como comentários inline.

O Claude executa a revisão como um subagente em background, então você pode continuar trabalhando enquanto ele processa a mudança. Os achados voltam para sua sessão quando a revisão termina.

A revisão pode relatar algo assim:

🔴 Important
weekly_revenue.py:9

The merge on customer_id can duplicate order rows because
customers contains multiple records per customer. This can
inflate revenue when a customer has more than one matching
customer record.

Verify that customer_id is unique in customers or join against
the intended current-record subset before aggregating revenue.

A revisão encontrou um modo de falha concreto e me dá algo que posso verificar contra o schema real, em vez de pedir para eu confiar no julgamento do Claude.

Leia os achados

Ainda assim, eu faria uma passada manual em tudo antes de rodar /code-review --fix. Primeiro, procure o código que constrói customers, inspecione as restrições de unicidade e veja os testes ao redor do weekly_revenue.py.

Se customers.customer_id for realmente único, o achado do Claude é um falso positivo. Se a tabela contiver uma linha por cliente por data de vigência, o achado é real e a transformação precisa mudar.

O ponto-chave aqui é que o revisor do Claude está olhando para o comportamento do código, enquanto eu continuo responsável por saber o que os dados representam.

Você pode pedir para o Claude investigar após a revisão:

Investigate the customer_id join finding.
Check how the customers table is built and determine whether
customer_id is unique at the point of this merge. Do not modify
the code yet.

Essa segunda etapa costuma ser mais útil do que pedir para o Claude corrigir cegamente o comentário. Ela transforma a revisão em uma breve investigação em vez de um exercício de geração de código.

Como rodar o Claude Code Review em um PR do GitHub?

O GitHub Code Review coloca os achados do Claude diretamente no PR, para que os revisores vejam o problema ao lado do código alterado. 

A ordem importa porque a revisão é anexada a um PR que já existe:

1. Dê push na branch weekly-revenue para o GitHub via git push.

2. Abra o pull request. O Claude só consegue revisar um PR aberto, então nada acontece antes disso.

3. Se o repo estiver com disparo automático, a revisão começa sozinha. Se estiver como Manual, publique @claude review como comentário de PR de nível superior para iniciar.

Três requisitos pegam as pessoas aqui. O comando precisa ser um comentário de nível superior no PR, e não uma resposta a um comentário inline; você precisa de permissão de write, maintain ou admin no repo. O comando também deve iniciar o comentário, com once ou always na mesma linha, se forem adicionados.

Dispare a revisão

A escolha que de fato impacta seu gasto é entre os dois comandos manuais, não entre manual e automático.

@claude review roda uma revisão e deixa o PR não inscrito. @claude review always roda uma revisão e inscreve o PR, então cada push posterior inicia outra.

Esse é o comportamento após julho de 2026 e válido em setembro de 2026. Antes dessa atualização, o comando simples @claude review inscrevia o PR para revisões futuras; se você estiver seguindo um tutorial antigo, confira isso primeiro.

A revisão costuma levar cerca de 20 minutos, embora a Anthropic diga que custo e duração dependem do tamanho e da complexidade do PR. Cada revisão também é cobrada separadamente por créditos de uso, e não consome o uso incluído do plano Team ou Enterprise. Se você quiser saber mais sobre a estrutura de custos, recomendo ler nosso guia de limites de uso do Claude Code.

Leia os comentários inline e o check run

Quando a revisão termina, o Claude publica comentários inline nas linhas relevantes. O check run do GitHub também inclui um resumo por severidade, útil quando um PR tem múltiplos achados ao longo do weekly_revenue.py, modelos SQL e arquivos de teste.

Por exemplo:

O comentário inline é onde eu investigaria o problema real. O check run é onde eu veria o panorama geral da revisão.

Só um detalhe: clicar em 👍 ou 👎 não dispara outra revisão, e responder a um comentário inline não faz o Claude responder. Para obter outra revisão, corrija o código e dê push, ou publique @claude review como um novo comentário de PR de nível superior.

A revisão também não bloqueia o merge por si só. O check tem conclusão neutra, embora a saída inclua informações de severidade legíveis por máquina que o time pode consumir via gh e jq se quiser construir seu próprio gate de merge.

Como priorizar os comentários do Claude?

A ideia é manter o humano no loop durante o ciclo de revisão. Isto é, toda revisão do Claude exige decidir se cada achado é um bug real, uma melhoria não bloqueante ou um falso positivo. Isso acontece porque um revisor de código pode inspecionar o comportamento da implementação sem conhecer todas as suposições de negócio por trás de um dataset ou métrica.

Eu uso uma decisão simples em 3 vias:

Essa última categoria é importante. Um revisor que relata 30 achados não é necessariamente melhor do que um que relata 5. Um comentário falso-positivo sobre um merge com pandas pode custar mais tempo do que a mudança original do código.

Corrigir, pular ou contestar

Se o bug de duplicação de linhas por cliente for real, eu poderia pedir para o Claude inspecionar o modelo upstream e então fazer a seguinte correção:

The customer_id finding is valid. Inspect the existing customer
model and update weekly_revenue.py to join only the current
customer record. Add a regression test for a customer with
multiple historical records, then run the relevant tests.

O Claude pode então inspecionar o repo, alterar o código Python, adicionar o teste e rodar a suíte.

Se você quiser trabalhar a partir dos comentários de revisão do GitHub, o Claude Code também pode interagir com o repo via GitHub CLI (gh). A distinção importante é que eu escolheria os consertos específicos que você considera válidos, em vez de entregar a revisão inteira para "corrigir tudo".

Isso mantém desenvolvedores no loop da revisão:

1. O Claude encontra um possível problema.
2. Eu verifico o problema contra o código e as suposições dos dados.
3. O Claude faz a correção solicitada.
4. Os testes rodam.
5. O Claude revisa o diff resultante de novo.

Esse ciclo é muito mais seguro do que tratar a primeira saída da revisão como uma fila automatizada de refatoração.

Para que um PR de dados ainda precisa de um humano?

O modo de falha que o Claude não cobre é quando o código roda corretamente e ainda faz a coisa errada. Três versões disso aparecem o tempo todo:

• Suposições que vivem fora do diff. O Claude lê seu repo, não seu data warehouse, seu serviço de config ou o contrato que outro time possui. Um join pode usar as chaves certas e ainda assim mudar a granularidade do resultado, porque o número de linhas por chave é uma propriedade da tabela upstream, não do código à sua frente.

• Definições que só o seu time possui. Se a receita deve ser contada no nível do pedido, do cliente ou da semana é uma decisão de negócio. O Claude pode dizer que um groupby() vai somar alegremente o que quer que receba. Ele não pode dizer qual número seu time de finanças aprova.

• Suposições de tempo e tipo. 2026-08-27 significa um dia UTC, um dia útil local ou uma data de reporte definida por um modelo upstream? Coerções silenciosas têm o mesmo formato: operações entre colunas object, inteiros anuláveis, datetimes com fuso e strings podem retornar algo plausível enquanto mudam silenciosamente como comparações se comportam.

Vazamento de dados é o exemplo mais agudo da primeira categoria. Uma transformação de features pode juntar um conjunto de treinamento a uma tabela que só tinha a informação depois da data de previsão. O join é válido, a contagem de linhas é a esperada e o modelo está corrompido.

Por isso, trato o Claude como um revisor do comportamento da implementação, não o dono da definição.

Quando usar Code Review vs. Ultrareview?

Use /code-review para feedback local rápido e /code-review ultra para uma análise mais profunda antes do merge. Ambos revisam código, mas /code-review é feito para iteração, enquanto o ultra executa múltiplos agentes remotos e verifica de forma independente os bugs relatados.

A Anthropic atualmente descreve o ultra review como prévia de pesquisa. Assinantes Pro e Max recebem 3 execuções grátis como cota única que não se renova; depois, uma revisão custa tipicamente de US$ 5 a US$ 25, dependendo do tamanho da mudança. Usuários Team e Enterprise não recebem essas execuções grátis, e o recurso não está disponível no Amazon Bedrock, no Agent Platform do Google Cloud, no Microsoft Foundry e para organizações com Zero Data Retention habilitado.

A diferença importante é a verificação. O /code-review ultra envia o estado do repo para um sandbox remoto e roda uma frota de agentes revisores, com bugs relatados reproduzidos de forma independente antes de retornarem como achados.

Eu não rodaria em todo commit. Se estou mudando o nome de uma variável em um notebook Python ou ajustando a formatação de um modelo dbt, um /code-review local é suficiente. Se estou mudando a lógica de geração de features de um modelo de produção, reescrevendo uma transformação de receita ou alterando uma agregação em nível de cliente, a passada extra de revisão faz mais sentido.

Há também um detalhe de nomenclatura importante. O comando documentado é /code-review ultra, e /ultrareview é um alias que funciona quando o ultrareview está disponível na sua conta. Tutoriais mais antigos costumam apresentar /ultrareview como comando principal, mas a documentação da Anthropic agora trata a revisão profunda em nuvem como parte da família /code-review, e /code-review ultra faz fallback para uma revisão local quando o recurso em nuvem não está disponível.

Rode o ultra review no mesmo PR

No repo, rode:

/code-review ultra

Para revisar um PR do GitHub diretamente:

/code-review ultra <pr#>

Sem argumento, o /code-review ultra compara sua branch atual com a branch padrão e inclui mudanças não comitadas e staged. Uma revisão de branch é limitada por padrão a cerca de 500 arquivos alterados e 8.000 linhas alteradas, embora a Anthropic observe que esses números podem mudar. Se seu diff for grande demais, dê push na branch e revise como PR.

Com um número de PR, o ambiente remoto clona o PR do GitHub, e nada é enviado do seu computador.

Antes de começar, o Claude mostra o escopo da revisão, as execuções grátis restantes e o custo estimado. Após a confirmação, a revisão roda em background, então você pode continuar usando o Claude Code enquanto os agentes remotos trabalham.

No nosso exemplo weekly_revenue.py, eu compararia os achados em vez de assumir que a revisão mais profunda está certa.

Se o /code-review sinaliza o join de clientes e o ultra review reproduz de forma independente a mesma duplicação de receita, minha confiança nesse achado aumenta. Se o ultra review ignorar porque a tabela upstream garante unicidade, eu inspecionaria a evidência de ambas as revisões e a definição real do modelo antes de mudar o código.

Essa é uma propriedade útil de múltiplos revisores: o desacordo te dá algo para investigar.

Há também a questão de custo. O GitHub Code Review hoje fica em média entre US$ 15 e US$ 25 por revisão, enquanto o ultra review geralmente custa de US$ 5 a US$ 25 após as execuções grátis no Pro e Max. Os custos do GitHub Code Review são separados do uso incluído do plano, e a Anthropic oferece controles de gasto para organizações.

Se você trabalha sozinho, /code-review local mais um /code-review ultra ocasional é um fluxo inicial razoável. Se você está em um plano Team ou Enterprise e quer que todo PR tenha uma revisão automatizada, o GitHub Code Review faz mais sentido.

Um fluxo prático de Claude Code Review

O fluxo útil não é "rodar o Claude antes de todo merge". É uma sequência em que cada revisão acontece em um momento diferente do desenvolvimento, porque cada uma custa diferente e pega uma classe distinta de problemas.

Aqui está o processo que eu usaria para uma mudança de produção:

Write code
	   ↓
Run tests and data checks
	   ↓
/code-review
	   ↓
Fix verified findings
	   ↓
Open GitHub PR
	   ↓
GitHub Code Review
	   ↓
Human triage
	   ↓
/code-review ultra for higher-risk changes
	   ↓
Final tests
	   ↓
Human merge

A revisão local captura problemas quando são baratos de corrigir. A revisão no GitHub dá ao time um registro compartilhado de achados, enquanto o ultra review oferece uma segunda opinião, mais custosa, antes de um merge de maior impacto.

Checagens adicionais para cientistas de dados

Para trabalhos de dados, eu adicionaria 4 checagens ao redor do Claude, em vez de esperar que o modelo faça a revisão inteira:

• Verifique contagem de linhas e granularidade do dataset antes e depois de joins importantes
• Rode testes unitários ou de integração em torno de transformações e lógica de features.
• Cheque vazamento ao construir features de machine learning.
• Valide métricas de negócio contra uma consulta ou dashboard de referência.

O Claude pode participar das 4 atividades, mas o resultado esperado deve vir de código, testes ou dados — e não da explicação do Claude.

Considerações finais

O Claude Code Review funciona melhor quando eu o trato como mais um engenheiro na thread de revisão, não como um carimbo automático de aprovação.

O comando local /code-review dá uma revisão rápida antes mesmo do PR existir. O GitHub Code Review leva achados multiagente para o PR em organizações Team e Enterprise, enquanto o /code-review ultra oferece uma revisão remota mais profunda quando a mudança merece outra passada.

Eu começaria pequeno. Coloque o /code-review no seu fluxo normal de branch, escreva um REVIEW.md curto para suas revisões no GitHub e experimente o /code-review ultra em mudanças em que um merge ruim realmente custaria algo.

Para os conceitos do modelo por trás disso, nosso curso Introduction to Claude Models traz o contexto mais amplo, enquanto GitHub Foundations e Intermediate GitHub Concepts cobrem o fluxo de Git e GitHub sobre o qual o Code Review se apoia. Para mais inspiração sobre como priorizar repos do GitHub com o Claude, recomendo também nosso tutorial do conector do Claude Code.