Test-driven development by example: como aplicar o ciclo teste, código e refatoração usando IA

Fala aí, beleza? Tem uma cena que todo mundo que usa IA no editor já viveu: você pede uma função e o assistente devolve 80 linhas prontas, com try/except, log e um teste que passa de primeira porque foi escrito depois do código 😅

O formato "by example" é o antídoto simples pra isso: em vez de estudar TDD na teoria, você conduz UM caso pequeno de ponta a ponta e a técnica aparece sozinha no caminho

Este post refaz exatamente esse exercício, só que com um assistente de código no editor: teste falhando primeiro, implementação mínima depois, refatoração no fim

É pra você que já usa IA pra codar todo dia mas nunca amarrou o ciclo teste, código e refatoração de verdade

O que significa "by example" e de onde veio o formato

TDD não nasceu ontem

A técnica foi criada por Kent Beck no fim dos anos 1990, dentro do Extreme Programming, como Martin Fowler registra no bliki dele

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

Já o "by example" do título vem do livro Test Driven Development: By Example, do próprio Kent Beck, publicado pela Addison-Wesley Professional em 2002, 1ª edição, 240 páginas, ISBN-13 9780321146533

E o livro é dividido em três partes:

• Parte I: The Money Example (caps. 1 a 17, começando em Multi-Currency Money e terminando em Money Retrospective)
• Parte II: The xUnit Example (caps. 18 a 24)
• Parte III: Patterns for Test-Driven Development (caps. 25 a 32, incluindo Red Bar Patterns, Green Bar Patterns e Refactoring)

Repara na Parte I, que é o coração da coisa: dezessete capítulos conduzindo UM exemplo pequeno, o do dinheiro multimoeda, até o fim

É esse o espírito de test-driven development by example: não é um catálogo de regras, é um caso minúsculo levado do começo ao fim pra você sentir o ritmo

E qual é o ciclo, afinal?

São três passos que se repetem, o famoso red, green, refactor:

1. escrever um teste para o próximo pedaço de funcionalidade
2. escrever o código funcional até o teste passar
3. refatorar código novo e antigo pra ficar bem estruturado

Mas tem um passo ANTES do ciclo que quase todo mundo pula: escrever a lista de casos de teste e escolher um por vez

Você escreve a lista, pega um item, aplica red-green-refactor nele, e só então passa pro próximo

E sim, sequenciar bem os testes é uma habilidade, não é sorte 🙂

O que você precisa antes de começar

A lista é curta, não precisa de PC da Nasa nem de setup mirabolante:

Um projeto com suíte de testes rodando. Nos exemplos aqui uso Python com pytest, que é invocado pelo comando pytest e descobre os testes por convenção de nome

Se você nunca parou pra ler essa convenção, se liga (está na documentação do pytest): ele executa todos os testes em arquivos no formato test_.py ou _test.py no diretório atual e nos subdiretórios

Dentro deles, descobre funções prefixadas com test_ e classes prefixadas com Test (sem método __init__)

Dá pra trocar essas convenções via python_files, python_classes e python_functions no arquivo de configuração, mas pro exercício aqui o padrão já resolve

Um assistente de código no editor. Os exemplos de comando abaixo usam Claude Code, porém a lógica do ciclo é a mesma em qualquer agente que rode teste no terminal

Um CLAUDE.md no projeto. É o arquivo markdown com instruções específicas do projeto, convenções e contexto que o Claude Code lê em toda sessão

É ali que a regra de TDD fica ESCRITA, pra você não repetir a mesma bronca a cada prompt novo

Passo a passo: o mesmo exercício conduzido com um assistente de código

O exemplo vai no espírito do Money Example: uma classe de dinheiro que multiplica valor sem perder a moeda

Pequeno de propósito, porque o objetivo é passar pelo ciclo inteiro uma vez, não construir um banco 😀

1. Escreva a lista de casos e escolha UM

Antes de qualquer prompt, abra um arquivo de rascunho e escreva os casos:

- 5 USD x 2 = 10 USD
- 5 USD x 3 = 15 USD
- 5 USD + 5 USD = 10 USD
- somar USD com BRL sem taxa deve dar erro

Agora escolhe o primeiro e ESQUECE o resto

O erro comum deste passo: despejar a lista inteira no prompt e pedir tudo de uma vez, aí o agente entrega a classe completa e você nunca vê a barra vermelha

2. Avise explicitamente que você está fazendo TDD

Isso não é firula minha, está na documentação de boas práticas do Claude Code, na letra: "Be explicit about the fact that you’re doing TDD so that Claude avoids creating mock implementations, even for functionality that doesn’t exist yet in the codebase"

Traduzindo o motivo: se você não avisa, o modelo tende a inventar uma implementação falsa (mock) pra funcionalidade que ainda nem existe no projeto, e o teste passa mentindo

