O que é spec driven development e como ele muda a forma de programar com IA?

Fala aí, beleza? Tem um tipo de bug novo rolando: o código que compila, roda, parece certinho e mesmo assim não é o que você pediu

Quando quem digita o código é o modelo, a especificação para de ser burocracia de projeto grande e vira o artefato central do trabalho

É exatamente isso que o spec driven development propõe, e é isso que a gente vai destrinchar aqui: o que é uma spec, qual problema ela resolve quando a IA escreve o código e em que momento do projeto ela entra

De onde vem a ideia (e por que ela voltou agora)

A ideia não nasceu ontem, se liga

Ela foi formalizada academicamente em 2004, como sinergia entre test-driven development (TDD) e design by contract (DbC), e teve um renascimento nos anos 2020 puxado pelos fluxos agênticos com LLM

Do outro lado da moeda tem o vibe coding, termo cunhado por Andrej Karpathy num post no X de 2 de fevereiro de 2025

O negócio pegou tanto que virou palavra do ano de 2025 no Collins Dictionary, olha o tamanho da coisa 😀

Aí a conta chegou

O SDD é apresentado justamente como resposta ao modo de falha do vibe coding com LLMs: não é uma moda paralela competindo por atenção, é o contragolpe de um problema que apareceu na prática

O que muda na prática quando a IA escreve o código

A frase que resume tudo é essa: o gargalo saiu de escrever sintaxe e foi para definir intenção

Digitar código deixou de ser a parte cara

O que ficou caro foi explicar, sem ambiguidade, o que o sistema tem que fazer

O modo de falha que a spec ataca

O SDD nasce mirando três coisas bem específicas que acontecem quando um LLM conduz o desenvolvimento:

• código plausível que desvia da intenção (parece certo, faz outra coisa)
• alucinação de APIs que não existem
• degradação conforme o projeto cresce

Repare que nenhuma das três se resolve com prompt melhor no meio da geração

As três se resolvem antes, definindo a intenção

A mudança de rotina

Na prática o seu tempo migra de lugar

Sai do prompt improvisado, aquele que você escreve na hora e reescreve três vezes, e vai pro documento que o agente lê antes de gerar qualquer linha

No contexto de IA o SDD é descrito como abordagem spec-first: o time define guardrails (limites), requisitos, restrições, critérios de aceite e casos de borda ANTES de a IA gerar código, testes e artefatos

A spec é o artefato primário, o código passa a ser derivado dela

Vibe coding x spec driven development: qual a diferença

Não é ferramenta contra ferramenta, é método contra método

O ponto central da tabela é a linha do meio

No vibe coding a decisão nasce junto com o código

No SDD a decisão já existe quando o código nasce, beleza?

O que você precisa para começar

A lista é curtinha

1) Um agente de código compatível. O Spec Kit, toolkit open source de spec-driven development mantido pelo GitHub, funciona com mais de 30 agentes de código, entre CLIs e assistentes de IDE

Na lista de integrações nomeadas estão Claude Code, GitHub Copilot, Gemini CLI, Cursor, Windsurf, Codex CLI e Kiro CLI, e ainda existe uma integração genérica pra quem usa outra coisa

2) A CLI Specify. É ela que inicia o Spec Kit, é escrita em Python e pode ser rodada sem instalação permanente via uvx

Ou seja: dá pra experimentar sem sujar a máquina, o que já ajuda bastante 🙂

Como funciona o fluxo de uma spec, do princípio à tarefa

Bora ver na prática?

A inicialização do projeto é assim:

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

Dá pra já declarar qual agente vai conduzir, por flag: --integration claude, --integration gemini ou --integration copilot

Daí pra frente o processo é conduzido por slash commands com prefixo /speckit.:

1. /speckit.constitution: estabelece os princípios do projeto, que viram o arquivo constitution.md
2. /speckit.specify: escreve os requisitos e histórias no spec.md, o coração da coisa
3. /speckit.clarify: resolve as ambiguidades da spec. Erro comum deste passo: pular ele porque "tá claro pra mim". O que é óbvio na sua cabeça é exatamente o que o modelo vai preencher por conta própria
4. /speckit.plan: gera o desenho técnico no plan.md
5. /speckit.checklist: monta a lista de verificação do que foi definido
6. /speckit.tasks: quebra tudo no tasks.md, uma lista de tarefas ordenada por dependência
7. /speckit.analyze: analisa o conjunto antes de sair gerando
8. /speckit.implement: aí sim, a implementação
9. /speckit.converge: fecha o ciclo

