Spec-Driven Development: o que vem depois do vibe coding?

Se você vem acompanhando o mundo do desenvolvimento, já deve ter esbarrado no termo vibe coding. A ideia era mais ou menos essa: você abre o chat com a IA, descreve o que quer no impulso, aceita o que ela gera, testa, não funciona, pede pra corrigir, aceita de novo... e vai repetindo este processo até parecer que está pronto. 😅

E isso pode funcionar… Pelo menos até certo ponto. Pra um protótipo de fim de semana ou um script rápido, esse fluxo é maravilhoso. O problema aparece quando você tenta usar isso em algo que precisa ir mais longe: um projeto real, com time, com código que outra pessoa vai ler daqui a seis meses. Aí acontece o que a comunidade batizou de drift (o "desvio"): a IA gera um código plausível, que compila, que até roda, mas que foi se afastando aos poucos daquilo que você realmente queria.

E, pior: você não tem nenhum documento que explique a intenção por trás daquelas decisões. O contexto morreu junto com a janela do chat.

O objetivo deste artigo é te apresentar o Spec-Driven Development (SDD), a abordagem que vem substituindo o vibe coding no desenvolvimento assistido por IA. Eu vou apresentar os principais frameworks do momento e, principalmente, detalhar o workflow do Spec Kit — que venho usando nos meus projetos pessoas, mas também nos projetos do meu trabalho, onde também tenho difundindo essa ferramenta.

Uma coisa antes de começar: tudo aqui pressupõe que você já usa algum agente de IA pra programar — Copilot, Cursor, Claude Code, Gemini CLI, tanto faz qual. É em cima dele que o Spec Kit roda. Vamos nessa! 🚀

Afinal, o que é Spec-Driven Development?

Spec-Driven Development (algo como "desenvolvimento guiado por especificação") é uma abordagem em que a especificação passa a ser a fonte da verdade do projeto, e não o código.

Especificação, nesse contexto, é um documento — normalmente em Markdown, versionado no Git junto com o repositório — que descreve o que o software precisa fazer, quais restrições ele tem e quais regras ele nunca pode quebrar. O código deixa de ser o artefato principal e vira uma consequência: ele é gerado e validado a partir daquele documento. Daqui pra frente eu vou chamar esse documento de spec, que é como todo mundo se refere a ele na prática.

A documentação oficial do Spec Kit resume isso de um jeito que eu gosto muito: por décadas o código foi o maioral, e as especificações eram só um andaime que a gente montava e descartava assim que o "trabalho de verdade" começava. O SDD inverte essa lógica.

Uma analogia que costumo usar: o vibe coding é como pedir pra um pedreiro muito habilidoso construir uma casa enquanto você vai apontando com o dedo — "põe uma janela ali", "esse quarto ficou pequeno, aumenta". Ele é rápido e faz bonito, mas ninguém nunca desenhou a planta. Quando você quiser um segundo andar, vai descobrir que a fundação não aguenta. O SDD é você desenhar a planta primeiro, discutir, aprovar... e só então mandar construir.

E olha que interessante: isso só faz sentido agora por causa da IA. Escrever especificação detalhada sempre foi caro e chato, porque um humano ainda teria que traduzir tudo aquilo em código na mão. Com agentes que implementam a partir de um documento bem escrito, a especificação deixa de ser burocracia e vira o insumo mais valioso do processo.

O que muda na prática

O ciclo do vibe coding é curto e caótico:

prompt → código → não funcionou → correção → código → correção → ...

O ciclo do SDD é mais longo, mas tem checkpoints:

especificação → plano técnico → lista de tarefas → implementação → verificação

Parece mais trabalhoso, e no começo é mesmo. A diferença é que cada etapa gera um artefato que você pode ler, revisar e corrigir antes que o erro vire código. Corrigir um parágrafo mal escrito numa spec custa trinta segundos. Corrigir a mesma decisão errada depois de 2.000 linhas geradas custa uma tarde inteira. 😬

Os principais frameworks do momento

Beleza, a ideia é boa. Mas como posso implementar isso na prática?

O ecossistema explodiu em 2025 e não parou de crescer em 2026. Existem literalmente dezenas de ferramentas se dizendo spec-driven, mas quatro nomes concentram boa parte da conversa hoje.

1. GitHub Spec Kit

