A IA não sabe o que você quer. · usnevs

Como o Spec-Driven Development resolve o maior problema de quem desenvolve com IA?

Existem dois jeitos de usar a IA para desenvolvimento.

Se você está começando a usar IA para desenvolver, provavelmente já caiu numa das duas categorias mesmo sem saber o nome de nenhuma delas.

Vibe coding é o jeito mais natural de começar: você tem uma ideia, abre o Lovable, o Cursor ou o Claude Code, digita o que quer construir e vai ajustando conforme a IA entrega. É intuitivo, rápido, e dá aquela sensação boa de progresso imediato. Você resolve os problemas conforme eles aparecem.

Spec-Driven Development é o oposto. Antes de escrever a primeira linha de código, você para e define: o que precisa ser feito, como deve funcionar, quais são as regras, os limites, o que pode dar errado e como você vai saber quando está pronto de verdade.
No começo, os dois parecem igualmente produtivos. É no médio prazo que a história muda, e muda bastante.

O problema invisível do vibe coding

Imagina que você quer construir um sistema simples de controle de gastos pessoais. Você abre o Claude Code e digita:

"Crie um sistema que importe meus extratos bancários e mostre um gráfico dos meus gastos por categoria."

Em minutos, você tem algo funcionando. Parece mágica. Mas três meses depois, você quer adicionar uma nova funcionalidade: filtrar os gastos por período. Você volta pro Claude Code e pede a mudança. Ele faz, mas agora os gráficos quebram em datas antigas. Você pede pra corrigir os gráficos, ele corrige. Mas aí o filtro para de funcionar no mobile.

Vira uma bola de neve e é o pesadelo clássico de quem vibecoda além do protótipo. Cada correção cria um novo problema, porque o código foi construído sem estrutura definida. A IA não tem como saber o que você realmente queria, porque você mesmo nunca parou pra escrever isso. Você não tem um projeto, você tem um amontoado de código.

No curto prazo parece velocidade. No médio prazo vira retrabalho. No longo prazo, às vezes, vira reescrita do zero.

O que Spec-Driven Development muda na prática

A ideia é simples: antes de codar, escrever. Não um documento de 100 páginas, só as respostas pra quatro perguntas:

O que precisa ser feito?
Como deve funcionar?
Quais são os limites e as regras?
Como vou saber que está pronto?

Parece burocracia, mas na prática, é o que separa um projeto que você consegue evoluir de um que você tem medo de mexer. E a ferramenta pra isso é mais simples do que parece: arquivos .md (Markdown). São arquivos de texto com formatação básica que você cria dentro do seu projeto. Eles funcionam como o "manual de regras" que a IA vai consultar sempre que trabalhar no seu código.

Antes de abrir qualquer ferramenta, PESQUISE.

Uma das decisões mais importantes do seu projeto acontece antes de escrever uma linha de código: escolher as tecnologias que você vai usar (sua Stack).

Se você já domina uma linguagem de programação use ela, se não, pesquise. Use o Perplexity, o ChatGPT, o próprio Claude, descreva o que você quer construir e pergunte diretamente:

"Estou construindo um SaaS de controle financeiro, sou iniciante, quero algo com boa documentação e comunidade ativa. Quais linguagens de frontend e backend fazem sentido pra mim?"

Algumas perguntas que vão guiar essa escolha:

Linguagem de backend: Python é uma excelente porta de entrada tem sintaxe simples, comunidade enorme e serve pra quase tudo. Ruby é outra opção com foco em produtividade. Go é mais robusto para sistemas que precisam de alta performance. Node.js é interessante se você já conhece JavaScript.

Banco de dados: PostgreSQL é uma escolha sólida pra maioria dos projetos, gratuito, confiável e bem suportado pelas IAs. MySQL é outra opção popular. Se o seu projeto trabalha com dados menos estruturados, MongoDB pode fazer sentido.

Frontend: React domina o mercado e tem a maior comunidade. Vue é uma alternativa mais simples pra começar. Angular é mais opinionado, bom pra projetos maiores.

Não tente aprender tudo de uma vez. Escolha uma stack, pesquise se ela faz sentido pro seu projeto, e documente essa decisão no seu projeto.md. A IA vai executar muito melhor quando souber exatamente com o que está trabalhando.

O que são skills, e como elas vão te salvar não só no Claude Code.

No Claude Code, você pode criar arquivos .md com instruções permanentes para o seu projeto. Quando você referencia esses arquivos num prompt de forma implícita, o Claude os lê e segue as regras que você definiu sem você precisar repetir tudo toda vez. Esses arquivos são chamados de skills ou simplesmente arquivos de contexto do projeto.

Em outras ferramentas de desenvolvimento com IA (Antigravity, Codex, Zed...) Você pode ser implícito ao gerar um novo Prompt citando sua skill começando com @ @system_database.md, por exemplo. Ou procurar com instalar essas skills em seu projeto.

Pensa assim: é como contratar um desenvolvedor novo e entregar pra ele um documento com os padrões da empresa. Em vez de explicar tudo do zero em cada conversa, você escreve uma vez e reutiliza sempre.

