O que é SDD (spec-driven development) e como funciona na prática?

Fala aí, beleza? Tem uma diferença gigante entre jogar uma tarefa solta no agente e escrever antes, em texto, o que o sistema tem que fazer

No primeiro caso a intenção mora na sua cabeça (e some quando a janela de contexto vira)

No segundo ela vira documento, e o documento é o que manda

É exatamente isso que a sigla SDD (spec-driven development) descreve: uma metodologia em que a especificação é escrita e acordada ANTES do desenvolvimento começar, e passa a ser tratada como fonte de verdade executável, não como papel de reunião que ninguém abre de novo 🙂

Ela apareceu como resposta a um problema bem conhecido de quem usa agente pra codar: o código sai plausível, roda, parece certo… e vai se afastando aos poucos daquilo que você queria

Por que o SDD apareceu agora (e o que ele corrige no vibe coding)

A motivação declarada do SDD é o modo de falha do vibe coding com LLMs

São três sintomas que andam juntos: o agente produz código plausível que dá drift da intenção original, alucina API que não existe e vai degradando conforme o projeto cresce

Enquanto o app tem duas telas, ninguém sente

Quando ele tem autenticação, perfis, painel e regra de negócio, aí a conta chega

Gosto de comparar com fazer um corpo sem cabeça: a ideia é boa, mas não tem condução, e a decisão ruim lá do começo cobra o preço depois, travando o projeto em coisa simples

A spec como fonte única de verdade:

A virada do SDD é de ordem, não de ferramenta

A especificação vem primeiro, é acordada, e o código é derivado dela

Isso inverte a documentação que a gente conhece: em vez de escrever depois, contando o que já foi feito (documentação retrospectiva, aquela que nasce desatualizada), a spec é escrita antes e continua VIVA

Mudou o requisito? Você edita a especificação e regenera a parte de código correspondente

A spec não é um artefato morto ao lado do repo, ela é o repo do ponto de vista da intenção

Ou seja: o SDD funciona como uma baliza (guard rail)

Você usa a mesma ideia, os mesmos prompts, o mesmo agente… só não sai fora da curva

Como funciona o ciclo do SDD na prática, etapa por etapa

O ciclo canônico tem quatro movimentos: escrever a spec do que o sistema deve fazer, derivar um plano de implementação, quebrar em tarefas atômicas e só então gerar o código

Vou destrinchar em cinco passos, porque o refinamento da spec (que ainda faz parte do primeiro movimento) merece linha própria: é justamente ali que a maioria escorrega

Parece burocrático quando você lê assim, mas cada etapa existe pra matar um tipo específico de erro

Bora ver o que entra e o que sai de cada uma?

1. Da intenção escrita para a spec. Entra a descrição em linguagem natural do que você quer, sai um documento com objetivos do usuário, cenários e critérios de aceite. O foco aqui é o QUE e o PORQUÊ, nunca o como. O erro comum deste passo: misturar implementação na spec. No momento que você escreve "criar tabela X com coluna Y", a spec deixou de ser acordo de intenção e virou plano disfarçado, e aí ninguém mais consegue discutir o produto sem discutir código

2. Do refinamento até a spec fechar. Entra a spec crua, sai a spec sem ambiguidade. É a etapa de fazer as perguntas chatas: o que acontece se o usuário não estiver logado, o que é obrigatório, qual o comportamento no erro. O erro comum deste passo: pular o refinamento por pressa. Toda ambiguidade que você não resolve no texto vai ser resolvida pelo agente, sozinho, do jeito dele, e você só descobre qual foi a decisão depois que o código já está escrito

3. Da spec para o plano. Entra o QUE já acordado, sai o COMO: stack, esquema de banco, rotas, páginas, componentes e as decisões técnicas que sustentam aquilo. É aqui que você decide as coisas que depois são caras de mudar, do modelo de dados até o ambiente onde isso vai rodar (e problema de infra tipo lentidão de I/O de disco na VPS é bem mais fácil de prevenir no plano do que de descobrir em produção). O erro comum deste passo: deixar a stack correr solta e escolher tecnologia que o agente conhece mal. Se você não vem da área técnica, apoiar-se na IA pra tomar essa decisão ajuda, mas não substitui um arquiteto experiente, e é bom saber disso

