Spec driven development com IA: o que é e como usar o Spec Kit

O pedido era pequeno: um campo de cupom na tela de pagamento do app que você montou com o Claude Code. O agente fez em poucos minutos. O cupom funciona. O login, que ontem funcionava, parou.

Você pede para consertar o login, e ele conserta. Some o histórico de pedidos. O fim de semana que era para tirar o app do papel já virou um mês, e cada prompt parece mexer numa peça que não tinha nada a ver com o pedido.

Spec driven development é o nome que o mercado deu para a saída desse vaivém. Neste guia eu explico o que é, a diferença para o vibe coding, como usar o Spec Kit do GitHub, como aplicar sem saber programar e o que continua sendo decisão sua.

O que é spec driven development (ou SDD)

Spec driven development é um jeito de construir software com IA em que você escreve primeiro uma especificação, a spec, e só depois pede o código. A spec diz o que o app faz, para quem, quais regras valem e como saber que ficou pronto. O agente de código, a inteligência artificial que escreve e roda o programa, trabalha a partir desse documento, e a última mensagem do chat deixa de ser a única referência.

O termo aparece escrito com hífen, spec-driven development, e abreviado como SDD. Em outubro de 2025, a Birgitta Böckeler, da Thoughtworks, escreveu no site do Martin Fowler que a spec vira a fonte da verdade para a pessoa e para a IA. Ela separa três níveis de spec: a spec escrita antes e usada na tarefa, a spec mantida depois para evoluir a funcionalidade e a spec como o único arquivo que a pessoa edita, sem nunca tocar no código.

Se você não programa, pense no velho documento de requisitos, a especificação de software que todo projeto sério sempre teve. Muda quem lê: agora o agente relê a spec toda vez que vai mexer no código.

Spec driven development e vibe coding: qual a diferença

No vibe coding, você descreve o app em português e vai ajustando a cada resposta. Para testar uma ideia numa tarde, funciona bem, e foi assim que muita gente tirou o primeiro protótipo do papel.

O aperto começa quando o app cresce. Cada prompt carrega uma decisão tomada na hora: o cupom vale para todo produto, o pedido cancelado devolve o estoque, quem pode ver o histórico. Essas decisões ficam espalhadas pela conversa, e o agente não guarda todas. Quando ele mexe no pagamento, não sabe que o login dependia daquele pedaço, porque isso nunca foi escrito em lugar nenhum.

O GitHub descreveu esse sintoma no lançamento do Spec Kit, em setembro de 2025: código que parece certo e não funciona direito. E apontou a causa no jeito de pedir, não na capacidade do agente de programar.

No vibe coding, a decisão mora na conversa. No spec driven, ela mora num arquivo que o agente relê antes de cada mudança, e mudar a regra começa por mudar a spec.

Como usar o Spec Kit, passo a passo

O Spec Kit é o kit de código aberto do GitHub que organiza o spec driven development em comandos chamados de dentro do agente de código. Funciona com o Claude Code, o GitHub Copilot e o Gemini CLI, entre outros. A instalação pede Python e o gerenciador uv: no terminal, uv tool install specify-cli e depois specify init com o nome do projeto.

Daí em diante, cada etapa vira um arquivo em Markdown dentro do projeto:

1. Constituição. As regras que valem para tudo: a linguagem, o banco de dados, o que nunca pode quebrar. Você escreve uma vez.
2. Especificar. O que a funcionalidade faz e por quê, do ponto de vista de quem usa. Nada de tecnologia ainda.
3. Esclarecer. O agente pergunta o que ficou ambíguo, como se o cupom acumula com outro desconto, e você responde antes de seguir.
4. Planejar e quebrar em tarefas. Aqui entra a parte técnica: como construir e em que ordem.
5. Implementar. O agente executa as tarefas uma a uma e você confere cada entrega contra a spec.

Cada etapa tem o seu comando no agente (constitution, specify, clarify, plan, tasks e implement). O ganho está na ordem: o agente só escreve código depois que a regra do cupom está escrita e respondida.

Spec driven development sem saber programar

O Spec Kit pede terminal e Git, e quase tudo que se escreve sobre ele é para dev. Se você constrói no Lovable, no Bolt ou no Claude Code sem saber programar, o método serve do mesmo jeito. O kit só automatiza a ordem.

• Escreva a spec antes de abrir a ferramenta. Uma página basta: quem usa, o que a pessoa faz em cada tela, as regras (quem vê o quê, o que acontece no caso estranho) e o que é pronto. O ChatGPT, o Claude ou o Gemini ajudam a escrever e, melhor ainda, a perguntar o que você esqueceu.
• Guarde a spec onde o agente sempre lê. No Claude Code, o arquivo CLAUDE.md na pasta do projeto. No Lovable, o conhecimento do projeto, nas configurações. Assim a regra deixa de depender de você repetir no prompt.
• Peça um pedaço por vez e confira contra a spec. Uma funcionalidade, um teste na mão, e só então a próxima. Se a regra mudou, atualize a spec primeiro e peça o código depois.

É o mesmo caminho do guia de criar app com IA, agora com nome e ferramenta. Se o seu app é um sistema interno que nasceu de uma planilha, a regra está nas fórmulas, e o guia de criar sistema com IA mostra como tirar de lá.

O que continua sendo decisão sua

A spec organiza o trabalho do agente. Três decisões ela só registra, porque alguém precisa tomar antes:

• O que entra e o que fica de fora. Escolher o menor pedaço que já serve a quem vai usar é decisão de produto, e a spec herda essa escolha, boa ou ruim.
• O que é pronto. Funcionar na sua tela é pouco. Pronto é quando quem usa consegue fazer a tarefa do começo ao fim, com os dados de verdade.
• Se o resultado bate com a spec. O GitHub diz isso no próprio lançamento: o seu papel é conduzir o agente e conferir. A IA gera os arquivos, e quem garante que estão certos é você.

O método também tem custo. A Böckeler testou o Spec Kit e achou demais até para uma funcionalidade média: tanto arquivo de Markdown para revisar que ela preferia revisar o código. O Radar da Thoughtworks de abril de 2026 ainda põe o Spec Kit em avaliação.

Para corrigir um texto, um bug simples ou testar uma ideia numa tarde, a spec completa é exagero. Ela se paga quando a funcionalidade tem regra de negócio, mexe em dinheiro ou dado de cliente, ou vai continuar no ar.

Nada de código antes do artefato

No protocolo antivibe, o método que eu uso para levar uma ideia até o uso real, tem uma regra que vem antes de qualquer spec: nada de código antes do artefato. Primeiro eu defino o resultado esperado num exemplo concreto: o desenho de uma tela, um mock, o arquivo que o sistema tem que devolver. Só depois vem a sequência que o Spec Kit automatiza: conversa sobre a ideia, spec, plano, execução e revisão.

O artefato é o passo 3 do protocolo, o menor experimento que responde a pergunta. Ele vai para a mão de quem vai usar, que é o passo 4, e responde "é isso?" antes de alguém escrever a spec. Uma spec bem escrita sobre a coisa errada só faz o agente construir a coisa errada mais rápido.

Escrever a spec é decidir o que construir antes de construir. Quando ninguém na empresa tem tempo para essa decisão, é por ela que começa a primeira sprint que eu conduzo. Se o seu app já existe e travou nesse vaivém de prompts, montei uma página sobre o que fazer com um app feito com IA.

Se a tela de pagamento do começo deste texto parece a sua, entre em contato e me conte qual funcionalidade você mudaria primeiro.