Os artefatos do processo são arquivos markdown, e isso é de propósito: constitution.md (princípios), spec.md (requisitos e histórias), plan.md (desenho técnico) e tasks.md (tarefas ordenadas por dependência)

Tudo texto, tudo versionável, tudo revisável em pull request

O recorte do Kiro: a mesma ideia, outro formato

O Kiro (AWS) materializa a mesma coisa com três arquivos que representam três fases do fluxo

Uma spec de funcionalidade lá é composta por requirements.md (histórias e critérios de aceite), design.md (arquitetura técnica e considerações de implementação) e tasks.md (plano de implementação em tarefas rastreáveis)

Se você quiser ver de perto o fluxo de specs do Kiro, tem post separado só sobre isso aqui no blog

E tem um detalhe que eu acho MUITO massa: o requirements.md do Kiro usa a notação EARS pra escrever requisitos estruturados e testáveis, no formato WHEN/THEN

Que notação? EARS é Easy Approach to Requirements Syntax

A estrutura geral segue uma ordem fixa de cláusulas, com vocabulário limitado de palavras-chave:

WHILE <pré-condição>, WHEN <gatilho>, the <sistema> SHALL <resposta>

Ela não veio do mundo de IA, veio da aviação: foi criada por Alistair Mavin e colegas na Rolls-Royce plc, durante a análise de regulamentos de aeronavegabilidade de um sistema de controle de motor, e publicada na conferência IEEE RE’09

Erro comum deste passo: escrever requisito que não dá pra testar

"o sistema deve ser rápido" não é requisito, é sentimento

A camisa de força do EARS existe exatamente pra te obrigar a dizer em que condição, disparado por quê, o sistema faz o quê

E o plan mode do Claude Code?

Se você não quer adotar toolkit nenhum agora, tem um jeito nativo de separar planejar de executar

No Claude Code, o plan mode é um dos modos de permissão, e você chega nele ciclando com Shift+Tab a partir do modo normal (passa primeiro pelo Auto-Accept, depois aparece o indicador plan mode on)

Nesse modo o modelo explora o código e produz um plano sem editar arquivos: as ferramentas de leitura rodam normalmente e as edições de arquivo nunca são auto-aprovadas, mesmo com regra de allow correspondente

Não é uma spec versionada, é outro nível de compromisso, mas já resolve o pior sintoma: o agente sair codando antes de você concordar com o caminho

Quando vale escrever uma spec (e quando é exagero)

Vale a pena quando:

• a funcionalidade tem regra de negócio de verdade e casos de borda que ninguém lembra de cabeça
• o trabalho é em time, e a intenção precisa sobreviver a quem não estava na conversa (o chat de outra pessoa não é documentação)
• o projeto já cresceu e degrada a cada nova geração, aquele clássico de arrumar aqui e quebrar ali

É exagero quando:

• é script descartável, daqueles que rodam uma vez e vão pro lixo
• é experimento de uma tarde, só pra ver se a ideia se sustenta

Nesses dois casos a spec custa mais do que entrega, e tudo bem admitir isso

O que eu aprendi rodando spec driven development de verdade

SDD não é conceito novo, isso eu faço questão de repetir

Ele voltou a ser falado porque muito projeto feito no vibe coding sem planejamento simplesmente não estava dando certo

O padrão que eu mais vejo é esse: a pessoa manda prompt, às vezes escreve um documentinho curto, sai desenvolvendo e trava quando o projeto cresce, ou vê o consumo de tokens explodir porque uma funcionalidade nova obrigou a reescrever a regra de negócio inteira

A imagem que eu uso é meio grosseira, mas funciona: vibe coding sem SDD é um corpo sem cabeça

A ideia é boa, só que não tem condução

O SDD entra como baliza, um guard rail que mantém o projeto na curva

Sem planejamento, quem decide é a IA

Sem base de planejamento a IA escolhe a stack sozinha, planeja as features pela própria base de conhecimento e te entrega um design fora do que você queria

Já me aconteceu de pedir algo sóbrio e premium e receber um visual chamativo, bem o oposto