Toolkit open source do GitHub, instalado via CLI (do inglês Command Line Interface, a interface de linha de comando que você usa no terminal). Ele funciona por cima de mais de 30 agentes diferentes — Copilot, Claude Code, Cursor, Gemini, Codex, Windsurf e outros —, então não te prende a nenhuma IDE nem a nenhum modelo. É o que eu uso, e vou entrar nos detalhes dele na próxima seção.

2. Kiro (AWS)

A IDE agêntica da AWS — ou seja, um editor de código completo (IDE, do inglês Integrated Development Environment) com agentes de IA embutidos no fluxo. Hoje ele também tem uma versão de linha de comando.

O Kiro foi construído do zero em torno da especificação e gera um sistema de três documentos: requirements.md (histórias de usuário escritas em notação EARS, um formato padronizado de requisito do tipo "quando X acontecer, o sistema deve fazer Y"), design.md (arquitetura técnica) e tasks.md (tarefas de implementação). É a experiência mais integrada do mercado — mas a spec, o roteamento dos modelos e a cobrança em créditos ficam todos dentro do ecossistema do Kiro. Você ganha comodidade e perde flexibilidade.

3. BMAD-METHOD

Framework open source (licença MIT) que orquestra mais de doze agentes especializados ao longo do ciclo de vida do software — cada um com um "papel": analista, arquiteto, gerente de produto, pessoa desenvolvedora, QA. É o mais pesado e cerimonioso dos quatro, o que pode ser ótimo pra projetos grandes e exagerado pra funcionalidades pequenas.

4. OpenSpec

O mais leve da lista. É uma camada de CLI que mora dentro do próprio repositório e organiza o trabalho em torno de propostas de mudança: /opsx:propose → /opsx:apply → /opsx:archive.

A sacada dele são os delta specs: cada mudança descreve só o que foi adicionado, modificado ou removido. Quando essa mudança é arquivada, o delta é fundido no diretório openspec/specs/, que representa o estado atual do sistema. Isso gera uma trilha de auditoria bem clara e funciona especialmente bem em código legado.

E qual escolher?

Não existe "o melhor" aqui — depende muito do seu contexto. Se você está começando do zero num projeto pessoal, o peso do BMAD pode te atrapalhar. Se você trabalha numa empresa com auditoria pesada, a rastreabilidade do OpenSpec pode valer mais do que qualquer outra coisa.

Eu escolhi o Spec Kit porque ele é agnóstico de agente e porque o fluxo dele é fácil de ensinar pra um time inteiro — e isso importa muito quando você quer que a prática pegue, não só que funcione pra você.

O workflow do Spec Kit, etapa por etapa

Antes de qualquer coisa, a instalação. O jeito recomendado é pelo uv, um gerenciador de pacotes e ambientes Python — se você ainda não tem, a instalação dele está na documentação oficial do uv.

# Instalação persistente (recomendada)

uv tool install specify-cli

# Cria um projeto novo já com a estrutura do Spec Kit

specify init meu-projeto --integration claude

# Ou inicializa dentro de um projeto que já existe

specify init .

Se você preferir não instalar nada, dá pra rodar direto do repositório com uvx --from git+https://github.com/github/spec-kit.git specify init meu-projeto.

Esse comando não escreve código nenhum. Ele monta a estrutura de diretórios, os templates de documento e — o mais importante — registra os slash commands no agente que você escolher. Ou seja, depois disso, todo o resto do fluxo acontece dentro do chat do seu agente de IA, não no terminal.

O fluxo completo recomendado é este:

/speckit.constitution → /speckit.specify → /speckit.clarify → /speckit.plan → /speckit.checklist → /speckit.tasks → /speckit.analyze → /speckit.implement → /speckit.converge

Parece muita coisa, mas vou destrinchar cada etapa. E já adianto: nem sempre você precisa de todas elas.

1. /speckit.constitution — as regras que nunca mudam

A "constituição" é o documento de princípios do projeto: padrões de teste, estilo de código, restrições de arquitetura, orçamento de performance, regras de experiência do usuário. Ela é escrita uma vez e passa a valer pra todas as specs e implementações que vierem depois.

/speckit.constitution Este projeto segue uma abordagem "Library-First": toda funcionalidade deve ser implementada primeiro como uma biblioteca independente. Usamos TDD de forma estrita. Preferimos padrões de programação funcional.

