Escreva a spec, não o código · desenvolvimento guiado por especificação com GitHub Spec Kit

Para quem é isto?

Para quem constrói com IA na base do "faz isso pra mim" e termina com um Frankenstein: cada função remendada sobre a anterior, ninguém —nem você nem a IA— lembra o que o app deveria fazer, e cada mudança quebra algo distante. Se você sentiu que a IA vai rapidíssimo, mas sem rumo fixo, isto é pra você. Você não precisa ser programador: precisa aprender a escrever a spec (a especificação) e deixar o agente fazer o resto. Funciona com Claude Code, Copilot, Cursor, Gemini e mais de 30 agentes.

O momento · quando "diz o que você quer" já não basta

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.

A analogia · a planta antes dos tijolos

Ninguém constrói uma casa dizendo ao pedreiro "começa por aquela esquina e a gente vê no que dá". Primeiro existe uma planta: onde ficam as paredes, os canos, as janelas. O pedreiro é ótimo assentando tijolos —assim como a sua IA é ótima escrevendo código— mas sem planta, cada um improvisa e a casa sai torta. O vibe coding é construir sem planta. O SDD é desenhar a planta primeiro. E aqui a planta não é um PDF morto: é executável — o agente lê e constrói direto a partir dela.

A dor · de onde sai o Frankenstein

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.

Por que acontece (e por que piora com o tempo)

O chat é linear e esquece. Nas 200 linhas de conversa, o que você decidiu no início já saiu da janela de contexto. A IA reconstrói a sua intenção a partir das últimas migalhas — e cada reconstrução se afasta um pouco do original, como uma fotocópia de uma fotocópia. Quanto maior o projeto, mais se degrada. Por isso o vibe coding parece incrível no dia 1 e desesperador no dia 20: não é que a IA piore, é que o contexto evapora e nunca houve uma âncora fora do chat.

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.

A solução · você inverte a ordem (spec primeiro, código depois)

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.

A analogia · o roteiro antes de gravar

Um filme não se grava improvisando cena por cena. Primeiro existe um roteiro (o que acontece), depois um plano de filmagem (como e em que ordem se filma), depois o decupagem de tomadas (as tarefas do dia), e só então a câmera é ligada. Se você muda o roteiro, muda tudo o mais em cascata — de forma organizada. O SDD é isso: a spec é o seu roteiro, o plano é o plano de filmagem, as tarefas são a decupagem, e o código é a filmagem. A IA é uma equipe de produção brilhante que enfim tem roteiro.

A ferramenta · GitHub Spec Kit

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.

github/spec-kitREPO

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.

PythonMITView on GitHub

Model-agnostic, igual à filosofia desta série

O Spec Kit não te prende a um modelo. A spec é o que tem valor e é texto puro — vive fora do agente. Se amanhã você trocar de Claude para Gemini, ou de Copilot para Cursor, a sua spec continua válida e o novo agente constrói a partir dela. O contrato sobrevive ao fornecedor. Esse é exatamente o princípio que repetimos em toda a biblioteca: o que você organiza (contexto, memória, spec) é seu; o modelo é intercambiável.

Instalação · dois comandos e você está dentro

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).

bash

# 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

A flag `--integration` é a que escolhe o seu agente

Em 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.

O protocolo · os comandos do Spec Kit, em ordem

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:

Os comandos do Spec Kit (o que cada um faz)

`/speckit.constitution` — define os princípios invioláveis do seu projeto: regras que a IA NUNCA deve quebrar (ex. "sempre validar a entrada do usuário", "nada de dados sensíveis em logs"). É a constituição que governa todo o resto.
`/speckit.specify` — a spec: o que você quer construir, em linguagem natural. Requisitos e histórias de usuário. O coração de tudo.
`/speckit.clarify` (opcional) — a IA te faz perguntas sobre o que ficou ambíguo na sua spec, ANTES de planejar. Fecha lacunas cedo.
`/speckit.plan` — o plano técnico: a IA propõe o stack, a arquitetura e como vai construir a spec. Você aprova ou corrige.
`/speckit.tasks` — decompõe o plano em uma lista de tarefas acionáveis, ordenadas e concretas. A decupagem de tomadas.
`/speckit.analyze` (opcional) — revisa se spec, plano e tarefas são consistentes entre si antes de construir. Caça contradições.
`/speckit.checklist` — gera checklists de qualidade sob medida para validar que os requisitos sejam cumpridos.
`/speckit.implement` — executa todas as tarefas e constrói o app conforme o plano. Aqui a câmera enfim é ligada.

