Quando o agente não deixa rastro, o review começa no escuro

Você abre um PR e o diff parece bom.

Os nomes fazem sentido. A mudança é plausível. Talvez os testes até tenham passado. O autor diz que usou um agente para ajudar, mas a explicação vem limpa demais: "ajustei a validação", "refatorei a função", "corrigi o bug".

Só que falta a parte que mais importa para quem revisa: por que esses arquivos foram tocados? Que caminho o agente tentou antes? Qual comando falhou? Ele mexeu só onde deveria? O que ficou para o humano conferir com mais calma?

É aí que o review começa no escuro.

Eu não acho que código escrito com agente precise carregar vergonha. Essa briga já ficou pequena. A pergunta madura não é "foi IA ou não?". É outra: o rastro é suficiente para alguém assumir responsabilidade por esse diff?

Se a resposta for não, o time não está fazendo code review. Está fazendo arqueologia.

Detectar IA é pouco

Tem uma tentação forte de transformar a conversa em policiamento: descobrir se um commit veio de humano, Copilot, Claude Code, Codex ou qualquer outro agente.

Isso até importa em alguns contextos. Projetos open source, empresas reguladas e times com regras explícitas precisam saber de onde veio a contribuição. O problema é que os sinais externos são ruins. Um estudo recente sobre agentes de código em open source analisou um volume enorme de repositórios e mostrou justamente isso: métodos simples, como procurar uma conta de bot ou uma assinatura óbvia, deixam muita coisa passar.

Na prática, o uso real pode ser bem maior do que o uso detectável.

Mas mesmo que você conseguisse detectar tudo, ainda faltaria a pergunta principal: o que o agente fez?

Saber que houve IA no fluxo não diz se a mudança é segura. Não diz se o agente entendeu o domínio. Não diz se ele escolheu a menor alteração possível. Não diz se ele apagou um caso estranho porque parecia "código morto". Não diz se o teste rodado cobre o comportamento afetado.

Detecção responde "quem apareceu no processo".

Rastreabilidade responde "como essa mudança chegou aqui".

Para review, a segunda pergunta é bem mais útil.

Volume sem contexto piora o review

Agentes de código estão saindo da fase de curiosidade individual e entrando no fluxo normal de desenvolvimento. Em rollout corporativo, adoção costuma se espalhar por prova social: um dev vê outro resolvendo um atrito real, copia o padrão, adapta, mostra para mais alguém.

Isso é bom. Ferramenta útil merece virar hábito.

Só que hábito muda carga de trabalho. Se o uso aumenta, o número de diffs também pode aumentar. Se tarefas longas e paralelas ficam mais comuns, o reviewer recebe mudanças que nasceram longe da conversa original. E quando o autor humano também não consegue explicar direito o caminho, o custo cai em quem revisa.

Você olha o diff e tenta reconstruir:

qual era a intenção original;
quais arquivos eram escopo da tarefa;
quais comandos foram executados;
que tentativa foi descartada;
que decisão o agente tomou sozinho;
que risco ficou escondido atrás de uma alteração aparentemente pequena.

Esse trabalho é caro. E é meio injusto com o reviewer.

Um PR gerado com ajuda de agente não deveria chegar só com o resultado final. Resultado final sem contexto é o equivalente técnico de "confia".

Segurança também é problema de visibilidade

O caso GhostApproval é um bom alerta porque não depende de teoria. A falha explorava uma diferença perigosa entre o que a interface mostrava e o alvo real da escrita, usando symlinks para fazer a aprovação parecer mais segura do que era.

O ponto que fica para mim vai além de "ferramentas têm bugs". Isso todo mundo sabe.

O ponto é: uma aprovação humana vale pouco quando a pessoa não enxerga o que está aprovando.

No review acontece uma versão mais silenciosa do mesmo problema. Se o agente entrega só o diff, mas não entrega intenção, escopo, comandos, falhas e riscos, o humano até consegue aprovar. Só que aprova com uma visão incompleta.

Permissão e rastreabilidade são coisas diferentes, mas se encontram no mesmo lugar: o dev precisa enxergar o suficiente para tomar responsabilidade.

Sem isso, o botão de aprovar vira teatro. O review também.

O recibo mínimo de um agente

Não precisa transformar todo uso de agente em processo pesado. Para time pequeno, isso morreria na primeira semana.

Eu começaria com um recibo curto, obrigatório quando o agente participa de uma mudança que vai para PR ou commit relevante.

Algo assim:

intenção da tarefa em uma frase;
arquivos e diretórios tocados;
comandos executados;
comandos que falharam ou foram interrompidos;
decisões tomadas sem confirmação humana;
riscos conhecidos;
testes rodados e o que eles cobrem;
pontos que precisam de revisão manual.

Parece simples porque é simples. A ideia não é criar documentação bonita. É deixar o reviewer parar de adivinhar.

Um exemplo ruim:

"Usei um agente para corrigir a validação."

Um exemplo útil:

"Pedi ao agente para corrigir a validação de CPF no cadastro. Ele alterou user-form.ts, validators.ts e os testes de validators.test.ts. Rodou npm test -- validators, que passou. A primeira tentativa mexia no schema global, mas descartei porque afetava o checkout. Revisar com atenção o comportamento de CPF vazio, porque mantive a regra antiga nesse caso."

Repara na diferença. O segundo texto não promete que está tudo certo. Ele mostra onde olhar.

Isso muda o review.

O que não deve ficar escondido

O recibo bom não precisa contar cada pensamento do agente. Ninguém quer um romance do terminal.

Mas algumas coisas não deveriam sumir.

Tentativas descartadas

Agente tenta caminhos errados. Normal.

O problema é quando o caminho errado deixa influência no diff final e ninguém percebe. Talvez ele tenha escolhido uma abstração porque tentou resolver outro caso antes. Talvez tenha removido um trecho porque parecia redundante. Talvez tenha mudado um teste para se adaptar ao código, não para proteger o comportamento.

Se uma tentativa relevante foi descartada, vale registrar em uma linha.

Comandos que falharam

Teste que passou é importante. Teste que falhou antes também.

Às vezes a falha revela mais do que o sucesso: dependência ausente, teste instável, ambiente quebrado, script pesado demais, fixture antiga. Se isso fica só no histórico local, o reviewer perde uma pista boa.

Arquivos fora do escopo

Esse é um dos sinais que eu mais gosto de olhar.

Se a tarefa era mexer em validação e o agente tocou configuração de build, arquivo de deploy ou dependência, a pergunta precisa aparecer cedo: por quê?

Pode haver um motivo legítimo. Mas "o agente achou melhor" não é motivo suficiente.

Pontos que o humano não revisou direito

Essa parte exige honestidade.

O autor humano nem sempre consegue revisar tudo com a mesma profundidade. Tudo bem. Melhor dizer "não revisei a migração com calma" do que deixar o reviewer acreditar que a mudança inteira recebeu a mesma atenção.

Review bom depende de confiança, e confiança depende de contexto.

Como aplicar sem virar burocracia

Eu colocaria a regra perto do código. Um trecho curto no AGENTS.md, no template de PR ou no README do time já resolve.

Algo como:

Se um agente participou da mudança, inclua um recibo com intenção, arquivos tocados, comandos executados, falhas relevantes, riscos e testes rodados.

Depois, aplicaria com bom senso:

tarefa pequena e mecânica pode ter recibo pequeno;
área sensível pede recibo mais explícito;
diff sem explicação em autenticação, pagamento, permissão, dados ou infraestrutura volta para ajuste;
mudança grande sem rastro não entra como "estilo do autor", entra como risco de manutenção.

O objetivo não é punir quem usa agente. É o contrário. É tornar o uso revisável o bastante para não depender de fé.

E tem uma regra prática que ajuda muito: medir retrabalho e tempo de review, não só volume de PR.

Se o agente aumenta a quantidade de diffs, mas cada diff exige uma investigação cansada, talvez o ganho esteja mal contado. Se ele entrega mudanças menores, com intenção clara e testes úteis, aí sim o time começa a ganhar confiança.

O agente não precisa parecer humano

Tem gente tentando fazer agente parecer colega de equipe. Eu entendo a ideia, mas acho que ela desvia um pouco o foco.

Eu não preciso que o agente pareça humano.

Preciso que ele seja auditável.

Um bom agente pode escrever em tom seco, repetir estrutura, listar comandos e admitir limite. Melhor isso do que um texto simpático que esconde as decisões importantes.

No fim, a responsabilidade continua humana. Quem abriu o PR responde pelo código. Quem aprovou responde pelo review. Quem mantém o sistema responde pelo custo depois.

Então a exigência mínima é bem razoável: se o agente tocou o código, ele precisa deixar pistas suficientes para alguém revisar sem virar detetive.

Código de agente não é contrabando.

Mas código sem rastro é dívida.