Spec-driven development ou vibe coding: quando usar cada abordagem?

Escolher entre improvisar com a IA e escrever uma especificação antes de codar não é briga de torcida, é cálculo de risco

Fala aí, beleza? As duas abordagens já têm nome, ferramenta e limite documentado: de um lado o vibe coding, batizado pelo Andrej Karpathy e eleito palavra do ano de 2025 pelo dicionário Collins; do outro o spec-driven development, com toolkit open source mantido pela própria GitHub

O que quase ninguém fala é QUANDO cada um faz sentido

É isso que a gente resolve aqui: a origem dos dois termos, uma comparação direta, os cenários em que cada abordagem ganha e, no fim, um critério de uma pergunta só pra você decidir na próxima tarefa 🙂

O que é vibe coding (e o que Karpathy realmente disse)

O termo nasceu num post do Karpathy no X

A definição dele é literalmente essa: "There’s a new kind of coding I call ‘vibe coding’, where you fully give in to the vibes, embrace exponentials, and forget that the code even exists"

E tem a parte que todo mundo esquece de citar: "I ‘Accept All’ always, I don’t read the diffs anymore"

Ou seja: aceitar tudo, não ler mais os diffs, esquecer que o código existe

Agora se liga no detalhe que sumiu do hype: no MESMO post ele delimitou o uso, dizendo que a prática é "not too bad for throwaway weekend projects", ou seja, projetos descartáveis de fim de semana

O recado original nunca foi "faça sua startup assim"

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

A palavra do ano e a virada de chave

O Collins elegeu vibe coding como palavra do ano de 2025

É o carimbo cultural: saiu do nicho de dev e virou vocabulário geral

Aí, em 30/04/2026, num evento da Sequoia Capital, o próprio criador do termo relativizou a coisa: disse que o código gerado por IA ainda é inchado, cheio de copy-paste e frágil (as palavras dele foram "awkward, gross, bloaty")

E contou que escreveu o projeto nanochat "basically entirely hand-written", com a justificativa de que "I tried to use Claude/Codex agents a few times but they just didn’t work well enough at all and net unhelpful"

Quem criou o termo escreveu um projeto na mão porque os agentes não deram conta

Isso não mata o vibe coding, mas coloca ele no lugar certo: uma marcha, não a única marcha

O que é spec-driven development

Aqui a lógica inverte: a especificação vira o artefato central do projeto, e o código vira consequência dela

Primeiro tu define O QUE o software faz e POR QUÊ, sem falar de stack

Depois vem o plano técnico, depois a lista de tarefas acionáveis e só então a implementação

Se você já trabalhou com cliente, isso soa familiar: é a reunião de planejamento antes de alguém abrir o editor

Spec Kit, da GitHub

O Spec Kit é um toolkit open source mantido pela própria GitHub, no repositório github/spec-kit, pra desenvolvimento guiado por especificação com agentes de IA

O fluxo é exposto como slash commands dentro do seu agente de código, com prefixo speckit:

• /speckit.constitution: os princípios do projeto
• /speckit.specify: o que e por quê, sem stack
• /speckit.plan: o plano técnico
• /speckit.tasks: a lista de tarefas acionáveis
• /speckit.implement: executa as tarefas

O ciclo completo documentado ainda tem clarify, checklist e analyze como portões de qualidade

Ele funciona com mais de 30 agentes de IA, entre CLIs e assistentes dentro da IDE, incluindo Claude Code, GitHub Copilot e Gemini CLI

Pra ter uma noção do tamanho do interesse: o repositório acumula mais de 120 mil estrelas no GitHub (120,2 mil registradas em 14/07/2026)

Kiro, da AWS

O Kiro é uma IDE agêntica da AWS que materializa a especificação em três arquivos versionáveis:

• requirements.md: requisitos e critérios de aceite
• design.md: arquitetura técnica e componentes
• tasks.md: passos de implementação acionáveis, com status acompanhado na interface

Repara que é a mesma espinha dorsal do Spec Kit, só que gravada em arquivo que entra no versionamento

Essa é a pegada do spec-driven development: a decisão fica escrita em algum lugar, não some no histórico do chat

Spec-driven development x vibe coding: comparação direta

