Especificação primeiro, prompt depois

Existe um jeito de usar IA para programar que virou popular o suficiente para ganhar nome: vibe coding. Descrever o que se quer em linguagem natural, deixar o modelo gerar o código, rodar, ver se quebra, pedir para ajustar, repetir. Funciona muito bem para prototipar algo pequeno rápido. E desmonta, de forma bem previsível, assim que o projeto cresce.

Por que vibe coding não escala

Um projeto pequeno cabe inteiro na cabeça de quem está escrevendo, e, por extensão, cabe razoavelmente dentro do contexto que se consegue passar para um modelo numa conversa. Um projeto grande não cabe. Ele tem decisões de arquitetura tomadas há meses, convenções que existem por motivo que não está escrito em lugar nenhum, código que depende de comportamento específico de outra parte do sistema que não está visível no arquivo aberto.

Quando o pedido para a IA é só “faça essa funcionalidade”, sem contrato explícito do que ela precisa respeitar, o resultado tende a ser plausível localmente e errado globalmente: código que funciona isolado mas quebra uma convenção do projeto, duplica algo que já existia, ou ignora uma regra de negócio que só estava na cabeça de quem pediu.

O que é spec-driven design

A alternativa é inverter a ordem: escrever a especificação antes de pedir o código, e usar essa especificação como contrato, tanto para guiar o modelo quanto para julgar o resultado depois. Isso não é burocracia nova inventada para a era da IA, acaba sendo, na prática, retomar uma disciplina antiga (escrever o que se quer antes de escrever como fazer) que muitos times relaxaram exatamente porque escrever prompt parecia mais rápido que escrever spec.

Uma especificação útil, nesse contexto, não precisa ser um documento formal de dezenas de páginas. Pode ser curta e ainda assim eficaz, desde que responda ao essencial: o que a funcionalidade precisa fazer, o que ela explicitamente não deve fazer, quais casos de borda importam, e que comportamento observável prova que está correta.

Onde o contexto entra

Duas peças resolvem boa parte do problema de “a IA não sabe as convenções do projeto”:

• Arquivo de instruções do repositório. Um arquivo na raiz do projeto, com instruções de estilo, decisões de arquitetura, comandos de build e teste, e armadilhas conhecidas. Isso dá ao modelo o contexto que normalmente só existe na cabeça de quem está no time há tempo. Sem isso, cada sessão de IA começa do zero, reaprendendo (ou errando) as mesmas coisas.
• Testes como especificação executável. Um conjunto de testes que descreve o comportamento esperado é uma especificação que a própria máquina consegue verificar, sem depender de leitura humana atenta. Pedir para o modelo trabalhar com testes escritos antes, ou juntos, a implementação dá um critério objetivo de “terminou” que uma conversa em linguagem natural sozinha não dá.

Revisão do código gerado

Código gerado por IA continua sendo código, e código continua precisando de revisão. O risco específico aqui é um tipo de revisão superficial: ler o diff, achar que “parece certo”, aprovar. Código gerado tende a ser sintaticamente limpo e estruturalmente convincente mesmo quando está semanticamente errado, o modelo não hesita, não parece inseguro, e isso engana o olho de quem revisa rápido.

Revisão séria de código de IA cobra as mesmas perguntas de sempre, só que sem o desconto de confiança que se daria a um colega: esse código cobre o edge case que a spec pedia? Ele duplica alguma lógica que já existia em outro lugar do projeto? A parte que “só funciona”, funciona por que motivo, e esse motivo faz sentido?

O que continua sendo trabalho humano

Nenhuma dessas práticas terceiriza a parte que mais importa: decidir o que construir, e por quê. Escrever a especificação é trabalho de entender o problema, e a IA pode ajudar a redigir, mas não substitui alguém pensando sobre qual comportamento é o certo. Julgar se o resultado está correto, continua exigindo alguém que entenda o domínio, não só a sintaxe.

O risco real para quem é júnior

Vale ser direto sobre isso: existe risco concreto de aprender menos programando com IA de forma descuidada. Se toda dificuldade é resolvida pedindo para o modelo gerar a solução, sem tentar entender por que aquela solução funciona, o efeito prático é pular a parte do aprendizado que só vem de errar e debugar sozinho. Isso não é hipotético nem exclusivo de IA, sempre existiu quem copia de Stack Overflow sem entender, mas a fluência e a velocidade da IA tornam esse atalho mais tentador e mais fácil de repetir sem perceber.

Um jeito prático de evitar isso, sem abrir mão da ferramenta: usar a IA para gerar uma primeira versão, mas depois explicar o código gerado de volta, linha por linha, como se fosse ensinar para outra pessoa. Se alguma parte não dá para explicar, é sinal de que ela foi aceita sem ser entendida, e vale investigar antes de seguir. Outro hábito útil é escrever a especificação e os testes você mesmo, mesmo quando o código vem do modelo: essa parte é onde o entendimento do problema realmente se forma, e é a parte mais fácil de pular sem perceber que pulou.

A ferramenta não é o problema. O problema é usá-la para evitar a dificuldade, em vez de usá-la para passar por ela mais rápido e mantendo o entendimento no caminho.