Como ler de verdade o código que seu agente de IA escreveu

Este artigo também existe em inglês: How to actually read the code your AI agent wrote.

Uma sessão com um agente termina com um resumo animado e um diff que mexe em um monte de arquivos. O caminho fácil é rolar a tela, achar que está tudo razoável e fazer o merge.

Isso é passar o olho, não revisar. O resumo diz o que o agente pretendia fazer; o diff mostra o que ele fez de fato, e as duas coisas nem sempre batem. Aqui vai o fluxo que eu sugiro para fechar essa diferença, venha a mudança do Claude Code, do Codex, do Cursor ou de qualquer outro.

Primeiro, saiba o que você está lendo

O trabalho de um agente costuma chegar em um de três formatos, e cada um pede uma abordagem um pouco diferente.

Um único commit. Bom quando o agente vai commitando conforme trabalha. git show <sha> mostra a mensagem e o diff juntos. Leia a mensagem primeiro e trate ela como uma afirmação que você vai conferir.

Uma branch comparada com a main. É o formato comum para tarefas mais longas. Aqui existem duas perguntas diferentes:

• git diff main...feature (três pontos) mostra só o que mudou na branch desde que ela saiu da main. Quase sempre é isso que você quer para revisar.
• git diff main feature (dois pontos ou espaço) compara as duas versões diretamente, então tudo o que entrou na main nesse meio-tempo aparece também. Útil para saber o que o merge vai fazer de verdade; confuso se você achar que são as mudanças da própria branch.

Mudanças locais não commitadas. Comum com agentes que editam sua working tree e deixam o commit para você. git diff cobre os arquivos rastreados, mas não mostra arquivos novos que o agente criou. Rode git status e olhe a lista de untracked, ou use git add -N . para os arquivos novos aparecerem no git diff (desfaça com git reset). Agentes criam scripts, helpers e fixtures com mais frequência do que os resumos deles contam.

Veja o formato antes das linhas

Antes de ler qualquer hunk, tenha uma visão geral:

git diff --stat main...feature
git diff --name-status main...feature

Depois faça algumas perguntas:

• Todo arquivo era esperado? Se a tarefa era "corrigir o bug de parsing de data" e mudaram o lockfile, a config de CI e um componente sem relação, descubra o porquê antes de qualquer outra coisa.
• Onde está o peso? Um arquivo com 300 linhas alteradas numa "correção pequena" merece atenção.
• Testes foram adicionados, alterados ou apagados? Asserções editadas merecem mais atenção que testes novos. Um agente que não consegue fazer um teste passar às vezes muda o que o teste espera.

Leia na ordem das dependências, não em ordem alfabética

Ferramentas de diff listam os arquivos em ordem alfabética, que raramente é a ordem em que a mudança faz sentido. Uma ordem melhor:

1. Tipos, interfaces, schemas e config: o que mudou no contrato.
2. A lógica principal que implementa a mudança.
3. Os pontos de chamada que foram ajustados.
4. Os testes por último, para lê-los já sabendo o que eles deveriam provar.

Em cada hunk, não pare nas linhas alteradas. Abra a função onde elas estão. Uma mudança de duas linhas numa condição só pode ser julgada com o código ao redor à vista, e é exatamente esse contexto que o diff deixa de fora.

Confira o raciocínio, não só o código

Agentes produzem código que lê bem, então "isso parece código razoável?" é o teste errado. Perguntas melhores:

• Você consegue dizer a causa do bug em uma frase, e a mudança ataca essa causa? Muita correção de agente trata o sintoma: um null check, um retry, um try/except que engole o erro.
• Siga uma função renomeada ou com assinatura nova até quem a chama. Procure no repositório o nome antigo e o novo. Chamadas esquecidas, ou "corrigidas" mudando o comportamento, são comuns.
• Procure aumento de escopo silencioso. Refatorações que ninguém pediu, arquivos reformatados, defaults alterados, dependências novas. Cada uma precisa da sua própria justificativa.
• Confira as afirmações do resumo. Se diz "adicionei validação de entrada", ache a validação. Se diz "todos os testes passam", rode você mesmo.
• Desconfie de invenções confiantes. Chamadas a funções de biblioteca ou opções de config que não existem, ou que existem em outra versão. Vá até a definição e confirme.

