Spec-driven development com IA: primeiro a spec, depois o código

A maioria dos times usa IA como se estivesse escrevendo prompts de memória. Você abre um agente, descreve a tarefa em três frases, recebe código, corrige, recebe mais código. Funciona, até o momento em que a tarefa não cabe mais numa frase só. Aí o agente chuta, e você se pega corrigindo as consequências da sua própria intenção mal especificada. O spec-driven development inverte a ordem: primeiro você escreve a especificação, depois o agente a implementa. O código é o resultado, não o ponto de partida.

Por que uma spec escrita vence o prompt de memória

Um prompt de memória tem três defeitos que crescem junto com a velocidade do agente. Primeiro, ele é efêmero: sai do contexto depois de algumas rodadas, e o agente passa a trabalhar com a própria interpretação de dez mensagens atrás. Segundo, ele é incompleto: na sua cabeça existem restrições (orçamento de tempo, formato dos dados, caminho de rollback) que você nunca diz em voz alta porque “são óbvias”. Para um agente, nada é óbvio. Terceiro, ele é inverificável: como você nunca registrou o que deveria ser construído, não tem como conferir se foi.

Uma spec escrita elimina os três. Ela é durável, então o agente volta a ela a cada rodada em vez de chutar. É completa, porque o ato de escrever obriga você a nomear as restrições que, de outra forma, ficariam na sua cabeça. É verificável, porque contém critérios de aceitação com os quais você pode confrontar o código pronto. Isso não é burocracia: é tirar o raciocínio da fase de correções e levá-lo para a fase de design, onde ele custa dez vezes menos.

Anatomia de um bom SPEC.md

Uma boa spec tem uma estrutura fixa, para que tanto o humano quanto o agente saibam onde encontrar cada coisa. Cinco seções resolvem 95% dos casos.

Objetivo. Uma frase, no máximo duas: o quê e para quem. Não o “como”, e sim o “porquê”. Se você não consegue resumir o objetivo em duas frases, provavelmente tem duas tarefas fingindo ser uma.

Requisitos funcionais. Uma lista de comportamentos observáveis. Cada item descreve algo que o sistema faz, de preferência no formato “quando X, então Y”. Esse é o miolo da spec, e é nele que você passa a maior parte do tempo.

Requisitos não funcionais. As restrições fáceis de deixar passar: latência, custo de chamada ao LLM, limites de memória, compatibilidade retroativa, caminho de rollback, segurança dos dados. Geralmente são elas que decidem se uma implementação está pronta para produção.

Fora de escopo. Uma lista explícita do que não vamos fazer nesta iteração. Sem essa seção, o agente (prestativo até demais) acrescenta funcionalidades que ninguém pediu, e você revisa um código que nunca deveria ter existido.

Critérios de aceitação. Uma lista verificável de condições de “pronto”, de preferência num formato que dê para transformar em testes. Se um critério não pode ser verificado, não é um critério: é um desejo.

Como o agente usa a spec como contrato

Quando a spec fica pronta, ela deixa de ser uma anotação e vira um contrato. O agente a recebe como contexto estável e trabalha dentro dos limites dela: os requisitos funcionais dizem o que construir; os não funcionais, dentro de quais limites ficar; o fora de escopo, onde parar; e os critérios de aceitação, quando considerar a tarefa concluída.

Essa mudança tem consequências práticas. Primeiro, você pode pedir ao agente que confira o próprio trabalho em relação aos critérios de aceitação antes de declarar que terminou, e que mande o trabalho de volta para correção sem a sua participação. Segundo, quando o agente quer fazer algo fora da spec, isso fica imediatamente visível: ou ele está quebrando o contrato, ou a spec estava incompleta. Nos dois casos, você recebe o sinal cedo, e não na revisão, depois de duas horas de geração.

O contrato também muda a natureza da sua revisão. Sem spec, você lê o código e pergunta “isso faz o que eu queria?”, apoiando-se na memória do que você queria. Com spec, você pergunta “isso atende aos critérios de aceitação?”, e a resposta é binária e independente do seu humor. A revisão deixa de ser uma negociação e passa a ser uma checagem contra um padrão combinado de antemão. O mesmo vale para um agente revisor: ele tem um ponto de referência explícito, então os comentários dele são concretos em vez de vagos.

Iterar com spec-first em vez de code-first

