DEV Community: Massimo Yang

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

Massimo Yang — Fri, 30 Oct 2026 09:16:11 +0000

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:

Tipos, interfaces, schemas e config: o que mudou no contrato.
A lógica principal que implementa a mudança.
Os pontos de chamada que foram ajustados.
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.

How to actually read the code your AI agent wrote

Massimo Yang — Fri, 30 Oct 2026 04:02:34 +0000

An agent session ends with a cheerful summary and a diff that touches a lot of files. The easy move is to scroll through it, see that it looks reasonable, and merge.

That's skimming, not review. The summary tells you what the agent meant to do; the diff tells you what it actually did, and the two don't always match. This post is the workflow I'd suggest for closing that gap, whether the change came from Claude Code, Codex, Cursor or anything else.

First, decide what you're reading

Agent work usually reaches you in one of three shapes, and each needs a slightly different approach.

A single commit. Good when the agent commits as it goes. git show <sha> gives you the message and the diff together. Read the message first and treat it as a claim you're going to check.

A branch compared against main. This is the usual shape for a longer task. There are two different questions here:

git diff main...feature (three dots) shows only what changed on the branch since it forked from main. This is almost always what you want for review.
git diff main feature (two dots or a space) compares the two versions directly, so anything that landed on main in the meantime shows up as well. Useful when you want to know what merging will actually do, confusing if you mistake it for the branch's own changes.

Uncommitted local changes. Common with agents that edit your working tree and leave committing to you. git diff covers tracked files, but it doesn't show new files the agent created. Run git status and look at the untracked list, or git add -N . so new files show up in git diff (undo with git reset). Agents create helper files, scripts and fixtures more often than their summaries mention.

Get the shape before the lines

Before reading any hunk, get an overview:

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

Then ask a few questions:

Is every file expected? If the task was "fix the date parsing bug" and the lockfile, the CI config and an unrelated component changed, find out why before anything else.
Where is the weight? One file with 300 changed lines in a "small fix" is worth a look.
Were tests added, changed, or deleted? Edited assertions deserve more attention than new tests. An agent that can't make a test pass will sometimes change what the test expects.

Read in dependency order, not alphabetical order

Diff tools list files alphabetically, which is rarely the order the change makes sense in. A better order:

Types, interfaces, schemas and config: what changed in the contract.
The core logic that implements the change.
Call sites that were updated to match.
Tests last, so you read them knowing what they're supposed to prove.

For each hunk, don't stop at the changed lines. Open the function they live in. A two-line change to a condition can only be judged with the surrounding code in view, and that's exactly the context a diff leaves out.

Check the reasoning, not just the code

Agents produce code that reads fluently, so "does this look like reasonable code?" is the wrong test. Better questions:

Can you state the cause of the bug in one sentence, and does the change address that cause? A lot of agent fixes treat the symptom: a null check, a retry, a try/except that swallows the error.
Follow one renamed or re-signed function to its callers. Search the repo for the old name and the new one. Missed call sites, and call sites "fixed" by changing their behavior, are common.
Look for silent scope creep. Refactors nobody asked for, reformatted files, changed defaults, new dependencies. Each one needs its own justification.
Check the claims in the summary. If it says "added input validation," find the validation. If it says "all tests pass," run them yourself.
Watch for confident inventions. Calls to library functions or config options that don't exist, or that exist in a different version. Go to the definition and confirm it's real.

If something doesn't add up, ask the agent why it made that choice. Then verify the answer against the code instead of accepting it. An explanation that cites specific lines is easy to check; one that doesn't is just more text to trust.

Keep the checkpoints small

Review is much easier when the units are small. A few habits help:

Ask the agent to commit after each logical step, with a message that says what and why.
Review between steps rather than at the end of a two-hour session.
When a diff is too big to read properly, say so: ask for it to be split, or reset and redo it in smaller pieces. A change you can't review is a change you don't understand yet.

Where Yenpo fits

Yenpo is the Mac app I made for the reading step above. To be clear about what it is and isn't:

It opens the three shapes from this post: a single commit, a branch compared against main (only the changes since the fork point, or a direct compare of the two versions), and uncommitted local changes, including untracked new files. Diffs are inline.
Go to definition and find references come from local language servers (Swift, Rust, C/C++/Objective-C, Python, JS/TS, Go). They aren't bundled: Swift and the C family use Xcode's, the others use what's on your PATH, and rust-analyzer has a one-click install. Go to definition works right in the diff for uncommitted changes; for commits and branches, you open the file in the editor. There's also full-text search.
There's an optional AI Reader that uses your own provider. It shows which files it read and what it searched, and the file:line references in its answers are clickable, so you can check them against the code. The AI Reader is read-only by default. Allow Edits applies only to the next message you send to the AI Reader, then switches back to read-only.
It's built for reading changes, not for writing code or driving your agent, and it doesn't integrate with Claude Code, Codex, Cursor or GitHub. It reads your local git repo. No Yenpo account or telemetry; it only goes online for your own AI provider, an optional daily update check, and downloads you start yourself.
It needs macOS 14 or later.

You don't need it to follow this workflow. git diff, your editor and some discipline get you most of the way. If you want to try it: yenpo.app.

The short version

Know which shape you're reading: a commit, a branch since its fork point, or local changes including untracked files.
Look at the file list and stats before the lines.
Read in dependency order, with the surrounding code open.
Treat the agent's summary and explanations as claims, and check them against the code.
Keep the steps small enough that you can actually read them.

I'd like to hear how others handle this, especially on large agent diffs. What do you check first?

Drafted with AI assistance and reviewed by me.