Quando o agente mexe no código, o Git precisa contar a história

Você abre um PR de alguns dias atrás e bate aquela dúvida chata: o que exatamente eu pedi para o agente fazer aqui?

O diff está lá. Os commits estão lá. Talvez tenha uma descrição simpática no corpo do PR. Mas, olhando com calma, fica difícil separar quatro coisas que fazem muita diferença:

o pedido original;
a tentativa do agente;
o ajuste manual que você fez depois;
a validação que realmente rodou antes do merge.

Isso é pequeno quando o agente só completou uma função óbvia. Vira problema quando ele mexe em fluxo de autenticação, migration, teste, copy de interface, contrato de API ou qualquer pedaço que alguém vai precisar entender daqui a duas semanas.

Para mim, essa é uma das mudanças mais práticas da programação com agentes: não basta o código final estar no Git. O Git precisa contar melhor a história do trabalho.

Não uma história longa. Ninguém quer transformar um PR simples em ata de reunião. Mas precisa deixar contexto suficiente para revisão, manutenção e responsabilidade humana.

O diff não explica a intenção

Git é excelente para mostrar o que mudou. Ele é bem pior para explicar por que mudou daquele jeito.

Com código escrito por uma pessoa, a gente já sofria com isso. Commit chamado fix, PR sem descrição, refactor misturado com bug, teste que "alguém rodou" mas ninguém sabe qual foi. Agente não inventou esse problema.

Só que agente aumenta a velocidade com que o problema aparece.

Ele consegue produzir um diff grande em pouco tempo, atravessar arquivos que você nem lembrava que existiam e propor uma solução plausível para uma hipótese errada. E, se você estiver cansado, ainda consegue te convencer com uma explicação bonita.

Aí o Git registra o resultado como se tudo fosse uma sequência tranquila de decisões. Mas o caminho real pode ter sido bem mais bagunçado:

o agente tentou uma abordagem e abandonou;
leu um arquivo fora do escopo e puxou uma regra antiga;
gerou teste para comportamento que você não queria manter;
fez uma limpeza oportunista junto da correção principal;
recebeu uma orientação sua no meio da conversa que não ficou registrada em lugar nenhum.

Quando esse contexto some, o review vira arqueologia.

Agente como colaborador operacional

Enquanto IA era só autocomplete, dava para fingir que o rastro não importava tanto. A sugestão entrava linha por linha, sob o olho do dev.

Agora a superfície mudou. Agentes estão cada vez mais próximos de issues, PRs, editores e tarefas delegadas. Você não está apenas aceitando uma sugestão de código. Muitas vezes está entregando uma tarefa: "investigue esse bug", "crie os testes", "ajuste esse fluxo", "abra um PR".

Quando a ferramenta passa a atuar nesse nível, ela precisa entrar no workflow com o mesmo mínimo de rastreabilidade que você esperaria de qualquer pessoa mexendo no repositório.

Não para punir o agente. Para proteger o time.

Se alguém abrir o PR depois, precisa conseguir responder:

qual era o pedido?
qual era o escopo autorizado?
quais arquivos saíram do escopo?
quais comandos rodaram?
o que falhou?
o que o humano revisou antes de assumir a mudança?

Essas perguntas parecem básicas. Justamente por isso não deveriam depender da memória de quem estava no chat.

Rastro demais também atrapalha

O outro extremo é tentar registrar tudo.

Prompt completo, cada tentativa, cada saída de terminal, cada comentário intermediário, cada raciocínio do modelo. Parece seguro, mas quase ninguém vai ler. Pior: o ruído começa a esconder a informação útil.

O rastro bom é curto.

Ele não tenta provar que o agente "pensou certo". Ele mostra o pacote operacional da mudança: pedido, escopo, alteração, validação e pendências.

Eu gosto de pensar no corpo do PR como a versão curta desse contrato:

## Pedido
Corrigir o bug em que o usuário autenticado caía de volta na tela de login ao recarregar a página.

## Mudanças
- ajusta a leitura do token no middleware
- cobre o fluxo com teste de sessão persistida
- mantém o comportamento atual para token expirado

## Validação
- pnpm test auth-session
- pnpm lint

## Pendências
- não mexi na renovação automática do token
- não revisei o fluxo mobile

Isso não é burocracia pesada. É o mínimo para alguém revisar sem depender da sua lembrança.

Branch e commit também falam

O primeiro rastro costuma nascer antes do PR.

Uma branch chamada ai-fix não ajuda ninguém. Ela diz que houve IA, mas não diz qual trabalho estava sendo feito. Prefiro algo como:

fix/session-refresh-login-loop
test/add-auth-session-coverage
refactor/extract-image-export-options

O mesmo vale para commit.

Se o agente fez investigação, correção e teste, talvez isso mereça mais de um commit. Não por fetiche de Git limpo. Por revisão mesmo. Um commit que mistura tudo força o humano a descobrir sozinho onde está a decisão importante.

Um padrão simples já resolve muita coisa:

um commit para a mudança mínima;
um commit para teste;
um commit separado para limpeza, se a limpeza for realmente necessária.

Quando o agente mistura esses blocos, peça para separar antes de revisar. O tempo que você gasta nisso volta na hora de entender o PR.

Registre também o que você recusou

Tem uma parte do trabalho com agente que quase nunca aparece no Git: as hipóteses abandonadas.

Às vezes o agente sugere trocar uma biblioteca. Às vezes quer simplificar uma regra que existe por causa de um caso antigo. Às vezes propõe apagar um teste porque ele "parece redundante".

Se você recusou uma sugestão importante, vale deixar uma linha no PR:

O agente sugeriu remover o fallback para Safari antigo, mas mantive porque ainda existe tráfego desse navegador no painel.

Ou:

A primeira tentativa mexia no contrato público da API. Voltei para uma correção interna para não quebrar clientes existentes.

Esse tipo de nota salva tempo. Ela evita que outra pessoa refaça a mesma pergunta no review, e ajuda você mesmo quando voltar ao código depois.

Não precisa registrar cada microdecisão. Só as que explicam por que o caminho final ficou do jeito que ficou.

Validação precisa ser evidência, não sensação

"Testei aqui" é melhor que nada, mas ainda é fraco.

Com agente, eu tentaria ser mais explícito. Não porque agente seja magicamente perigoso, e sim porque ele costuma entregar uma narrativa muito confiante. A evidência precisa ser concreta o bastante para competir com essa confiança.

No PR, escreva o comando:

pnpm test auth-session
pnpm lint

Se não rodou, escreva também:

Não rodei a suíte completa porque ela depende do banco local.
Validei manualmente o login, refresh e logout no Chrome.

Isso parece pequeno, mas muda o tom da revisão. Quem revisa deixa de tentar adivinhar se houve validação e passa a discutir se aquela validação é suficiente.

Quando o agente roda comandos, peça para ele guardar a saída importante. Quando ele não consegue rodar, peça para explicar o bloqueio. Quando você roda manualmente, registre o resultado com a mesma honestidade.

Não esconda que houve IA

Eu entendo a vontade de esconder.

Ainda existe julgamento meio bobo em cima de código feito com agente, como se a pergunta principal fosse "foi você ou foi a IA?". Para mim, essa pergunta está ficando velha rápido.

A pergunta melhor é: o trabalho está revisável?

Se está revisável, testável e limitado ao escopo, pouco importa se o primeiro patch veio de Codex, Copilot, Cursor, Claude Code ou de uma tarde sua com café demais. Se não está revisável, também não melhora só porque foi escrito por humano.

O ponto de marcar o uso de agente não é pedir desculpa. É deixar claro onde houve delegação e onde houve responsabilidade humana.

Uma frase basta:

Patch inicial gerado com agente; revisei o diff, ajustei a validação e assumi a decisão final antes do merge.

Pronto. Sem teatro.

Um checklist pequeno para começar

Se você usa agente em repositório real, eu começaria com uma regra bem simples:

branch com nome de tarefa, não nome genérico de IA;
PR com pedido, mudanças, validação e pendências;
commits separados quando houver correção, teste e refactor;
comentário curto para hipótese recusada ou decisão importante;
evidência explícita de teste antes do merge;
nada de refactor oportunista dentro de bug urgente.

Esse checklist não deixa o processo perfeito. Mas já reduz bastante aquela sensação de abrir um PR e pensar: "o que aconteceu aqui?".

E tem um efeito colateral bom: ele melhora o prompt também.

Quando você sabe que vai precisar registrar pedido, escopo e validação, começa a pedir trabalho de um jeito mais claro. O agente recebe uma tarefa mais justa. O diff fica menor. O review fica menos cansativo.

O melhor agente é o que deixa manutenção possível

Usar agente bem não é fingir que não houve IA.

Também não é transformar cada mudança em documento corporativo.

É tratar o agente como parte real do fluxo de engenharia. Se ele mexeu no código, o repositório precisa guardar uma história mínima: o que foi pedido, o que mudou, como foi validado e onde o humano assumiu.

Daqui a alguns dias, você não vai lembrar da conversa inteira. O reviewer também não estava lá. O próximo dev só vai ter o Git.

Então faça o Git contar a história.