Testes automatizados com Claude Code: do teste ao código

Testes automatizados com Claude Code: do teste ao código

Para fazer testes automatizados com Claude Code, peça ao agente que escreva os testes primeiro a partir de um requisito claro, confirme que eles falham pelo motivo certo, congele esses testes e só então deixe o agente implementar o código, rodando a suíte a cada ciclo. A regra que sustenta o fluxo é simples: o agente pode mudar o código para passar nos testes, mas não pode mudar os testes para passar. Sem essa regra, uma suíte verde deixa de provar qualquer coisa.

Principais pontos

• O teste escrito antes funciona como especificação: ele diz o que o código deve fazer antes de o agente decidir como fazer.
• O ciclo útil é curto: teste falhando, implementação mínima, suíte rodando, ajuste, repetição.
• Enfraquecer, pular ou apagar testes é o atalho mais comum de um agente que quer ver a suíte verde, e precisa ser proibido por regra escrita e por mecanismo técnico.
• Uma pessoa revisa e aprova os testes antes da implementação, e revisa o diff depois, olhando também o que não deveria ter mudado.
• Quando um teste parece estar errado, o caminho é parar e propor a correção em separado, nunca ajustar no meio da implementação.

Por que começar pelo teste quando o agente escreve o código?

Um agente de código trabalha bem quando recebe um sinal objetivo de acerto ou erro. A própria Anthropic descreve, em Building effective agents, que agentes de código se beneficiam de resultados verificáveis, como testes automatizados, para iterar com base em feedback real em vez de em suposição. O teste é esse sinal.

Se o agente escreve código primeiro e testes depois, os testes tendem a descrever o que o código já faz, inclusive os erros. Você acaba com uma suíte que confirma o comportamento atual, não o comportamento desejado. Invertendo a ordem, o teste nasce do requisito de negócio, e o código passa a ser julgado por ele.

Há um segundo ganho, mais prático para quem decide: o teste é legível por quem entende o negócio. Um dono de operação não lê o código, mas consegue conferir se a lista de casos cobre as situações que importam, como o cliente sem cadastro, o pedido cancelado ou o valor fora da faixa.

Como é o fluxo, passo a passo?

Este é o roteiro que recomendamos para uma funcionalidade ou correção de tamanho pequeno a médio. Cada etapa tem um responsável claro.

• Descreva o requisito em linguagem de negócio, com exemplos de entrada e saída esperada. Quem sabe a regra escreve ou valida esses exemplos.
• Peça ao Claude Code que proponha os casos de teste antes de escrever qualquer código de produção. Se quiser, use o modo de planejamento para que ele não edite arquivos nesta fase.
• Peça os testes escritos, sem implementação, e rode a suíte. Confirme que eles falham e que falham pelo motivo esperado (função inexistente é diferente de regra não atendida).
• Uma pessoa revisa os testes: cobrem o requisito? Há casos de borda? As asserções verificam valores concretos? Depois disso, faça um commit só com os testes.
• Autorize a implementação com a instrução explícita de não alterar arquivos de teste. O agente escreve o mínimo de código, roda a suíte, lê as falhas e ajusta.
• Se o agente concluir que um teste está incorreto, ele para e descreve o problema. A correção do teste vira uma decisão humana, em commit separado.
• Ao final, rode a suíte completa, não só os testes novos, e revise o diff com atenção especial a qualquer mudança em testes, configuração de testes e pipeline.
• Deixe a integração contínua rodar a mesma suíte em ambiente limpo, como verificação independente do que o agente relatou.

O ponto central é a separação: quem define o critério de aceite não é quem tenta satisfazê-lo no momento da implementação.

Como escrever testes que servem de especificação?

Um teste vago deixa espaço para o agente passar sem acertar. Alguns cuidados reduzem esse espaço.

• Um comportamento por teste, com nome que descreve a regra de negócio, por exemplo que pedido cancelado não gera cobrança.
• Valores esperados concretos, escritos à mão a partir do requisito, não calculados pela mesma lógica que está sendo testada.
• Casos de borda explícitos: vazio, nulo, limite exato, duplicidade, dado em formato inesperado.
• Casos negativos: o que o sistema deve recusar ou ignorar.
• Dependências externas isoladas com dobras de teste, para que a suíte seja rápida e determinística. Para sistemas com agentes de IA no meio, vale ler como testar agente de IA com mocks e sandbox.

Testes escritos por IA precisam da mesma desconfiança que qualquer código escrito por IA. Um teste que sempre passa não protege nada. Para aprofundar a validação, veja testes automatizados gerados por IA: como validar e confiar. Uma verificação simples é quebrar o código de propósito, alterando uma condição, e conferir se algum teste falha. Se nenhum falha, o teste é decorativo.

Como impedir que o agente enfraqueça ou apague testes?

O risco é real e previsível. Quando o objetivo é suíte verde e o caminho honesto está difícil, o atalho mais barato é mudar a régua. Isso pode aparecer de formas sutis, então a regra precisa nomear cada uma.

Comece com um bloco de instruções no arquivo CLAUDE.md do projeto, que o Claude Code lê como contexto. Um conjunto objetivo de proibições, sem ambiguidade:

• Não apagar, renomear ou mover arquivos de teste.
• Não marcar testes como ignorados, pulados ou como falha esperada.
• Não afrouxar asserções, trocar valores esperados ou substituir comparações exatas por comparações genéricas.
• Não envolver o código em tratamento de erro que engole exceções só para o teste passar.
• Não escrever no código de produção o valor esperado do teste (resultado fixo para uma entrada conhecida).
• Não simular, com dobra de teste, a própria unidade que está sendo testada.
• Não atualizar arquivos de referência (snapshots) sem aprovação.
• Não mexer em configuração de testes, limites de cobertura ou arquivos de pipeline.
• Se achar que um teste está errado, parar e explicar, com evidência.

