Leia o diff e exija uma prova

Field Note

Quarta-feira, 18h. O Claude Code termina e escreve: "Implementei a validação de CPF, todos os testes passam." Você está com pressa, faz o commit. No dia seguinte, o cadastro aceita 000.000.000-00. Você abre o diff e encontra a explicação: a função nova está certa para os casos do teste, e o teste só tinha três casos, todos válidos. "Todos os testes passam" era verdade. Só não provava nada.

Conceito

Código plausível não é código correto. O agente para quando o trabalho parece pronto. Sem uma prova que corresponda ao risco da mudança, "parece pronto" é tudo que você tem, e quem aprova continua sendo você.

Esta lição fecha o Território 2 com três hábitos: ler o diff, ligar cada mudança a um critério de aceite e exigir evidência em vez de afirmação.

Ler o diff dentro da sessão. /diff mostra as mudanças na sua árvore de trabalho, incluindo as edições do Claude e o que mais você não comitou. Na renderização em tela cheia, ele abre um painel ao lado da conversa que se atualiza enquanto o trabalho segue. No renderizador clássico, abre um visualizador no lugar do prompt. Fora da sessão, git diff resolve igual.

O que procurar em cada arquivo:

• Mudou o que precisava? Cada trecho alterado responde a algum item do critério de aceite.
• Mudou o que não precisava? Formatação em arquivo que não tinha nada a ver, renomeação "de brinde", dependência nova.
• Mexeu em teste? Asserção trocada, teste pulado, caso removido. É o alerta mais importante.
• Silenciou algum erro? @ts-ignore, eslint-disable, catch vazio, try engolindo exceção.

Evidência, não afirmação. A doc de boas práticas pede que o Claude mostre evidência em vez de declarar sucesso: a saída do teste, o comando que rodou e o que voltou, um print do resultado. Revisar evidência é mais rápido que rodar tudo de novo, e funciona até para sessões que você não acompanhou.

A doc também mostra um contraste útil. Em vez de "o build está falhando", algo como "o build falha com este erro: [erro]. Corrija e confirme que o build passa. Resolva a causa raiz, não suprima o erro".

Prova proporcional ao risco. Nem toda mudança pede o mesmo nível de prova:

• Texto, estilo, log: o diff basta.
• Lógica interna: teste unitário que cobre o caso novo e um caso inválido.
• Fluxo de usuário: teste de integração ou rodar a aplicação e ver funcionando.
• Dinheiro, dado pessoal, permissão, migração: tudo acima, mais revisão de outra pessoa.

Ferramentas de revisão que a doc lista. Conferidas em outubro de 2026:

• /code-review: revisa o diff atual em busca de bugs de correção. Com --fix, aplica as correções. /review é apelido.
• /security-review: revisa o diff em busca de vulnerabilidades.
• /simplify: procura oportunidades de limpeza. A doc avisa que ele não procura bugs.
• /verify: confirma a mudança construindo e rodando a aplicação e observando o resultado, em vez de confiar só em teste ou checagem de tipo.

Revisor com olhar fresco. A doc recomenda um passo adversarial: um subagente revisa o diff num contexto limpo, vendo só a mudança e os critérios, não o raciocínio que a produziu. Com um alerta honesto: um revisor instruído a achar lacunas quase sempre acha alguma, mesmo quando o trabalho está bom. Peça que ele aponte só o que afeta correção ou requisito.

Para quando virar rotina. Se a checagem precisa acontecer sempre, sem exceção, a doc indica um hook de Stop, que roda seu script e impede o turno de terminar até passar. Isso é assunto para mais adiante na trilha. Por enquanto, vale saber que existe.

Quando usar

• Sempre que for fazer commit de algo que o agente escreveu.
• Com mais rigor quando a mudança mexe em regra de negócio, dado sensível, segurança ou dinheiro.
• Quando a resposta final é curta e confiante demais para o tamanho da mudança.
• Antes de abrir PR para outra pessoa revisar. Ela merece receber algo que você já leu.

Quando não usar

Ler o diff não tem exceção. O que varia é a profundidade da prova:

• Não exija teste de integração para ajuste de texto.
• Não rode revisão adversarial em mudança de uma linha. O custo passa do benefício.
• Não persiga todo achado de revisão automática. A doc avisa que isso leva a excesso de engenharia: abstração a mais, código defensivo e teste para caso impossível.

Faça agora

A prática é entregar um Primeiro commit auditado.

1. Escolha uma alteração pequena e real: uma validação, uma regra, uma correção de bug. Branch separada.
2. Peça com critério de aceite e exigência de evidência:

Implemente X. Critérios de aceite: [liste dois ou três]. Escreva ou ajuste testes que cubram pelo menos um caso válido e um inválido. Rode os testes e me mostre o comando e a saída. Não altere asserções existentes. Se precisar, explique por quê antes.

3. Rode /diff e leia cada linha. Para cada trecho, escreva qual critério ele atende. Trecho sem critério é suspeito.
4. Encontre pelo menos um ponto para questionar: um caso de borda sem teste, um nome confuso, um erro engolido, uma mudança fora do escopo. Pergunte a ele. Anote a resposta.
5. Rode os testes você mesmo, fora da conversa, e compare com a saída que ele mostrou.
6. Opcional: rode /code-review e veja se ele encontra algo que você não viu.
7. Faça o commit com uma mensagem que diga o que mudou, por quê, e como foi verificado.

Armadilhas

• "Todos os testes passam." Pergunte quais testes, quantos, e se algum foi alterado.
• Teste ajustado para passar. Asserção trocada no mesmo diff da correção é sinal vermelho até prova em contrário.
• Mock que esconde o problema. Teste que simula exatamente o trecho que deveria ser testado não testa nada.
• Ler só o resumo. O resumo é o que ele acha que fez. O diff é o que ele fez.
• Aprovar pelo tamanho. Diff pequeno também quebra produção.
• Terceirizar a revisão inteira. /code-review ajuda, não assina por você.

Material para levar

Ficha do commit auditado:

Tarefa:
Branch:
Critérios de aceite:
1.
2.
3.

Arquivo         | Trecho alterado      | Critério atendido
                |                      |

Mudanças fora do escopo encontradas:
Testes alterados? Quais e por quê:
Erros silenciados? (ts-ignore, eslint-disable, catch vazio):

Ponto que eu questionei:
Resposta do agente:

Comando de teste que eu rodei:
Saída (resumo):
Bate com o que ele mostrou? sim / não

Mensagem do commit:

Prova proporcional ao risco:

Texto, estilo, log            → diff lido
Lógica interna                → teste com caso válido e inválido
Fluxo de usuário              → integração ou app rodando
Dinheiro, dado, permissão     → tudo acima e outra pessoa revisando