Spec driven development: o que ele resolve no vibe coding, e o que não

Spec driven development resolve 2 falhas de agente bem específicas: o agente que tenta construir o sistema inteiro numa tacada e o agente que olha para um trabalho pela metade e anuncia que terminou. A spec cobre essas duas e para ali, e saber onde fica essa fronteira evita cobrar dela o que ela não faz.

Quem separou uma coisa da outra ao vivo foi gbrl808, numa live em que ele parou de codar para explicar por que agentes falham mesmo com modelo bom. Ele começa pela cena que quem faz vibe coding com agente já viveu ao menos uma vez.

O one shot hero: 40 minutos de geração e um diff de 3.000 linhas

"Dá um pr agente de a constrói uma aplicação full stack com autenticação, dashboard e integração com stripe. O agente sai gerando código doidão por 40 minutos. Quando termina tu abre um DIF de 3.000 linhas alteradas. Metade funciona, metade não compila, tem feature duplicada, ele sobrescreveu um teste, ele [d]eletou teste, ele declarou tudo como pronto e tu gastou um monte de token."

One shot hero é o nome que ele dá ao padrão. O agente tenta o aplicativo inteiro de uma vez, estoura a janela de contexto no meio, alucina o que falta, e a sessão seguinte abre o projeto e encontra o que ele chama de campo minado. Os 40 minutos e as 3.000 linhas são o custo que aparece na tela, e a sessão do dia seguinte ainda vai queimar token para descobrir o que a anterior fez.

Ele põe a culpa em outro lugar:

"Isso não é um bug do modelo. Os modelos de hoje são muito capazes. O problema é que ninguém ensinou ele como trabalhar."

Por que a spec resolve o one shot hero

A spec desarma esse padrão por um motivo mecânico. Ela planeja o trabalho antes e quebra em tarefas menores, e cada tarefa passa a caber numa janela de contexto. O agente para de tentar segurar o sistema inteiro na cabeça porque ninguém mais pede isso a ele.

O modelo continua o mesmo, com a mesma capacidade que gerou as 3.000 linhas quebradas. O que a spec muda é o tamanho do pedaço entregue a ele em cada rodada, e é aí que o estouro de janela deixa de acontecer no meio da implementação. O mesmo problema apareceu em react native vs flutter.

A vitória prematura, e o que conta como pronto no vibe coding

A segunda falha é o agente parar no meio e dizer "Isso aqui já tá pronto". Ele se perde num contexto grande, chega a um ponto qualquer, anuncia "Terminei isso daqui" e deixa um monte de coisa para trás. A spec resolve porque escreve antes a lista de features, com o que precisa existir para a tarefa contar como feita, e o agente perde a autoridade de decidir sozinho o que é pronto.

Outro builder atacou o mesmo sintoma por outro caminho, exigindo prova de que a tarefa foi feita, um print da tela como critério de aceite, porque "terminei" não é entregável. A spec chega pelo começo e define pronto antes de o trabalho existir, enquanto o print chega pelo fim e cobra evidência depois de ele existir.

A frase dele amarra as duas falhas:

"A spec impede o one shot e define o que o pronto significa."

Onde a spec para

Ele também é explícito sobre onde a spec acaba:

"a spec é o feed forward puro. Ela diz o que fazer, mas não verifica se foi feito de forma certa."

A spec é escrita antes e não olha o resultado depois. Um exemplo do que fica de fora é a amnésia entre sessões: cada sessão nova do agente começa do zero, e a spec diz o que fazer, mas não diz o que já foi feito, o que deu errado nem qual é o estado atual do código. O agente novo chega, olha o código e gasta metade dos tokens tentando entender o que aconteceu ali.

Segundo ele, quem usa spec driven development está na metade do caminho, e a metade seguinte é uma camada que verifica o resultado, o que ele chama de harness. Quando essa camada vira um segundo agente, a spec deixa de ser só um plano e passa a valer como contrato entre o agente implementador e o validador: a mesma lista de critérios que orienta quem escreve o código é a interface pela qual quem valida aceita ou recusa a entrega. Para quem escreve spec hoje, o que importa é que ela cobre a entrada do trabalho e não a saída. Vale ver como isso terminou em harness engineering.

O que fazer amanhã, antes de abrir o agente

Escreva a spec da tarefa com a lista de features e quebre até cada item caber numa sessão do agente. Se você não consegue dizer, olhando para o item, o que precisa existir para ele estar pronto, o item ainda está grande demais e vai voltar na forma de vitória prematura.

Depois disso, aceite a segunda parte do recado. A spec não confere nada. Quem confere é uma ferramenta fora do agente, um teste que roda ou um print que alguém olha, e o sinal que ela devolve é o único que o agente não controla. Sem esse sinal, o agente continua sendo juiz do próprio trabalho, e o diff de 3.000 linhas volta em versões menores e mais difíceis de perceber.

A explicação inteira, com a demonstração rodando na tela, está em assistir à live.