Como nossa equipe faz revisão de código do jeito do time do Claude Code

A Anthropic compartilhou recentemente como a equipe do Claude Code revisa código: How the Claude Code team does code review. O objetivo cabe em uma frase: gastar o mínimo possível de tempo humano em revisão sem aumentar reverts nem incidentes. A revisão deixou de ser um único portão antes do merge. Verificações automáticas rodam o tempo todo, e a atenção humana vai só para as partes arriscadas.

Isso nos tocou. Somos uma equipe de engenharia de pouco mais de dez pessoas e, há mais de um ano, buscamos a mesma coisa: colocar o esforço humano onde ele é realmente necessário e deixar o resto para a IA. A ferramenta que usamos para isso é o HeyDeer, o serviço de revisão de código com IA que criamos. A seguir, mostramos nossa abordagem lado a lado com o artigo da Anthropic e explicamos por que o HeyDeer foi projetado assim.

1. Por que as pessoas não conseguem mais revisar cada linha

A Anthropic conta que o Claude escreve cerca de 90% do código do Claude Code e que o número de PRs com merge mais que dobrou em poucos meses. Nosso caminho foi parecido.

Antes, tínhamos um padrão rigoroso para a revisão de código: alguém lia cada linha com atenção e pensava se havia um jeito melhor de escrevê-la, porque código ruim que entra na base é difícil de tirar depois.

Na época do Opus 4.1, a IA já escrevia de 70% a 80% do nosso código, e os PRs esperando revisão no GitHub só se acumulavam. Começamos a ficar para trás. Hoje, com o Opus 5.5, os modelos são capazes o bastante para que os engenheiros definam principalmente os objetivos e deixem a implementação para os agentes de código, e a IA escreve quase 100% do nosso código. Se as pessoas ainda revisassem cada linha, seriam a etapa mais lenta de todo o processo.

Ao mesmo tempo, a revisão linha por linha vale menos do que antes. Os code smells que mais nos preocupavam são fáceis para a IA limpar, então as pessoas não precisam mais vasculhá-los linha por linha. Vamos explicar como fazemos isso em outro post.

Então a pergunta já não é “como as pessoas podem revisar mais rápido?”, e sim:

1. Quais mudanças realmente precisam que uma pessoa olhe?
2. Como manter a qualidade alta nas que não precisam?

Vamos a cada uma delas.

2. Quais mudanças precisam de uma pessoa: níveis de risco

A resposta da Anthropic é a aprovação humana baseada em risco: um classificador define o nível de risco a partir da própria mudança, não de quem a escreveu. Mudanças de risco baixo não precisam de aprovação humana depois que as verificações automáticas passam, as de risco médio precisam de uma pessoa e as de risco alto, de duas.

O HeyDeer funciona do mesmo jeito. Cada revisão avalia o nível de risco do PR (baixo, médio ou alto) e explica o motivo. Na configuração PRs que o HeyDeer pode aprovar, você escolhe quais níveis de risco o HeyDeer pode aprovar.

Risco baixo e médio: o HeyDeer aprova

Nossa equipe escolheu PRs de risco baixo e médio: desde que um PR não seja de risco alto e a revisão completa do HeyDeer não encontre problemas, o HeyDeer o aprova e o PR entra na main automaticamente.

Trabalhamos assim há 8 meses e nem uma vez o merge de código com bug derrubou nosso serviço em produção.

Risco alto: as pessoas avaliam a direção, o HeyDeer cuida dos detalhes

PRs de risco alto ainda precisam da aprovação de outro engenheiro. Mas o papel dessa pessoa mudou: em vez de caçar erros linha por linha, ela avalia, de um nível mais alto, se a abordagem e a direção do PR estão certas. Isso coincide com os pontos em que o artigo da Anthropic mantém as pessoas envolvidas: decidir se algo deve ser construído, revisar a arquitetura e ler as evidências por trás de uma mudança. Os detalhes finos podem ficar com o HeyDeer.

Para ajudar as pessoas a encontrar mais rápido o que importa, o HeyDeer oferece um roteiro:

• Ele agrupa mudanças relacionadas, marca cada grupo como Leitura obrigatória, Leitura recomendada ou Leitura rápida e lista em Outras as mudanças fora do caminho principal, com o motivo de cada uma estar ali. Você vê de relance o que pode pular e concentra a atenção nas partes que mais importam.
• Ele informa o nível de risco do PR e o raciocínio por trás dele, para você saber o que confirmar com cuidado.

Quem revisa não lê mais do primeiro ao último arquivo. Vai direto aos poucos pontos que mais precisam do julgamento de uma pessoa.

3. Manter a qualidade alta onde ninguém olha

Deixar a IA aprovar a maioria dos PRs só funciona se a revisão dela for confiável: ela precisa encontrar o que existe sem soterrar as pessoas em ruído. O HeyDeer foi projetado para as duas coisas e permite que cada equipe o ajuste ao seu jeito de revisar.

Preciso: vários modelos revisam e verificam o trabalho uns dos outros

Na revisão com IA da Anthropic, vários agentes procuram bugs em paralelo, depois outros agentes votam em cada achado, e só os aprovados são publicados.

