Vibe coding e spec-driven development: quando usar cada um
A escolha entre vibe coding e spec-driven development decide se a velocidade da IA vira produto ou dívida técnica. Neste artigo, comparamos as duas abordagens e mostramos por que a especificação devolve previsibilidade ao trabalho com agentes.
O que diferencia vibe coding e spec-driven development
Em poucas palavras, vibe coding e spec-driven development divergem sobre onde mora a fonte da verdade. No primeiro caso, ela vive no histórico de uma conversa com o agente.
No segundo, ela vive em arquivos versionados que descrevem o comportamento esperado antes de qualquer linha de código. Por isso, a diferença não está na ferramenta, e sim no contrato que guia a geração.
Os dois modelos usam os mesmos agentes, como GitHub Copilot, Claude Code ou Cursor. Contudo, cada um coloca o desenvolvedor em um papel distinto: explorador em um caso, arquiteto e revisor no outro.
Entender essa diferença evita uma armadilha comum. Muita gente acredita que basta trocar de ferramenta para sair do improviso, quando na verdade o que muda é o processo.
Por que o vibe coding conquistou os desenvolvedores
Andrej Karpathy batizou a prática em fevereiro de 2025. Na ocasião, ele descreveu um jeito de programar em que você se entrega ao fluxo e esquece que o código existe.
A ideia pegou tão rápido que o Collins Dictionary elegeu o termo como palavra do ano de 2025. Em poucos meses, ferramentas como Lovable, Bolt, Replit Agent e Cursor transformaram a prática em rotina para milhões de pessoas.
O apelo é fácil de entender. Você descreve o que quer em linguagem natural, o agente gera o código, e então você testa e pede ajustes até o resultado parecer certo.
Além disso, a barreira de entrada praticamente desaparece. Pessoas sem formação técnica conseguem colocar uma ideia de pé em uma tarde, algo impensável há poucos anos.
Onde a geração exploratória brilha
Na prática, o vibe coding brilha quando o custo de errar é baixo. Protótipos, provas de conceito, scripts descartáveis e demos para validar hipóteses se encaixam bem nesse perfil.
Nesses cenários, descobrir o que você realmente quer construir importa mais do que a qualidade interna do código. Assim, tocar em algo funcionando, ainda que tosco, acelera o aprendizado sobre o problema.
Também vale lembrar que explorar é uma etapa legítima, e nenhuma comparação entre vibe coding e spec-driven development deveria ignorar isso. O problema começa quando o protótipo vira produção sem que ninguém perceba a transição.
O custo escondido do vibe coding em repositórios complexos
Em um repositório pequeno e novo, quase tudo funciona. Entretanto, o cenário muda quando o projeto acumula módulos, regras de negócio implícitas e anos de decisões arquiteturais.
O agente não carrega essas decisões consigo entre uma conversa e outra. Ele enxerga apenas o contexto que cabe na janela atual, e o restante simplesmente deixa de existir para ele.
É aqui que a comparação entre vibe coding e spec-driven development deixa de ser teórica. Quanto maior o repositório, maior o preço de depender da memória de uma sessão de chat.
Deriva de intenção e perda de contexto
Cada novo prompt corrige um detalhe e, sem querer, desloca outro. Com isso, a distância entre o que você pretendia e o que o código faz cresce a cada iteração.
Alguns autores chamam esse fenômeno de deriva de intenção. Ele aparece de formas bem concretas, como um segundo serviço de autenticação criado porque o agente não encontrou o primeiro.
Outro exemplo clássico é a validação duplicada em camadas diferentes. Cada cópia evolui de um jeito, e logo a mesma regra passa a ter três comportamentos distintos.
Além disso, no vibe coding o requisito nunca fica em lugar durável, ao contrário do spec-driven development. Quando alguém precisa entender por que uma regra existe, a única pista é um chat que talvez nem esteja mais acessível.
Por fim, surge a dívida de compreensão. O código funciona, mas ninguém do time sabe explicar como, e isso só fica evidente durante um incidente em produção.
O que os dados mostram sobre manutenção
Os números confirmam a intuição. Uma pesquisa da GitClear com a GitKraken analisou 623 milhões de alterações de código entre 2023 e 2026.
Segundo o levantamento divulgado pela LeadDev, a duplicação cresceu 81% e o reuso caiu 70% em relação ao período anterior à IA. O mesmo estudo indica que commits assistidos por IA já representam cerca de um quarto de todos os commits.
Portanto, o problema deixou de ser marginal. Ele já afeta a base de código de muitas empresas, inclusive daquelas que nunca adotaram o vibe coding de forma oficial.
Outro dado incômodo vem do METR. Em um experimento controlado com 16 desenvolvedores experientes e 246 tarefas reais, quem usou IA levou 19% mais tempo para concluir o trabalho.
Curiosamente, esses mesmos profissionais esperavam ganhar cerca de 24% de velocidade. Ou seja, a sensação de produtividade e a produtividade real podem andar em direções opostas em bases de código maduras.
Um dos fatores apontados é o conhecimento implícito do repositório. Como o agente não acessa essas regras não documentadas, o desenvolvedor gasta tempo revisando, corrigindo e explicando o que o projeto já sabia.
Em resumo, a diferença entre vibe coding e spec-driven development aparece justamente nesse conhecimento implícito. Quando ele vive só na cabeça das pessoas, o agente adivinha, e adivinhação em escala vira dívida técnica.
Spec-driven development como resposta madura ao vibe coding
A resposta da comunidade foi mover a fonte da verdade para fora do chat. Nesse modelo, a especificação vem primeiro, e o código passa a ser a implementação dessa especificação.
Essa ideia não é nova. Test-Driven Development e Behavior-Driven Development já defendiam escrever a intenção antes da implementação, mas os agentes de IA tornaram a prática muito mais barata.
Afinal, o trabalho pesado de transformar intenção em plano e tarefas agora cabe ao agente. Enquanto isso, o humano mantém o controle sobre o que deve ser construído e sobre a revisão do resultado.
Em outras palavras, vibe coding e spec-driven development usam a mesma velocidade de geração. A diferença é que, no segundo modelo, essa velocidade trabalha a favor de um contrato explícito e revisável.
Os três níveis de rigor da especificação
Um artigo publicado no arXiv organiza as abordagens em três níveis de rigor. Essa classificação ajuda a entender que adotar especificações não significa adotar burocracia.
- Spec-first: a especificação guia a implementação inicial e depois perde relevância.
- Spec-anchored: a especificação evolui junto com o código e continua sendo verificada.
- Spec-as-source: a especificação é o único artefato que humanos editam, e o agente gera o código a partir dela.
Na maioria dos times, o ponto de partida realista é o spec-anchored. Dessa forma, a especificação deixa de ser documentação morta e passa a funcionar como referência viva para cada mudança.
Esse detalhe importa porque spec-first sozinho tende a envelhecer rápido. Se ninguém atualiza a spec depois da primeira entrega, o time volta ao improviso em poucas semanas.
Como o Spec Kit organiza o fluxo de trabalho
O Spec Kit é um toolkit open source da GitHub, sob licença MIT, que transforma a especificação em comandos concretos. Ele funciona com diversos agentes, incluindo o GitHub Copilot no VS Code.
Para quem vem do vibe coding, ele é a porta de entrada mais simples para o spec-driven development.
A instalação usa o uv, e a inicialização cria a pasta .specify com templates, scripts e a memória do projeto.
# instala a CLI do Spec Kit
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# cria um novo projeto usando o GitHub Copilot como agente
specify init orders-api --ai copilot
Depois disso, o fluxo segue uma sequência de comandos no chat do agente. Cada comando produz um artefato versionado que alimenta o próximo passo.
| Comando | Artefato gerado | Papel no fluxo |
|---|---|---|
/speckit.constitution |
constitution.md |
Define os princípios inegociáveis do projeto |
/speckit.specify |
spec.md |
Descreve a funcionalidade em termos de produto |
/speckit.clarify |
spec.md refinada |
Resolve ambiguidades antes do plano técnico |
/speckit.plan |
plan.md, data-model.md, contracts/ |
Desenha a solução técnica |
/speckit.tasks |
tasks.md |
Quebra o plano em tarefas ordenadas |
/speckit.implement |
Código e testes | Executa as tarefas e valida cada etapa |
Repare que só o último comando escreve código de produção. Todos os anteriores existem para que, quando o agente começar a implementar, ele já saiba exatamente o que construir e quais limites respeitar.
A constituição como guarda arquitetural
O arquivo .specify/memory/constitution.md é o coração da governança. Nele, o time registra regras que nenhuma funcionalidade pode violar, como padrões de arquitetura, estratégia de testes e contratos de erro.
# Orders API Constitution
## Core Principles
### I. Clean Architecture
The Domain project MUST NOT reference infrastructure packages.
### II. Test-First
Every acceptance scenario MUST have an automated test before implementation.
### III. Error Contract
Every HTTP error MUST return a ProblemDetails payload (RFC 9457).
O plano gerado pelo /speckit.plan começa com uma verificação de conformidade contra essa constituição. Se o desenho técnico quebrar algum princípio, o processo para antes que o agente escreva qualquer código.
É exatamente aqui que vibe coding e spec-driven development se separam de vez. Enquanto o chat esquece decisões, a constituição as reaplica em toda nova funcionalidade, com o mesmo rigor.
Na prática, isso resolve o problema da coerência arquitetural entre sessões. O agente da segunda-feira e o agente da sexta-feira leem as mesmas regras, mesmo que nunca tenham visto a conversa um do outro.
Da especificação às tarefas verificáveis
A especificação descreve o comportamento em cenários testáveis. Um trecho típico do spec.md fica assim:
### User Story 1 - Create an order (Priority: P1)
**Acceptance Scenarios**:
1. **Given** a customer with an empty cart, **When** they submit an order,
**Then** the API returns 400 with the message "Order must contain at least one item."
2. **Given** a cart with valid items, **When** they submit an order,
**Then** the API returns 201 with the order id.
Como cada cenário é verificável, ele vira teste automatizado com naturalidade. Em um projeto .NET 10, o primeiro cenário poderia gerar o teste abaixo.
public class CreateOrderTests
{
[Fact]
public void Should_reject_order_without_items()
{
// cenário 1 da spec.md: pedido sem itens deve ser rejeitado
var result = Order.Create(customerId: Guid.NewGuid(), items: []);
Assert.False(result.IsSuccess);
Assert.Equal("Order must contain at least one item.", result.Error);
}
}
Assim, a especificação deixa de ser um texto bonito e passa a controlar o que entra no repositório. Se a spec não bloqueia nada, você não pratica spec-driven development: continua no vibe coding, apenas com etapas extras.
Por sua vez, o tasks.md agrupa o trabalho por história de usuário e marca com [P] o que pode rodar em paralelo. Com isso, o agente implementa em fatias pequenas e revisáveis, em vez de uma mudança gigante e opaca.
Vale um alerta honesto, porém. O Thoughtworks Technology Radar observou que algumas ferramentas geram especificações longas e difíceis de revisar, então mantenha cada spec enxuta e focada em uma funcionalidade.
Vibe coding e spec-driven development lado a lado
A tabela abaixo resume as diferenças mais relevantes para quem mantém software em produção.
| Critério | Vibe coding | Spec-driven development |
|---|---|---|
| Fonte da verdade | Histórico do chat | Especificação versionada |
| Velocidade inicial | Muito alta | Alta, depois de revisar a spec |
| Previsibilidade | Baixa, resultado probabilístico | Alta, resultado verificável |
| Coerência arquitetural | Depende do contexto da sessão | Protegida pela constituição |
| Governança | Revisão reativa | Gates antes da implementação |
| Trabalho em equipe | Difícil de compartilhar | Artefatos revisáveis em pull request |
| Melhor uso | Protótipos e exploração | Produto que terá manutenção |
Note que vibe coding e spec-driven development não aparecem como rivais na tabela. Na verdade, cada um otimiza uma métrica diferente.
O primeiro reduz o tempo até a primeira versão funcionando. Já o segundo reduz o custo total de manter o sistema ao longo dos anos.
Determinismo, aqui, não significa que o modelo responde sempre igual. Significa que o comportamento esperado está escrito, revisado e verificado, então qualquer desvio aparece como falha, não como surpresa.
Da mesma forma, governança não significa aprovação em cinco níveis hierárquicos. Significa que constituição, spec e plano passam pelo mesmo pull request que o código, e a revisão acontece onde o time já trabalha.
Quando usar vibe coding e quando adotar spec-driven development
A decisão depende menos do gosto pessoal e mais do custo de errar. Usar spec-driven development em um script descartável é tão equivocado quanto aplicar vibe coding em um sistema de pagamentos.
Prefira a geração exploratória nestes casos:
- o código vai para o lixo depois de validar uma hipótese;
- você ainda não sabe o que quer construir e precisa explorar;
- o projeto é pessoal, pequeno e sem usuários reais.
Por outro lado, adote a especificação nestes casos:
- o sistema vai para produção e terá manutenção por anos;
- várias pessoas ou vários agentes trabalham no mesmo repositório;
- existem regras de negócio, compliance ou segurança envolvidas;
- a arquitetura precisa permanecer coerente entre funcionalidades.
Vale lembrar também que o custo da especificação caiu muito. Afinal, o próprio agente redige o rascunho da spec, do plano e das tarefas, e o seu papel é revisar e decidir.
Por isso, o argumento de que spec-driven development atrasa a entrega em relação ao vibe coding perdeu força. Quinze minutos revisando uma spec costumam economizar horas de retrabalho depois que o código chega à produção.
Um fluxo híbrido entre vibe coding e spec-driven development na prática
Muitos times combinam vibe coding e spec-driven development em vez de escolher um só. O segredo está em tornar explícito o momento da transição entre explorar e construir.
- Explore a ideia livremente em um branch ou repositório descartável.
- Registre o que aprendeu como especificação com o comando de specify.
- Descarte o protótipo, ou use-o apenas como referência visual.
- Gere plano e tarefas, revise os gates da constituição e só então implemente.
O passo três costuma doer, mas é o mais importante. Código de protótipo carrega as decisões apressadas da exploração, enquanto a implementação guiada pela spec nasce alinhada ao projeto.
Em projetos existentes, o caminho é parecido. Primeiro, você escreve a constituição a partir das regras que o time já segue e, em seguida, aplica o fluxo a cada nova funcionalidade.
Não é preciso especificar o sistema inteiro de uma vez. Ao contrário, cada nova funcionalidade entra pelo fluxo completo, e o legado ganha especificações aos poucos, conforme alguém precisa mexer nele.
Para entender melhor como os agentes raciocinam e por que o contexto pesa tanto nessa dinâmica, leia o artigo O que são Agents? aqui no blog. Ele explica o ciclo de observação, raciocínio e ação que está por trás de todas essas ferramentas.
Conclusão sobre vibe coding e spec-driven development
O entusiasmo com a geração exploratória é legítimo, porque ela encurtou o caminho entre ideia e software funcionando. Contudo, a mesma velocidade cobra juros altos quando o protótipo vira produto sem que ninguém escreva o que ele deveria fazer.
Nesse sentido, vibe coding e spec-driven development representam fases diferentes de maturidade, e não lados de uma disputa. Explore com liberdade, mas leve para produção apenas o que estiver especificado, planejado e verificado.
Com o Spec Kit, a constituição e os gates de revisão, você mantém determinismo, governança e coerência arquitetural. Ao mesmo tempo, continua aproveitando toda a velocidade que os agentes oferecem.
FAQ
Vibe coding é sempre uma má prática?
Não. Ele funciona muito bem para protótipos, provas de conceito e ferramentas descartáveis, desde que o resultado não vá para produção sem revisão.
Spec-driven development deixa o desenvolvimento mais lento?
O início fica um pouco mais lento, porque você revisa a especificação antes do código. Em compensação, o retrabalho cai, e o agente redige boa parte dos artefatos.
Preciso do Spec Kit para aplicar spec-driven development?
Não. O Spec Kit é uma das opções, ao lado de ferramentas como Kiro e OpenSpec, e o essencial é manter uma especificação versionada que guie e valide o código.
O que é a constituição no Spec Kit?
É o arquivo constitution.md com os princípios inegociáveis do projeto. O plano de cada funcionalidade passa por uma verificação contra esses princípios antes da implementação.
Dá para usar spec-driven development em um projeto existente?
Sim. Você escreve a constituição a partir das regras que o time já segue e aplica o fluxo a cada nova funcionalidade, sem precisar especificar o sistema inteiro de uma vez.