Desenvolvimento Orientado por Especificações vs. Vibe Coding: Waterfall?

Especificações como fonte de verdade, ou cerimônia lenta?

Conteúdo da página

O Desenvolvimento Orientado por Especificação (Spec-Driven Development) entrou em 2026 como a resposta séria dos desenvolvedores ao desvio do “vibe coding”.

O argumento é simples: agentes de IA produzem resultados melhores e mais consistentes quando implementam com base em uma especificação revisada, em vez de um prompt ad hoc. Dificilmente se pode argumentar contra isso em teoria.

Na prática, o Hacker News chamou isso de “O Retorno do Waterfall”.

Ambos os lados têm razão.

Desenvolvimento Orientado por Especificação versus Vibe Coding

O Caso do SDD em um Mundo de Vibe Coding

Vibe coding – a prática de escrever um prompt amplo e iterar sobre o que o agente de IA produz – funciona notavelmente bem para trabalhos pequenos, exploratórios e descartáveis. Nos primeiros seis meses de 2025, foi o padrão dominante de codificação com IA. Os desenvolvedores entregaram scripts, protótipos e ferramentas simples mais rápido do que nunca.

Em seguida, os projetos cresceram. Recursos multi-arquivo começaram a se desviar. Restrições estabelecidas na sessão um foram esquecidas na sessão três. Suposições de segurança foram descartadas. Decisões arquiteturais mudaram no meio do recurso porque o agente não tinha memória durável da intenção.

O Desenvolvimento Orientado por Especificação (SDD) surgiu como a resposta disciplinada. A tese central: torne a especificação o artefato central, não o prompt. Escreva requisitos, um design e um plano de tarefas primeiro. Permita que o agente implemente contra esses artefatos, fatia por fatia. Mantenha a especificação versionada e atualizada.

Ferramentas de codificação com IA – GitHub Spec Kit, Kiro, BMAD e um conjunto crescente de fluxos de trabalho personalizados do Claude Code – são todas implementações dessa ideia. As ferramentas são reais. O interesse é real. A reação negativa também é real.

No Que o Vibe Coding é Bom

Antes de descartar o vibe coding, vale a pena ser preciso sobre o que ele faz bem.

Protótipos exploratórios. Quando você não tem certeza do que quer construir, o caminho mais rápido é construir algo rascunhado e reagir a ele. O SDD exige saber o que especificar. Se você ainda não sabe, as especificações são prematuras.

Experimentos de UI. Layout visual e sensação de interação são difíceis de especificar antecipadamente. O vibe coding permite ver opções rapidamente, descartar a maioria delas e convergir para algo que realmente parece certo. Um documento de requisitos não ajuda aqui.

Automação descartável. Scripts únicos, trabalhos de extração de dados, ajudantes de migração – estes raramente precisam de um documento de design. O custo de errar ligeiramente é baixo. O custo de um processo lento e cerimonial é real.

Feedback rápido. Quando você precisa aprender algo rapidamente – essa API funciona como eu acho que funciona? – o vibe coding reduz o ciclo de aprendizado a minutos. O SDD retardaria isso sem benefício algum.

O erro é levar os padrões de sucesso desses contextos e aplicá-los a recursos de produção com restrições reais, usuários reais e consequências reais para errar.

Onde o Vibe Coding Falha

O vibe coding degrada-se de forma previsível à medida que o escopo e as apostas aumentam.

Alterações em múltiplos arquivos. Assim que um recurso toca cinco ou mais arquivos, a janela de contexto do agente começa a perder o controle dos invariantes. Sem um documento de design, cada prompt precisa reestabelecer o contexto que foi estabelecido e esquecido em uma sessão anterior.

Deriva arquitetural. Sem objetivos não-alvo explícitos, os agentes implementam coisas. O agente adiciona uma camada de cache porque parece razoável. Três sessões depois, a suposição de cache está embutida no modelo de dados e removê-la é caro.

Restrições esquecidas. “Apenas usuários autenticados podem acionar isso” é uma frase em um documento de requisitos. Em uma sessão de vibe coding, é algo que você mencionou uma vez na sessão um e o agente não lembra na sessão quatro quando escreve o novo endpoint.

Suposições de segurança ocultas. Regras de autorização, limites de validação de entrada, manipulação de segredos – estes são exatamente o tipo de requisitos implícitos que passam despercebidos quando o agente está otimizando para código funcional plausível, em vez de código correto e restrito.