O HeyDeer vai além: modelos de fornecedores diferentes revisam cada mudança e verificam o trabalho uns dos outros. Um único modelo deixa passar problemas e aponta problemas falsos com facilidade, e várias cópias do mesmo modelo tendem a cometer os mesmos erros. Modelos diferentes têm pontos cegos diferentes, então a revisão cruzada encontra visivelmente mais problemas, e a verificação cruzada filtra boa parte do ruído e dos falsos positivos.

Cortar o ruído também protege a atenção humana. Com falsos positivos demais, as pessoas não dão conta e acabam parando de ler. Se você entregar tudo a um agente de código, ele pode seguir os falsos positivos cegamente e inchar a base de código. Deixar a revisão para a IA só funciona quando os resultados dela são precisos.

Completo: verificações do repositório garantem as convenções da equipe

A abordagem da Anthropic é que, quando o mesmo comentário de revisão continua aparecendo, você o resolve na origem: em skills, regras de lint, CLAUDE.md ou REVIEW.md.

Na nossa experiência, ferramentas de revisão de uso geral têm dificuldade com as necessidades de uma base de código específica: como os rótulos dos botões usam maiúsculas, o tom dos textos da interface, as convenções da equipe para usar React e assim por diante. Escritas no AGENTS.md ou em uma skill, essas convenções orientam os agentes de código enquanto escrevem, mas, em uma revisão de código completa, elas se perdem facilmente em um contexto grande e passam despercebidas.

As verificações do repositório do HeyDeer foram feitas para isso. Escreva em linguagem simples, em .agents/checks, os requisitos que você quer verificar, e o HeyDeer dá a cada verificação seu próprio revisor, que revisa todo PR que altera arquivos correspondentes com base nesse único requisito, para que nada passe despercebido.

Ajustável: um escopo do feedback que combina com o jeito de revisar da sua equipe

Cada equipe precisa de coisas diferentes do feedback de revisão, por isso o HeyDeer oferece a configuração escopo do feedback:

• Conciso: para equipes que ainda dependem principalmente da revisão humana, como as do setor financeiro. Mantém só os problemas importantes, para que as pessoas gastem o tempo onde ele mais importa.
• Equilibrado (o padrão) ou Detalhado: para equipes que entregam a maior parte da revisão e das correções a agentes de código ou ao HeyDeer. Corrigir problemas pequenos quase não custa nada para a IA, então até os problemas menores são resolvidos.

4. Depois da revisão: o Autopilot corrige até o PR convergir

Quando a revisão encontra problemas, alguém ainda precisa corrigi-los. Se um engenheiro tem de voltar a cada rodada para ler os comentários, pedir mudanças a um agente e esperar a próxima revisão, a atenção dele continua presa.

O artigo da Anthropic é franco sobre um problema bem real: a revisão com IA pode não convergir. Um dos PRs deles passou por mais de cinquenta rodadas de revisão e correção durante a noite. Cerca de 59% do que o revisor continuava apontando era código que já estava lá desde a primeira passada: cada rodada não encontrava bugs novos, apenas mais alguns antigos. Desde então, eles fizeram uma série de melhorias, como limitar o número de rodadas, revisar só as mudanças novas depois das primeiras passadas e não repetir achados já publicados.

Desde o início, o HeyDeer trata a convergência como um objetivo de design da revisão. Quando o HeyDeer encontra um lote de problemas pequenos, você pode entregá-los ao Autopilot: ele corrige o que está pendente, envia para a branch do PR e revisa as próprias mudanças, repetindo até o PR ficar pronto para o merge ou surgir uma questão que precise de uma pessoa. No nosso uso, a maioria dos PRs fica pronta em duas rodadas, e os mais complexos, em três. O Autopilot executa no máximo 5 rodadas e, quando para, explica por que parou e o que ainda precisa de você.

Isso importa muito para nós. Trocar de contexto custa muito caro para as pessoas, e não queremos engenheiros com duas coisas na cabeça ao mesmo tempo: escrevendo uma nova funcionalidade enquanto se perguntam se os comentários do último PR já foram resolvidos. Depois de iniciar o Autopilot, os engenheiros podem passar para a próxima tarefa com tranquilidade.

Juntando tudo, esta é a rotina diária da nossa equipe: depois de abrir um PR, os engenheiros podem passar para outra coisa. O HeyDeer o revisa e o Autopilot corrige o que ele encontrar. PRs de risco baixo e médio são aprovados pelo HeyDeer e entram direto na main; nos PRs de risco alto, outro engenheiro usa o roteiro para conferir a direção.

5. Quais equipes podem trabalhar assim

Para quem serve essa abordagem de “só mudanças de risco alto precisam de revisão humana”? Com o que a IA já consegue fazer hoje, achamos que a maioria das startups e das pequenas e médias empresas pode trabalhar assim, desde que o negócio não envolva informações especialmente sensíveis. Você pode começar deixando o HeyDeer aprovar só PRs de risco baixo e depois estender para risco médio quando a equipe ganhar confiança.

Considerações finais

Em linhas gerais, é assim que as práticas da Anthropic se relacionam com a forma como usamos o HeyDeer:

Ferramentas e modelos vão mudar, mas o objetivo não: a atenção humana é o recurso mais escasso de uma equipe, então use-a onde ela mais conta. Se a sua equipe também está percebendo que a IA escreve código mais rápido do que as pessoas conseguem revisar, experimente o HeyDeer.