Nenhuma linha dessa tabela é métrica medida, é comparação qualitativa mesmo

Os números que existem aparecem nas seções abaixo, e eles falam do código assistido por IA em geral, não de uma abordagem contra a outra

Quando o vibe coding ganha

Tem cenário em que parar pra escrever documento é queimar token à toa

• Protótipo descartável: aquele projeto de fim de semana que o próprio Karpathy citou como uso legítimo
• Validação de ideia numa tarde: você quer ver se a coisa é interessante, não construir a coisa
• Script que roda uma vez: converter arquivo, migrar planilha, gerar relatório e deletar depois
• Bug pontual em arquivo isolado: escopo pequeno, efeito local, revisão rápida
• Aprender uma API nova: aqui o valor está em ver funcionando, não em manter

O ponto comum de todos: custo do erro baixo e código sem futuro

No vídeo eu falo isso sem meia palavra: em projeto pessoal, que ninguém vai usar, o SDD vira gasto desnecessário, porque a etapa de planejamento também consome token

Aplicação simples? Vibe coding resolve

O problema começa quando aquele projetinho simples ganha a ideia de virar produto…

Quando a especificação ganha

Agora vira o jogo

• Funcionalidade que vai pra produção, com gente de verdade usando
• Mudança que atravessa vários arquivos, onde o agente precisa de mapa e não de palpite
• Código que outra pessoa mantém, inclusive você daqui a três meses
• Integração com regra de negócio, aquele detalhe que só existe na cabeça do cliente
• Refatoração grande, o cenário clássico de "ficou quase certo" e quebrou tudo

E aqui os números ajudam a entender o custo real de não especificar

A pesquisa da GitClear sobre código assistido por IA, feita sobre 211 milhões de linhas de mudanças de código entre 2020 e 2024, mostra que as linhas copiadas e coladas passaram de 8,3% em 2020 pra 12,3% em 2024, uma alta relativa de 48%

No mesmo período, as linhas movidas, que são o indicador de refatoração, caíram de 24,1% pra 9,5%

2024 foi o primeiro ano em que o volume de copy-paste superou o de linhas refatoradas

Traduzindo: está entrando MUITO código duplicado e saindo pouca faxina

E tem o outro lado, o da confiança: na pesquisa de desenvolvedores da Stack Overflow de 2025, 46% dos devs desconfiam da precisão das respostas de IA (contra 31% no ano anterior), 33% confiam e só 3% confiam muito

A dor campeã aparece em 66% das respostas: soluções que chegam perto mas erram o alvo

A solução "quase certa" é exatamente o que uma especificação com critério de aceite pega antes de virar seu problema de sexta à noite

O critério de uma pergunta só pra decidir agora

Prometi lá em cima e tá aqui, é uma pergunta só:

Esse código vai sobreviver à semana e ser mantido por alguém?

Se a resposta for não, vibe coding e bola pra frente

Se for sim, escreve a spec

Minha regra de bolso, a que eu uso de verdade: se o projeto passa de três prompts, ou se ele já prevê autenticação, pagamento, perfis de usuário e dashboard, o SDD compensa

E existe o meio-termo, que é onde mora a maioria das tarefas do dia a dia: o plan mode resolve antes de você puxar um toolkit completo

Tarefa média, dois ou três arquivos, escopo claro? Plan mode

Feature nova que atravessa o sistema e vai pra produção? Spec Kit ou o esquema dos três documentos

Não é rivalidade, é escala do risco

A lógica é a mesma de escolher a ferramenta de IA certa pra cada tipo de tarefa: você não torce por uma, você olha o custo do erro

O que aprendi usando spec-driven development na prática

No vídeo abaixo eu mostro o SDD do zero montando um gerador de QR code

O que mais me chamou atenção foi o padrão do vibe coding sem planejamento: o projeto anda rápido no começo e depois trava em coisa boba, porque as decisões iniciais foram ruins

Sem documento de planejamento, a IA escolhe sozinha a stack, as features e o visual

Eu queria algo sóbrio e premium e recebi um resultado colorido demais 😅

E tem o efeito colateral que dói no bolso: mudar regra de negócio no meio do caminho, por causa de uma funcionalidade nova, dispara o consumo de tokens