Repare que nesse exemplo eu declarei três coisas: um padrão de arquitetura, o uso de TDD (do inglês Test-Driven Development, a prática de escrever o teste antes do código) e uma preferência de estilo.

Pense na constituição como uma camada de regras que vale pro projeto inteiro. É o que impede o agente de, na terceira funcionalidade, decidir sozinho que agora vamos usar outro padrão de nomenclatura.

2. /speckit.specify — o que e o porquê

Aqui você descreve a funcionalidade que quer construir. E existe uma regra de ouro nessa etapa: fale sobre o problema, não sobre a solução técnica. Nada de mencionar framework, banco de dados ou biblioteca — isso vem depois.

/speckit.specify Construa uma aplicação que me ajude a organizar minhas fotos em álbuns separados. Os álbuns são agrupados por data e podem ser reorganizados arrastando e soltando na página principal. Álbuns nunca ficam dentro de outros álbuns. Dentro de cada álbum, as fotos são exibidas em uma interface de mosaico.

O agente transforma isso num documento de especificação estruturado, com requisitos, critérios de aceite e cenários. Leia esse documento com calma — é o momento mais barato de discordar de alguma coisa.

3. /speckit.clarify — resolvendo as ambiguidades

Essa é, na minha opinião, a etapa mais subestimada do fluxo. O comando faz até cinco perguntas direcionadas, uma de cada vez, sobre os pontos ambíguos da sua spec — e grava as respostas direto no documento, numa seção ## Clarifications com a data da sessão.

/speckit.clarify Foque nos requisitos de segurança e performance.

Por que isso importa tanto? Porque toda ambiguidade que sobrevive até a implementação vira uma decisão que a IA tomou sozinha, sem te avisar. Esclarecer antes de planejar evita que você projete a arquitetura em cima de uma dúvida.

4. /speckit.plan — agora sim, o “como fazer”

Só nesta etapa você fala de tecnologia. O agente pega a spec já esclarecida e produz um plano técnico de implementação com a stack (o conjunto de tecnologias do projeto), a arquitetura e os contratos entre as partes.

/speckit.plan A aplicação usa Vite com o mínimo possível de bibliotecas. Use HTML, CSS e JavaScript puros sempre que der. As imagens não são enviadas pra lugar nenhum e os metadados ficam num banco SQLite local.

Repare na separação: a spec descreve o problema e sobrevive a uma troca de tecnologia; o plano descreve a solução e é descartável. É isso que permite que você explore duas arquiteturas diferentes pro mesmo requisito.

5. /speckit.checklist — validando a qualidade dos requisitos

O checklist gera uma lista de verificação personalizada pra sua funcionalidade, checando se os requisitos estão completos, claros e consistentes entre si. A documentação chama isso de "testes unitários dos seus requisitos", e eu acho a comparação perfeita: é um code review, só que dos requisitos, antes de existir código.

/speckit.checklist

Ele roda depois do plano justamente porque nessa altura você já sabe o que é tecnicamente viável — e antes de quebrar tudo em tarefas, que é quando o custo de mudar de ideia começa a subir.

6. /speckit.tasks — quebrando em pedaços executáveis

Esse comando gera um tasks.md com as tarefas derivadas do plano, organizadas por história de usuário, ordenadas por dependência, com o caminho exato dos arquivos que vão ser alterados e marcadores [P] nas tarefas que podem rodar em paralelo.

/speckit.tasks

É aqui que o projeto deixa de ser abstrato. Você consegue bater o olho na lista e estimar se aquilo faz sentido. 👨‍💻

Dica pra quem trabalha em time: existe também o /speckit.taskstoissues, que transforma essa lista em issues do GitHub. Ótimo pra quando o planejamento precisa sair do seu repositório local e virar trabalho visível pro resto do pessoal.

7. /speckit.analyze — o portão de qualidade final

O analyze faz uma auditoria cruzada entre os três artefatos: a spec, o plano e as tarefas. Ele procura contradições, requisitos órfãos (que estão na spec mas não viraram tarefa nenhuma) e tarefas que não correspondem a requisito nenhum.

/speckit.analyze

Rode esse comando antes do implement. Você até pode rodar depois como revisão extra, mas a primeira passada tem que acontecer enquanto o plano ainda pode ser ajustado sem custo.

