Resposta rápida: Para fazer com que agentes de IA revisem pull requests, atribua a revisão a um segundo agente com instruções próprias, seu próprio checkout e, se possível, um modelo diferente. Inicie-o automaticamente assim que a tarefa atingir o status de revisão, configure-o para executar os testes e publicar um veredito de PASS ou CHANGES REQUIRED, e devolva as falhas ao builder. O merge continua sendo feito por uma pessoa.
Por que agentes de IA devem revisar pull requests antes de você
Cada pull request criado por um agente vai parar na mesma mesa: a sua. Quando um único agente entrega um PR por hora, tudo bem. Mas quando cinco agentes rodam em paralelo, a fila cresce mais rápido do que a sua capacidade de ler diffs, e a primeira triagem vira o gargalo.
Um agente revisor assume essa primeira triagem. Ele não substitui o seu julgamento técnico. O papel dele é filtrar os PRs que quebram testes, fogem do escopo ou vazam segredos, garantindo que apenas os que realmente valem a pena cheguem até você. No Sharkly, você configura isso com um Agente adicional e duas Automations — e o restante deste guia explica cada uma dessas etapas.
Se você quiser entender primeiro os limites da revisão automatizada, leia o que agentes de code review com IA podem e não podem verificar. Este post é focado na configuração prática.
Por que um agente não pode revisar o próprio código
O agente que escreveu o código também criou a narrativa em torno dele. Quando você pede para ele revisar o próprio trabalho, ele apenas relê o seu próprio raciocínio e concorda com ele. Os mesmos pontos cegos que geraram o bug são os que farão a revisão.
Isso fica evidente sobretudo nos testes. Um builder que não conseguiu fazer um teste passar pode simplesmente afrouxar uma asserção e dar a tarefa por concluída. Já abordamos esses padrões no artigo sobre como identificar agentes de código trapaceando em testes. Um revisor sem qualquer apego ao resultado analisa o diff friamente e faz uma pergunta diferente: essa alteração faz exatamente o que a tarefa pediu, e nada além disso?
O ensaio de arquitetura sobre superagentes da equipe do DeepSeek Harness propõe uma divisão semelhante: vários Workers vinculados ao mesmo PR acompanham seus eventos e podem resolver conflitos entre si. O texto descreve um protótipo, não um produto finalizado, mas o princípio se sustenta: a revisão funciona muito melhor quando o revisor é uma parte independente.
Passo 1: Separe o builder e o revisor
Crie dois Agentes, e não um único Agente com dois modos. Cada um deve ter suas próprias instruções, repositórios e alvo de execução.
| Builder Agent | Reviewer Agent | |
|---|---|---|
| Função | Implementar a tarefa, abrir o PR | Avaliar o PR em relação à tarefa |
| Escreve código | Sim | Não |
| Faz push | Para uma branch de feature | Nunca |
| Runtime | Por exemplo, Claude Code | Idealmente um diferente, como o Codex |
| Saída | Branch, PR, comentário com resumo | Comentário com veredito |
Um Agente do Sharkly não possui um seletor de modelos. Seu alvo de execução é um Computer somado a um Runtime detectado nele; portanto, “usar um modelo diferente” significa vincular o revisor a um Runtime diferente. Um segundo Runtime traz uma perspectiva e padrões de análise diferentes para o diff. Cada execução é faturada de acordo com o plano já associado àquele Runtime, pois o Sharkly não vende tokens.
Configure o diretório de trabalho do revisor para o modo Temporary. A documentação de Computers explica como cada execução recebe um diretório isolado, permitindo que execuções no repositório preparem um Git worktree novo. O revisor faz o checkout da branch do PR em sua própria cópia, sem risco de sobrescrever os arquivos do builder. Nosso artigo sobre agentes paralelos em worktrees isolados explica por que isso é fundamental quando múltiplos agentes compartilham o mesmo repositório.
Passo 2: Escreva as instruções do revisor
As instruções do agente definem seu papel, as verificações necessárias e o formato do relatório. Detalhes específicos de cada tarefa permanecem na própria tarefa. Mantenha as instruções do revisor concisas e testáveis:
You are the code reviewer for this Space. You never push, merge or edit files.
1. Read the triggering task. If it is not a code task in this Space, reply "not mine" and stop.
2. Find the linked pull request (the task ID appears in its title, description or branch).
3. Check out the PR branch in your worktree. Run the test command from the repo README.
4. Compare the diff to the task's acceptance criteria.
5. Post one verdict comment on the task in the format below. Nothing else.
O primeiro passo é mais importante do que parece. Atualmente, gatilhos de status e de comentário têm correspondência em toda a Organização, portanto as instruções precisam confirmar a tarefa antes de qualquer ação. A documentação de Automations afirma isso explicitamente.
Passo 3: Escolha o gatilho
As Automations do Sharkly combinam instruções, um Agente ou Crew, e um ou mais gatilhos. Para revisão de PR, dois tipos de gatilhos se encaixam perfeitamente.
Mudança de status da tarefa. Adicione um status como In Review ao fluxo de trabalho do seu Space. O builder move a tarefa para esse status após abrir o PR, e o revisor é iniciado. Uma execução disparada por status cria uma conversa na própria tarefa, mantendo o veredito e o consumo de tokens vinculados ao trabalho realizado.
Essa captura de tela mostra o fluxo de validação que este blog usa para seus próprios rascunhos: uma tarefa atinge o status Ready for Release e um Agente revisor a assume. O padrão para código é exatamente o mesmo.
Webhook. Se os PRs forem abertos fora do seu quadro de tarefas, aponte um webhook de pull_request do GitHub para a URL de webhook da Automation. Com a verificação de assinatura ativada, o Sharkly também aceita o cabeçalho X-Hub-Signature-256 do GitHub, bastando colar o segredo de assinatura no campo Secret do GitHub. Como execuções via webhook não estão vinculadas a uma tarefa, o revisor publica o veredito diretamente no PR usando a GitHub CLI.
Teste qualquer um dos fluxos com a opção Run now antes de colocá-lo em produção.
Passo 4: Dê um checklist ao revisor
Um revisor sem checklist escreve redações. Com um checklist, ele apresenta apontamentos objetivos. Cinco perguntas cobrem a maioria dos PRs gerados por agentes:
- Os testes rodam e passam? O próprio revisor executa a suíte, sem nunca confiar apenas no resumo do builder.
- O escopo foi respeitado? Arquivos alterados fora do escopo da tarefa são considerados um problema, mesmo quando a mudança parece inofensiva.
- Há algum segredo exposto? Tokens, chaves de API e valores de
.envno diff ou nos logs. - Houve quebra de compatibilidade para chamadores? Assinaturas alteradas, endpoints removidos ou migrações de banco sem rollback.
- Os testes foram enfraquecidos? Asserções removidas, novos skips adicionados ou valores esperados afrouxados.
Mantenha essa lista em uma Skill caso vários Agentes revisores a compartilhem; assim, uma única edição atualiza todos eles.
Passo 5: Padronize o formato do veredito
Um veredito que pode ser lido em dez segundos é muito melhor do que uma análise detalhada que ninguém lê. Use uma estrutura fixa:
VERDICT: CHANGES REQUIRED
Tests: 41 passed, 2 failed (test_refund_rounding, test_refund_zero)
Scope: OK, 3 files, all under billing/
Secrets: none found
Breaking changes: refund() now raises on amount=0; two callers in api/ not updated
Weakened tests: none
Required:
1. Handle amount=0 in refund() or update both callers.
2. Fix the rounding in test_refund_rounding; do not change the expected value.
O veredito PASS possui os mesmos campos, com a lista Required vazia. Campos estruturados também tornam os vereditos mensuráveis: você consegue acompanhar com que frequência cada item falha e aprimorar as instruções do builder de acordo.
Passo 6: Feche o ciclo de feedback com o builder
Um veredito de CHANGES REQUIRED deve acionar o builder novamente sem que você precise intermediar. Crie uma segunda Automation, atribuída ao Agente builder, com um gatilho de comentário baseado em uma frase específica.
A correspondência de comentários não diferencia maiúsculas de minúsculas e é disparada sempre que a frase aparece em qualquer parte do comentário. Escolha uma frase que ninguém digitaria por engano e instrua o revisor a incluí-la apenas na linha de CHANGES REQUIRED. Se o builder citar essa frase na própria resposta, ele pode acabar acionando a si mesmo — portanto, instrua-o a nunca repeti-la.
Limite o ciclo. Defina o máximo de duas rodadas de revisão e correções; depois disso, o revisor deve encaminhar a tarefa para uma pessoa, anexando seu último veredito.
O que continua sob responsabilidade humana
O merge continua sendo responsabilidade sua. Na integração com o GitHub do Sharkly, o ID da tarefa no título do PR vincula o pull request à tarefa, e fazer o merge não altera o status dela. Nada vai para produção só porque um agente deu PASS.
Reforce isso no próprio GitHub: configure branches protegidas exigindo aprovação humana obrigatória, evitando que um revisor excessivamente confiante seja sua última linha de defesa. Você também é responsável pelas decisões arquiteturais que um checklist não consegue avaliar: esse design é o mais adequado? Essa funcionalidade deveria mesmo existir? Para aprender a ordenar os PRs que chegam até você, confira como priorizar a fila de PRs gerados por agentes e por que a revisão humana é o gargalo.
Conclusão
Os PRs gerados por agentes deixam de acumular na sua fila quando um segundo agente assume a primeira triagem. Separe o builder do revisor, dê ao revisor seu próprio worktree e Runtime, configure o disparo por status ou webhook e faça-o responder a cinco perguntas fixas em um formato padronizado. Devolva as correções usando uma frase de gatilho em comentário, limite o ciclo a duas rodadas e reserve o merge final para você.
Se você já executa dez agentes de código simultaneamente, este é o próximo passo a implementar. Comece gratuitamente no Sharkly e crie primeiro o seu Agente revisor.
FAQ
Um agente de IA pode revisar o próprio pull request?
Pode, mas ele detecta muito menos problemas. O agente carrega as mesmas premissas que geraram o código. Um revisor independente com suas próprias instruções e, idealmente, um Runtime diferente analisa o diff sem esse viés.
O revisor deve usar um modelo diferente do builder?
Sim, sempre que possível. No Sharkly, o modelo é determinado pelo Runtime; portanto, vincule o Agente revisor a um Runtime diferente do builder — por exemplo, o Codex revisando o trabalho do Claude Code.
O que um revisor de código de IA deve verificar primeiro?
Os testes. Faça com que ele mesmo execute a suíte e informe o número de aprovações e falhas. Em seguida, avalie escopo, segredos expostos, breaking changes e testes enfraquecidos, nessa ordem.
Um agente revisor pode aprovar e fazer o merge de um PR?
Não permita isso. Mantenha os privilégios de merge com pessoas reais por meio de proteção de branches. O revisor publica um veredito em comentário; a decisão final é sempre de um humano.
Como evitar que o ciclo de revisão rode indefinidamente?
Limite o processo a duas rodadas nas instruções do revisor e use uma frase de comentário que o builder nunca repita. Ao atingir o limite, o revisor repassa a tarefa para uma pessoa.
Isso funciona com pull requests do GitHub abertos fora do Sharkly?
Sim. Basta conectar um webhook do GitHub ao gatilho de webhook de uma Automation. O Sharkly aceita o cabeçalho de assinatura do GitHub quando a verificação está ativada.