4. Do plano para as tarefas atômicas. Entra o plano, sai uma lista ordenada de tarefas que dá pra executar uma por vez. Ordem por criticidade funciona bem: setup primeiro, depois a parte complexa e vital (autenticação, por exemplo), depois as funcionalidades, e uma tarefa de polimento no fim. O erro comum deste passo: gerar tarefa grande demais. "Implementar a área do usuário" não é tarefa, é epic, e o agente vai improvisar metade dela

5. Das tarefas para o código. Entra uma tarefa por vez, sai implementação. E aqui vem a parte que ninguém conta: os prompts ficam CURTOS e repetitivos. Executa a tarefa 3, segue o design doc, me avisa quando terminar. O erro comum deste passo: voltar a improvisar no meio, pedindo coisa que não está na spec. Se apareceu requisito novo, o certo é subir de volta e editar a especificação, não empurrar por prompt

SDD x pedir tarefa solta para a IA: o que muda em cada etapa

A tabela abaixo compara as duas rotinas no mesmo ponto do processo

SDD com o Spec Kit: instalação e os comandos do fluxo

Dá pra fazer SDD 100% na mão, escrevendo os documentos você mesmo (e funciona!)

Mas existe toolkit pra isso: o Spec Kit é o toolkit open source de spec-driven development publicado no repositório github/spec-kit

A versão 0.11.0, de 16 de junho de 2026, integra com mais de 30 agentes de código, entre eles GitHub Copilot, Claude Code, Cursor, Gemini CLI, Codex CLI e Windsurf

Bora ver na prática?

1. Instale a CLI de forma persistente. O Spec Kit instala uma CLI chamada specify

uv tool install specify-cli

2. Ou rode em uso pontual, sem instalar nada. Dá pra apontar o uvx direto pro repositório git

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> --integration copilot

3. Inicialize o projeto escolhendo o seu agente. É a flag --integration que define isso, e pro Claude Code o valor é claude

specify init <project_name> --integration claude

O erro comum deste passo: rodar em sessão não interativa (CI ou execução via pipe) sem informar a flag. Nesse caso o Spec Kit assume GitHub Copilot como integração padrão, e você fica se perguntando por que os comandos não apareceram no agente que você usa 😀

4. Entenda o que o init deixou na pasta. Ele grava os arquivos de comando na pasta do agente, por exemplo .claude/ pro Claude Code e .github/prompts/ pro Copilot. Depois disso o agente lê esses arquivos direto

O erro comum deste passo: achar que precisa chamar a CLI toda vez. O specify init roda uma vez por projeto (ou no upgrade), o resto do fluxo acontece dentro do agente

5. Use os comandos dentro do agente. Na maioria deles o Spec Kit se expõe como slash commands com prefixo /speckit.. O Codex CLI em modo skills usa $speckit- no lugar. A lista inclui constitution, specify, clarify, plan, checklist, tasks, analyze, implement e converge

6. Comece pelo caminho enxuto se for experimento. É a sequência mais curta que a documentação traz, nesta ordem:

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

7. Vá pro caminho completo quando for feature de produção. Aqui entram os portões de qualidade a mais

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

E o que cada portão faz? O /speckit.constitution cria um documento versionado com os princípios inegociáveis do projeto (princípios centrais, restrições técnicas, convenções de time e regras de governança), rodado uma vez no começo e usado pra avaliar as etapas seguintes

O /speckit.specify gera a especificação a partir da sua descrição em linguagem natural, focada em objetivos do usuário, cenários e critérios de aceite, sem detalhe de implementação

O /speckit.clarify é iterativo: pode rodar várias vezes antes de você seguir pro plano

O /speckit.checklist gera checklists de qualidade que funcionam como teste unitário dos requisitos, validando se cada um está completo, claro, consistente e mensurável

E o /speckit.analyze varre spec.md, plan.md e tasks.md procurando conflito, lacuna e ambiguidade entre eles, além de checar aderência à constitution

8. Saiba onde os artefatos vivem. Cada fase produz um arquivo em Markdown que alimenta a fase seguinte, organizados por feature na pasta specs/