Coloca isso no CLAUDE.md, algo como:

## TDD

Neste projeto trabalhamos com TDD.
Nunca crie mock de funcionalidade que ainda não existe.
O teste vem primeiro e deve falhar antes de qualquer implementação.

O erro comum deste passo: avisar uma vez no chat e achar que valeu pra sempre, quando na sessão seguinte o contexto já era

3. Peça pesquisa e plano, sem escrever código

A mesma documentação registra uma coisa que bate com a prática: sem os passos de pesquisa e planejamento, o Claude tende a ir direto pro código

E pedir pesquisa e plano antes melhora o resultado em problemas que exigem raciocínio mais profundo

Então o prompt aqui é: leia os arquivos relevantes, NÃO escreva código, me devolva um plano

Pra travar isso de verdade, usa o modo plano, onde o agente pesquisa e propõe mudanças sem editar o código:

• Shift+Tab cicla entre default → acceptEdits → plan
• dá pra prefixar o prompt com /plan
• a barra de status mostra ⏸ plan mode on
• Ctrl+G abre o plano no editor de texto

Quem já trabalha com IA descrevendo a intenção antes vai reconhecer o padrão: é primo direto de escrever a spec antes do código, só que aqui a spec é o teste

O erro comum deste passo: aprovar o plano no automático, no next, next e finish, e só descobrir depois que ele já previa "criar a classe e o teste juntos"

4. RED: rode os testes e confirme que falham

Agora escreve o teste do primeiro caso da lista:

# test_money.py
from money import Money


def test_multiplicar_dolar_por_dois():
    cinco = Money(5, "USD")
    assert cinco.times(2) == Money(10, "USD")

E roda:

pytest

A documentação do Claude Code descreve esse passo assim: peça pra rodar os testes e confirmar que falham, dizendo EXPLICITAMENTE pra não escrever código de implementação ainda

Quando os testes estiverem satisfatórios, commita eles antes de partir pra implementação

Parece bobo commitar teste quebrado, mas é isso que impede o agente (e você) de ajustar o teste depois pra ele caber no código que saiu

O erro comum deste passo: ver o vermelho e já mandar "agora resolve", sem ler a mensagem de erro; o ModuleNotFoundError aqui é informação, ele confirma que nada existe ainda

5. GREEN: libere a implementação mínima

Agora sim o agente pode escrever código, com uma condição: o mínimo pro teste passar

# money.py
class Money:
    def __init__(self, amount, currency):
        self.amount = amount
        self.currency = currency

    def times(self, multiplier):
        return Money(self.amount * multiplier, self.currency)

    def __eq__(self, other):
        return self.amount == other.amount and self.currency == other.currency

Roda pytest de novo e olha o verde

O erro comum deste passo: deixar passar o "já aproveitei e implementei a soma, a conversão e um cache"; tudo que veio sem teste vermelho antes é código que ninguém pediu

6. REFACTOR: arruma a casa com os testes de rede

Com o verde na mão, aí sim você refatora código novo E antigo pra ficar bem estruturado

No exemplo acima tem cheiro fácil de arrumar: __eq__ explodindo se other não for Money, o construtor sem validação de moeda, por aí vai

A regra é uma só: refatorou, roda pytest

Se ficou vermelho, você não refatorou, você quebrou 😛

O erro comum deste passo: pedir "refatora esse arquivo" solto e aceitar uma reescrita gigante; refatoração boa é pequena e o teste continua verde a cada passo

Quando o ciclo segura a IA (e quando ele atrapalha)

Amarrar o agente ao teste não é regra de fé, tem hora que rende muito e hora que só atrapalha

Rende bem em três situações bem concretas:

Agora o contraponto honesto, porque nem tudo merece esse rigor: script descartável, prova de conceito de fim de semana e exploração de API que você nem sabe se vai usar ainda cabem no modo solto

Escrever lista de casos pra um script de 20 linhas que roda uma vez é cerimônia sem retorno

Veja também

Pra continuar no assunto de modelos de código, este vídeo do canal compara três deles frente a frente:

Próximo passo: rode um caso pequeno hoje

A sacada do formato "by example" é essa: não adianta ler sobre o ciclo, tem que passar por ele inteiro uma vez

Então escolhe um caso minúsculo do teu projeto de hoje, escreve a lista de casos, pega o primeiro item e faz o red-green-refactor completo com o assistente segurado no modo plano

Depois disso, duas coisas pra fixar o hábito: escrever a regra de TDD no CLAUDE.md do projeto, pra ela valer em toda sessão, e repetir o ciclo no próximo item da lista

Um caso por vez, sem pressa

O resto do arquivo vai acompanhando…

até o próximo post!