Spec-Driven Development: o futuro de programar com IA (SDD)

O spec driven development (SDD) é uma metodologia em que você escreve uma especificação estruturada antes do código, e um agente de IA usa essa spec como contrato para gerar o plano, as tarefas e a implementação. Em vez de digitar prompts soltos e torcer pelo melhor, a intenção vira um artefato auditável que o agente executa de forma previsível. Portanto, o SDD surge como resposta direta aos problemas do vibe coding.

Neste guia, você vai entender o que é SDD e como funciona o fluxo de quatro fases. Também vamos cobrir as principais ferramentas: GitHub Spec Kit, AWS Kiro, Tessl, OpenSpec e o próprio Claude Code. Além disso, vamos comparar SDD com vibe coding e mostrar quando cada abordagem ainda faz sentido. Em seguida, você terá um plano prático para começar hoje mesmo.

Sean Grove, da OpenAI, popularizou a ideia de que “a spec é o novo prompt” na palestra “The New Code”, no AI Engineer World’s Fair. Para Grove, código representa apenas 10 a 20% do valor entregue por um time de produto. Os outros 80 a 90% estão na comunicação estruturada de intenção, exatamente o que o SDD formaliza.

O que é spec driven development (SDD)

O spec driven development é uma metodologia que coloca a especificação textual no centro do projeto. Ela descreve o que o software deve fazer e vira o artefato principal. Primeiro, o desenvolvedor descreve requisitos, comportamentos esperados, restrições e critérios de aceite em linguagem natural estruturada. Em seguida, um agente de IA traduz essa especificação em plano técnico, tarefas e código funcional. Portanto, a spec deixa de ser documentação descartável e se torna um contrato executável.

A ideia central é simples: a IA é ótima em escrever código, mas ruim em adivinhar intenção. Por isso, em vez de gastar tempo refinando prompts, você investe esse tempo redigindo uma spec clara. Dessa forma, o agente tem contexto suficiente para gerar saídas consistentes e auditáveis. Além disso, a spec funciona como fonte da verdade ao longo do projeto inteiro.

Em fevereiro de 2026, um paper publicado no arXiv formalizou três níveis de rigor dentro do spec driven development. Primeiro, o nível spec-first escreve a spec antes do código e a descarta depois. É o caso de arquivos como CLAUDE.md ou .cursorrules. Em seguida, o nível spec-anchored mantém a spec viva ao lado do código. A sincronização é contínua, como propõem o Spec Kit e o Kiro. Por fim, o nível spec-as-source trata a spec como o próprio código-fonte, abordagem radical defendida pela Tessl.

SDD vs vibe coding: por que a comunidade está mudando de paradigma

O vibe coding popularizou a ideia de programar conversando livremente com a IA. Funciona muito bem para protótipos, scripts curtos e validação de hipóteses. No entanto, à medida que o projeto cresce, problemas aparecem rapidamente. Por exemplo, o agente esquece decisões anteriores, refatora código sem motivo e entrega features que não correspondem ao pedido original.

Em fevereiro de 2025, Andrej Karpathy popularizou o termo “vibe coding” para descrever o fluxo livre com IA. Menos de doze meses depois, o próprio Karpathy admitiu publicamente que essa era terminou, e o ecossistema entrou na fase da “agentic engineering era”, onde specs estruturadas substituem prompts soltos. O reversal de quem cunhou o termo é o sinal mais claro de que o paradigma mudou.

Os números reforçam a urgência. Equipes que aceleram só com vibe coding tendem a bater no que a Augment chama de “parede de três meses”: a dívida técnica acumulada por código gerado sem spec estoura em produção depois de aproximadamente 90 dias. Em paralelo, o estudo de Yan et al. (2025) mediu vulnerabilidades em código gerado por LLMs entre 9,8% e 42,1%. E uma pesquisa de 2026 com líderes de SRE e DevOps apontou que 43% das mudanças de código geradas por IA ainda exigem depuração manual em produção, mesmo após passarem por QA e staging (VentureBeat, sobre o relatório da Lightrun). Por isso, o SDD não é overhead burocrático: é o mecanismo que mantém o agente sob contrato.

O SDD resolve isso impondo disciplina sem perder a velocidade. Em vez de descrever a feature em uma frase solta, você escreve uma spec curta. Ela inclui requisitos, casos de uso e critérios de aceite. Dessa forma, o agente sabe exatamente o que entregar. O desenvolvedor consegue revisar a intenção antes do código. Por isso, equipes que adotaram SDD relatam menos retrabalho e maior previsibilidade.

