Como comprovar uma correção

A pontuação foi corrigida. A resposta traz a saída do terminal, uma captura de tela do placar e um breve "pronto". Há muitos arquivos, mas a pergunta é simples: qual deles responde ao requisito da tarefa?

Evidência não é qualquer arquivo que esteja junto da correção. É o resultado de uma verificação específica, que mostra o que foi verificado, em que estado estava o código e qual foi o resultado. Materiais diferentes respondem a perguntas diferentes; nenhuma responde a todas de uma vez.

Veja como transformar um requisito em uma afirmação verificável, o que registrar ao executar um comando e o que o log, o diff e uma captura de tela podem comprovar. Depois, vamos organizar tudo em um registro curto, o EVIDENCE_LOG, com seis campos, e avaliar se um conjunto pronto de materiais é suficiente.

O critério define a verificação

Vamos usar o mesmo exemplo ao longo do artigo: um pequeno jogo de bônus com a pontuação no placar. A pontuação começa em 0; três combinações devem somar 3 pontos, mas antes da correção somavam 30. Essa regra de pontuação foi criada para este jogo. Em outro projeto, ela pode ser diferente, portanto não a aplique lá.

Não dá para verificar a frase "a pontuação foi corrigida": não fica claro o que executar nem o que observar. Uma afirmação verificável tem três partes: estado inicial, ação e resultado esperado. Por exemplo: "com a pontuação em 0, três combinações somam 3 pontos, e o placar mostra 3". Agora há uma verificação para essa afirmação.

Em seguida, a afirmação se divide em observações separadas. O cálculo e o que o jogador vê são coisas diferentes, comprovadas de maneiras diferentes. A terceira linha da tabela trata da pontuação no leaderboard. Talvez esse requisito nem exista na tarefa, mas, se existir, precisa de uma observação própria.

A terceira coluna é a mais útil aqui. Uma evidência quase sempre comprova menos do que gostaríamos; seu limite está onde termina a ação executada. No nosso exemplo, o teste de cálculo não verifica o placar, e a captura do placar não mostra a linha de código alterada.

Mantenha duas coisas separadas: o requisito descreve o que deve ser verdade no final; o resultado é o que de fato foi obtido. Quando os dois se misturam no mesmo parágrafo, "deve somar 3" vira "soma 3" sem que ninguém tenha executado nada.

O comando e o resultado

Uma execução de verificação é descrita por cinco elementos. Para quem for repeti-la na semana que vem, nenhum deles é óbvio:

• a pasta de onde o comando foi executado;
• o comando, exatamente como foi executado;
• o estado do código: antes ou depois da correção e quais alterações ainda não foram commitadas;
• o resultado: código de saída e contadores finais;
• quais verificações foram realmente executadas e quais não foram.

Também é importante distinguir "é preciso executar npm test" de "executei npm test, aqui está a saída". A primeira frase é uma instrução, um plano para depois. A segunda relata um fato. É fácil confundir intenção com resultado, sobretudo quando a resposta lista com cuidado o que deveria ser verificado.

npm test não executa "todos os testes que existem". Ele roda o que está definido no campo test da seção scripts do package.json do projeto que o npm selecionou. Para não ficar na dúvida sobre qual projeto foi escolhido, execute o comando na raiz dele e anote essa pasta no registro. Em outro projeto, o mesmo nome pode corresponder a outra ferramenta, a outra sequência de etapas ou a nada.

O comando termina com um código de saída: 0 geralmente significa que "a ferramenta considera a execução bem-sucedida". No bash, echo $? mostra o código logo após o comando; no PowerShell, para um programa externo como npm, use $LASTEXITCODE. Só que o zero não indica se o teste relevante foi executado: ele pode ter sido ignorado, filtrado pelo nome ou nem sequer ter sido escrito. Por isso, junto do código de saída, registre sempre os contadores e o nome do teste que interessa ao(à) senhor(a).

O que guardar do log

A saída de uma execução pode ser longa, e ninguém a copia inteira para o registro. Um trecho curto deve conter quatro itens: o nome do teste que falhou, o valor esperado e o obtido, o motivo da falha e os contadores finais. O restante fica em um arquivo, com um link no registro. Abaixo há um exemplo didático de saída resumida, não o registro de uma execução real.

