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 como funciona o fluxo, quais ferramentas usar (GitHub Spec Kit, AWS Kiro, Tessl, OpenSpec e o próprio Claude Code) e quando o spec driven development vale o esforço. Sean Grove, da OpenAI, resumiu a ideia na palestra “The New Code”, no AI Engineer World’s Fair: “a spec é o novo prompt”. De fato, para Grove o código representa apenas 10 a 20% do valor entregue por um time de produto. Logo, o resto está na comunicação estruturada de intenção, exatamente o que o SDD formaliza.
O que é spec driven development?
O spec driven development coloca a especificação textual no centro do projeto. 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. Além disso, a spec funciona como fonte da verdade ao longo do projeto inteiro. Dessa forma, o agente tem contexto suficiente para gerar saídas consistentes e auditáveis.
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, como em arquivos CLAUDE.md ou .cursorrules. Em seguida, o nível spec-anchored mantém a spec viva ao lado do código, como propõem o Spec Kit, o Kiro e o OpenSpec. Por fim, o nível spec-as-source trata a spec como o próprio código-fonte, abordagem radical defendida pela Tessl.
O que mudou em 2026: o GitHub Spec Kit chegou à versão 1.0 em 21 de agosto (hoje está na 1.0.8), trocou os comandos com ponto por skills com hífen, como /speckit-specify, e ganhou a etapa /speckit-converge. Além disso, o Kiro passou a cobrar em créditos e lançou um CLI. Por sua vez, o OpenSpec virou o segundo projeto open source mais popular da categoria, e a Tessl abriu seu registro de specs em beta público.
Qual a diferença entre SDD e vibe coding?
O vibe coding popularizou a ideia de programar conversando livremente com a IA. Na prática, 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.
Inclusive, Andrej Karpathy, que cunhou o termo em fevereiro de 2025, menos de um ano depois já falava em “agentic engineering”, com specs estruturadas no lugar de prompts soltos.
Os números reforçam a urgência. Segundo a Augment, equipes que aceleram só com vibe coding batem numa “parede de três meses”, quando a dívida técnica estoura em produção depois de cerca de 90 dias. Da mesma forma, o estudo de Yan et al. (2025) mediu vulnerabilidades em código gerado por LLMs entre 9,8% e 42,1%. Segundo a Lightrun, 43% das mudanças de código geradas por IA ainda exigem depuração manual em produção, mesmo após QA e staging, conforme reportou a VentureBeat. Por isso, o SDD não é burocracia: é o mecanismo que mantém o agente sob contrato.
Spec driven development é o mesmo que cascata?
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. No entanto, a cascata produz um documento gigante e congelado, enquanto o SDD moderno propõe specs curtas e atualizadas a cada feature. Portanto, o desafio prático é manter a spec enxuta o suficiente para evoluir sem virar burocracia.
Publicidade
Como funciona o fluxo do spec driven development?
O fluxo canônico, popularizado pelo Spec Kit do GitHub, divide o trabalho em fases que produzem artefatos concretos. Dessa forma, você ganha pontos de revisão claros e evita que a IA pule etapas críticas. Na versão 1.0 do Spec Kit, o ciclo ficou assim:
- 1ConstitutionPrincípios de arquitetura e estilo que valem para todas as features.
- 2SpecifyO que e por quê: requisitos e critérios de aceite no spec.md.
- 3PlanComo construir: stack, arquitetura e contratos no plan.md.
- 4TasksO plano quebrado em tarefas atômicas no tasks.md.
- 5ImplementO agente gera e testa o código respeitando o plano.
- 6ConvergeCompara código e spec; repete implement e converge até o status “Converged”.
Clarify, checklist e analyze viraram portões opcionais entre as fases.
Sobretudo, a grande novidade é a etapa converge. Antes, o fluxo terminava no implement, e ninguém conferia se o código ainda batia com a spec. Agora, o agente repete implement e converge até o relatório indicar que os dois estão alinhados. Além disso, os comandos clarify (tira ambiguidades), checklist (valida cobertura) e analyze (revisa a consistência dos artefatos) ficaram opcionais. Veja a seguir um exemplo simplificado de spec.md:
# Feature: Endpoint /users (GET)
## Contexto
API REST de cadastro de usuários para painel interno.
## Requisitos
- Listar todos os usuários ativos.
- Suportar paginação (limit, offset).
- Retornar 401 quando token JWT inválido.
## Critérios de aceite
- Resposta segue contrato OpenAPI em /docs/api.yaml.
- Tempo de resposta < 200ms para 1000 registros.
- Cobertura de testes acima de 80%.Em seguida, o agente lê esse arquivo e gera o plano técnico. Por exemplo, se o endpoint mudar amanhã, basta atualizar a spec e rodar o agente novamente.
Como usar spec driven development com Claude Code?
Na prática, o spec driven development com Claude Code funciona em dois níveis. O mais leve usa um arquivo CLAUDE.md na raiz do repositório como spec de baixo overhead. Segundo a documentação oficial do Claude Code, o agente lê esse arquivo no início de toda sessão, e também consegue ler um AGENTS.md que o repositório já tenha. Dessa forma, cada tarefa já começa com o contrato do projeto carregado.
Além disso, a própria ferramenta oferece recursos que casam com o SDD. O plan mode (ativado com Shift+Tab ou com claude --permission-mode plan) faz o Claude ler os arquivos e propor um plano sem editar nada até você aprovar. As skills empacotam fluxos repetíveis que o time compartilha, os hooks rodam comandos de shell antes ou depois das ações do agente, como um lint, e os subagentes pesquisam em uma janela de contexto própria. Para um panorama das novidades, veja nosso guia do Claude Code em 2026.
A forma mais estruturada é rodar o GitHub Spec Kit por cima do Claude Code, um dos agentes suportados oficialmente. Os comandos exigem o uv instalado, o gerenciador de pacotes Python. Veja a seguir o ciclo completo:
# 1. Instala o CLI e inicializa o projeto com a integração do Claude Code
uv tool install specify-cli
specify init meu-app --integration claude
# 2. Dentro do Claude Code, as skills consomem cada fase:
/speckit-constitution # princípios do projeto
/speckit-specify # gera spec.md a partir da descrição da feature
/speckit-plan # lê a spec e produz plan.md + contratos
/speckit-tasks # quebra o plano em tasks.md atômicas
/speckit-implement # implementa cada tarefa
/speckit-converge # repete com implement até "Converged"O Spec Kit instala essas skills na pasta .claude/skills do projeto. Por isso, o spec.md vira a memória durável do projeto, e não uma anotação descartável. Recomendamos começar pelo CLAUDE.md e só migrar para o Spec Kit quando o time sentir falta de rastreabilidade por feature.
Publicidade
Quais são as ferramentas de spec driven development?
O ecossistema cresceu rápido em 2026, e cada projeto cobre um nível diferente de rigor. Veja a seguir as principais opções, do mais aberto ao mais radical.
GitHub Spec Kit
O GitHub Spec Kit é a referência open source da categoria, com cerca de 137,8 mil estrelas no GitHub e integração com mais de 50 agentes, incluindo Copilot, Claude Code e Gemini CLI. Além do fluxo principal, ele aceita extensões opcionais. Por exemplo, a extensão de bugs adiciona /speckit-bug-assess, /speckit-bug-fix e /speckit-bug-test, e a de avaliação de ideias ajuda a decidir se uma feature merece spec. Da mesma forma, o antigo comando que transformava tarefas em issues virou a extensão do GitHub.
AWS Kiro
Em seguida, o AWS Kiro aposta em uma IDE dedicada ao SDD. Ele estrutura cada feature em três artefatos versionados: requirements.md com user stories, design.md com arquitetura e tasks.md com o plano executável. Desde 2026, o preço é em créditos: o Free dá 50 por mês, o Pro custa US$ 20 (1.000 créditos), o Pro+ US$ 40 (2.000), o Pro Max US$ 100 (5.000) e o Power US$ 200 (10.000). Além disso, o Kiro CLI, disponível desde novembro de 2025, leva o mesmo fluxo para o terminal.
OpenSpec
O OpenSpec, da Fission AI, é o concorrente open source que mais cresceu: está na versão 1.13.1 (17 de setembro de 2026) e passa de 68 mil estrelas. Ele cria uma pasta openspec/ no repositório e funciona com qualquer assistente, incluindo o Claude Code. O ciclo usa três comandos: /opsx:propose abre a mudança, /opsx:apply implementa e /opsx:archive incorpora o resultado às specs. A filosofia declarada é “fluid not rigid, iterative not waterfall”, com foco em projetos brownfield.
Tessl e a abordagem lightweight
Por outro lado, a Tessl propõe a visão mais radical: a spec é o código-fonte. Na prática, ela tem hoje duas frentes. O Spec Registry, com mais de 10 mil specs de bibliotecas, está em beta aberto. Já o Framework, que regenera código a partir da spec, continua em beta fechado. Finalmente, existe a abordagem lightweight que muita gente já usa sem saber: arquivos como CLAUDE.md, .cursorrules e copilot-instructions.md são specs de baixo overhead.
| Ferramenta | Tipo | Rigor da spec | Melhor para |
|---|---|---|---|
| GitHub Spec Kit | Open source (CLI) | Spec-first / anchored | Times que já usam Claude Code, Copilot ou Gemini e querem o fluxo completo sem trocar de IDE. |
| OpenSpec | Open source (npm, MIT) | Spec-anchored | Projetos brownfield e specs vivas no repositório, agnóstico de agente. |
| AWS Kiro | Proprietária (IDE + CLI) | Spec-anchored | Equipes que aceitam ambiente dedicado e pagamento por créditos em troca de fluxo guiado. |
| Tessl | Proprietária (beta) | Spec-as-source | Quem quer apostar na visão em que a spec é o código-fonte. |
Na dúvida, recomendamos começar pelo Spec Kit ou pelo OpenSpec, ambos gratuitos e compatíveis com o agente que você já usa. Kiro e Tessl fazem sentido quando o time aceita o trade-off de um ambiente proprietário. Afinal, em todos os casos o nível de rigor importa mais que a marca.
Quando usar SDD (e quando o vibe coding ainda faz sentido)?
O SDD brilha onde a previsibilidade vale mais que a velocidade bruta. Por exemplo, em sistemas que vão para produção, equipes médias ou grandes, projetos com compliance e código que outras pessoas vão manter. Por outro lado, o vibe coding continua sendo a melhor opção para hackathons, scripts pessoais e exploração rápida. Portanto, a regra prática é simples: vibe coding para descobrir, SDD para entregar.
Vale uma ressalva de Maxi Ferreira (Frontend at Scale): SDD não é universal. Por exemplo, um bug pequeno escrito com spec completa vira overengineering. Assim, adote o método quando o custo de errar passar o custo de escrever a spec. Já se você delega trabalho a um agente autônomo que roda por horas sem supervisão, a spec deixa de ser opcional. Afinal, sem ela o risco de o agente desviar do objetivo cresce a cada passo.
EARS notation: o formato que os agentes entendem melhor
Para escrever critérios de aceite sem ambiguidade, vale aprender EARS (Easy Approach to Requirements Syntax). O padrão usa templates curtos, como “when X, the system shall…”. O Kiro, por exemplo, gera requisitos nesse formato. Segundo o trabalho de Alistair Mavin e colegas, o EARS reduz bastante a ambiguidade e a prolixidade dos requisitos.
Para a base teórica, vale o livro Specification by Example, do Gojko Adzic (Manning), que documenta como times ágeis alinhavam requisitos antes mesmo da IA.
Produtos populares
Para acompanhar esse ritmo em casa, vale investir num bom setup home office de programador.
Equipamentos recomendados.
Testados pela redação do techknow pra quem trabalha de casa:
Para ir além: se você quer levar o SDD para o dia a dia, dois recursos ajudam. O livro abaixo cobre o uso de IA em todas as etapas do desenvolvimento, do planejamento aos testes. E rodar o Claude Code com vários agentes e o projeto aberto pede ao menos 16 GB de RAM, como no notebook sugerido.
Conclusão
Portanto, o spec driven development representa a evolução natural de programar com IA. A metodologia preserva a velocidade dos agentes e adiciona disciplina, sem voltar à burocracia da cascata. Além disso, 2026 tornou a adoção mais fácil: o Spec Kit chegou à versão 1.0, o OpenSpec amadureceu e o Claude Code já traz plan mode, skills e hooks de fábrica.
Primeiro, escolha um projeto pequeno para experimentar. Em seguida, crie um CLAUDE.md ou instale o Spec Kit. Por fim, escreva sua primeira spec hoje mesmo e compare o resultado com o fluxo antigo. Lembre-se: a spec não substitui o código, ela orienta a IA a gerar o código certo.
Publicidade
Este artigo contém links de afiliado — se você comprar, podemos receber uma pequena comissão sem custo adicional pra você. Nossas recomendações seguem critérios próprios e independem de comissão.
