Vibe Coding: Os 4 Problemas e o Workflow em 5 Etapas que Resolve

Sem escopo explícito, o modelo preenche lacunas inventando decisões: nomes de funções que não existem, bibliotecas que não estão instaladas, padrões arquiteturais que conflitam com o restante do código. Quanto mais aberto o prompt, mais o modelo improvisa — e o que parecia uma solicitação simples vira uma feature com três camadas a mais do que se pediu.

O sintoma clássico é a duplicação: um componente de botão é criado em uma tela e, dias depois, um botão equivalente nasce em outra parte do projeto porque o agente não tinha mapa do que já existia. A manutenção passa a custar o dobro, e a base perde coerência visual e estrutural.

A raiz não é o modelo — é a ausência de escopo verificável. Sem descrição de páginas, componentes, comportamentos e fluxos, qualquer resposta é tecnicamente válida.

O resultado direto da alucinação é uma base de código cheia de puxadinhos: componentes paralelos com pequenas variações, utilitários redefinidos a cada feature, estilos repetidos porque ninguém centralizou os tokens. Cada nova alteração precisa ser feita em N lugares.

Esse tipo de débito não aparece nos primeiros sprints. Aparece no momento em que o projeto precisa escalar — quando uma mudança de design system, uma troca de provider ou uma regulação obriga a tocar dezenas de arquivos que deveriam ser um só. É nesse ponto que projetos vibe-coded costumam exigir reescrita parcial.

A correção é simples no conceito e custosa de implementar depois: tratar reaproveitamento como restrição antes de gerar código novo, não como refatoração futura.

Modelos de geração de código não têm modelo de ameaça. Eles produzem o que parece funcional dentro do contexto local: uma rota que retorna dados, um endpoint que aceita um payload, uma integração que consome uma API. Decisões de segurança — validação de input, escopo de tokens, rotação de credenciais, cabeçalhos de CORS, rate limiting — só aparecem se o desenvolvedor pedir explicitamente.

Os incidentes públicos seguem o mesmo padrão: chaves de API hardcoded no front-end, rotas administrativas sem autenticação, variáveis de ambiente versionadas no repositório, endpoints internos expostos pela ausência de filtro no gateway. Nenhum desses problemas exige conhecimento avançado para ser explorado — basta inspecionar o cliente.

Mitigação prática: tratar revisão de segurança como etapa obrigatória do fluxo, não como verificação opcional. Documentação como o OWASP Top 10 existe justamente para servir de checklist mínimo antes de qualquer deploy.

Modelos de linguagem têm uma janela de contexto finita — centenas de milhares a um milhão de tokens, dependendo da versão. Quando essa janela enche, o agente comprime a conversa: resume mensagens antigas, descarta trechos e passa a operar sobre uma versão lossy do histórico. A partir desse ponto, o modelo começa a assumir premissas em vez de consultar o que foi dito.

Na prática isso se manifesta como regressão silenciosa: uma decisão tomada três horas atrás é "esquecida", um padrão de nomenclatura combinado some, um arquivo gerado começa a divergir do que já existe. A eficiência cai justamente quando o projeto está mais maduro e o contexto acumulado vale mais.

A solução não é "conversar menos" — é externalizar o contexto. Documentação estruturada, specs e planos em arquivos permitem que o agente leia apenas o que precisa para a tarefa corrente, sem carregar todo o histórico. Esse é o mesmo princípio do prompt caching: estabilizar o que não muda para economizar leitura.

A primeira etapa gera um documento de especificação que cobre tudo que o agente precisa saber antes de tocar em código:

• Páginas — todas as telas que a funcionalidade vai expor.
• Componentes — elementos reutilizáveis presentes em cada página, com referência aos componentes já existentes na base.
• Behaviors — comportamento de cada interação relevante. "Se X acontece, o sistema responde com Y."
• User flows — sequências completas do usuário, do login ao caso de uso final.

A spec não nasce no agente. Nasce em um protótipo de média fidelidade, feito antes de qualquer prompt. Ferramentas de design como Figma servem para traduzir o problema visualmente — não como deliverable, mas como ancoragem para o documento. O agente recebe o protótipo já anotado e devolve a spec em formato estruturado, pronta para ser revisada.

É a etapa mais trabalhosa do fluxo e a que mais elimina alucinação. Sem ela, todas as etapas seguintes herdam ambiguidade.

Pedir para o agente implementar a spec inteira de uma vez é voltar ao vibe coding. A quantidade de decisões abertas é grande demais; o modelo escolhe atalhos e se desvia. A decomposição quebra a spec em unidades pequenas e verificáveis, agrupadas por bloco:

• Página + componentes viram uma tarefa de protótipo de front-end. Permite validar a interface em alta fidelidade antes de qualquer lógica.
• Behavior + user flow viram uma tarefa funcional. É onde regras de negócio, integrações e estado de fato são implementados.

O resultado são três blocos claros: protótipos, front-end e back-end, cada um com tarefas bem delimitadas. Cada tarefa tem entrada conhecida, saída esperada e critérios de aceite.

Antes de qualquer modificação, o agente faz uma varredura na base atual: quais arquivos são impactados, quais módulos compartilham responsabilidades com a tarefa, quais componentes podem ser reaproveitados e onde a mudança pode quebrar contratos existentes.

O entregável dessa etapa é um relatório de impacto — não código. O objetivo é ancorar o modelo no que já existe, eliminando o reflexo de criar componentes paralelos. Sem essa etapa, o problema 02 (código bagunçado) reaparece em todas as features.

Com a spec, a decomposição e o relatório de impacto em mãos, o agente produz um plano de implementação por escrito. O plano descreve, em etapas:

• arquivos que serão criados ou alterados;
• componentes reaproveitados versus novos;
• contratos de API e schemas tocados;
• ordem de execução das mudanças.

É o último checkpoint humano antes de qualquer linha de código de produção. Revisar um plano custa minutos; revisar um pull request com 40 arquivos alterados custa horas. Quando o plano está errado, é mais barato refazer o documento do que descartar uma implementação.

Plano aprovado, uma skill de implementação executa cada etapa em ordem, sem improvisar. A cada bloco entregue, o agente emite um conjunto de casos de teste manuais — passos reproduzíveis que o desenvolvedor humano percorre para validar comportamento. Se um caso falha, o agente corrige; se passa, segue para o próximo bloco.

Esse loop fecha o ciclo: a IA não declara a tarefa como concluída — quem declara é a validação. É a aplicação prática do princípio de evidence before assertion: nenhuma etapa é dada como pronta sem prova reproduzível.