Transição de equipe. Se você construiu por meio de prompting iterativo, o artefato que registra o que foi decidido e por quê é… o log do git. Boa sorte com isso.

O Que o Desenvolvimento Orientado por Especificação Muda

O SDD não afirma eliminar a iteração. As boas versões do SDD são explicitamente iterativas. O que elas mudam é onde a iteração acontece. Para a definição completa – incluindo como o SDD difere do TDD, BDD e métodos formais – veja O Que é Desenvolvimento Orientado por Especificação?

Em vez de iterar no código e inferir a intenção a partir das diferenças (diffs), você itera na especificação e então implementa. A especificação torna-se o artefato que registra o que foi decidido, por quê, e o que está fora do escopo – servindo uma função semelhante a Registros de Decisão Arquitetural mas orientada para a intenção do recurso em vez de escolhas em nível de sistema. O código implementa essa intenção.

Um fluxo de trabalho típico do SDD passa por cinco fases:

Especificar. Declaração do problema, usuários, objetivos, não-objetivos, critérios de aceitação, questões em aberto.

Planejar. Decisões arquiteturais, módulos afetados, modelo de dados, contratos de API, preocupações de segurança, estratégia de teste.

Decomposição de tarefas. Fatias pequenas de implementação com critérios de validação explícitos e pontos de verificação humana.

Implementar. Uma tarefa por vez, com reinício de contexto entre tarefas, aplicando restrições da especificação e atualizando o plano quando a realidade difere do design.

Validar. Testes, lint, verificações de tipo, critérios de aceitação, diferença entre especificação e código.

O agente participa da maioria das fases – rascunhando a especificação, gerando o design, propondo tarefas – mas os humanos revisam os artefatos antes que a implementação comece. Essa etapa de revisão é a diferença central entre SDD e vibe coding.

Por Que os Desenvolvedores Chamam Isso de Waterfall

A crítica ao waterfall não está errada. Ela apenas visa um SDD ruim, não o SDD em si.

O modo de falha específico é o planejamento extenso antecipado. A característica definidora do waterfall é um loop de feedback que se estende por semanas ou meses: fase de requisitos, fase de design, fase de construção, fase de teste, lançamento. O feedback chega tarde. Quando você descobre que a suposição de design estava errada, você já construiu sobre ela por semanas.

Quando um desenvolvedor usa o Spec Kit e gera uma lista de tarefas de 200 linhas antes de escrever uma única linha de código, e depois passa dois dias polindo o documento de requisitos antes que o agente toque em qualquer coisa, isso é waterfall. É waterfall com markdown em vez de UML, mas o modo de falha é idêntico.

Um comentarista do HN descreveu o uso do Spec Kit para uma pequena ferramenta CLI e encontrou-a “demais lenta, demais ajustes antes de ver o código.” Essa é a versão ruim. Esse usuário estava certo em rejeitá-la para aquela tarefa.

A crítica útil não é “especificações são ruins”. É “planejamento antecipado longo antes do feedback é ruim”. São afirmações diferentes.

O Terceiro Caminho Útil

Um bom SDD evita a armadilha do waterfall mantendo a especificação pequena e iniciando a implementação cedo.

Especificações pequenas. Um documento de requisitos para um único recurso deve caber em uma tela. Se a especificação tem dez páginas, é либо um design de plataforma ou precisa ser dividida em recursos menores. Especificações muito grandes levam muito tempo para revisar e ficam obsoletas rapidamente.

Fatias de tarefas curtas. Cada tarefa deve ser implementável em uma única sessão do agente, revisável como uma pequena diferença (diff) e testável isoladamente. Se as tarefas forem muito grandes, o loop de implementação se estende e o mapeamento especificação-código torna-se difícil de verificar.

Implementação precoce. Especifique a primeira tarefa, implemente-a, valide-a e, em seguida, avance para a próxima tarefa. Não especifique tudo antes de implementar qualquer coisa. A primeira implementação revelará coisas que sua especificação errou. Atualize a especificação antes de continuar.

Especificação viva. Quando a realidade difere do design – e diferirá – atualize a especificação, não apenas o código. A especificação só é útil se refletir o que foi realmente construído.