Spec driven development é o mesmo que cascata (waterfall)?

Não, mas a crítica merece atenção. A Marmelab argumenta que o SDD se parece com cascata, já que planejar tudo antes de codar costuma falhar quando os requisitos mudam. De fato, esse é um risco real quando a spec é tratada como documento congelado.

A diferença está na granularidade e no ciclo de vida da spec. Na cascata clássica, escreve-se um documento gigante de requisitos no início e ele raramente volta a ser tocado. Já o SDD moderno propõe specs curtas, vivas e iterativas, atualizadas junto com o produto a cada feature. Ferramentas como o OpenSpec reforçam essa filosofia (“fluid not rigid, iterative not waterfall”) e foram pensadas para brownfield, não só para projetos novos. Portanto, o desafio prático é manter a spec enxuta o suficiente para evoluir sem virar burocracia.

Na prática, os dois paradigmas coexistem. Vibe coding continua imbatível para hackathons e provas de conceito. Já o SDD se torna essencial em sistemas que vão para produção, onde cada decisão precisa ser rastreável. Inclusive, ferramentas como o Claude Code já incluem comandos nativos para gerar specs antes de implementar.

As 4 fases do fluxo SDD (specify, plan, tasks, implement)

O fluxo canônico do SDD, popularizado pelo Spec Kit do GitHub, divide o trabalho em quatro fases sequenciais. Cada fase produz um artefato concreto e o próximo agente só começa quando o anterior termina. Dessa forma, você ganha pontos de revisão claros e evita que a IA pule etapas críticas.

Primeiro, a fase specify captura o que precisa ser construído em linguagem natural estruturada. A spec inclui contexto do produto, requisitos funcionais, comportamentos esperados e critérios de aceite. Em seguida, a fase plan traduz a spec em um plano técnico: stack, arquitetura, dependências e contratos de API. Depois, a fase tasks quebra o plano em tarefas pequenas e independentes. Por fim, a fase implement entrega o código pronto para revisão.

Veja a seguir um exemplo simplificado de spec.md no formato esperado pelo Spec Kit:

A seguir, o agente lê esse arquivo e gera o plano técnico automaticamente. Em projetos reais, cada fase termina com um commit dedicado. Assim, todo histórico fica rastreável no git e qualquer pessoa do time consegue auditar o porquê de cada decisão. Por exemplo, se o endpoint mudar amanhã, basta atualizar a spec e rodar o agente novamente.

Spec-Driven Development com Claude Code na prática

Na prática, o spec driven development com Claude Code funciona de duas formas complementares. A mais leve usa um arquivo CLAUDE.md na raiz do repositório como spec de baixo overhead: ele descreve convenções, comandos e contexto de domínio, e o Claude Code lê esse arquivo automaticamente em toda sessão. Dessa forma, o agente já começa cada tarefa com o contrato do projeto carregado, sem você repetir as mesmas regras a cada prompt.

A forma mais estruturada é rodar o GitHub Spec Kit por cima do Claude Code, que é um dos agentes suportados oficialmente. Você inicializa o projeto, escreve a spec da feature e deixa o Claude Code consumir cada artefato na ordem do fluxo de quatro fases. Os comandos uvx a seguir exigem o uv instalado, o gerenciador de pacotes Python. Veja a seguir como fica o ciclo dentro do agente:

O ponto-chave é que o arquivo de spec deixa de ser uma anotação descartável. Em cada fase, o Claude Code abre o artefato gerado na fase anterior e o usa como entrada, então o spec.md vira a memória durável do projeto. Por isso, se a feature mudar amanhã, você edita a spec e roda o agente de novo, em vez de tentar reconstruir a intenção por prompts soltos. Recomendamos começar pelo CLAUDE.md e só migrar para o Spec Kit quando o time sentir falta de rastreabilidade por feature.

Esse é o fluxo que o AI Overview do Google costuma citar quando alguém pesquisa por SDD com Claude Code, em boa parte ancorado no relato de Heeki Park sobre usar spec driven development com Claude Code e na documentação oficial do Claude Code. A lição comum dos dois é a mesma: investir tempo na fase de planejamento, e não no improviso, é o que separa um agente confiável de um que desanda no meio da tarefa.

Ferramentas de SDD: spec kit, kiro, tessl, openspec e CLAUDE.md