A principal mudança de mentalidade: quando a implementação dá errado, você não corrige o código, você corrige a spec. Código é barato e reproduzível; o agente o gera de novo em um minuto. A spec é a fonte da verdade, então é nela que você corrige a causa, e não o sintoma.

Na prática, funciona assim: o agente entrega uma implementação, você a lê pela ótica dos critérios de aceitação e encontra uma divergência. Em vez de digitar “muda isso e aquilo” no chat, você volta à spec, acrescenta o requisito que faltava ou esclarece o que estava ambíguo e pede que a parte afetada seja reimplementada. Depois de algumas iterações, a spec está precisa e o código é o reflexo fiel dela. Correções pelo chat fazem o contrário: o código fica certo, mas a spec fica para trás e ninguém mais sabe o que é verdade.

Essa abordagem também protege você da armadilha mais comum do trabalho com IA: entregar rápido algo que parece funcionar, mas resolve metade do problema. Os critérios de aceitação são implacáveis: ou todos são atendidos, ou a tarefa não está pronta, não importa quão bonito o código pareça.

Spec curta é spec boa

Uma spec deve caber em 400-800 palavras. Não é um limite arbitrário: é o patamar abaixo do qual a spec continua legível de uma só olhada, tanto para um humano quanto para a janela de contexto do agente. Uma spec mais longa costuma ser sintoma de um de dois problemas: ou a tarefa é grande demais e deveria ser dividida em várias specs menores, ou você está descrevendo a implementação em vez da intenção.

A segunda armadilha é traiçoeira. Quanto mais “como” você coloca na spec, menos espaço deixa para o agente encontrar uma solução que talvez supere a sua primeira ideia, e mais rápido a spec fica desatualizada a cada mudança no código. A spec descreve o quê e por quê; deixe o como para o agente, a menos que o “como” seja um requisito não funcional rígido.

Um exemplo de esqueleto de spec que cabe no limite:

• Objetivo: um endpoint para exportar as faturas de um cliente em PDF, usado pelo painel de cobrança.
• Funcionais: quando um cliente solicita uma exportação, o sistema devolve um PDF com todas as faturas do período escolhido; quando o período está vazio, devolve uma mensagem clara; quando o cliente não tem permissão, devolve 403.
• Não funcionais: resposta em menos de 2 s para 100 faturas; nenhum PDF armazenado em disco; logs sem dados pessoais.
• Fora de escopo: envio por e-mail, exportação para outros formatos, cobrança recorrente.
• Aceitação: um teste para um período com faturas devolve um PDF válido; um teste de período vazio devolve uma mensagem, e não um erro; um teste sem permissão devolve 403; tempo de resposta p95 abaixo de 2 s.

Como isso escala num time

O spec-first deixa de ser uma disciplina pessoal e vira um protocolo do time. A spec é um artefato compartilhado que você pode colocar num PR ao lado do código, linkar numa issue e revisar como se fosse um diff. Revisar uma spec é mais barato do que revisar uma implementação, porque ela se lê em um minuto e pega premissas erradas antes que alguém escreva uma linha de código.

Para um time, isso traz três coisas. Onboarding: uma pessoa nova lê a spec e entende a intenção sem fazer arqueologia no código. Consistência: duas pessoas com a mesma spec recebem do agente soluções comparáveis, porque o contrato é o mesmo. Auditabilidade: depois do fato, você sabe o que deveria ser construído e por quê, então as decisões são reproduzíveis, em vez de ficarem trancadas na memória de alguém.

Na prática, adote uma regra simples: toda mudança que mexe em mais do que alguns arquivos ganha uma spec que um humano aprova antes da implementação. O agente pode escrever o primeiro rascunho (ele é bom nisso), mas a aprovação final é humana. Sem essa decisão, a spec deixa de ser um contrato e vira só mais um texto gerado em que ninguém confia.

TL;DR

O spec-driven development com IA inverte a ordem: primeiro você escreve um SPEC.md curto (400-800 palavras) com objetivo, requisitos funcionais e não funcionais, uma seção de fora de escopo e critérios de aceitação, e só então o agente o implementa. A spec é um contrato: o agente trabalha dentro dos limites dela e, quando algo dá errado, você corrige a spec, e não o código. Uma spec curta continua legível e atualizada; como artefato do time, ela escala o onboarding, a consistência e a auditabilidade. Uma spec escrita vence o prompt de memória porque é durável, completa e verificável, e a aprovação final dela sempre cabe a um humano.