📐 Adote o fluxo orientado por especificação
Spec-Driven Development significa que a especificação vem antes do código — e permanece como fonte da verdade durante toda a execução. Uma especificação não é um texto genérico: ela existe para reduzir ambiguidade e transformar intenção em critérios verificáveis.
Como ler: repare nas duas pontas. A especificação (esquerda, em destaque) e a verificação (direita, em ciano) falam da mesma coisa — a segunda só existe para conferir a primeira. Se você não escreveu a spec, a verificação não tem contra o que comparar, e "pronto" vira opinião.
🆕 Novo aqui?
Especificação (spec) é um documento curto que diz o que precisa existir e como saber que ficou pronto — não é documentação de arquitetura nem um chamado no Jira. Critério de aceitação é uma frase que pode ser respondida com sim ou não olhando o sistema ("a resposta continua idêntica para os mesmos parâmetros"). Se a frase depende de gosto ("ficar mais organizado"), ela ainda não é critério.
Antes do código
Spec precede o plano
Ambiguidade
Alguém sempre decide
Verificável
Sim/não, não "melhor"
Fonte da verdade
Vale mais que o chat
🧱 Monte os elementos de uma boa especificação
Este é o esqueleto. Cada campo ausente vira uma decisão que o agente toma sozinho — normalmente a mais genérica possível. Use como checklist: se um campo está vazio, pergunte-se quem vai decidir aquilo, e quando.
Problema
Qual problema precisa ser resolvido? (não é a solução)
Objetivo
Qual resultado deve ser alcançado?
Escopo · Fora do escopo
O que faz parte da tarefa — e o que não deve ser alterado.
Entradas · Saídas
Quais dados ou eventos entram; quais resultados o sistema produz.
Contratos
Interfaces, formatos e comportamentos que devem ser preservados.
Condições de erro
O que deve acontecer quando algo falhar.
Restrições
Tecnologias, padrões, limites e regras a respeitar.
Critérios de aceitação · Testes
Como verificar a conclusão; quais testes criar ou executar.
Definição de pronto
Quais condições encerram o trabalho — sem negociação posterior.
💡 Dica prática
Comece guardando esse esqueleto como specs/_template.md no repositório. Spec que mora junto do código é lida; spec que mora numa wiki externa envelhece em duas semanas.
Campo vazio
= decisão delegada
Fora do escopo
Freio da refatoração
Contrato
Protege quem consome
Pronto
Encerra a discussão
🎯 Delimite escopo e critérios de aceitação
Escopo positivo todo mundo escreve. O que salva a revisão é o escopo negativo: a lista do que não pode ser tocado. Sem ele, um agente competente "aproveita a viagem" e devolve um diff de quarenta arquivos que ninguém revisa direito.
✓ Critério verificável
- ✓"A resposta permanece idêntica para os mesmos parâmetros."
- ✓"Requisição duplicada com a mesma chave de idempotência não cria segunda cobrança."
- ✓"Nenhum arquivo fora de src/pagamentos/ é alterado."
- ✓"A suíte roda em menos de 90 segundos."
✗ Critério que não decide nada
- ✗"Deixar o código mais limpo."
- ✗"Melhorar a performance."
- ✗"Seguir as boas práticas."
- ✗"Manter compatibilidade" (sem dizer com o quê).
Teste do escopo negativo
Antes de mandar a tarefa, responda em uma linha cada:
Quais arquivos/pastas ele NÃO pode tocar?
Quais dependências ele NÃO pode adicionar?
Qual comportamento existente NÃO pode mudar?
Que tipo de refatoração fica para depois?
Sim/não
Critério é binário
Escopo negativo
Vale tanto quanto o positivo
Diff pequeno
É revisável de verdade
Sem "melhor"
Comparativo vago não serve
🔌 Descreva contratos, entradas, saídas e erros
Quase toda regressão grave nasce de um contrato implícito: alguém sabia que aquele campo nunca podia vir nulo, mas isso não estava escrito em lugar nenhum. O agente não adivinha o que o time inteiro esqueceu de registrar.
🔒 O que um contrato fixa
- •Forma: nomes de campos, tipos, obrigatoriedade, formato de data, unidade de valor monetário.
- •Comportamento: ordenação, paginação, idempotência, efeitos colaterais.
- •Falha: qual código de erro, qual corpo de resposta, se há retentativa e com qual espera.
- •Compatibilidade: quem consome hoje e o que não pode quebrar para essa pessoa.
🧭 Condições de erro que quase sempre faltam
Implícito quebra
Escreva o óbvio
Erro é requisito
Caminho triste tem spec
Quem consome
Liste antes de mudar
Teste de contrato
Transforma acordo em gate
🆚 Compare uma spec ruim com uma spec completa
O par canônico do workshop. Leia os dois e conte quantas decisões estavam escondidas na frase curta.
✗ Especificação ruim
Crie um sistema de pagamentos.
Meios de pagamento, duplicidade, estados, webhooks, dados sensíveis, testes, rollback — tudo isso será decidido por quem executar, do jeito que parecer razoável no momento.
✓ Especificação mais completa
Criar um serviço de pagamentos que: - aceite PIX e cartão; - impeça duplicidade por chave de idempotência; - registre todos os estados da transação; - processe webhooks; - realize retentativas; - gere logs estruturados; - preserve compatibilidade com a API atual; - não armazene dados sensíveis de cartão; - inclua testes unitários e de integração; - tenha rollback para migrações; - bloqueie o merge se os testes falharem.
Cada linha fecha uma porta de decisão. Quanto melhor a especificação, menor a chance de o agente tomar decisões incompatíveis com o sistema.
🧪 Exercício copiável — gere a spec com o próprio agente
Objetivo: sair da frase curta sem escrever tudo do zero. Cole no seu agente, dentro do repositório real.
Você vai escrever uma ESPECIFICAÇÃO, não código. Não altere nenhum arquivo. Tarefa que eu quero fazer: <descreva em uma frase> Repositório: leia <caminhos relevantes> antes de responder. Produza um documento com estas seções, e nada além delas: problema · objetivo · escopo · fora do escopo · entradas · saídas · contratos · condições de erro · restrições · critérios de aceitação · testes · definição de pronto Regras: - cada critério de aceitação deve ser verificável com sim ou não; - liste explicitamente o que NÃO deve ser alterado; - no final, liste em "PERGUNTAS" tudo que você teve que supor. - não invente regras de negócio: se não achou no código, vai para PERGUNTAS.
Como verificar: a seção "PERGUNTAS" é o ouro do exercício — ela lista exatamente as decisões que o agente teria tomado sozinho se você tivesse mandado o prompt curto. Responda-as, atualize a spec e só então autorize a implementação.
Uma linha
Esconde dez decisões
Idempotência
Requisito, não detalhe
PERGUNTAS
Suposições à vista
Spec versionada
Mora no repositório
🔗 Transforme cada critério em teste
Aqui a spec deixa de ser documento e vira mecanismo. Uma regra escrita em texto é útil; a mesma regra transformada em teste automático é muito mais confiável — e é o que permite delegar execução ao agente sem perder controle.
Leia o critério em voz alta
"Requisição duplicada com a mesma chave não gera segunda cobrança."
Escreva o teste que falha hoje
Dispara duas vezes a mesma requisição e afirma que existe exatamente uma cobrança. Ele precisa falhar antes da implementação — senão não está testando nada.
Entregue o teste ao agente como definição de pronto
A tarefa deixa de ser "implemente idempotência" e passa a ser "faça este teste passar sem alterar o próprio teste". É uma condição de parada objetiva — o assunto da trilha 2.
⚠️ Atenção
Se o agente pode editar os testes livremente, ele tem permissão para redefinir o que significa "pronto". Trate arquivos de teste como área protegida: alterar teste é mudança de spec e exige aprovação humana explícita.
Spec executável
Teste é a regra viva
Falha primeiro
Senão não prova nada
Teste protegido
Mudar teste = mudar spec
Autonomia
Vem do verificador
📌 Resumo do Módulo
Próxima trilha:
Trilha 2 - Harness Engineering: o sistema que envolve o modelo (ferramentas, contexto, permissões, limites).