Um pull request chega na sua fila com 340 linhas alteradas em nove arquivos. Um agente de código o escreveu. O diff não diz o que foi pedido ao agente, quais abordagens ele tentou e descartou, o que ele executou para se convencer de que a mudança funciona, nem onde ele sabe que cortou caminho. Então você faz uma de duas coisas: passa os olhos e aprova, ou reconstrói a mudança inteira do zero. A primeira é como código ruim vai para produção. A segunda significa que o agente não te economizou nada.
Revisar bem código gerado por IA é um trabalho diferente de revisar o PR de um colega, porque o autor não pode sentar ao seu lado e explicar seu raciocínio. A solução é revisar o diff junto com suas evidências: o objetivo, as verificações que rodaram e os limites que o agente já sinalizou. É nisso que o Sharkly foi construído. O Sharkly fica acima dos seus agentes de código (Claude Code, Codex, Gemini e outros) e mantém o objetivo, a mudança, os resultados de verificação e a revisão humana de cada execução em uma única Task, em vez de espalhados por terminais e descrições de PR.
Este guia percorre o modelo operacional por trás disso: quem atribui o trabalho, quem o executa, quem o revisa, quem o aceita, os status e gates que separam o trabalho do agente do trabalho humano, e um exemplo prático do ticket ao PR mergeado.
Resposta rápida
Revise código gerado por IA no nível da Task, não no nível do diff. Faça o agente anexar um resumo da mudança, os resultados de typecheck/testes/build que ele executou e quaisquer limites conhecidos a uma Task compartilhada; em seguida, mova essa Task para um status de revisão. Uma pessoa lê as evidências junto com o diff, solicita alterações ou aceita, e toma a decisão de merge. Agentes produzem e verificam; pessoas aceitam.
Por que revisar apenas o diff não funciona
Ler código é mais difícil do que escrevê-lo. Uma realidade bem documentada da revisão de código é que o revisor tem menos contexto que o autor e, quando o autor é um agente, essa lacuna é total. Um diff do GitHub mostra o destino, nunca o caminho. Você não vê que o agente tentou primeiro uma camada de cache, esbarrou em uma race condition e desfez a alteração. Você não vê que ele rodou a suíte de testes e que um teste instável falhou por um motivo sem relação com a mudança.
Sem esse contexto, a revisão se resume a dois modos de falha. Aprovar no automático significa dar o aval a um código que parece plausível, mas que silenciosamente quebra um caso de borda que o agente nunca considerou. Reconstruir tudo do zero faz você refazer o raciocínio por conta própria e, nesse ponto, a vantagem de velocidade do agente desaparece. Nenhuma das duas abordagens escala quando três agentes abrem PRs ao mesmo tempo. A saída é tornar o trabalho do agente revisável, não apenas o seu resultado.
O que significa, de fato, evidência no nível da Task
Evidência no nível da Task é o registro que um Agente anexa à sua Task: o objetivo a partir do qual trabalhou, a mudança que produziu, as verificações que executou e os limites que conhece. Em vez de um diff puro, você recebe um diff com uma trilha de procedência.
Na prática, o pacote de evidências é composto de quatro itens:
- O objetivo e os critérios de aceite, na descrição da Task, para que a revisão seja medida em relação ao que foi pedido, e não ao que parece razoável.
- O resumo da mudança, nas palavras do próprio agente: o que ele alterou e por quê.
- Os resultados de verificação: a saída do typecheck, dos testes e do build que o agente executou antes de entregar.
- Os limites conhecidos: os casos de borda, as premissas e os desdobramentos que o agente sinalizou em vez de esconder.
Tudo isso retorna à Task. Execução, bloqueios, resultados e discussões de acompanhamento ficam em uma única linha do tempo, de modo que o revisor abre um só registro em vez de juntar um PR, uma thread do Slack e um prompt lembrado pela metade. É essa a disciplina por trás de um fluxo de trabalho rastreável de requisitos até o código: as evidências fazem parte da entrega.
O modelo operacional: quem atribui, quem executa, quem revisa, quem aceita
Uma boa revisão depende de papéis claros. O contrato é curto: 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.
| Papel | Quem | Função |
|---|---|---|
| Atribuidor | Uma pessoa (normalmente o Task Owner) | Descreve a necessidade, define os critérios de aceite, atribui a Task |
| Executor | Um Agente, em um Computer conectado, por meio de um Runtime | Assume a Task, executa em um worktree isolado, anexa evidências |
| Revisor | Uma pessoa | Lê o diff em conjunto com as evidências, solicita alterações ou aprova |
| Aprovador | Uma pessoa (o Owner ou um aprovador designado) | Toma a decisão final de aceite e de merge/release |
O Sharkly não substitui o Claude Code, o Codex ou outras ferramentas de execução. Ele adiciona a camada compartilhada de Task, Computer, contexto e revisão em torno das ferramentas que sua equipe já usa. O runtime escreve o código; o Sharkly decide em qual fila a revisão vai cair e quais evidências precisam estar presentes antes de uma pessoa olhar. Se você quer a versão aprofundada do lado da atribuição, veja quem atribui e quem aceita o trabalho dos agentes.
Status e gates de revisão: agentes movem para Ready for review, humanos movem para Done
O gate de revisão é uma fronteira de status. No Sharkly, todo status de tarefa pertence a uma categoria fixa que carrega um significado de sistema: Backlog (estacionado), Unstarted (pronto, não iniciado), Started (em andamento) e Completed (terminal). Vários status visíveis podem compartilhar uma mesma categoria, então o fluxo de um tipo de tarefa pode ter Development e Ready for review como dois status distintos da categoria Started antes que qualquer coisa chegue a Completed.
É essa estrutura que torna o gate real. Um Agente pode levar uma Task de Development para Ready for review e pode deixá-la aguardando revisão humana. Ele não pode mover a Task para um status Completed por conta própria. O aceite é uma transição humana, por design.
| Status | Categoria | Quem move para cá |
|---|---|---|
| Backlog | Backlog | Pessoa, ao estacionar o trabalho |
| Todo | Unstarted | Pessoa, quando a Task está pronta |
| Development | Started | Agente, quando assume e trabalha a Task |
| Ready for review | Started | Agente, quando as evidências são anexadas |
| Done | Completed | Pessoa, após aceitar |
Configure o fluxo de trabalho para que a transição para o seu status Completed exija uma pessoa, e você terá um gate de revisão que se mantém mesmo quando os agentes produzem mais rápido do que você consegue acompanhar. Essa é a versão mecânica de manter um humano no loop para agentes de código, e é onde você decide onde interromper os agentes antes que eles façam o merge.
Um exemplo prático: do ticket ao PR mergeado
Considere a SH-312: “Adicionar rate limiting ao endpoint público de busca, 60 requisições por minuto por chave de API.”
- Uma pessoa abre a SH-312 com esse objetivo e dois critérios de aceite: requisições acima do limite retornam HTTP 429, e o limite é por chave, não por IP. A Task começa em Todo.
- Um Agente a assume, move para Development e executa em um worktree isolado, para que seu checkout nunca colida com o de outros agentes trabalhando no mesmo repositório. (Os worktrees são o motivo pelo qual execuções paralelas permanecem limpas; veja um checkout por tarefa.)
- O Agente implementa um limitador do tipo token bucket, abre um PR e anexa suas evidências à SH-312: um resumo da mudança, os resultados aprovados de typecheck e testes unitários, o resultado do build e um limite conhecido: “O bucket fica na memória do processo, então os limites são reiniciados a cada deploy e não são compartilhados entre instâncias.”
- O Agente move a SH-312 para Ready for review. Ela chega à fila de uma pessoa com o diff e as evidências juntos.
- O revisor lê primeiro a nota de limite conhecido, decide que o bucket em memória está bom por enquanto e solicita uma alteração: retornar o cabeçalho
Retry-Afterem uma resposta 429. O Agente faz a alteração e anexa novamente a saída atualizada dos testes. - O revisor aceita, faz o merge do PR e move a SH-312 para Done, com um ticket de acompanhamento para um limitador compartilhado já vinculado.
A revisão levou minutos porque o revisor nunca reconstruiu a mudança; as evidências fizeram esse trabalho. É o mesmo ciclo do gerenciamento de projetos do Claude Code, da issue à revisão, com o pacote de evidências tornando a revisão rápida em vez de um gargalo.
Como revisar as evidências rápido e quando pegar leve
Nem toda mudança precisa do tratamento completo. Use uma regra de decisão.
Vá a fundo quando a mudança envolver autenticação, cobrança, migrações de dados, APIs públicas ou qualquer coisa difícil de reverter: leia o diff linha por linha, rode os testes você mesmo e confira a nota de limites conhecidos em relação aos seus próprios casos de borda. Pegue leve quando a mudança for um ajuste de texto, uma refatoração interna bem testada ou uma atualização de dependência com verificações verdes: leia o resumo, passe os olhos pelo diff, confirme que a verificação passou e aceite.
Uma checklist rápida para revisões aprofundadas:
- O diff atende a todos os critérios de aceite, e não apenas ao caminho feliz?
- O agente realmente executou as verificações, ou apenas disse que sim? Confirme a saída anexada.
- Leia a nota de limites conhecidos. Algum limite é um bloqueador, e não apenas um item de acompanhamento?
- A mudança está restrita ao que foi solicitado, ou o agente mexeu em arquivos sem relação?
Se você já executa vários agentes de código, este é o fluxo de trabalho que o Sharkly oferece em um único lugar para gerenciar: atribua a Task, deixe o agente anexar as evidências e revise no gate. Você pode montar as peças manualmente com worktrees, templates de PR e um quadro de status, ou baixar o Sharkly e ter a Task, as evidências e o gate como um único sistema.
Perguntas frequentes
O que é evidência no nível da Task para código gerado por IA? É o registro que um agente anexa à sua Task junto com o diff: o objetivo, um resumo da mudança, os resultados de typecheck/testes/build que ele executou e quaisquer limites conhecidos. Revisar esse pacote é mais rápido e mais seguro do que revisar apenas o diff.
Um agente de IA pode aprovar o próprio código? Não, e é exatamente esse o propósito de um gate de revisão. Um agente pode mover uma Task para Ready for review, mas a transição para um status Completed é uma decisão humana. Agentes produzem e verificam; pessoas aceitam.
Como revisar código de IA mais rápido sem aprovar no automático? Adeque o esforço ao risco. Leia as evidências de toda mudança, mas reserve a revisão linha por linha e a reexecução dos testes para áreas de alto risco, como autenticação e migrações. Veja como a capacidade de revisão escala quando os agentes superam os humanos.
Continuo usando pull requests? Sim. Os agentes abrem pull requests reais no GitHub; a camada de Task adiciona as evidências e o gate em torno deles, para que o PR não seja o único lugar onde o contexto vive.
