O Claude Code disse que terminou, mas a feature não funciona: como conferir antes de confiar

Fala aí, beleza? A cena é sempre a mesma: o agente escreve que implementou tudo, ainda avisa que rodou os testes, tu abre o app, clica no botão principal e não acontece nada

Quando o Claude Code disse que terminou, o que você tem em mãos é uma afirmação, não uma prova

E não é frescura sua nem caso isolado: o padrão está reportado publicamente no repositório oficial, na issue #14947 "Claude marks tasks complete without verifying implementation", aberta em 21/12/2025, relatando itens de todo marcados como completed sem terem sido implementados

Tem mais gente na mesma: a #12369 ("Claude Code fails to verify task completion against documented requirements") e a #37818 ("Claude repeatedly declares fixes done without end-to-end verification") descrevem o mesmo comportamento

Então bora montar a rotina de conferência: o que checar, com qual comando, e como voltar atrás quando você descobre tarde demais

Sintoma: a tarefa aparece como concluída, mas nada foi implementado

O todo fica marcado como completed, a resposta final diz que terminou, e o arquivo que deveria mudar continua igualzinho

Por que acontece: o Claude Code trabalha num ciclo de reunir contexto, agir e verificar o resultado, usando ferramentas (inclusive rodar testes) pra checar o próprio trabalho

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

É o famoso gather context → take action → verify work → repeat

O problema mora no terceiro passo: se não existe nada executável pra ele rodar, o "parece pronto" vira o único sinal disponível

Aí adivinha quem assume o papel de loop de verificação? você 🙂

Como resolver: dar ao Claude uma checagem que ele mesmo consiga rodar, que é exatamente o que a documentação oficial de boas práticas recomenda

Vale qualquer uma destas:

• suíte de testes
• exit code de build
• linter
• script que compara a saída com uma fixture
• screenshot de navegador comparado ao design

Como prevenir: definir essa checagem antes de pedir a tarefa, e não depois de receber o relatório bonitinho

É a diferença entre pedir um resultado e pedir um resultado com critério de aceite embutido, mesma lógica de exigir prova em vez de relato em qualquer correção que ele diz ter feito

Sintoma: você esperava que o /verify rodasse sozinho e ele não rodou

A tarefa acaba, o resumo aparece, e nenhuma verificação contra o app rodando aconteceu

Por que acontece: desde a versão 2.1.215 do Claude Code, as skills /verify e /code-review não são mais auto-executadas, elas exigem invocação explícita

Antes da 2.1.215 o Claude podia disparar o /verify por conta própria, e é daí que vem a sensação de que "antes ele conferia" (as notas da 2.1.215 registram a mudança)

Como resolver: invocar /verify na mão

Ele é uma skill embutida que sobe o app e confirma a mudança contra o app rodando, e não só contra os testes

Que diferença faz? testes passando provam que a função retorna o que a função deveria retornar

O /verify mira outra coisa: a mudança aparece de verdade quando o app está de pé

Como prevenir: tratar essa invocação como parte fixa do seu checklist de fim de tarefa

O opt-in não é castigo, é controle: essas checagens são mais longas e gastam tempo e tokens, então quem decide a hora é você

Sintoma: o /verify não consegue subir o app do seu projeto

A verificação começa e trava, porque seu projeto precisa de banco, arquivo .env, sessão gráfica ou um build de vários passos

Por que acontece: sem receita gravada, o /verify funciona sem setup e infere como subir o app pelo tipo de projeto (CLI, server, TUI, browser-driven) e pelo que existe no README, no package.json ou no Makefile

Em projeto padrãozinho ele acerta

No teu monstrinho com três serviços e variável de ambiente obrigatória, adivinhação não cola

Como resolver: rodar /run-skill-generator

Ele grava a receita de subir o app como uma skill por projeto, em .claude/skills/run-<nome>/

São três skills embutidas trabalhando juntas, se liga:

Como prevenir: rodar o /run-skill-generator uma vez por projeto, e de novo quando o build ou o processo de subida mudar