O SDD funciona como uma baliza, um guard rail: mesma ideia, mesmos prompts, só que sem sair da curva

Os três documentos que eu usei

Eu estruturei o planejamento em três partes:

1. Requisitos: o que o app faz
2. Documento de design: como ele é construído
3. Lista de tarefas: a ordem de execução

Tome cuidado com um mal-entendido comum: o documento de design NÃO é sobre cores

Ali entram stack, esquema de banco, rotas, páginas, componentes e decisões técnicas

No documento de requisitos eu escrevi também a seção do que o projeto NÃO faz (sem analytics, sem QR code dinâmico, sem logo, sem API pública, sem plano pago), justamente pra IA não inventar escopo

Essa seção é meio contraintuitiva e é uma das que mais economiza retrabalho

Outra coisa: eu recomendo cocriar os documentos com a IA em vez de mandar ela escrever sozinha, porque o texto sai mais rígido e menos natural quando você não mete a mão

O que importa se você não é da área técnica

A parte mais importante dos requisitos é justamente a que independe de conhecimento técnico: o que o app faz, quais são as funcionalidades e como é a jornada do usuário

Pra decisão de stack, se você não é técnico, dá pra apoiar na própria IA: o resultado fica pior que o de um arquiteto experiente, mas fica melhor que deixar solto

No esquema de banco também não precisa acertar os tipos de campo, basta definir quais dados serão salvos

Eu escolhi uma stack padrão e bem dominada pelas IAs: Next, TypeScript, Prisma, SQLite e uma ferramenta de estilização

O SQLite entrou pra evitar setup, e num projeto real provavelmente teria que virar Postgres

Já as tarefas eu ordenei pela lógica de uso: setup inicial, depois autenticação (que é complexa e vital), depois a geração do QR code, salvar, dashboard e um polimento final pra aparar arestas

Regra que eu sigo: cada prompt executa uma tarefa concreta (uma página, um recurso), não um ajuste de cor

E não confunde documento de planejamento com arquivo de memória e instrução do agente, que é outro papo: esses eu mantenho sucintos, e vale entender a diferença entre skills, rules e workflows antes de misturar tudo no mesmo arquivo

A spec pode ser longa, o arquivo de instrução não

Amarrando com as ferramentas

Se você quiser o fluxo pronto em vez de escrever os três documentos na unha, o Spec Kit faz esse caminho dentro do seu agente

Pra rodar sem instalação permanente, via uvx:

uvx --from git+https://github.com/github/spec-kit.git specify init meu-projeto

Pra iniciar na pasta atual, usa . no lugar do nome do projeto

Se virar rotina, dá pra instalar como ferramenta uv:

uv tool install --from git+https://github.com/github/spec-kit.git specify-cli

A partir daí a sequência é aquela dos slash commands: /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks e /speckit.implement, com clarify, checklist e analyze quando você quiser apertar a qualidade

E tem a versão leve da mesma ideia, que é o plan mode do Claude Code

No plan mode o Claude lê arquivos e roda comandos de exploração, escreve um plano e não edita o código-fonte: as edições ficam bloqueadas até você aprovar o plano

São duas formas documentadas de entrar nele: apertar Shift+Tab, que cicla entre os modos de permissão (default, acceptEdits, plan), ou prefixar um prompt único com /plan

É planejamento com custo quase zero de aprendizado

Conclusão

O vibe coding nasceu com um recorte honesto do próprio Karpathy (projeto descartável de fim de semana) e virou palavra do ano em 2025, o que fez muita gente esquecer o recorte

O spec-driven development é o outro extremo: a especificação como artefato central, com Spec Kit e Kiro materializando isso em comandos e arquivos versionáveis

O critério continua sendo aquela pergunta única: esse código sobrevive à semana e alguém vai mantê-lo?

Próximo passo prático: na sua próxima tarefa média, entra no plan mode do Claude Code com Shift+Tab antes de deixar o agente editar qualquer coisa

Se a coisa crescer, sobe pro Spec Kit via uvx, sem instalação permanente, e vê se o fluxo de constitution, specify, plan, tasks e implement encaixa no teu jeito de trabalhar

Faça o teste e me conta como foi

até o próximo post! 😀