✖ three matches give 3 points (2.4108ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
  30 !== 3
      at TestContext.<anonymous> (src/bonus-game/score.test.js:8:10)
ℹ tests 1
ℹ pass 0
ℹ fail 1
ℹ skipped 0

Este é um trecho; a saída completa foi salva em um arquivo, por exemplo, logs/test-fail.txt. O trecho já mostra o essencial: falhou justamente o teste das três combinações, que esperava 3 e obteve 30. Nenhuma verificação foi ignorada.

A saída original entra no registro sem alterações. Recontar com suas palavras ("o teste falhou por causa do multiplicador incorreto") parece mais claro, mas isso já é uma conclusão, não uma observação, e não pode ser conferida pelo log. Mantenha as duas coisas lado a lado: primeiro, as linhas da ferramenta; depois, sua explicação.

O endereço na linha do stack trace aponta para o ponto em que a verificação disparou: o arquivo de teste. A causa é investigada no código do jogo, e o multiplicador encontrado ali vem da leitura do código, não do log. Identifique essas duas fontes separadamente no registro; assim, depois fica claro de onde veio o número 10.

O que o diff comprova

O diff mostra a diferença entre dois estados do arquivo. Ele não informa se o código corrigido chegou a ser executado, muito menos se o comportamento mudou como o(a) senhor(a) esperava.

--- a/src/bonus-game/score.js
+++ b/src/bonus-game/score.js
@@ -1,5 +1,5 @@
-const POINTS_PER_MATCH = 10;
+const POINTS_PER_MATCH = 1;

 function calcScore(matches) {
   return matches * POINTS_PER_MATCH;
 }

Este trecho precisa de uma legenda de uma linha que diga quais estados foram comparados. Por exemplo: "árvore de trabalho contra o commit a1b2c3d anterior à correção, comando git diff HEAD". O identificador aqui é didático; no seu registro, use o real. Esse comando compara os arquivos rastreados atuais com HEAD, incluindo as alterações preparadas para commit. Já git diff sem HEAD mostra apenas a diferença em relação ao estado preparado e pode ficar vazio depois de git add. Sem legenda, o diff parece "algo contra alguma coisa", e não dá para repetir a comparação.

Confira também se o valor esperado no teste continuou sendo 3. Se o número esperado mudou junto com o código, a história é outra: o teste se adaptou ao comportamento, em vez de o comportamento atender ao requisito.

Um detalhe técnico que pode confundir: enquanto a correção não foi commitada, ela aparece na comparação entre a árvore de trabalho e o último commit. Depois do commit, a mesma comparação fica vazia. Isso não quer dizer que nada mudou na tarefa: a alteração apenas entrou no histórico, e agora é preciso comparar o commit com o estado anterior. Um diff vazio não comprova nada por si só; o que importa é quais dois estados estão sendo comparados.

O que aparece na captura de tela

Estado e ação

Uma captura com o número 3 no placar comprova exatamente uma coisa: no momento da captura, o placar mostrava 3. Isso não equivale a dizer que "três combinações somaram 3 pontos". Entre as duas afirmações estão todas as informações que não aparecem na imagem: qual era a pontuação inicial e o que foi feito.

Para que a captura sirva como evidência, registre o cenário junto dela:

1. o que foi aberto: endereço da página ou modo de execução, e qual versão - com ou sem a correção;
2. estado inicial: a pontuação começa em 0 e os dados antigos não foram carregados;
3. ação: foram feitas três combinações;
4. observação: o placar mostra 3; a captura foi feita logo após a ação.

Sem esse registro, dá para obter qualquer captura de várias maneiras. Uma aba antiga, aberta no dia anterior com uma versão desatualizada, outra forma de execução ou uma pontuação que já era diferente de zero: tudo isso pode produzir uma imagem convincente que, na verdade, não significa nada.

Este artigo não inclui uma captura do placar de propósito. Para verificar, capture a tela depois de reproduzir o cenário na versão certa, manualmente ou com automação. Um placar desenhado ou montado para ilustrar não vira evidência, mesmo que pareça idêntico. Quando fizer sua captura, mostre o placar inteiro, registre o endereço da página no cenário e guarde a imagem junto do registro. Senão, na semana que vem o(a) senhor(a) nem vai lembrar qual execução ela mostra.

O que o modelo pode ler

É possível enviar a imagem na sessão e pedir que o modelo a leia. A formulação faz toda a diferença: peça que ele diga qual número está visível e liste as dúvidas ("o estado inicial aparece?", "dá para identificar a versão?"), em vez de confirmar uma conclusão pronta. Se pedir "confirme que o bug foi corrigido", é fácil receber uma resposta afirmativa e educada que não verifica nada.

A possibilidade de enviar imagens depende do modelo e do ambiente em que o(a) senhor(a) trabalha. No Claude Code, informe o caminho da imagem salva e peça para analisá-la. Se a imagem não carregar, confira primeiro o caminho e se o arquivo está acessível; trocar de modelo não garante que o problema será resolvido.

O mesmo cenário antes e depois

Uma comparação útil é esta: a mesma verificação falha na implementação com defeito e passa na versão corrigida. A falha mostra que a verificação detecta o problema; a aprovação mostra que, após a correção, o defeito não aparece naquele cenário verificado.

Isso só funciona se os dados de entrada e os resultados esperados forem os mesmos. A mesma pontuação inicial, o mesmo número de combinações, o mesmo valor esperado: 3. Veja o resultado aprovado do mesmo teste após a correção:

✔ three matches give 3 points (1.3983ms)
ℹ tests 1
ℹ pass 1
ℹ fail 0
ℹ skipped 0

Entre as execuções, só a implementação deve mudar; o teste, os dados de entrada, o resultado esperado e as condições de execução permanecem iguais. Se foi preciso alterar o requisito ou corrigir o valor esperado no teste, faça um novo par de execuções com essa verificação: uma explicação não substitui a execução nos dois estados. Dizer apenas "antes falhava, agora passou" nesse caso induz ao erro.

Dois arquivos chamados before.txt e after.txt não garantem nada por si só. O nome do arquivo não é evidência. É preciso olhar o conteúdo: o comando, o teste e o valor esperado são os mesmos? Reverter temporariamente para o estado com defeito (aquele procedimento com git stash) é uma verificação separada, com regras próprias. Por enquanto, basta saber que a falha anterior à correção deve vir de uma execução real, não da memória.

Um EVIDENCE_LOG curto

Neste artigo, EVIDENCE_LOG é um registro de texto comum, com seis campos nesta ordem: SINTOMA, EVIDÊNCIA_DO_LOG, FALHA_COM_DEFEITO, CORREÇÃO, APROVAÇÃO_REAL, CAPTURA_DE_TELA. Assim fica mais fácil relacionar o sintoma, a correção e o resultado. A ordem dos campos, por si só, não garante a confiabilidade dos registros.

Tudo o que reunimos até aqui cabe nesses campos. O comando e a pasta ficam no campo da falha; os estados comparados, no da correção; os links para os arquivos completos, junto da evidência correspondente. Não é preciso criar outro pacote de documentos.

Abaixo há um modelo didático de preenchimento: ele mostra o que escrever em cada campo, não relata verificações executadas. No seu registro, substitua o texto pelos resultados reais.

SINTOMA: no jogo de bônus, com pontuação inicial 0, três combinações
somam 30 pontos em vez de 3. Acontece sempre: abrir o jogo,
fazer três combinações e olhar o placar.

EVIDÊNCIA_DO_LOG: a saída da execução mostra "30 !== 3" no teste
"three matches give 3 points"; a saída completa está em logs/test-fail.txt.
Separadamente, pela leitura do código: em src/bonus-game/score.js,
o multiplicador POINTS_PER_MATCH vale 10. Isso vem da leitura do código;
o número 10 não aparece na saída do teste.

FALHA_COM_DEFEITO: HEAD a1b2c3d (identificador didático),
árvore de trabalho limpa; o commit contém o cálculo com defeito e o teste.
Pasta: /project/bonus-game; comando: npm test.
Em package.json, scripts.test = node --test. Falha "three matches give 3 points",
motivo "30 !== 3", tests 1, pass 0, fail 1, skipped 0, código de saída 1.
Trecho da saída acima; completa em logs/test-fail.txt.

CORREÇÃO: POINTS_PER_MATCH foi alterado de 10 para 1 no arquivo
src/bonus-game/score.js; não há outras alterações. O HEAD continua a1b2c3d.
Diff: git diff HEAD, árvore de trabalho comparada com esse commit;
salvo em diffs/score-fix.diff.
O valor esperado no teste continua sendo 3.

APROVAÇÃO_REAL: o mesmo comando npm test, na mesma pasta, com o código
após a correção descrita. O mesmo teste passa: tests 1, pass 1,
fail 0, skipped 0, código de saída 0.
A saída completa está em logs/test-pass.txt.
O cenário com cinco combinações não foi executado.

CAPTURA_DE_TELA: screenshots/bonus-score-3.png. O jogo foi aberto novamente
em http://localhost:3000, na mesma árvore de trabalho,
após a correção. A pontuação inicial é 0, foram feitas três combinações
e o placar mostra 3. O salvamento do resultado no leaderboard não foi verificado.

Os caminhos do exemplo são ilustrativos. Guarde logs, diffs e imagens onde o projeto já costuma armazenar esse tipo de arquivo; não é necessário criar uma estrutura obrigatória de pastas.

Observe as duas últimas linhas dos campos 5 e 6. Registre uma omissão diretamente, em uma frase: "não foi executado", "não foi verificado". Isso não é admitir preguiça, é deixar claro o limite da conclusão. Sem essas linhas, o registro parece mais completo, mas apenas omite o que ninguém fez.

Faça uma autoavaliação

A tarefa tem dois critérios: o cálculo soma 3 pontos para três combinações com pontuação inicial zero, e a interface mostra 3 depois dessas combinações. Há seis itens em mãos:

1. uma mensagem do agente:"pronto, bug corrigido";
2. uma instrução para executar npm test;
3. execuções reais de um teste: falha antes da correção e aprovação depois;
4. um diff que mostra a alteração do multiplicador;
5. uma captura isolada com o número 3, sem descrição da execução;
6. um registro do cenário reproduzido, com a captura correspondente.

Quais itens são suficientes para comprovar os dois critérios e o que ainda não foi verificado? Pense na resposta antes de continuar.

Vamos analisar. O primeiro critério é comprovado pelo item 3: um par real de execuções do mesmo teste. O diff do item 4 explica o que mudou no código, mas não substitui a execução - alterar e executar são coisas diferentes. O segundo critério é comprovado pelo item 6: uma captura junto com o registro do cenário, que mostra o estado inicial e a ação. Os itens 1 e 2 não comprovam nada: a mensagem de conclusão não traz evidências verificáveis, e a instrução descreve uma ação futura. O item 5 mostra o número 3, mas não permite saber como a pontuação foi calculada. E o salvamento do resultado no leaderboard continua sem verificação, mesmo com os seis itens à vista: nenhum deles registra um cenário que leia de volta o valor salvo.

Também dá para montar esse registro em uma sessão. Use este prompt:

Monte um EVIDENCE_LOG com seis campos. Para cada conclusão, indique
a verificação real, o estado do código e a origem do resultado.
Marque à parte o que não foi executado. Na captura de tela, descreva
somente o que está visível, sem inferir que o cálculo interno está correto.

Como reunir evidências com o Claude Code

O fluxo de trabalho fica assim:

1. o agente relaciona cada critério a uma verificação específica: o que executar, em que estado do código e qual resultado esperar;
2. executa as verificações disponíveis naquele ambiente e mostra o comando junto com a saída original;
3. anexa as observações: trechos da saída, links para os arquivos completos e a descrição do cenário reproduzido;
4. deixa claro o limite: o que não foi executado e o que não pode ser afirmado com base nas evidências disponíveis.

Ao(À) senhor(a) cabe conferir as próprias evidências: abrir os arquivos anexados, ver o conteúdo, comparar o cenário com o critério e fazer uma pergunta incômoda sobre qualquer item sem verificação aparente. Em geral, isso basta para distinguir evidências reunidas de um relato bem apresentado.

Referências técnicas: git diff, git stash, test runner do Node.js, npm test, imagens no Claude Code.