E se eu não rodar o gerador? aí entra um segundo mecanismo, que é outro e não se confunde com o primeiro: quando o /verify precisa subir e dirigir o app sem receita gravada, é ele mesmo que escreve o que funcionou num arquivo de skill

Os dois caminhos são diferentes, e vale gravar essa distinção:

• receita que você manda gravar de propósito com o /run-skill-generator: vai pra .claude/skills/run-<nome>/
• anotação que o /verify deixa sozinho quando não achou receita: vai pra .claude/skills/verify/SKILL.md na raiz do repositório, ou no diretório do pacote tocado em monorepo

O ganho é o mesmo nos dois casos: a próxima execução (e outros agentes) seguem os mesmos passos em vez de reinventar tudo

Se a receita gravada não pegar do jeito que você esperava, vale o mesmo raciocínio de quando uma skill não roda no seu projeto: o problema costuma estar no contexto local, não na skill em si

Sintoma: o diff parece correto, mas o comportamento na tela não é o esperado

Você lê a mudança linha por linha, faz todo sentido, aprova

Aí roda o fluxo real e ele falha

Por que acontece: revisar código e observar comportamento são duas checagens diferentes

Diff bonito responde "a lógica está coerente?"

Só o app rodando responde "o usuário consegue fazer o que precisa?"

Como resolver: usa as duas frentes

Pra correção do código tem o /code-review, skill embutida que revisa o diff atual em busca de bugs num subagente separado e devolve os achados pra sua sessão (existe também o /code-review ultra, revisão multiagente na nuvem)

Pra app web, o Claude Code conecta ao Chrome via extensão Claude in Chrome (v1.0.36+, da Chrome Web Store), o que permite testar o app, depurar com logs do console e preencher formulários a partir do CLI ou da extensão do VS Code

Roda /chrome no painel do Claude Code pra habilitar a conexão, checar status, gerenciar permissões ou reconectar

Tome cuidado! o Claude abre abas novas e compartilha o estado de login do seu navegador, e as ações acontecem numa janela visível do Chrome em tempo real

Se quiser deixar ligado por padrão, roda /chrome e escolhe "Enabled by default"

Como prevenir: rodar o fluxo de ponta a ponta pela interface antes de aceitar a entrega, nem que seja o caminho feliz

Sintoma: descobri o problema depois e o código já mudou demais

A entrega quebrou alguma coisa, você só percebeu três tarefas na frente e agora não sabe onde voltar

Por que acontece: aceitar o "pronto" e seguir empilhando mudança em cima de mudança não verificada

Como resolver: o Claude Code tem checkpointing automático, ou seja, ele salva o estado dos arquivos antes de cada mudança e deixa você voltar a um ponto anterior

Abre o menu com /rewind, ou apertando Esc duas vezes com o campo de prompt vazio

As opções são:

• restaurar código
• restaurar código e conversa
• restaurar só a conversa

Os limites que importam saber antes de precisar:

• ele guarda os 100 checkpoints mais recentes por sessão
• os checkpoints são apagados junto com as sessões após 30 dias (período ajustável por cleanupPeriodDays)

E tem uma pegadinha que dá pra se ferrar: o checkpointing não reverte arquivos que são symlink ou hard link

Esses caminhos são pulados na restauração, e você vê o aviso Restored the code, but skipped N files

Se aparecer essa mensagem, não assuma que voltou tudo, confere os arquivos pulados na mão

Como prevenir: conferir por entrega, não por lote

Quanto menor o intervalo entre o "terminei" e a sua checagem, menor a chance de precisar do plano B

Como prevenir: transformar a conferência em rotina com hooks

Até aqui tudo depende de você lembrar

Dá pra automatizar parte disso: o Claude Code tem hooks de ciclo de vida, e existe o evento Stop, que dispara logo depois que o Claude termina de responder, antes do turno acabar de fato

É o momento exato do "terminei"

E o que dá pra fazer nesse ponto? um hook que sai com exit code 2 sinaliza erro bloqueante

