Existe um padrão que quase todo mundo que constrói com IA repete: no começo você conversa, o código aparece, funciona, é mágica. Mas por volta da quinta ou sexta função a mágica se quebra — você pede uma mudança pequena e outra coisa cai, explica pela terceira vez como funciona o login "porque ela esqueceu", e abre o projeto no dia seguinte sem lembrar por que metade dos arquivos existe. O problema de fundo não é que a IA seja burra: é que ela não tem memória de intenção e adivinha diferente cada vez que preenche uma lacuna. O Spec-Driven Development inverte a ordem do vibe coding: antes de a IA escrever uma linha, você escreve a spec —o que o app deve fazer, com as suas palavras— e esse documento vira a única fonte de verdade a partir da qual o agente gera plano → tarefas → código, com checkpoints seus no meio. Neste guia você vai ver a ferramenta que instala isso como comandos dentro do seu próprio agente (GitHub Spec Kit, grátis e open source), o fluxo real de 4 fases, os comandos exatos, e um único prompt mestre para começar qualquer projeto spec-first sem virar programador.
No começo, o vibe coding é mágico. Você conversa com a IA, uma tela aparece, funciona, você aplaude. Mas chega um ponto —quase sempre por volta da quinta ou sexta função— em que a mágica se quebra. Você pede uma mudança pequena e outra coisa que você nem tocou cai. Você explica pela terceira vez como o login deve funcionar "porque ela esqueceu". Você abre o projeto no dia seguinte e nem você sabe por que metade dos arquivos existe. Esse é o momento: quando a conversa deixa de ser suficiente como fonte de verdade, e você precisa de algo mais sólido que um chat com memória de peixe.
O Spec-Driven Development (desenvolvimento guiado por especificação, ou SDD) nasce exatamente aí. A ideia é tão simples que quase ofende: antes de a IA escrever uma linha de código, você escreve o que o app deve fazer — de forma clara, organizada e salva em um arquivo. Esse documento, a spec, vira a única fonte de verdade. E o agente gera, a partir dele, um plano → uma lista de tarefas → o código. Nessa ordem. Com pontos de controle seus no meio.
O problema não é que a IA seja burra. É que a IA não tem memória de intenção. Em cada mensagem ela toma a melhor decisão para aquela mensagem, sem uma imagem completa do que você está construindo nem por quê. Você tem essa imagem na cabeça — mas a cabeça não é um documento que o agente possa ler. Então a IA preenche as lacunas adivinhando, e adivinha diferente a cada vez. Uma vez o carrinho guarda impostos, outra vez não. Uma vez o usuário pode editar o perfil, outra a função desaparece num refactor. Ninguém mentiu: simplesmente nunca existiu um contrato dizendo o que é correto.
O que acontece se você não corrigir isso? Não é o apocalipse — é um acidente lento. Você termina com um app que quase funciona, impossível de explicar para outra pessoa (ou para a IA da semana que vem), onde cada correção tem a sua própria chance de quebrar algo mais. E essas chances não perdoam: num blog desta mesma série contamos a matemática dos 27% — um agente que acerta 85% em cada passo só completa um fluxo de oito passos 27% das vezes (0,85⁸), porque os acertos se multiplicam, não se somam. Construir às cegas encadeia passos frágeis exatamente da mesma forma. A spec é o que rompe essa corrente de fragilidade: dá à IA um ponto fixo contra o qual verificar cada passo, em vez de deixar que cada um dependa da boa sorte do anterior.
No vibe coding o fluxo é: você conversa → código → (às vezes) documenta. No SDD ele se inverte por completo: você especifica → planeja → gera tarefas → código. A documentação deixa de ser a sobra esquecida do fim e vira o ponto de partida. E não é burocracia: cada fase é um artefato que o agente gera quase sozinho a partir do anterior, com um checkpoint seu para aprovar antes de seguir. Você dirige; a IA executa.
Você não precisa inventar esse fluxo na mão. O GitHub Spec Kit é um kit de ferramentas open source —do GitHub, grátis, licença MIT— que instala o SDD como uma série de comandos dentro do seu agente de IA. Você escreve a spec em linguagem natural; ele te dá a estrutura, os checkpoints e os comandos para que a IA a converta em app. É uma das ferramentas de IA que mais cresceu: 122.000 estrelas no GitHub, e a sua última versão estável, a v0.13.0, saiu em 17 de julho de 2026. Integra mais de 30 agentes — Claude Code, GitHub Copilot, Cursor, Gemini CLI e o que você usar.
O kit oficial do GitHub para Spec-Driven Development. Instala um fluxo de comandos (constitution → specify → plan → tasks → implement) dentro do seu agente de IA, para que você construa a partir de uma especificação executável em vez de improvisar. Model-agnostic: funciona com mais de 30 agentes.
O Spec Kit se instala com o uv, o gerenciador de pacotes de Python moderno (rápido, sem dramas). Se você não tem o uv, instala ele primeiro — uma linha. Depois você instala o CLI do Spec Kit de forma persistente, e inicializa o seu projeto escolhendo o seu agente. Não se assuste com o terminal: são literalmente estes comandos, em ordem, e você não volta a mexer nele para o trabalho de verdade (esse acontece dentro do chat da sua IA).
# 1) Se você não tem o uv (o gerenciador de pacotes de Python), instale-o: curl -LsSf https://astral.sh/uv/install.sh | sh # 2) Instale o CLI do Spec Kit de forma persistente (fixando a versão estável): uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.13.0 # 3) Veja quais agentes você pode escolher (o valor exato para a flag --integration): specify integration list # 4) Inicialize o seu projeto escolhendo o seu agente (aqui, Copilot como exemplo): specify init mi-proyecto --integration copilot # 5) Verifique se há uma versão mais nova (não modifica nada, só lê): specify self check
specify init mi-proyecto --integration copilot, o valor depois de --integration é a sua ferramenta. O Spec Kit traz mais de 30 integrações e vai mudando elas entre as versões, então em vez de decorar o nome exato, rode antes specify integration list e escolha dessa lista o que você usa (Copilot, Cursor, Gemini, Claude Code, etc.) — é como pedir o cardápio antes de fazer o pedido, assim você nunca pede um prato que não está disponível. Esse comando init cria a pasta com os comandos /speckit.* já cabeados dentro do seu agente; a partir daí, todo o trabalho acontece conversando com a IA, não no terminal.Uma vez inicializado, o Spec Kit te dá uma série de slash commands que você escreve dentro do seu agente. Eles não são mágicos: cada um pede à IA que gere o próximo artefato do fluxo. A ordem importa — é uma cascata onde cada passo se apoia no anterior. Estes são os reais, exatamente como vêm na v0.13.0:
/speckit.implement é voltar ao vibe coding com passos a mais. A cascata funciona porque cada artefato restringe o próximo: a constituição limita o plano, o plano limita as tarefas, as tarefas limitam o código. Se você quebra a corrente, a IA volta a adivinhar. A disciplina está em respeitar os checkpoints, não em ter os comandos.Juntando tudo, é assim que um projeto fica do início ao fim. Repare que em cada fronteira você revisa e aprova antes de a IA avançar. Esse é o truque: não é que a IA trabalhe sozinha sem freio, é que ela trabalha sozinha entre checkpoints que você controla.
/speckit.constitution e define as regras de ouro do projeto. Checkpoint: você lê e confirma que esses princípios são os corretos. Escreve-se uma vez, governa sempre./speckit.specify e descreve o que construir. Depois /speckit.clarify para a IA fechar ambiguidades te perguntando. Checkpoint: a spec diz EXATAMENTE o que você quer, sem lacunas./speckit.plan dá o plano técnico; /speckit.tasks o transforma em tarefas; /speckit.analyze verifica se tudo é coerente. Checkpoint: você aprova o stack e as tarefas antes de qualquer código ser escrito./speckit.implement constrói. A IA executa as tarefas uma a uma contra a spec. Checkpoint: você usa /speckit.checklist para validar que o que foi construído cumpre os requisitos.O SDD não é para tudo. Uma mudança de uma linha, um botão de cor, um texto — para isso você conversa normal com a IA e pronto. Escrever uma spec para isso seria como pedir planta de arquiteto para pendurar um quadro. O bom hábito é reconhecer o limiar: no momento em que uma tarefa toca mais de um arquivo, tem regras de negócio, ou você vai voltar a ela na semana que vem — aí sim, spec primeiro. E daí em diante, cada função nova grande nasce de uma spec, não de um impulso.
Aqui está o único prompt que você precisa decorar. É o que você dá à sua IA (com o Spec Kit já inicializado) para começar bem desde o primeiro minuto: ele pede que ela primeiro fixe a constituição, depois construa a spec com você perguntando o que falta, e que não escreva código até você aprovar. Copie, preencha os [colchetes], e cole no seu agente ao começar qualquer projeto sério.
Vamos construir este projeto com Spec-Driven Development usando o GitHub Spec Kit, que já está inicializado. NÃO escreva código ainda. Siga este fluxo comigo, parando em cada checkpoint para que eu aprove antes de avançar. Meu projeto é: [descreva o que você quer construir e para quem, em 3-5 frases]. O que NÃO deve fazer / meus limites: [ex. sem guardar cartões de crédito, funcionar no celular, nada de dados sensíveis em logs]. PASSO 1 — CONSTITUIÇÃO. Antes de tudo, rode /speckit.constitution e proponha os princípios invioláveis deste projeto (segurança, validação de entradas, consistência, o que se aplicar). Mostre-os para mim e espere o meu aval. PASSO 2 — SPEC. Depois rode /speckit.specify e redija a especificação a partir da minha descrição: requisitos claros e histórias de usuário. Em seguida rode /speckit.clarify e me faça TODAS as perguntas necessárias para eliminar ambiguidades — não adivinhe, me pergunte. Não siga em frente até eu dizer que a spec está correta. PASSO 3 — PLANO E TAREFAS. Com a spec aprovada, rode /speckit.plan e proponha o stack e a arquitetura (me explique em bom português por que escolheu cada coisa). Depois /speckit.tasks para a decupagem, e /speckit.analyze para verificar que spec, plano e tarefas não se contradigam. Mostre-me tudo e espere a minha aprovação. PASSO 4 — IMPLEMENTAR. Só quando eu autorizar, rode /speckit.implement e construa. Ao terminar, gere um /speckit.checklist para validar que o que foi construído cumpre a spec. Regra de ouro durante todo o processo: a spec é a única fonte de verdade. Se algo do código se afastar da spec, a spec ganha — ou você me avisa para atualizarmos juntos. Nunca mude o comportamento em silêncio.
/speckit.clarify existe justamente para isso: trazer essas suposições à tona antes de virarem código.Para você não se perder: quase tudo acontece conversando com a sua IA. No terminal você mexe uma única vez (instalar e inicializar). Os /speckit.* você escreve dentro do chat do seu agente, como qualquer outra mensagem. E a spec você escreve com as suas palavras — não em código. Esta é a divisão:
uv, instalar o specify-cli, ver os agentes com specify integration list, rodar specify init mi-proyecto --integration <seu-agente>, e specify self check para conferir se está atualizado. Acabou — você não volta ao terminal./speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement. Você os escreve como mensagens normais./speckit.clarify, e as aprovações em cada checkpoint. Zero código da sua parte.Se você acompanhou a biblioteca, isso não soa novo — é o próximo degrau. O protocolo C-A-R te ensinou a separar construir de auditar para não enviar bugs. O recurso de sistema de design te ensinou a fixar as regras visuais antes da primeira tela. Ambos compartilham uma mesma ideia: decida o contrato antes de executar. O SDD leva essa ideia à sua forma mais pura: a spec é o contrato, e é a única fonte de verdade para todo o app — design, lógica, comportamento. Você passa de "organize o seu contexto" para "escreva o contrato e deixe a IA cumpri-lo".
Join 4,200+ builders. No credit card. Build your first app with AI in minutes.