Spec driven development ou desenvolvimento tradicional: qual muda mais o seu dia a dia?

Fala aí, beleza? Existe um tipo de código que é pior do que o código quebrado: o código plausível

Aquele que roda de primeira, tem nome de variável bonito, passa no lint e mesmo assim faz uma coisa que ninguém pediu

Se você chegou aqui pesquisando a sigla SDD, a pergunta real provavelmente é essa: isso muda mesmo o meu dia a dia ou é só mais um processo pra escrever documento que ninguém lê?

Bora comparar spec driven development e o jeito tradicional (ticket solto, direto no editor) olhando onde cada um gasta tempo, onde cada um erra e que tipo de projeto favorece cada abordagem

O que é spec driven development (e por que ele apareceu agora)

Spec driven development (SDD) é a metodologia em que a especificação versionada, e não o código, é a fonte da verdade

A ordem inverte: primeiro se escreve o que o sistema deve fazer, depois um plano técnico, depois tarefas atômicas e só então o código é gerado

A spec vira contrato

O código vira artefato derivado e verificável, ou seja, dá pra olhar pro que foi entregue e checar contra o que estava escrito

Repara que isso não tem nada de mágico, é planejamento de software de sempre com um detalhe novo: agora quem escreve o código na maior parte do tempo é um agente, e agente não adivinha intenção, ele preenche lacuna

E é justamente aí que o SDD apareceu

Ele nasceu em 2025 como reação ao modo de falha do vibe coding: código plausível que se afasta da intenção, alucina APIs e degrada conforme o projeto cresce

Em 2026 virou padrão de mercado, com as principais ferramentas de codificação com IA ganhando cada uma a sua variação: GitHub Spec Kit, AWS Kiro, Claude Code, Cursor, OpenSpec, BMAD, Tessl e Google Antigravity

Se você quer a base conceitual antes do comparativo, eu já destrinchei o que é SDD na prática por aqui

SDD x desenvolvimento tradicional: onde cada um gasta o tempo

A comparação honesta não é "qual é melhor", é onde cada um cobra o pedágio

A linha mais importante dessa tabela é a de tamanho de tarefa

SDD não escala pra baixo: existe crítica documentada de que, em refatorações simples ou ajustes de UI, o desenvolvedor gasta mais tempo administrando a IA do que entregando

Quando adotar SDD e quando o ticket solto ganha

Cenário 1: feature nova com regra de negócio de verdade

Aqui o SDD ganha fácil, porque a regra precisa estar escrita em algum lugar antes de virar código, senão o agente inventa a regra por você

Cenário 2: projeto em time, com handoff pra agente

Ganha também: o documento é o que faz duas pessoas (ou uma pessoa e três agentes) construírem a mesma coisa

Cenário 3: trocar a cor de um botão, renomear função, extrair componente

Perde, e perde feio

Montar constituição, spec, plano e lista de tarefas pra mexer em quinze linhas é o clássico processo mais caro que o trabalho

A régua que eu uso pra decidir é bem prática: se o projeto passa de uns três prompts, ou se eu já prevejo autenticação, pagamento, perfis de usuário e dashboard, provavelmente compensa planejar antes

Aplicação simples e projeto pessoal? Vibe coding solto resolve, sem drama

E tem o custo que quase ninguém fala: planejamento consome tokens a mais

Pra um projeto que ninguém vai usar, isso é desperdício puro

Como o fluxo funciona na prática: do SDD na mão ao Spec Kit

No vídeo abaixo eu monto um SDD na mão, sem framework nenhum, justamente pra mostrar que o método vem antes da ferramenta

O exemplo é um gerador de QR code: sem login, gera e baixa o código (texto, wi-fi, contato) e, com login, salva e gerencia os códigos criados

O formato que eu uso são três documentos:

• requirements: o que o app faz, funcionalidade por funcionalidade, mais regras de negócio e requisitos não funcionais
• design doc: como será construído (stack, esquema de banco, rotas, páginas, componentes e decisões técnicas)
• lista de tarefas: a ordem de execução

No requirements eu incluo uma seção de o que o app NÃO faz, e essa é a parte que mais salva a pele, porque é o que impede a IA de inventar recurso

O grosso desse documento não exige conhecimento técnico, viu? É funcionalidade e jornada do usuário, coisa que quem teve a ideia domina melhor do que qualquer modelo

No esquema de banco, basta definir quais dados você quer salvar, mesmo sem saber o tipo exato de cada campo

E a ordem de tarefas que eu considero lógica é: setup inicial, autenticação (complexa e vital, então vem cedo), a função principal, os recursos que dependem de login e, por fim, uma etapa de polimento

Cada prompt executa uma tarefa concreta, tipo uma página ou um recurso mais complexo, não um ajuste bobo de cor

Um detalhe que confunde muita gente: documento de planejamento pode ser longo e detalhado, arquivo de contexto do agente precisa ser sucinto

São coisas diferentes, não jogue a spec inteira na memória do agente

Ah, e não delegue tudo pra IA escrever: documento 100% gerado fica mais rígido e menos natural

Cocriação funciona MUITO melhor, com você trazendo funcionalidade e jornada, e a IA ajudando na parte técnica (inclusive na escolha de stack, se você não tem base pra isso: não vai sair coisa de arquiteto experiente, mas é bem melhor do que deixar a IA escolher tecnologia solta)

E a versão com ferramenta?

O SDD na mão é ótimo pra entender o método

Pra automatizar, o caminho mais direto hoje é o spec-kit, mantido no repositório github/spec-kit, sob a organização GitHub, descrito como toolkit para começar com Spec-Driven Development

