Lição 1 de 7 · 15 min · Verificado em 6 de Outubro de 2026
Pedir bem a um agente: tarefas pequenas, critério de pronto e o que é um teste
No fim desta lição vais conseguir:
- Transformar um pedido vago numa tarefa pequena com um critério de pronto que se pode verificar
- Explicar o que é um teste automático e ler um teste simples em Python
- Pedir o teste antes do código e confirmar no diff que o agente não mexeu no teste
A Rita faz bolos na Calheta e recebe as encomendas por mensagem. Quer um programa pequeno que faça as contas: cada bolo custa 10 euros e, a cada 6, um é oferecido. Abre o agente e escreve: «Faz-me um programa para as encomendas.»
Dez minutos depois tem catorze ficheiros, uma base de dados e um ecrã de entrada com palavra-passe. Não sabe se as contas estão certas. E não pediu nada daquilo.
O agente não trabalhou mal. Fez o trabalho que o pedido deixava fazer. Um pedido sem fim à vista não tem fim.
O conceito: dizer quando está pronto
Um bom pedido a um agente tem três partes:
- O quê, uma coisa só: «a função que calcula o preço de uma encomenda».
- Onde: «no ficheiro
encomendas.py». - Como se sabe que acabou: o critério de pronto. Tem de ser algo que se verifica sem opiniões, como «quando
python3 -m pytestpassar e o README explicar como correr».
Exemplo
Vago: «Faz-me um site.»
Com critério de pronto: «Cria a função preco_encomenda(quantidade, preco_unitario) no ficheiro encomendas.py. Regra: a cada 6 bolos, um é oferecido. Está pronto quando python3 -m pytest passar e o README.md explicar como correr os testes.»
Com o segundo pedido, tu e o agente sabem quando parar. O guia do Codex diz o mesmo: um pedido útil diz o que queres, onde, que limites respeitar e como verificar.
Passos de 10 a 20 minutos
Um trabalho grande divide-se em passos que consigas rever em 10 a 20 minutos, cada um com o seu critério e o seu commit (lição 1/05). Se um correr mal, recuas só esse.
Não tens de ser tu a fazer a divisão. Pede o plano antes do código, como na lição 1/03:
Quero um programa para as encomendas de bolos. Antes de escrever código, divide o trabalho em passos de 10 a 20 minutos. Para cada passo, escreve o critério de pronto, que eu tenho de conseguir verificar. Não mudes ficheiros ainda.
Lê o plano, corta o que não pediste e só depois manda avançar com o primeiro passo.
Dica
Se o plano tiver mais de cinco passos para uma coisa pequena, pede: «Corta para o mínimo que funciona. O resto fica para depois.»
O que é um teste automático
Quando a Rita tira uma fornada, prova um bolo antes de vender os outros. Um teste automático faz o mesmo ao código: é uma pequena função que chama a tua função com um exemplo de resposta conhecida e grita se o resultado for diferente.
Seis linhas de Python:
# ficheiro test_encomendas.py
from encomendas import preco_encomenda
def test_seis_bolos_pagam_cinco():
# 6 bolos a 10 euros: um é oferecido, paga 50
assert preco_encomenda(6, 10) == 50
A palavra assert quer dizer «garanto que». Se preco_encomenda(6, 10) der 50, o teste passa em silêncio. Se der 60, falha e mostra os dois valores. As outras peças já as conheces da lição 0/03.
Quem corre os testes é o pytest. Procura os ficheiros cujo nome começa por test_, corre as funções que começam por test_ e no fim diz, por exemplo, 1 passed (passou) ou 1 failed (falhou).
Primeiro o teste, depois o código
A ordem importa. Pede primeiro só o teste:
Escreve só o ficheiro test_encomendas.py para esta regra: a cada 6 bolos, um é oferecido. Inclui um caso com 6 bolos e outro com 5. Não escrevas a função ainda. Diz-me que comando corro e o que devo ver.
Corres os testes e eles falham, porque a função não existe. Ainda bem: o teste dá pela falta. Depois:
Agora escreve a função em encomendas.py para que os testes passem. Não mudes o ficheiro de testes. Corre os testes e mostra-me o resultado.
Porquê esta ordem? Um teste escrito depois do código tende a copiar o que o código já faz, erros incluídos. Escrito antes, nasce do que tu queres. O guia de boas práticas do Claude Code recomenda o mesmo: um teste que falha e que o agente tem de pôr a passar.
Ler o diff
Antes de aceitar, lê o diff (lição 1/03) e faz três perguntas:
- Mudou só os ficheiros que disse que ia mudar?
- Tocou no ficheiro de testes? Se sim, porquê?
- O valor esperado continua a ser o teu (50, e não outro)?
Cuidado
Quando um teste não passa, um agente pode «resolver» o problema mudando o teste em vez do código: troca o 50 por 60, ou apaga a linha do assert. Os testes passam e o erro fica. Se o diff mexer no valor esperado, recusa e repete: «Corrige a função. O teste não se muda.»
Dica
Corre tu os testes, mesmo que o agente diga que já os correu. Demora dois segundos e a prova fica do teu lado.
Como se faz hoje: correr os testes
Isto é como está a 6 de Outubro de 2026; se o ecrã for diferente, procura o botão com o mesmo nome.
O pytest não vem com o Python. Instala-se num ambiente virtual, uma pasta .venv só deste projecto. Dentro da pasta do projecto (guias: ambientes virtuais e primeiros passos com o pytest):
python3 -m venv .venv
source .venv/bin/activate
pip install pytest
python3 -m pytest
No Windows, a segunda linha é .venv\Scripts\Activate.ps1 e, se python3 não existir, escreve python. Junta .venv/ ao .gitignore (lição 1/06). Em cada terminal novo, repete a linha do activate.
Dica
Põe o critério de pronto no AGENTS.md ou no CLAUDE.md (lição 1/07): «Antes de dizeres que acabaste, corre python3 -m pytest.» Assim não o repetes em cada pedido.
Exercício
Como sei que ficou bem no passo 3, o pytest mostra um erro porque encomendas ainda não existe. No passo 5 mostra 2 passed, o ficheiro de testes está igual ao do passo 3 e o README tem os comandos para correr os testes.
Se não deu
- «No module named pytest»: o ambiente virtual não está activo. Corre outra vez a linha do
activatee confirma que aparece(.venv)no início da linha do terminal. - «No module named encomendas»: o ficheiro tem outro nome ou está noutra pasta. Os dois ficheiros têm de estar lado a lado, e o comando corre-se nessa pasta.
- «no tests ran»: o nome do ficheiro ou da função de teste não começa por
test_. - O agente escreveu logo a função: recusa e repete o pedido com «só o teste, mais nada».
Fontes:
Vídeos
Introdução aos testes unitários para quem começa: o que são, o conceito por trás e a sua importância. É de 2023, mas o conceito mantém-se.
Porque o ciclo vermelho, verde e refactor (TDD) funciona tão bem com agentes de código: o teste dá ao agente um critério de pronto e um ciclo de feedback.