8. /speckit.implement — finalmente, o código

Chegamos ao comando que todo mundo quer rodar logo de cara. Ele não precisa de argumento nenhum: o agente já tem a constituição, a spec, o plano e a lista de tarefas.

/speckit.implement

Na prática, o agente vai percorrendo o tasks.md e marcando as tarefas conforme conclui cada uma, então dá pra acompanhar o progresso lendo o próprio arquivo — o que é bem mais confortável do que ficar caçando o que mudou no histórico do chat.

E aqui vai a dica que mais mudou meus resultados: em projetos grandes, implemente em fases. Peça a fase 1, valide que funciona, depois siga pra fase 2. Mandar tudo de uma vez satura a janela de contexto do agente — a quantidade de texto que o modelo consegue considerar de uma vez só — e a qualidade despenca justamente nas últimas tarefas.

9. /speckit.converge — o código bate com a spec?

Essa é a etapa que eu mais demorei a valorizar, e hoje não abro mão dela. O converge compara o código que existe de verdade no repositório com a spec, o plano e as tarefas, e aponta onde a implementação divergiu da intenção.

/speckit.converge

O detalhe genial é que ele é append-only: nunca edita nem apaga código. A única coisa que ele escreve é uma seção de convergência no tasks.md, com as tarefas que ficaram faltando. Aí você roda implement de novo, roda converge de novo, e repete até ele reportar que convergiu.

É esse laço que fecha o ciclo do SDD. Sem ele, você tem um processo bonito de planejamento e nenhuma garantia de que o resultado final corresponde ao que foi planejado.

Ah, e nem sempre você precisa de tudo isso

Pra experimentos rápidos, o próprio time do Spec Kit recomenda um caminho enxuto:

/speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement → /speckit.converge

Os comandos clarify, checklist e analyze são pontos de verificação de qualidade (quality gates): você os adiciona quando a funcionalidade tem ambiguidade relevante ou vai pra produção. Tratá-los como obrigatórios em tudo é o caminho mais rápido pra abandonar o método por cansaço. 😁

Dois detalhes que vão te economizar tempo

O primeiro é sobre como o Spec Kit sabe em qual funcionalidade você está trabalhando: ele usa um arquivo de estado, o .specify/feature.json (que dá pra sobrescrever com a variável de ambiente SPECIFY_FEATURE_DIRECTORY). Existe uma extensão opcional de Git que cria branches numeradas tipo 001-nome-da-feature, mas quem manda é o arquivo de estado — só trocar de branch não troca a spec ativa.

O segundo é que nem todo agente usa o prefixo /speckit.. O Codex, por exemplo, usa $speckit-*, e o Kimi usa /skill:speckit-*. Vale conferir a documentação da sua integração antes de sair digitando e achar que quebrou tudo.

Vale a pena? Uma dose de honestidade

Eu não vou te vender o SDD como bala de prata, porque ele não é.

O custo é real: você gasta mais tempo antes de ver a primeira linha de código rodando. Pra quem está acostumado com a dopamina do vibe coding, essa espera incomoda. Além disso, os artefatos consomem contexto e tokens (os pedacinhos de texto que o modelo processa, e pelos quais você geralmente paga). E uma spec mal escrita gera um plano ruim, que gera tarefas ruins — lixo entra, lixo sai, só que agora em quatro documentos..

Por outro lado, o que eu ganhei foi bem concreto:

revisões mais objetivas, porque eu revejo a intenção e não só as linhas alteradas;
integração muito mais rápida de pessoas novas no projeto;
a possibilidade de trocar de agente de IA sem perder o contexto, já que ele mora no repositório e não no histórico do chat.

O padrão que muitos times acabam adotando, e que eu acho bem sensato, é um meio-termo: faça vibe coding pra explorar e descobrir o que você quer, destile o resultado numa spec, e então use SDD pra construir a versão de produção. Os dois modos convivem — cada um no seu momento.

Conclusão

Se você quiser experimentar, minha sugestão é começar pequeno: pegue uma funcionalidade média do seu projeto atual, rode o fluxo enxuto do Spec Kit e compare o resultado com o que você teria feito no improviso.

E você, já testou algum framework de SDD? Se sim, me conta qual foi a sua experiência — tenho muita curiosidade de saber se bateu com a minha.

Até a próxima! 🚀