O ecossistema de ferramentas para SDD cresceu rápido. Cada projeto cobre um nível diferente de rigor e atende a perfis distintos de equipe. Veja a seguir as principais opções, do mais leve ao mais radical.

GitHub Spec Kit

O GitHub Spec Kit é hoje a referência open source da categoria, com mais de 100 mil estrelas no GitHub. Ele oferece um CLI universal que funciona com mais de 20 agentes, incluindo Copilot, Claude Code e Gemini CLI. Para começar, basta rodar um único comando:

A partir da versão atual, o Spec Kit expõe oito comandos slash que cobrem o ciclo completo:

• /speckit.constitution: define princípios cross-cutting que vivem acima de qualquer feature.
• /speckit.specify: abre a spec da feature em linguagem natural.
• /speckit.clarify: agente pergunta sobre pontos ambíguos antes de planejar.
• /speckit.plan: traduz a spec em arquitetura técnica.
• /speckit.tasks: quebra o plano em tarefas atômicas paralelizáveis.
• /speckit.analyze: faz revisão estática da spec antes de executar.
• /speckit.checklist: valida gaps de cobertura.
• /speckit.implement: agente executa o plano respeitando o contrato.

Equipes maduras tratam o /speckit.constitution como o artefato mais importante: ele garante que princípios de arquitetura e estilo sobrevivem entre features.

AWS Kiro

Em seguida, o AWS Kiro aposta em uma IDE proprietária dedicada exclusivamente ao SDD. Ele estrutura cada feature em três artefatos versionados: requirements.md com user stories, design.md com arquitetura e diagramas, e tasks.md com o plano executável. O Kiro tem free tier com 50 interações por mês; o Pro custa USD 19 (1 mil interações) e o Pro+ USD 39 (3 mil). Segundo benchmarks internos divulgados pela própria AWS/Kiro, features que levariam cerca de 40 horas humanas teriam sido entregues em menos de 8 horas quando a equipe começou pela spec. Vale ler esse número como claim de fornecedor, não como medição independente.

Tessl e a abordagem lightweight

Por outro lado, a Tessl propõe a visão mais radical. A spec é o código-fonte e o binário regenera a cada mudança. Atualmente está em beta privado, mas representa o futuro do conceito spec-as-source.

Finalmente, existe a abordagem lightweight que muitas pessoas já usam sem saber. Arquivos como CLAUDE.md, .cursorrules e copilot-instructions.md são specs de baixo overhead. Eles vivem na raiz do repositório e descrevem convenções, contexto e regras do projeto. Inclusive, o IBM iac-spec-kit aplica a mesma filosofia para infraestrutura como código. Para uma análise comparativa profunda, recomendamos o artigo de Martin Fowler sobre as três ferramentas SDD.

OpenSpec

Mais recente e em forte ascensão, o OpenSpec da Fission AI é um framework open source (licença MIT, distribuído via npm) que leva o SDD para qualquer assistente de IA, incluindo o Claude Code. Em vez de uma IDE fechada, ele cria uma pasta openspec/ no repositório com proposta, specs, design e tasks, e mantém esses artefatos vivos ao lado do código. A filosofia declarada é “fluid not rigid, iterative not waterfall”, com foco explícito em projetos brownfield, e não só em greenfield. Na prática, ele se encaixa no nível spec-anchored, entre o CLAUDE.md leve e a visão spec-as-source da Tessl.

Spec Kit vs Kiro vs Tessl vs OpenSpec: qual ferramenta escolher

Com tantas opções, a dúvida natural é qual ferramenta de spec driven development adotar. A resposta depende do nível de rigor que o projeto pede e do quanto você quer fugir do seu ambiente atual. A tabela abaixo resume as quatro principais, do mais aberto ao mais radical, para você escolher com base no caso de uso.

Na dúvida, recomendamos começar pelo Spec Kit ou pelo OpenSpec, ambos open source e compatíveis com o agente que você já usa. Kiro e Tessl fazem sentido quando o time decide investir em um ambiente dedicado e aceita o trade-off de proprietário versus controle. Em todos os casos, o nível de rigor importa mais que a marca: comece leve e aperte conforme o produto exigir.

Como começar com spec driven development na prática

Adotar o SDD não exige reescrever sua stack. Pelo contrário, dá para começar pequeno em um projeto novo ou em uma feature isolada. Primeiro, escolha uma ferramenta compatível com o agente que você já usa. Em seguida, escreva uma spec curta com cinco a dez linhas e deixe o agente gerar o plano. Por fim, revise antes de aprovar a implementação.