specs/[###-feature]/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
└── tasks.md

Spec Kit, plan mode do Claude Code e Kiro: três formas de fazer SDD

Nem todo mundo precisa do fluxo completo, e nem todo SDD passa por toolkit

Se liga na diferença de formalidade entre os três caminhos

Repara que o plan mode do Claude Code é o SDD em versão mínima: ele lê arquivos, roda comandos de exploração e escreve um plano, mas não mexe no código

E isso não é gambiarra: a própria documentação recomenda separar pesquisa de código em problema complexo, analisando a base no plan mode, refinando o plano na conversa e só depois deixando implementar, porque essa abordagem em duas fases dá resultado melhor que ir direto ao código

Quando vale escrever spec e quando é exagero

Agora a parte honesta: SDD não é pra tudo

O planejamento gasta mais tokens e mais tempo na frente, então em projeto pessoal que ninguém vai usar isso vira queima de token à toa

Minha régua prática é o número de prompts: se o trabalho passa de três prompts, provavelmente compensa

Casos em que vale:

• Feature de produto, coisa que outra pessoa vai usar de verdade
• Projeto com autenticação, pagamento, perfis de usuário e dashboard (ou seja, regra de negócio pra valer)
• Base que já cresceu, onde uma mudança mal pensada respinga em cinco lugares
• Trabalho que precisa de rastro e revisão de outra pessoa, porque a spec é o que dá pra revisar antes de existir código
• Projeto que vai escalar: sem planejamento, uma funcionalidade nova obriga a reescrever a regra de negócio inteira e o consumo de token dispara

Casos em que é exagero:

• Ajuste pontual, aquele fix de uma linha
• Script descartável, que roda uma vez e morre
• Exploração, quando você ainda está descobrindo se a ideia faz sentido
• Projeto pessoal que não vai crescer nem sair da sua máquina

Dá pra pensar no processo tradicional da área técnica, aliás: reunião de planejamento, conversa com quem vai usar, entendimento do problema antes de sair programando

O SDD é isso, só que o documento final é lido por um agente também 😀

O que mudou no meu fluxo depois de adotar SDD

No vídeo abaixo eu monto um gerador de QR code do zero usando SDD, e dá pra ver o fluxo inteiro na tela

Eu estruturei o planejamento em três documentos, que é o número de etapas que eu sugiro (pode variar, mas três dá conta): o requirements, dizendo o que o app faz, o design doc, dizendo como vai ser construído, e a task list, com a ordem das tarefas, uma tarefa por prompt

Depois eu condensei os três num arquivo de contexto pro agente entender do que se trata o projeto

A task list eu ordenei por criticidade: setup inicial, depois a autenticação (por ser complexa e vital), depois a geração do QR code, depois salvar e a dashboard, e fechei com uma tarefa de polimento

O que me chamou atenção na execução: a autenticação saiu em cerca de 2 minutos

Quando eu começo projeto sem SDD, essa mesma parte costuma me tomar mais de 10 minutos de vai e volta

A aplicação subiu na porta 3002, gerei um QR code em tempo real, baixei o PNG, escaneei com o celular, o link abriu, e o login validou também

E tem uma coisa que é mais sensação do que número: depois do planejamento, os prompts ficaram curtos e repetitivos

Eu parei de caprichar em cada prompt, porque o capricho já estava no design doc

Só pra deixar claro: isso é observação de UM projeto meu, na minha máquina, não é benchmark

Os números acima valem como ordem de grandeza do que eu vi ali, não como promessa de desempenho

No vídeo dá pra acompanhar a montagem dos três documentos, a execução tarefa por tarefa e o teste da aplicação rodando de verdade

Conclusão

SDD (spec-driven development) é, no fundo, uma inversão simples: escrever a intenção ANTES, tratar essa especificação como fonte única de verdade e mantê-la viva conforme o requisito muda

O ciclo é sempre o mesmo: spec, plano, tarefas atômicas, código

O que muda é o quanto de formalidade você coloca, do plan mode nativo do Claude Code (Shift+Tab e pronto) até o caminho completo do Spec Kit com clarify, checklist e analyze

Meu conselho de próximo passo: pega uma feature PEQUENA, roda o caminho enxuto (/speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement) e compara com o jeito antigo de pedir tarefa solta

Se a diferença aparecer no seu contexto, aí sim você sobe pro caminho completo

faça o teste e me conta 😀

até o próximo post!