Se algo não fecha, pergunte ao agente por que ele fez aquela escolha. Depois confira a resposta no código em vez de aceitá-la. Uma explicação que cita linhas específicas é fácil de checar; uma que não cita é só mais texto para confiar.

Mantenha os checkpoints pequenos

Revisar é muito mais fácil quando as unidades são pequenas. Alguns hábitos ajudam:

• Peça ao agente para commitar a cada passo lógico, com uma mensagem dizendo o quê e por quê.
• Revise entre os passos, não no fim de uma sessão de duas horas.
• Quando um diff for grande demais para ler direito, diga isso: peça para dividir, ou volte e refaça em partes menores. Uma mudança que você não consegue revisar é uma mudança que você ainda não entende.

Onde o Yenpo entra

Demo de 20 segundos: revisando o que o seu agente de IA mudou — mudanças locais antes do commit, incluindo arquivos novos.

Eu fiz o Yenpo, um app para Mac, justamente para essa etapa de leitura. A ideia é acompanhar o que a IA fez enquanto você constrói um projeto com ela. Para deixar claro o que ele é e o que não é:

• Ele abre os três formatos deste post: um único commit, uma branch comparada com a main (só as mudanças desde o ponto em que ela saiu da main, ou a comparação direta das duas versões) e mudanças locais não commitadas, incluindo arquivos novos ainda não rastreados. Os diffs são inline.
• Ir para a definição e encontrar referências vêm de language servers locais (Swift, Rust, C/C++/Objective-C, Python, JS/TS, Go). Eles não vêm embutidos: Swift e a família C usam os do Xcode, os outros usam o que estiver no seu PATH, e o rust-analyzer tem instalação com um clique. Ir para a definição funciona direto no diff para mudanças não commitadas; para commits e branches, você abre o arquivo no editor. Também tem busca de texto completo.
• Tem um AI Reader opcional que usa o seu próprio provedor. Ele mostra quais arquivos leu e o que pesquisou, e as referências arquivo:linha nas respostas são clicáveis, então dá para conferir no código. O AI Reader é somente leitura por padrão. O Allow Edits vale só para a próxima mensagem que você enviar ao AI Reader, e depois volta para somente leitura.
• Ele foi feito para ler mudanças, não para escrever código nem comandar o seu agente, e não se integra com Claude Code, Codex, Cursor ou GitHub. Ele lê o seu repositório git local. Não tem conta Yenpo nem telemetria; ele só acessa a internet para o seu próprio provedor de IA, uma verificação diária de atualização opcional e downloads que você mesmo inicia.
• Precisa do macOS 14 ou mais recente.

Você não precisa dele para seguir esse fluxo. git diff, seu editor e um pouco de disciplina resolvem a maior parte. Se quiser testar: yenpo.app.

Resumindo

• Saiba qual formato você está lendo: um commit, uma branch desde o ponto em que saiu da main, ou mudanças locais incluindo arquivos não rastreados.
• Olhe a lista de arquivos e as estatísticas antes das linhas.
• Leia na ordem das dependências, com o código ao redor aberto.
• Trate o resumo e as explicações do agente como afirmações, e confira no código.
• Mantenha os passos pequenos o bastante para você conseguir ler de verdade.

Queria muito ouvir como vocês fazem isso, principalmente com diffs grandes de agente. O que vocês olham primeiro? E se testarem o Yenpo, o que faltou ou atrapalhou? Pode ser sincero.

Rascunho feito com ajuda de IA e revisado por mim.