A ordem não é decorativa

Pular a constitution ou a spec e rodar direto o /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.

O fluxo real · 4 fases com pontos de controle seus

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.

O fluxo de 4 fases, com o seu papel em cada uma

Fase 1 · Constituição. Você roda /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.
Fase 2 · Especificar (e esclarecer). Você roda /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.
Fase 3 · Planejar e decompor. /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.
Fase 4 · Implementar. /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.

A analogia · você é o diretor, não o operador de câmera

Numa boa produção, o diretor não segura a câmera nem empunha o martelo. Ele lê o roteiro, aprova o plano, revisa cada cena filmada e diz "essa sim, essa a gente refaz". Com SDD você faz isso: não escreve código nem briga com a sintaxe — aprova artefatos nos checkpoints. Toda a potência da IA, com o seu critério nos pontos que importam. Esse equilíbrio é o que as pessoas buscam quando dizem "quero que a IA trabalhe sozinha, mas sem perder o controle".

O hábito · quando escrever spec e quando não

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.

O momento exato em que se ativa

A regra prática: se você se pega explicando à IA a mesma coisa pela segunda vez, ou se abre o projeto e não lembra por que um arquivo existe — esse é o seu lembrete de que faltou uma spec. Não se martirize: escreva a spec agora, mesmo que o código já exista. O Spec Kit serve tanto para projetos novos (greenfield) quanto para colocar ordem em um que já virou uma bagunça (brownfield).

O prompt mestre · começar um projeto spec-first

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.

Cole na sua IA · começar um projeto guiado por spectexto

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.

O detalhe que faz a diferença

A frase "não adivinhe, me pergunte" no Passo 2 é a mais importante de todo o prompt. É o que transforma a IA de preenchedora-de-lacunas em colaboradora. A maioria dos bugs de vibe coding nasce de uma suposição silenciosa que você nunca questionou. O /speckit.clarify existe justamente para isso: trazer essas suposições à tona antes de virarem código.

Os caminhos mais fáceis · o que você faz por chat e o que por comando

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:

Divisão de tarefas

Pelo terminal (uma única vez): instalar 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.
Pelo chat com a sua IA (o trabalho de verdade): todos os comandos /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement. Você os escreve como mensagens normais.
Com as suas palavras (o que você contribui): a descrição do projeto, as respostas às perguntas do /speckit.clarify, e as aprovações em cada checkpoint. Zero código da sua parte.
Guarde a spec no git: a spec e a constituição são arquivos de texto. Comite eles. São o ativo mais valioso do projeto — mais que o código, que pode ser regenerado a partir deles.

Não confunda rápido com dirigido

O SDD parece mais lento no começo — você está "escrevendo documentos" em vez de ver código na hora. É uma ilusão. Esse tempo investido na spec te poupa os cinco rounds de "não, não era assim" que vêm depois no vibe coding. Você vai mais devagar no quilômetro 1 e muitíssimo mais rápido —e sem batidas— do quilômetro 2 em diante. A velocidade real não é código por minuto, é app terminado e correto por semana.

De onde isso vem (a evolução desta série)

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".

No NeuralOS, você já constrói contra um contrato

Há uma doutrina que governa como o NeuralOS é construído por dentro, e é exatamente esta filosofia: o frontend é a fonte de verdade. O design e a interface definem o contrato — o que deve existir e como se comporta — e o backend apenas preenche esse contrato; nunca inventa por conta própria. É SDD aplicado a um produto real: primeiro se especifica o que o usuário vê e espera, e todo o resto é construído para cumprir. Quando você conversa com o chat orquestrador do NeuralOS para construir o seu app, essa disciplina de contrato-primeiro é a que trabalha invisível por baixo para que o que você pede seja o que você recebe — sem que você tenha que montar a cascata de comandos.

O protocolo C-A-R · construir sem bugsO irmão mais velho deste recurso: separa construir de auditar. A spec te diz O QUE construir; o C-A-R garante que o que foi construído está certo.Crie o seu sistema de design ANTES de construirA mesma ideia aplicada ao design: fixe o contrato visual antes da primeira tela. A spec e o sistema de design são duas faces do mesmo princípio.

#spec-driven-development#spec-kit#github#vibe-coding#prompt#arquitetura