O setup é assim:

1. Confira os pré-requisitos: Python 3.11+ e o uv, o gerenciador da Astral

O erro comum deste passo é achar que o uv já vem com o sistema operacional: ele não vem, é instalado à parte

2. Instale a CLI

uv tool install specify-cli

Se você preferir sair do uv, dá pra instalar a partir do PyPI:

pipx install specify-cli
# ou
pip install specify-cli

3. Inicialize o projeto com specify init

Ele aceita opções como --here, --force e --no-git

O erro comum aqui é rodar o init esperando trabalhar na pasta atual sem passar --here, que é justamente a opção pra isso

specify init
specify init --here

4. Cheque o ambiente com specify check, e confirme a instalação com specify version

specify check
specify version

Com o ambiente de pé, aí sim entra o fluxo em si, exposto ao agente em cinco comandos de barra:

1. /speckit.constitution pra definir os princípios inegociáveis do projeto

2. /speckit.specify pra capturar os requisitos, que saem no spec.md

3. /speckit.plan pra gerar o plano técnico no plan.md

4. /speckit.tasks pra gerar a lista ordenada no tasks.md

5. /speckit.implement e aí sim o agente escreve o código

Repara que a sequência é exatamente a mesma dos três documentos que eu monto na mão, só que empacotada em comandos de barra

Depois do specify init, esses comandos ficam instalados na pasta do agente dentro do próprio projeto, em pastas como .claude/ ou .github/prompts/, conforme o agente escolhido

E a estrutura de arquivos que aparece no projeto é essa:

• .specify com memory, scripts e templates
• a constituição em memory/constitution.md
• os documentos por feature em specs/, numa pasta com o nome da branch, com spec.md, plan.md e tasks.md

Documento por branch, se liga nisso: é o que faz a spec viver junto do código em vez de apodrecer num Notion esquecido

O mesmo método em outras ferramentas: Kiro e o plan mode do Claude Code

SDD não é uma ferramenta só, é um jeito de trabalhar, e cada produto embrulha isso do seu jeito

No Kiro, a IDE agêntica da AWS (que teve GA anunciada em 17 de novembro de 2025, com recursos de time e suporte a CLI), o fluxo spec driven gera três documentos que viram a unidade de trabalho:

• requirements.md com histórias e critérios de aceite
• design.md com arquitetura, diagramas de sequência e decisões técnicas
• tasks.md com o plano de implementação em tarefas rastreáveis

O detalhe interessante é que o requirements.md do Kiro escreve os critérios de aceite na notação EARS (Easy Approach to Requirements Syntax)

E o EARS não é invenção da era da IA, não: ele foi criado 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 publicado na IEEE International Requirements Engineering Conference (RE’09) em 2009

A estrutura da frase é essa:

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

Parece burocrático? Parece

Mas é exatamente essa rigidez que tira a ambiguidade que o agente adoraria preencher no chute

Já no Claude Code existe a versão leve da mesma ideia: o plan mode

Nele o agente pesquisa e propõe as mudanças sem aplicá-las: lê arquivos e roda comandos de shell somente leitura pra explorar, escreve um plano e não edita o código-fonte

Pra entrar, você aperta Shift+Tab ou prefixa um único prompt com /plan

As edições ficam bloqueadas até você aprovar o plano, e dá pra abrir o plano proposto no seu editor de texto padrão com Ctrl+G pra ajustar antes de liberar

Não é um fluxo de arquivos de especificação versionados como o do Spec Kit ou o do Kiro, é outra coisa: é a recomendação da própria documentação do Claude Code de separar pesquisa e planejamento da implementação, pra evitar resolver o problema errado

O que é, no fundo, o coração do desenvolvimento guiado por especificação em versão de bolso

Vale adotar spec driven development no seu dia a dia?

Veredito honesto: vale por tamanho de projeto e maturidade de time, não por hype

O SDD resolve um problema específico, que é o código plausível se afastando da intenção conforme o projeto cresce

Se o seu projeto não cresce, você está pagando por um seguro que não vai usar

E tem os custos reais, que não são pouca coisa:

• spec drift: manter a spec em sincronia com o código cria um imposto de manutenção que cresce com a complexidade do sistema, porque requisitos mudam e restrições mudam
• fadiga de revisor: fatiar em tarefas pequenas e focadas facilita cada revisão, só que aumenta a frequência delas, e em volume alto isso cansa
• não escala pra baixo: em tarefa pequena, o processo custa mais que o trabalho

Ou seja, spec driven development não é upgrade automático

É troca de um tipo de dor (retrabalho e deriva) por outro (manutenção de documento e revisão constante)

Se quiser um contraponto independente antes de escolher ferramenta, vale ler o comparativo entre Kiro, spec-kit e Tessl no site do Martin Fowler, que olha as três abordagens sem torcida

Conclusão

O SDD é planejamento antes do código (requisitos, design e lista de tarefas) funcionando como guard rail pro vibe coding

Ele custa mais tokens no início e pode ser dispensável em projeto pessoal, mas é o que permite escalar quando o projeto tem várias features e intenção comercial

O vibe coding sem planejamento é meio que um corpo sem cabeça: a ideia até é boa, o que falta é condução

Meu próximo passo sugerido é o mais barato possível: pegue a próxima feature de porte médio e rode ela pelo plan mode do Claude Code, que tem custo zero de setup

Se você sentir que o plano evitou retrabalho, aí sim instale a CLI do Spec Kit e suba pro fluxo completo, com os documentos versionados junto do código

E mede, beleza? A pergunta que interessa não é "gostei do processo", é "o retrabalho caiu?"

até o próximo post! 🙂