E tem o efeito que engana: no começo o avanço é rapidíssimo, depois você trava em coisa boba por causa de decisão ruim tomada lá no início

Vibe coding solto ainda serve, viu? Pra aplicação simples e projeto pessoal segue valendo

O problema aparece quando a intenção é comercializar e crescer

Os três documentos que eu uso

O SDD inverte a ordem: base forte de planejamento primeiro (requisitos, design do sistema incluindo comportamento, UI e UX, e escopo de tarefas), programação depois

Na área técnica eu vivi isso de outro jeito: reunião de planejamento com cliente e com os setores que iam usar o sistema, tudo antes de qualquer linha de código

Minha divisão é essa:

• requirements: o que o app faz
• design doc: como será construído (stack, esquema de banco, rotas, páginas, componentes, decisões técnicas)
• task list: a ordem das tarefas a executar

Três etapas é o padrão que eu sugiro, mas dá pra ser mais ou menos dependendo do projeto

Dividir em escopo de tarefas limita o que o agente faz em cada parte do sistema e melhora MUITO a entrega, bem melhor do que pedir tudo de uma vez

A granularidade que eu considero certa: cada prompt executa uma tarefa concreta com resultado visível no sistema, tipo uma página ou um recurso complexo

Ajuste de cor não é tarefa, é polimento

As dúvidas que sempre aparecem

"E quem não sabe programar?"

Dá pra se apoiar na própria IA pra definir a stack

O resultado não iguala um arquiteto experiente, óbvio, mas é bem melhor do que deixar a IA escolher as tecnologias solta

"E o esquema de banco, que eu não sei definir tipo?"

Basta listar quais dados você quer salvar: nome, e-mail, senha, e por aí vai

O grosso do requirements não exige conhecimento técnico, é aí que mora a boa notícia 🙂

Minha régua de quando usar: se o projeto passa de três prompts, ou se envolve autenticação, pagamento, perfis de usuário e dashboard, provavelmente compensa

E o outro lado, que eu não escondo: SDD custa mais tokens no planejamento

Pra projeto pessoal que ninguém vai usar, pode ser queima de token à toa

O que eu faço diferente

Eu cocrio os documentos com a IA, não deixo ela escrever tudo

Quando ela escreve sozinha o texto sai mais rígido e menos natural, e a parte que VOCÊ sabe (as funcionalidades e a jornada do usuário) tem que vir de você

Meu requirements começa com uma visão geral curta e depois detalha funcionalidade por funcionalidade

E tem uma seção que eu considero a mais subestimada de todas: o que o app NÃO faz

Listar as não-funcionalidades é o que impede a IA de inventar escopo

O design doc pode ser longo e detalhado, sem medo, ao contrário dos arquivos de contexto do agente, que precisam ficar sucintos

A task list eu ordeno por dependência e criticidade: começo pela parte complexa e vital (autenticação), depois geração, salvamento e dashboard, e fecho com uma tarefa de polimento pra aparar arestas

Com os três documentos prontos eu inicio o agente (uso Claude Code por ser o que mais uso no momento, mas o método serve pra outros agentes) e condenso os documentos no contexto do agente antes de começar a codar

E olha, esse fluxo é um SDD montado à mão

Existe forma mais automatizada de fazer isso, inclusive dá pra empacotar o processo em uma skill de spec-driven development e reusar em todo projeto novo

No vídeo abaixo eu mostro esse fluxo rodando de ponta a ponta num gerador de QR code (sem login gera e baixa o código, com login salva e gerencia), com os três documentos aparecendo na tela e a task list sendo executada, coisa que texto nenhum consegue mostrar direito:

Por onde começar

Se você levar uma frase só daqui, leve essa: definir a intenção antes de gerar o código

O resto é formato

O próximo passo pode ser pequeno, não precisa refundar o seu projeto hoje

Escolha UMA funcionalidade e escreva a spec dela antes do próximo prompt, com os critérios de aceite e os casos de borda no papel

Ou, se você usa Claude Code, cicle com Shift+Tab até o plan mode on e deixe o modelo explorar e propor o plano sem tocar em arquivo

E se você quiser o toolkit pronto em vez do processo à mão, o repositório github/spec-kit é o ponto de partida: é open source, mantido pelo GitHub e tem uma comunidade grande em volta, então material não vai faltar

Bora planejar antes de pedir código? até o próximo post! =)