Exemplo prático: suponha que você está construindo qualquer sistema que use banco de dados. Sem uma skill, você torce pra IA usar o mesmo padrão de nomenclatura de tabelas que ela usou semana passada. Com uma skill, você garante isso.

Um exemplo simples:

# system_database.md

## Nomenclatura de tabelas
- Segurança e login: prefixo sec_ (ex: sec_usuarios)
- Configurações do sistema: prefixo ctl_ (ex: ctl_configuracoes)
- Dados financeiros: prefixo fin_ (ex: fin_transacoes)

## Campos obrigatórios em toda tabela
Toda tabela deve ter os campos: created_by, modified_by, created_at, modified_at
Isso permite saber quem criou ou alterou cada registro e quando.

## Tipos de dados para valores monetários
- Dinheiro (ex: preço, saldo): número com 2 casas decimais
- Percentual (ex: desconto, juros): número com 4 casas decimais

## Chaves primárias
- Dados comuns: use INTEGER autoincremental
- Dados sensíveis (usuários, pagamentos): use UUID

Esse é um exemplo bem simples, quanto mais você documentar melhor e agora, no seu prompt, você escreve:

"Crie a tabela de transações financeiras seguindo @system_database.md"

O Claude lê o arquivo, entende os padrões e os aplica, automaticamente, consistentemente, toda vez.
Você pode criar quantas skills quiser para aspectos diferentes do projeto:

auth_patterns.md — regras de autenticação e login
ui_components.md — padrões visuais e de interface
error_handling.md — como tratar e registrar erros
api_standards.md — formato das rotas e respostas da API

Vamos usar um exemplo concreto pra deixar a diferença visual.

Cenário: você quer construir uma tela de login com email, senha e opção de entrar com Google.

Vibe-coding:

"Crie uma tela de login com email, senha e botão de entrar com Google."

Vai funcionar, mas você não sabe:

O que acontece depois de 10 tentativas de senha errada?
Onde o token de autenticação é guardado? É seguro?
O que o usuário vê se o Google estiver fora do ar?
Como isso se conecta com o resto do sistema?

A IA vai tomar essas decisões por você e pode tomar decisões ruins sem você perceber.

Spec-Driven:

"Crie o módulo de autenticação seguindo @auth_patterns.md e @system_database.md. Requisitos específicos desta tela:

Login com email/senha ou login via Google (OAuth2);

Após 5 tentativas erradas, bloquear o acesso por 15 minutos e mostrar mensagem clara para o usuário;
Mensagens de erro nunca devem revelar se o email existe no sistema (por segurança)

Feedback visual em menos de 1 segundo após o usuário clicar em entrar;

Se o login com Google falhar, mostrar mensagem de fallback e manter o login por email disponível."

Agora a IA sabe exatamente o que fazer e o que não fazer. Você tomou as decisões importantes antes de começar.

Por onde começar sem se perder

Se você é iniciante, não tente implementar tudo de uma vez. Comece pequeno:

Semana 1: Antes de qualquer projeto novo, crie um arquivo projeto.md com três parágrafos: o que você está construindo, pra quem é e o que ele não vai fazer (os limites são tão importantes quanto as funcionalidades).
Semana 2: Crie seu primeiro system_database.md com os padrões de banco de dados do projeto. Copie o exemplo deste artigo e adapte.
Semana 3: Quando um módulo específico ficar complexo (autenticação, pagamentos, relatórios), crie uma skill (.md) só pra ele, pode ser usando a própria ferramenta que você estiver usando (inclusive você pode criar uma skill ou buscar uma skill que já existe para documentar o projeto.), e LEIA.

Você vai errar, vai ajustar, vai refinar. Isso é normal. O importante é criar o hábito de pensar antes de executar.

Nesse ponto você pode pensar assim: "Eu não eu vou gastar tempo e tokens para criar uma documentação." Mas você deveria, isso vai te economizar muito mais tempo e muito mais tokens, acredite.

O vibe coding tem o seu lugar

Para ser honesto, vibe coding não é errado e é uma mão na roda, o problema é quando o "rapidinho" vira o produto. Quando o código que era pra durar uma semana fica dois anos em produção com usuários reais dependendo dele. Aí a conta chega.

A IA vai te ajudar a executar muito mais rápido do que qualquer dev conseguiria sozinho. Mas pra isso funcionar de verdade, pra você conseguir manter, escalar e evoluir o que construiu e o planejamento é o que faz a diferença.

Use o Perplexity e o ChatGPT pra pesquisar. Use o Claude pra escrever seus documentos e suas skills. Use o Claude Code, Cursor, Antigravity ou Lovable pra executar. Cada ferramenta tem seu momento.

O formato dos seus documentos, importa menos do que o hábito de criá-las. Comece com um arquivo de markdown (.md). Evolua conforme o projeto pede.
Uma vez que você experimenta construir com especificação, é difícil voltar pra qualquer outra forma.

Essa é minha primeira contribuição aqui, então me desculpem qualquer erro ou falta de precisão. Qualquer sugestão, dúvida ou crítica construtiva, deixa nos comentários. Vou responder tudo.