Testes como feedback executável. Cada critério de aceitação deve mapear para pelo menos um teste. A suíte de testes é a versão legível por máquina da especificação. Se a especificação diz “apenas usuários autenticados podem acionar isso”, deve haver um teste que verifique se solicitações não autenticadas são rejeitadas.

Este híbrido – especificações pequenas, tarefas curtas, implementação precoce, documentos vivos – é o que realmente funciona. Não é vibe coding e não é waterfall. É iteração controlada com artefatos duráveis.

Quando o SDD Vence o Vibe Coding

Use o SDD – mesmo um SDD leve – quando o custo de errar for real.

Lógica de negócio arriscada. Cobrança, permissões, migrações de dados, idempotência – qualquer lógica onde comportamento incorreto seja caro ou difícil de reverter. O vibe coding deixa esses tipos de requisitos implícitos. O SDD os torna explícitos e revisáveis antes da implementação.

Alterações de API em produção. Qualquer alteração em um contrato de API pública ou interna deve ter um documento de design. O documento de design é o que você revisa antes que o agente escreva código que quebre os chamadores.

Fluxos de trabalho multi-agente. Quando múltiplos agentes estão implementando partes diferentes de um recurso, a especificação é a fonte de verdade compartilhada. Sem ela, cada agente otimiza localmente e as peças podem não se encaixar.

Transição de equipe. Se outro desenvolvedor ou outro agente continuar este trabalho, a especificação é o artefato de transição. Um log do git e um README não são suficientes.

Refatorações significativas. Refatorações que tocam abstrações centrais precisam de uma declaração explícita do que deve permanecer o mesmo (comportamento) e do que está permitido mudar (estrutura). Sem isso, o agente pode quebrar contratos que você pensou que estavam preservados.

Quando o Vibe Coding Ainda é Melhor

O SDD é sobrecarga. Às vezes, a sobrecarga não vale a pena.

Scripts rápidos. Um script de 50 linhas para renomear arquivos ou transformar JSON não precisa de um documento de requisitos. Escreva o prompt, verifique a saída, entregue-o.

Experimentos. Se você está aprendendo se uma abordagem é viável – explorando uma API, testando uma biblioteca, validando uma hipótese – você precisa de velocidade, não de estrutura. Experimente primeiro, especifique se o experimento tiver sucesso.

Rascunhos de UI. O design de interação se beneficia de ver em vez de especificar. Construa várias variações rascunhadas rapidamente, reaja ao que você vê e especifique apenas o que você realmente vai entregar.

Automação descartável. Scripts únicos, importações de dados, ajudantes de migração – o custo de um resultado ligeiramente errado geralmente é baixo, e o artefato será excluído após o uso de qualquer maneira.

Protótipos solo. Se você é a única pessoa que verá este código e o objetivo é aprendizado em vez de produção, o vibe coding é mais rápido e as desvantagens são contidas.

Um Framework de Decisão Simples

A questão prática não é “SDD ou vibe coding?”. É “quanta especificação eu preciso para esta tarefa específica?”

Use vibe coding quando:

  • A tarefa leva menos de um dia
  • Você está explorando ou aprendendo
  • O artefato é descartável ou de baixo risco
  • Você é a única pessoa que tocará nisso
  • A velocidade de feedback importa mais do que a correção

Use SDD leve quando:

  • A tarefa leva dois ou mais dias
  • Múltiplos arquivos são afetados
  • Existem requisitos explícitos de segurança ou correção
  • Outra pessoa ou agente continuará o trabalho
  • Você precisa escrever testes que mapeiem para requisitos

Use SDD completo quando:

  • O recurso toca uma interface pública ou contrato de dados
  • Múltiplos agentes ou membros da equipe estão envolvidos
  • A organização exige uma revisão de design antes da implementação
  • Conformidade ou trilhas de auditoria são necessárias

O erro mais comum é aplicar SDD completo a tarefas que só precisam de SDD leve, e aplicar nenhuma especificação a tarefas que precisam de pelo menos uma leve.

Um SDD ruim é waterfall com markdown. Um bom SDD é iteração controlada com artefatos duráveis. O vibe coding é a ferramenta certa para as tarefas certas – e a ferramenta errada para as erradas. Conhecer a diferença é a habilidade.

Assinar

Receba novos artigos sobre sistemas, infraestrutura e engenharia de IA.