Você descreve o que quer para a IA, ela escreve o código e funciona. Na primeira vez, parece mágica. Depois de um tempo, você percebe que cada execução entrega um resultado ligeiramente diferente, e nenhum deles é exatamente o que você tinha na cabeça.
Você descreve o que quer para a IA, ela escreve o código e funciona. Na primeira vez, parece mágica. Depois de um tempo, você percebe que cada execução entrega um resultado ligeiramente diferente, e nenhum deles é exatamente o que você tinha na cabeça. É assim que o vibe coding começa a custar caro.
O problema não está na IA. Está na falta de um documento antes do código.
Neste artigo você vai aprender:
- Por que "adicione autenticação" não é um pedido específico (e o que a IA decide por você quando você não decide antes)
- Os 3 documentos que todo mundo confunde: PRD, design doc e spec
- O framework SPEC-5: os 5 blocos que todo spec precisa ter
- O loop de 5 passos que transforma o spec em código entregue
- Quando escrever spec é desperdício de tempo (sim, existe)
Por que o vibe coding trava
O vibe coding funciona bem para coisas pequenas. Um script rápido, uma tela de teste, algo no ar em trinta segundos. Ninguém deveria abrir mão disso. E quem não programa também consegue usar IA para automatizar tarefas — eu escrevi sobre isso em Codex para quem não programa.
O problema aparece quando o resultado não fica exatamente certo. Você ajusta o prompt. A IA reescreve. Você ajusta de novo. Até que parece bom o bastante para publicar.
O que aconteceu nesse loop? A IA tomou centenas de decisões pequenas que você nunca viu, e nada registrou o motivo. Rode o mesmo prompt cem vezes e você terá cem versões diferentes. Nenhuma está errada. Só não é a que você tinha na cabeça.
Pegue um pedido comum: "adicione autenticação". Parece específico. Não é.
Qual estratégia de token? Quanto tempo dura a sessão? Existe fluxo de refresh? Recuperação de senha? Login social? Qual banco de dados? Qual ORM? Como os erros são formatados? Onde os tokens ficam guardados? Precisa de testes, e de que tipo?
Você não respondeu nada disso. Então a IA respondeu por você, em silêncio. Você só descobre quais respostas recebeu depois que o código roda.
O código quase sempre está certo. As decisões é que nunca foram suas. Essa é a falha real do vibe coding.
O que as grandes empresas já fizeram
Enquanto você ajusta prompt, as quatro maiores empresas de engenharia do mundo não escreveram artigos de opinião. Elas lançaram ferramentas.
- Amazon criou o Kiro, um IDE desenhado em torno de especificações
- GitHub liberou o Spec Kit como kit open source
- Google publicou um codelab de desenvolvimento guiado por spec para o Antigravity
- Microsoft aborda o tema no blog de desenvolvedores
Quatro das maiores organizações de engenharia do planeta não ficaram filosofando. Elas entregaram ferramentas. Quando o mercado age assim, o debate já acabou: a direção é essa.
Os 3 documentos que todo mundo confunde
Grande parte da confusão sobre esse tema é vocabulário. PRD, design doc, spec, requisitos. As pessoas usam as quatro palavras como se fossem a mesma coisa.
PRD é escrito para pessoas. Product managers, stakeholders, quem aprova. Responde o que vamos construir e por que vale a pena. Valor de negócio mora aqui.
Design doc é escrito para engenheiros. Responde o como. Arquitetura, escala, segurança, trade-offs.
Spec é escrito para a IA. É o novo da lista, e é o assunto deste artigo. Pega um pouco do porquê do PRD, porque contexto ajuda a IA a decidir melhor quando algo não foi definido. Mas o spec existe para ser executado, não para ser discutido.
Escreva um spec como PRD e a IA se afoga em justificativa de negócio que não consegue usar. Escreva como design doc e você ganha arquitetura sem critério de aceite. É um documento próprio, com um trabalho próprio.
O framework SPEC-5
Um spec que funciona tem cinco blocos. Falte um e você sente exatamente qual faltou.
1. Why — o porquê
Duas ou três frases de contexto. Qual problema resolve e para quem. É o bloco que permite à IA tomar uma decisão sensata quando você esqueceu de especificar algo.
2. What — o quê
O comportamento observável. Endpoints, entradas, saídas, estados. Concreto o bastante para que dois engenheiros, lendo o mesmo documento, construam a mesma coisa.
3. Constraints — as restrições
O bloco mais subestimado, e o que separa um spec de um desejo. Agentes de IA são ansiosos. Deixados sozinhos, instalam pacote, inventam padrão e refatoram arquivo que você nunca mencionou. Constraints é onde você diz não por antecipação.
4. Out of scope — fora do escopo
Uma lista separada de propósito. Constraints diz como construir. Fora do escopo diz o que não tocar. Toda feature carrega uma feature vizinha óbvia que a IA vai adicionar de boa vontade se você não cortar.
5. Tasks — as tarefas
O trabalho dividido em pedaços discretos. Cada um diz o que construir, quais arquivos toca e como saber que está pronto.
Leia o bloco de constraints de novo. Quatro linhas, e cada uma fecha uma decisão que a IA tomaria por você. É o bloco que todo mundo pula, e é o que mais trabalha.
O loop de 5 passos
O spec não é o fluxo de trabalho. Isto é:
- Gerar. Descreva a feature e peça para a IA rascunhar o spec. Escrever a primeira versão à mão é mais lento e não é melhor.
- Revisar. Leia como adversário. Em qualquer lugar onde a IA ainda tenha espaço para adivinhar, feche agora. Toda ambiguidade deixada aqui vira reescrita depois.
- Quebrar. Divida o trabalho em tarefas pequenas o bastante para terminar e verificar de uma sentada.
- Rodar uma tarefa. Uma. Não o spec inteiro. É o passo que as pessoas mais erram.
- Revisar e commitar. Confira o trabalho contra a condição de pronto que você já escreveu, faça o commit e vá para a próxima tarefa.
Você não entregaria a um engenheiro novo um documento de quarenta páginas e sumiria. Você daria um ticket, revisaria e daria o próximo. Com IA não é diferente, e ela falha do mesmo jeito quando você pula esse passo.
O ganho composto aparece na segunda sessão. O spec continua lá. A IA retoma a tarefa quatro com as mesmas restrições da tarefa um, e nada deriva.
Quando escrever spec é desperdício
Honestidade faz parte do método. O spec compra previsibilidade. Não compra velocidade, e em trabalho pequeno ele custa as duas coisas.
Pule o spec quando:
- A tarefa é um arquivo com uma função. Escrever o spec demora mais que o conserto
- Você ainda está explorando. Se você não sabe o que quer, um spec trava uma suposição e torna caro abandoná-la
- É descartável. Um protótipo que você vai apagar na sexta não precisa de contrato
- Tanto faz qual abordagem a IA escolher. Se qualquer implementação razoável serve, deixe-a escolher
O teste é simples. Pergunte se você ficaria irritado se a IA tomasse aquela decisão de forma diferente. Se sim, a decisão pertence ao spec. Se você der de ombros, pode continuar vibrando.
E existe a armadilha do outro lado: um spec tão detalhado que vira a implementação é só código escrito em prosa, e agora você mantém duas coisas. Se o seu spec é maior que a feature, você não escreveu um spec. Você escreveu a coisa.
Perguntas rápidas
O que é spec-driven development?
É a prática de escrever, antes do código, um documento curto que define o que será construído, as restrições, o que está fora do escopo e as tarefas. A IA executa o spec em vez de adivinhar com um prompt solto.
Preciso saber programar para escrever um spec?
Não. O spec descreve comportamento observável, não implementação. Um founder consegue escrever o Why, o What, as restrições e o fora do escopo do próprio produto sem escrever uma linha de código.
Vibe coding morreu?
Não. Vibe coding continua ótimo para protótipos, scripts e exploração. Ele simplesmente não escala para o que você vai manter em produção. Spec-driven development é o próximo degrau.
Qual a diferença entre PRD, design doc e spec?
O PRD é para pessoas e fala de valor de negócio. O design doc é para engenheiros e fala de arquitetura. O spec é para a IA e existe para ser executado, com critérios de pronto.
Quanto tempo leva para escrever um spec?
Minutos para tarefas pequenas, algumas horas para features grandes. A regra é simples: se o spec demora mais que a feature, você escreveu a coisa errada.
Na prática
Escreva um spec curto antes do próximo código que você pedir à IA. Cinco blocos, sem perfeccionismo. Se a IA ainda tiver espaço para adivinhar em algum ponto, feche esse ponto antes de rodar.
O papel do líder muda junto. Você deixa de ser quem digita e vira quem decide: o que entra, o que não entra e onde ficam as fronteiras. A IA cuida do como. Os engenheiros que escrevem um spec limpo vão entregar mais do que os que ficam ajustando prompt até parecer certo.
Vibe o demo. Especifique o que você vai entregar de verdade.
Se você quer levar esse debate para a sua liderança ou seu time, eu falo sobre IA, inovação e futuro do trabalho em palestras para empresas. Conheça a palestra sobre IA e veja como preparar seu time para construir com IA previsível.
---
Fontes: post original de 0xjeyx sobre spec-driven development, GitHub Spec Kit, Amazon Kiro, Google Antigravity
Quer transformar esta ideia em uma palestra, workshop ou advisory conectado ao desafio da sua empresa?