Onde você está na curva de SDD

Para quem usa Claude Code ou Copilot, o caminho mais rápido é o Spec Kit. A instalação é direta e a curva de aprendizado dura cerca de um dia. Veja a seguir o passo a passo recomendado pelo blog oficial da Microsoft Developer:

1. Instale o CLI com uvx --from git+https://github.com/github/spec-kit.git specify init.
2. Escreva uma spec curta no diretório specs/ usando linguagem natural.
3. Rode o comando de plano para gerar arquitetura e dependências.
4. Revise o plano e peça ajustes antes de aprovar.
5. Deixe o agente quebrar em tarefas e implementar uma a uma.

Da mesma forma, equipes que preferem manter o ambiente atual podem começar pelo nível spec-first. Basta criar um arquivo CLAUDE.md ou .cursorrules na raiz do repositório. Nele, descreva convenções, padrões de código, comandos úteis e contexto de domínio. Dessa forma, qualquer agente que abrir o projeto recebe automaticamente o contexto certo. Inclusive, esse é o caminho recomendado pela DeepLearning.AI no curso oficial sobre SDD.

EARS notation: o formato que os agentes entendem melhor

Para escrever critérios de aceite que o agente consome sem ambiguidade, vale aprender EARS (Easy Approach to Requirements Syntax). O padrão usa cinco templates curtos: ubiquitous (“the system shall…”), event-driven (“when X, the system shall…”), state-driven (“while X, the system shall…”), optional (“where X, the system shall…”) e complex (composto). Tanto Spec Kit quanto Kiro consomem EARS nativamente. Segundo o trabalho de Alistair Mavin e colegas, aplicar EARS gera uma redução substancial de ambiguidade, vagueza e prolixidade nos requisitos, exatamente o que um agente precisa para não desviar do contrato.

Quem quer entender de onde veio a base teórica de escrever specs executáveis vai gostar do livro Specification by Example do Gojko Adzic (Manning). Ele documenta as práticas que times de software ágil usavam para alinhar requisitos antes mesmo da IA, e que hoje a comunidade SDD revisitou para ensinar agentes a programar com previsibilidade.

Quando usar SDD (e quando o vibe coding ainda faz sentido)

O SDD brilha em cenários onde a previsibilidade vale mais que a velocidade bruta. Por exemplo, sistemas que vão para produção e equipes médias ou grandes. Inclusive projetos com compliance e código que outras pessoas vão manter. Nesses casos, a spec funciona como documentação viva e protege contra ambiguidades caras.

Por outro lado, o vibe coding continua sendo a melhor opção para hackathons e scripts pessoais. Também brilha em automações pontuais e exploração rápida de ideias. Quando o objetivo é descobrir se algo é viável, parar para escrever uma spec atrasa o aprendizado. Portanto, a regra prática é simples: vibe coding para descobrir, SDD para entregar.

Vale uma ressalva importante de Maxi Ferreira (Frontend at Scale): SDD não é universal. Um bug pequeno isolado escrito com spec completa vira overengineering. Programar com IA tem um componente que ele chama de “jazz”: improviso fundamentado, sem partitura. A regra prática: adote SDD quando o custo de errar passar o custo de escrever a spec. Não trate como dogma.

Vale considerar ainda o tipo de agente envolvido. Se você está delegando trabalho para um agente autônomo que roda por horas sem supervisão, a spec é obrigatória. Sem ela, o risco de o agente desviar do objetivo cresce exponencialmente. Por isso, equipes que usam Claude Cowork, Devin ou outros agentes de longo prazo já adotaram SDD por padrão.

Conclusão

Portanto, o spec driven development representa a evolução natural de programar com IA. A metodologia preserva a velocidade dos agentes enquanto adiciona a disciplina necessária para sistemas reais. Dessa forma, equipes conseguem entregar features previsíveis sem voltar à burocracia da cascata tradicional.

Lembre-se: a spec não substitui o código, ela orienta a IA a gerar o código certo. Além disso, a escolha entre Spec Kit, Kiro, Tessl ou CLAUDE.md depende do nível de rigor que seu projeto precisa. Por isso, comece simples e suba o nível conforme a equipe e o produto exigirem.

Primeiro, escolha um projeto pequeno para experimentar. Em seguida, instale o Spec Kit ou crie um CLAUDE.md no repositório. Por fim, escreva sua primeira spec hoje mesmo e compare o resultado com o fluxo antigo. Você vai sentir a diferença na primeira feature entregue.