No evento Stop, isso impede o Claude de parar e faz a conversa continuar

Detalhe importante: esse bloqueio do exit 2 é o único resultado que o JSON de saída não consegue sobrepor

O efeito prático é bem massa: o "terminei" deixa de ser a palavra final e passa a ser só mais um passo do ciclo

Se a checagem não passou, a conversa segue e ele volta pro trabalho, sem depender da sua vigilância

O que aconteceu quando eu conferi as páginas uma a uma

No vídeo abaixo eu mostro exatamente esse momento de desconfiança saudável

O agente anunciou que tinha terminado e ainda afirmou que havia rodado os testes

Eu tratei aquilo como promessa, não como prova, e falei que ia conferir se o projeto tinha sido criado do jeito certo mesmo

Antes de qualquer teste teve um passo que só eu podia fazer, e que o próprio agente apontou no fim: colocar a chave de API no arquivo de variáveis de ambiente

Sem isso a funcionalidade principal não teria como funcionar, por mais correto que estivesse o código

O relatório final trouxe três informações que serviram direitinho pra checagem: como testar, como rodar o projeto e o que ainda faltava configurar da minha parte

Aí eu fui na mão mesmo: criei uma conta, fiz login, caí na dashboard e só então descrevi um produto pra ver se os 5 slogans eram gerados de verdade

Foram 4 páginas entregues e conferidas uma a uma: landing page, registro, login e dashboard

O custo dessa execução, medido no painel de uso, ficou em torno de 11 a 12 centavos de dólar

Uma execução de teste anterior tinha dado 3 centavos

Eu tinha colocado 2 dólares de crédito na conta só pra acompanhar o consumo de perto

Um aviso honesto sobre esse número: rodar a aplicação pra testar consome a mesma chave de API que o agente usa, então o gasto medido fica um pouco mascarado pelos meus próprios testes

Meu veredito, separado da entrega: o projeto não é dos mais fabulosos

Mas depois do teste manual eu pude afirmar com tranquilidade que estava funcional, e isso só foi possível porque percorri o fluxo, não porque li o resumo

Teve também o que eu não fiz direito, e assumi na hora: pedi um arquivo de documentação do projeto e segui em frente sem ler o resultado

O certo seria ler e entender se deu tudo certo ou se faltou complementar alguma coisa

A razão de criar esse arquivo é dar contexto pro próximo agente continuar o trabalho sem destruir o que já existe, uma camada de segurança mesmo em projeto pequeno

Ah, e antes de liberar a execução eu li o planejamento que ele apresentou

Plano aprovado na entrada, fluxo conferido na saída: é isso que sustenta um veredito

Conferir pela interface custou alguns minutos e centavos

Aceitar o "pronto" e descobrir o problema três tarefas depois custa bem mais caro, e você paga em retrabalho

Antes de aceitar o próximo "pronto"

"Pronto" é uma afirmação

Prova é comportamento observado com o app de pé

Então no próximo pedido, faz assim:

1. Defina a checagem executável antes de começar: testes, exit code de build, linter, script comparando saída com fixture ou screenshot contra o design. O erro comum aqui é combinar isso só depois que o agente já entregou, quando o "parece pronto" já se instalou como único sinal
2. Invoque /verify no fim, lembrando que desde a 2.1.215 ele não roda mais sozinho. O erro comum é esperar a execução automática que existia antes e concluir que "não verificou nada"
3. Se o projeto for chatinho de subir, rode /run-skill-generator pra gravar a receita em .claude/skills/run-<nome>/. O erro comum é rodar uma vez e esquecer: se o build ou o processo de subida mudar, roda de novo
4. Passe o /code-review no diff pra pegar bug de correção num subagente separado
5. Percorra o fluxo pela interface, do começo ao fim, como usuário
6. Guarde o /rewind como plano B, sabendo dos limites: 100 checkpoints por sessão, 30 dias de retenção, e symlink ou hard link não voltam

O agente dizer que terminou não encerra o trabalho, só encerra a parte dele

A sua parte é olhar a tela 😀

até o próximo post!