# Spec driven development com IA: o que é e como usar o Spec Kit
> Antes do primeiro prompt, você escreve o que o app faz e o que é pronto. Dá trabalho no começo, e é esse trabalho que faz o agente parar de desfazer o que já funcionava.
Por Alexandre Leite, Colaboratório. Publicado em 2026-10-30, atualizado em 2026-10-30.
Fonte: https://colaborato.rio/blog/spec-driven-development/
## Em 30 segundos
- Spec driven development é escrever, antes de pedir o código, um documento que diz o que o app faz, para quem, com quais regras e como saber que ficou pronto. O agente de IA programa a partir dele, e a spec fica guardada no projeto para a próxima conversa. O Spec Kit, do GitHub, organiza esse caminho.
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](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html): 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](https://colaborato.rio/blog/o-que-e-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](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/), 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](https://github.com/github/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.
1. **Especificar.** O que a funcionalidade faz e por quê, do ponto de vista de quem usa. Nada de tecnologia ainda.
1. **Esclarecer.** O agente pergunta o que ficou ambíguo, como se o cupom acumula com outro desconto, e você responde antes de seguir.
1. **Planejar e quebrar em tarefas.** Aqui entra a parte técnica: como construir e em que ordem.
1. **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](https://colaborato.rio/blog/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](https://colaborato.rio/blog/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](https://www.thoughtworks.com/pt-br/radar/languages-and-frameworks/github-spec-kit) 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](https://colaborato.rio/blog/sai-dessa-vibe-errada/), 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](https://colaborato.rio/app-feito-com-ia/).
Se a tela de pagamento do começo deste texto parece a sua, [entre em contato](https://wa.me/5521992438381?text=Ol%C3%A1%2C%20Alexandre%21%20Li%20o%20post%20%22Spec%20driven%20development%20com%20IA%3A%20o%20que%20%C3%A9%20e%20como%20usar%20o%20Spec%20Kit%22%20e%20quero%20conversar%20sobre%20o%20meu%20app.) e me conte qual funcionalidade você mudaria primeiro.
## Perguntas frequentes
### O que é spec em IA?
Spec é a especificação: o documento que diz o que o software faz, para quem, com quais regras e como saber que ficou pronto. Em IA, é o texto que o agente de código lê antes de programar. Ela fica guardada no projeto e vale para todas as conversas, inclusive as da semana que vem.
### O que é um spec kit?
O Spec Kit é um kit de código aberto do GitHub, lançado em 2025, que organiza o spec driven development em comandos dentro do agente de código. Ele cria os arquivos da constituição, da spec, do plano e das tarefas. Funciona com o Claude Code, o GitHub Copilot e o Gemini CLI, entre outros.
### Como instalar o spec kit?
Você precisa de Python, do gerenciador uv e de um agente de código instalado. No terminal, rode uv tool install specify-cli e depois specify init com o nome do projeto, escolhendo o agente que você usa. A partir daí, os comandos do kit aparecem dentro do agente.
### Como funciona spec-driven?
Primeiro você escreve as regras gerais do projeto e a spec da funcionalidade, sem falar de tecnologia. Depois o agente tira as dúvidas, monta o plano técnico e quebra o trabalho em tarefas. Por fim ele programa tarefa por tarefa, e você confere cada entrega contra a spec.
### Preciso saber programar para usar spec driven development?
Para o Spec Kit, ajuda, porque ele roda no terminal e usa Git. Para o método, não precisa: escrever o que o app faz, as regras e o que é pronto é trabalho de quem conhece o negócio. A spec pode morar num documento e entrar nas instruções do projeto no Lovable ou no Claude Code.