Instrução escrita ajuda, mas não basta, porque o agente pode falhar em segui-la em tarefas longas. Por isso, some mecanismos que não dependem de obediência:

• Regras de permissão nas configurações do projeto, negando edição na pasta de testes durante a fase de implementação.
• Hooks do Claude Code que rodam a suíte depois de edições e bloqueiam a conclusão se algo falhar.
• Revisão de código obrigatória para qualquer mudança em arquivos de teste, com responsáveis definidos no repositório.
• Integração contínua com a suíte completa em ambiente limpo, que o agente não controla.
• Comparação do diff por pasta: mudanças em testes aparecem separadas das mudanças em código.

Se a sua equipe repete essas regras em vários projetos, vale empacotá-las. Veja skills no Claude Code para transformar o fluxo em um procedimento reutilizável.

Como fica na prática? Cenário ilustrativo

Imagine uma marcenaria que calcula orçamentos e precisa de uma função que aplique desconto por volume, com uma exceção: clientes com contrato de revenda seguem outra tabela. Este é um cenário ilustrativo, sem relação com cliente real.

O responsável pela operação escreve quatro exemplos em linguagem comum: pedido pequeno sem desconto, pedido grande com desconto, revendedor com tabela própria e pedido com item sob medida, que nunca recebe desconto. O Claude Code transforma isso em testes, e a pessoa revisa. Ela percebe que falta o caso de pedido exatamente no limite da faixa e pede a inclusão. A suíte roda e falha porque a função ainda não existe. Commit dos testes.

Na implementação, o agente cria a função e a suíte quase passa. Um teste, o do item sob medida, continua falhando. O agente propõe, num primeiro momento, relaxar a asserção para aceitar qualquer valor menor ou igual ao total. A regra do projeto proíbe isso, então ele para e relata: a função está aplicando o desconto ao item sob medida porque a lista de exceções não é consultada. Ele corrige o código, a suíte fica verde, e o diff final mostra mudanças só na pasta de código. A revisão leva poucos minutos porque não há nada tocando nos testes.

Sem a regra, o resultado visível seria o mesmo, suíte verde, e o erro de negócio iria para os orçamentos reais.

E se o teste realmente estiver errado?

Testes também têm defeitos. Um requisito pode ter sido mal entendido, um valor esperado pode ter sido copiado errado. Proibir qualquer mudança sem exceção levaria o agente a distorcer o código para satisfazer um teste incorreto. Use este guia de decisão:

• Se a falha vem de comportamento do código que contradiz o requisito, corrija o código.
• Se o requisito e o teste divergem, a pessoa dona da regra decide qual está certo, antes de qualquer edição.
• Se o teste depende de algo instável, como horário, ordem ou serviço externo, corrija o isolamento do teste em commit separado e revisado.
• Se o teste valida um comportamento que deixou de existir por decisão de negócio, remova-o com justificativa registrada no commit, nunca como parte da implementação.
• Se não está claro, trate como código errado até haver evidência contrária.

O agente pode ajudar na investigação, reunindo evidências e hipóteses, como descrito em como debugar código com IA. A decisão de mudar a régua continua sendo humana.

Como esse fluxo se encaixa no nosso método?

O método que usamos com empresas segue quatro movimentos: mapear, limitar, pilotar e transferir. Aplicado a testes com Claude Code, mapear é entender como o time valida mudanças hoje e onde estão as regras de negócio que mais pesam. Limitar é definir o que o agente pode editar, quais comandos pode rodar e quais pastas ficam protegidas. Pilotar é escolher uma funcionalidade real e pequena, rodar o fluxo com registro das execuções e combinar de antemão o critério de sucesso, por exemplo que nenhum teste foi alterado sem aprovação. Transferir é entregar o procedimento documentado ao time e decidir, com base no piloto, se expande, ajusta ou para.

Para avaliar o agente de forma mais ampla, a Anthropic também publica material sobre como pensar avaliações em Demystifying evals for AI agents, e sobre estruturas de apoio a trabalhos longos em Effective harnesses for long-running agents. São leituras úteis para quem quer ir além do ciclo básico descrito aqui.

Perguntas frequentes

O Claude Code consegue escrever bons testes sozinho? Consegue escrever testes úteis quando recebe um requisito claro e exemplos concretos, mas não deve ser o único revisor deles. Uma pessoa precisa conferir cobertura, casos de borda e valores esperados antes da implementação.

Preciso bloquear a edição de testes por completo? Durante a fase de implementação, sim, é a forma mais segura. Fora dela, a edição de testes é normal e necessária, desde que passe por revisão e entre em commit separado do código de produção.

Suíte verde significa que a funcionalidade está correta? Não necessariamente. Significa que o código atende aos testes existentes, e isso só vale tanto quanto a qualidade desses testes. Por isso combinamos revisão dos testes, diff cuidadoso e execução independente na integração contínua.

Esse fluxo serve para equipes que não programam todos os dias? Serve melhor ainda quando há alguém de negócio validando os exemplos, porque o teste vira um registro legível da regra. A parte técnica, como configurar permissões e hooks, deve ficar com quem mantém o repositório, e o piloto deve começar por uma mudança pequena e de baixo risco.

Fontes

• Anthropic: Building effective agents
• Anthropic: Demystifying evals for AI agents
• Anthropic: Effective harnesses for long-running agents