Tem uma cena que eu repito com frequência. Abro o Lovable/Replit, descrevo o que quero em linguagem natural, vejo a mágica acontecer na tela e me impressiono de novo. A cada semana os modelos ficam mais capazes, o código gerado tem mais lógica por trás, e o que antes levava dias de desenvolvimento tradicional começa a ficar pronto em horas.

Isso é real. E é incrível.

Mas tem uma armadilha embutida nesse processo que pouca gente está discutindo com seriedade. E eu quero falar sobre ela aqui.

Vibe Coding: ótimo pra explorar, perigoso pra escalar

O termo "Vibe Coding" surgiu pra descrever uma prática que a maioria das pessoas já adotou sem perceber: você manda um prompt, vê se o resultado parece funcionar, ajusta aqui e ali, e segue em frente. É programação por tentativa e erro, guiada mais pela sensação de que "parece certo" do que por uma compreensão clara do que está sendo construído.

Para um protótipo rápido ou um experimento de fim de semana? Perfeito. É exatamente o que você precisa.

O problema começa quando essa mesma abordagem é usada para construir algo que precisa sobreviver ao tempo, crescer com a base de usuários e ser mantido por outras pessoas (ou por você mesmo, seis meses depois, sem lembrar de nada).

Tem um dado que vale anotar. Pesquisas recentes mostram que o código gerado por IA tende a permanecer nos repositórios por mais tempo do que o código escrito por humanos, com uma taxa de modificação quase 16 pontos percentuais menor por linha. O que parece ótimo, até você descobrir que esse mesmo código acumula mais bugs ao longo do tempo. O código fica parado, mas carregando problemas sutis que vão aparecendo aos poucos.

A IA construiu exatamente o que foi pedido. O problema é que o que foi pedido não era exatamente o que precisava ser construído.

Entra o Spec-Driven Development

O Spec-Driven Development (SDD) não é uma buzzword nova. É uma mudança de mentalidade: em vez de tratar a especificação como documentação burocrática que ninguém lê, o SDD coloca a spec no centro de tudo. Ela vira a fonte da verdade. O código passa a ser um produto derivado dela.

Uma analogia boa: na construção civil, a planta do engenheiro tem mais autoridade do que a parede que o pedreiro levantou. Se a parede não está de acordo com a planta, a parede é refeita. No SDD, a lógica é a mesma.

E não é sobre escrever menos código. É sobre pensar melhor antes de pedir para a IA escrever qualquer linha.

A IA não pergunta quando encontra algo ambíguo. Ela tenta adivinhar, e faz isso em silêncio. Essas suposições silenciosas vão se acumulando no código como uma dívida técnica invisível. O sistema parece funcionar, passa nos testes básicos, mas falha em cenários específicos que nunca foram descritos porque nunca foram pensados.

Como isso funciona na prática (a minha versão)

Tanto nos meus projetos no trabalho (o que eu chamo de build to earn) quanto nos meus projetos paralelos (build to learn), eu tento ao máximo operar com essa lógica de especificação antes de execução.

O primeiro passo é definir o alicerce técnico. Antes de qualquer prompt de geração de código, eu descrevo qual stack técnica quero usar naquele produto específico. Isso não é capricho de arquiteto. É um guardrail que ajuda o agente a tomar decisões consistentes ao longo de toda a construção.

A minha stack favorita atual foi montada pensando justamente nisso: ferramentas AI Friendly, bem documentadas, que ajudam a guiar a forma como os agentes escrevem o código e facilitam a leitura e manutenção do produto ao longo do tempo.

No frontend, uso Next.js 14 com App Router e TypeScript (obrigatório, sem exceções), shadcn/ui para todos os componentes de UI e Tailwind CSS para estilização. No backend, Supabase com PostgreSQL, Auth, Storage e Realtime, com Row Level Security para multi-tenancy isolado no nível do banco, Prisma ORM como schema fonte de verdade e pgvector para embeddings. Para IA, centralizo todas as conexões com LLMs pelo OpenRouter, o que permite usar diferentes modelos com um único provider. Na infra, Vercel para deploy e preview environments por branch, GitHub para controle de versão com feature branches, Inngest para jobs assíncronos e PostHog para analytics, session replay e experimentos.

Até as convenções de código entram nas instruções: componentes em PascalCase, funções e variáveis em camelCase, arquivos de componente em kebab-case.tsx, Server Components por padrão com "use client" apenas quando necessário. Parece detalhe, mas faz uma diferença enorme na consistência do que o agente gera.

Depois da stack definida, vem o ERD.

Se você para um momento para pensar em como as informações do produto serão guardadas e organizadas, e apresenta esse Diagrama de Entidade-Relacionamento para a IA como uma estrela-guia, as chances de o agente criar entidades aleatórias que fujam da visão original caem drasticamente. O ERD não é só documentação técnica. É um contrato com o sistema sobre como a realidade do produto está modelada.

Com a stack e o ERD no lugar, o próximo passo é escrever os specs. Eu descrevo o que imagino em um cenário ideal do produto, escrevo PRDs para cada funcionalidade principal e, a partir daí, uso os agentes para destrinchar esses specs em tarefas menores. Depois executamos essas tarefas de forma incremental, desenvolvendo e testando cada funcionalidade antes de avançar.

O grande diferencial

Vibe Coding é "me faz um CRUD de usuários" e ver o que aparece.

SDD é definir que esse CRUD precisa respeitar RLS no Supabase, seguir o schema do Prisma que foi pensado junto com o ERD, estar numa API Route em /app/api/usuarios/route.ts e ter tratamento de erro consistente com o restante do sistema.

Não é sobre cortar a autonomia da IA. É sobre definir os focos e restrições que vão determinar a direção do que está sendo construído.

O engenheiro de software (ou o PM, ou o designer, ou qualquer pessoa que interage com produtos digitais) precisa deixar de operar só no modo "comandar e rezar" para se tornar um arquiteto de intenção. Alguém que define o que o sistema deve fazer e por que, com precisão suficiente para que a IA cuide do como.

Desacelerar para especificar parece custar tempo. Na prática, é o investimento que te poupa de semanas de retrabalho depois.

Para quem isso é relevante

Falo muito disso pensando em PMs e pessoas de inovação, mas a verdade é que esse raciocínio é útil para qualquer pessoa que, de alguma forma, interage com produtos digitais. Seja você dev, designer, analista ou alguém que usa agentes de IA para automatizar partes do seu trabalho.

A IA é extraordinária para executar. O problema é que ela executa o que foi pedido, e pedir bem é uma habilidade que ainda estamos desenvolvendo coletivamente.

Spec-Driven Development é, no fundo, isso: a prática de pedir bem.