Você conectou um agente de revisão de código com IA ao seu pipeline, e ele funcionou. Sinalizou uma verificação de null ausente, detectou um import não utilizado e deixou três comentários bem arrumados sobre nomenclatura. Você fez o merge. Dois dias depois, um cliente esbarrou em um bug que o agente tinha simplesmente deixado passar: a mudança era internamente impecável e fazia a coisa errada. O agente de revisão verificou o código. Não conseguiu verificar a intenção.
Essa lacuna resume toda a história dos agentes de revisão de código com IA. Eles são bons em uma classe específica e verificável de problemas e cegos para outra classe que parece idêntica em um diff. Trate a aprovação deles como aceite e você vai entregar justamente a classe para a qual são cegos. Saiba onde fica a linha divisória e você ganha uma primeira passada rápida que libera seus revisores para o julgamento que só pessoas conseguem fazer.
Este artigo mapeia essa linha: o que um agente de revisão de código com IA consegue verificar, o que não consegue e o modelo operacional que mantém a distinção entre os dois. O Sharkly é a camada que vamos percorrer, o espaço de trabalho compartilhado onde a revisão do agente e o aceite humano são dois status diferentes na mesma Task, e não um único carimbo. Você já tem agentes de codificação; o ponto aqui é revisar o resultado deles sem fingir que um segundo agente fecha o ciclo.
O que um agente de revisão de código com IA consegue verificar
Um agente de revisão de código com IA é um programa que lê um diff, executa verificações sobre ele e reporta achados como um revisor humano deixaria comentários. Sua zona confiável é tudo aquilo que um revisor atento conseguiria confirmar lendo a mudança e seus arredores imediatos:
- Correção mecânica: sintaxe, tipos, tratamento óbvio de null e de limites, rejeições de promise não tratadas, vazamentos de recursos visíveis no diff.
- Lógica local: erros de off-by-one, condições invertidas, branches mortos, uma variável lida antes de ser atribuída.
- Convenções: nomenclatura, formatação, higiene de imports, se uma nova função tem um teste ao lado.
- Antipadrões conhecidos: SQL montado por concatenação de strings, segredos commitados em texto puro, um método público sem validação de entrada.
Todos eles têm um traço em comum: a evidência está dentro do diff. O agente não precisa conhecer o seu negócio para detectá-los, e os detecta mais rápido e de forma mais consistente do que um humano cansado às 18h. Isso é valor real, e é por isso que as equipes recorrem a essas ferramentas. O guia de revisão de código do Google trata essa passada mecânica como o mínimo indispensável, para que a atenção humana possa se concentrar no design. Um revisor com IA é uma forma paciente de cumprir essa passada todas as vezes.
O que ele não consegue verificar
Aqui está a fronteira, dita sem rodeios: um agente de revisão de código com IA não consegue verificar se a mudança é a mudança certa. Tudo o que vem abaixo exige um contexto que o diff não contém.
- Intenção versus especificação. O código pode estar impecável e resolver o problema errado. Só os critérios de aceite do ticket decidem isso, e o agente raramente os tem à vista.
- Correção de negócio. Se uma regra de desconto, um cálculo de imposto ou um limite de permissão corresponde a como a empresa funciona é uma questão de julgamento, não uma regra de lint.
- Comportamento entre sistemas. Uma mudança que parece boa em um arquivo pode quebrar um chamador a três serviços de distância. O Top Ten da OWASP está cheio de falhas como controle de acesso quebrado que só aparecem quando você rastreia todo o caminho da requisição, não o diff.
- Se os testes são honestos. Um agente consegue confirmar que um teste existe e passa. Não consegue dizer se o teste verifica o que realmente importa, nem se o agente que escreveu o código também escreveu um teste moldado para passar.
Esse último ponto é a armadilha específica de código escrito por IA. Quando a mesma classe de sistema produz a mudança e a revisão, um diff limpo e um check verde podem ambos ser verdadeiros e ambos não significar nada. Portanto, a aprovação de um agente de revisão é um sinal, não uma decisão. O agente reporta; uma pessoa aceita.
O modelo operacional que cobre a lacuna
A solução não é um agente de revisão melhor. É um modelo operacional em que o trabalho do agente de revisão e o da pessoa são estados diferentes, e nenhum dos dois é pulado.
O Sharkly torna esses estados explícitos como status de Task. Uma Task passa por In progress, Ready for review e Done. A regra é simples e estruturante: os agentes movem o trabalho para Ready for review; as pessoas o movem para Done. Um agente, seja o que escreveu o código ou o que o revisou, nunca pode marcar o próprio trabalho como aceito. Agentes pesquisam, executam, testam e reportam. Pessoas definem a direção, concedem autoridade e aceitam o resultado. A automação para onde o julgamento da equipe é necessário.
Cada papel tem uma função. O Agente de codificação produz a mudança. O Agente de revisão executa a passada mecânica e anexa seus achados. A pessoa revisora lê esses achados, confere a mudança em relação à intenção do ticket e decide. Tudo isso retorna à Task: o diff, os comentários do Agente de revisão, a saída dos testes e a decisão humana ficam em uma única linha do tempo, em vez de espalhados por um PR, um chat e a memória de alguém.
Use um agente de revisão como primeira etapa de verificação quando a mudança for mecânica e autocontida — uma refatoração, uma atualização de dependência, uma correção de bug bem delimitada; deixe que ele elimine o ruído para que a passada humana seja rápida. Não se apoie nele como única etapa de verificação quando a mudança envolver dinheiro, autenticação, migrações de dados ou contratos públicos; nesses casos, a pessoa lê primeiro e a passada do agente é uma lista de conferência, não um veredito.
Um exemplo prático: do ticket ao PR mesclado
Veja o SH-312: “Rejeitar códigos de cupom expirados no checkout”. Uma pessoa escreve os critérios de aceite e atribui a Task. Um Agente de codificação assume a tarefa, trabalha em um worktree isolado e devolve à Task um diff mais um teste que passa, movendo-a para Ready for review.
Agora o Agente de revisão entra em ação. Confirma os tipos, sinaliza uma verificação de null ausente e observa que o teste cobre o caso de expiração. Passada limpa. Pelo hábito antigo, essa aprovação seria mesclada.
Em vez disso, a pessoa revisora abre a Task e faz a leitura em relação à intenção. O código rejeita cupons expirados, exatamente como escrito. Mas os critérios de aceite também davam a entender que cupons já resgatados deveriam ser rejeitados, e nem o Agente de codificação nem o Agente de revisão sabiam disso, porque essa informação está na cabeça do revisor e na especificação do produto, não no diff. O revisor solicita uma alteração. O SH-312 volta para In progress com uma observação específica, o Agente amplia o trabalho e só então uma pessoa o move para Done e faz o merge do pull request.
O agente de revisão fez bem o seu trabalho e, ainda assim, teria deixado passar uma lacuna. O modelo operacional a capturou, porque o aceite foi um ato separado, feito por uma pessoa com o contexto. É a mesma disciplina por trás de revisar código gerado por IA com evidências no nível da Task: a unidade de revisão é a Task e sua intenção, não o diff isolado.
Onde posicionar suas etapas de verificação
A questão prática não é se você deve usar agentes de revisão de código com IA. É onde a passada deles conta e onde uma pessoa precisa ler primeiro. Algumas regras que se sustentam:
- Deixe o agente verificar estilo, formatação e bugs mecânicos em todas as mudanças. É a passada em que ele é melhor e a que os humanos fazem pior quando estão cansados.
- Exija uma etapa humana para qualquer coisa que envolva autenticação, cobrança, migrações de dados ou uma API pública. A zona cega se concentra aí.
- Dimensione suas etapas de verificação de acordo com sua capacidade de revisão. Os agentes produzem mais rápido do que as pessoas conseguem aceitar, então invista a passada humana onde o agente é cego.
- Transforme a etapa de verificação em um status, não em um hábito. Uma etapa de aprovação documentada que bloqueia o Done é aplicável; uma norma de que “alguém deveria dar uma olhada” não é. Manter um humano no loop só funciona quando o loop é uma etapa exigida pelo fluxo de trabalho.
Um agente de revisão de código com IA não substitui uma pessoa revisora. Ele é a primeira passada que torna a passada humana mais rápida e mais afiada. Se você já executa vários agentes de codificação e quer que o resultado deles seja revisado e aceito em um único lugar, em vez de em cinco abas de PR, esse é o problema em torno do qual o Sharkly foi construído: atribuir, acompanhar e revisar o trabalho dos agentes em Tasks compartilhadas, com os achados do Agente de revisão e a decisão humana retornando ao mesmo registro. Mantenha os agentes de codificação e o agente de revisão que você já usa e então adicione a camada que decide quando a passada deles é suficiente.
