Do código à spec: o que é Spec Driven Development e por que ele muda tudo

Percebi que parei de escrever código

Outro dia fiz uma conta rápida e levei um susto: na última semana, passei mais tempo escrevendo texto do que código. Não era documentação para cumprir tabela, nem e-mail. Era a descrição do que o sistema precisava fazer, com regras, exceções e critérios de aceite. O código? Quem escreveu foi um agente de IA, a partir desse texto.

No começo isso me deu um certo desconforto. Passei anos me orgulhando de escrever um código limpo, de conhecer os atalhos da linguagem, de achar o bug que ninguém achava. E de repente o meu trabalho mais importante virou outro: dizer com clareza o que eu quero.

Esse jeito novo de trabalhar ganhou nome: Spec Driven Development, ou desenvolvimento guiado por especificação. Neste artigo eu quero contar o que é isso, por que eu acho que não é só mais uma moda, e como ele se encaixa numa história que começou lá nos cartões perfurados. Spoiler: a gente vem fugindo do código há setenta anos.

Afinal, o que é uma spec?

Spec é apelido de especificação: um texto que descreve o que o software deve fazer e por quê, sem se prender ao como. Pense na planta de uma casa. O pedreiro não precisa adivinhar onde vai a porta, porque está tudo desenhado. A spec é a planta do software.

O que muda em relação aos velhos documentos de requisitos é o leitor. Antes, quem lia a especificação era um humano, que interpretava, preenchia lacunas e, às vezes, ignorava tudo. Hoje o primeiro leitor costuma ser um agente de IA, que pega a spec e transforma em plano, tarefas e código. Por isso ela precisa ser clara, verificável e viva, guardada no repositório junto com o código.

Uma spec boa costuma ter quatro coisas:

• Objetivo: que problema estou resolvendo e para quem.
• Comportamento: o que o sistema faz, contado como histórias de usuário.
• Critérios de aceite: como eu sei que ficou pronto, de um jeito que dá para testar.
• Restrições: o que não pode acontecer, regras de negócio, limites técnicos.

Para ficar menos abstrato, olha um pedaço de spec de verdade, do tipo que eu escreveria hoje para uma funcionalidade de recuperação de senha:

# Recuperação de senha

## Objetivo
Permitir que o usuário volte a acessar a conta sem falar com o suporte.

## História
Como usuário que esqueceu a senha, quero receber um link por e-mail
para criar uma nova senha.

## Critérios de aceite
- QUANDO o usuário informar um e-mail cadastrado, o sistema DEVE
  enviar um link de redefinição válido por 30 minutos.
- QUANDO o e-mail não estiver cadastrado, o sistema DEVE mostrar a
  mesma mensagem de sucesso (para não revelar quem tem conta).
- SE o link já tiver sido usado, o sistema DEVE recusá-lo.

## Fora do escopo
- Recuperação por SMS.

Repara que não tem uma linha de código ali, nem nome de framework. Mesmo assim, qualquer pessoa (ou agente) que leia sabe exatamente o que construir e como testar. Esse “QUANDO… DEVE” não é enfeite: ferramentas como o Kiro, da AWS, usam uma notação chamada EARS justamente para escrever requisitos assim, sem ambiguidade.

Um pouco de história: a eterna briga entre intenção e máquina

Se tem uma coisa que eu aprendi olhando para trás, é que a história do software é a história de uma distância: entre o que a gente quer e o que a máquina entende. Cada grande virada foi uma tentativa de encurtar esse caminho.

Anos 40 e 50: falando a língua da máquina

No começo, programar era literalmente mexer em hardware: plugar cabos, perfurar cartões, escrever zeros e uns. Depois veio o Assembly, que trocou os números por apelidos como ADD e MOV. Ajudou, mas você ainda pensava como o processador.

Em 1957 a IBM lançou o Fortran, e a ideia era revolucionária: o cientista escreveria fórmulas parecidas com matemática, e um programa (o compilador) traduziria para a máquina. Teve muita gente torcendo o nariz, dizendo que código gerado nunca seria tão bom quanto o escrito à mão. Soa familiar?

1968 a 1990: a crise e os documentos gigantes

Em 1968, numa conferência da OTAN, o pessoal admitiu em voz alta que existia uma “crise do software”: projetos atrasados, caros e cheios de bugs. Foi ali que o termo engenharia de software pegou.

A resposta da época foi o modelo em cascata: primeiro você escreve um documento de requisitos enorme, depois o projeto, depois o código, depois os testes. Na teoria, linda. Na prática, a spec ficava desatualizada no dia seguinte, e ninguém mais abria aquele calhamaço. O código virava a única verdade.

Anos 90: a promessa de gerar código a partir de desenhos

Nos anos 90 veio a UML e, logo depois, a ideia de arquitetura dirigida por modelos: você desenha diagramas e a ferramenta gera o código. Não pegou. Os modelos eram rígidos demais, as ferramentas caras demais, e o código gerado precisava ser remendado à mão, o que matava a sincronia.

2001 em diante: o Ágil e o código como documentação

Em 2001 o Manifesto Ágil virou a mesa: software funcionando importa mais que documentação abrangente. Foi um alívio, e com razão. Mas o pêndulo foi longe: em muitos times, a “spec” virou um post-it no quadro e uma conversa no corredor. O código passou a ser a documentação.

No meio disso surgiram ideias que hoje parecem visionárias, como o TDD e o BDD, com seu famoso Dado… Quando… Então. Eram tentativas de escrever a intenção num formato que a máquina conseguisse verificar. Guarda essa ideia, porque ela volta.

2023 a 2025: a máquina aprende a ler a nossa língua

Aí vieram os grandes modelos de linguagem, e pela primeira vez a máquina passou a entender texto comum razoavelmente bem. O Andrej Karpathy brincou que a linguagem de programação mais quente do momento era o inglês. Em 2025 ele cunhou o termo vibe coding: você conversa com a IA, aceita o que ela gera e vai no embalo. E logo depois apareceram as ferramentas que organizam isso tudo em torno de uma spec, como o Kiro, da AWS, e o Spec Kit, do GitHub.

O padrão que se repete: cada geração sobe um degrau

Quando eu coloco essa história em fila, aparece um padrão claro. Cada geração sobe um degrau de abstração: a gente para de dizer como a máquina deve fazer e passa a dizer o que quer. E em todo degrau novo, o anterior não some; ele vira algo que uma ferramenta gera para a gente.

Ninguém hoje escreve Assembly para fazer um site, porque o compilador faz isso. Do mesmo jeito, cada vez menos gente vai escrever à mão o código de um CRUD, porque o agente faz isso a partir da spec. O degrau de cima é sempre onde mora a intenção humana.

O que mudou agora: do vibe coding à spec

A grande novidade é que, pela primeira vez, o “compilador” entende intenção. Antes, o degrau mais alto que a máquina conseguia ler era uma linguagem de programação. Agora ela lê um parágrafo em português. Isso muda quem faz o trabalho pesado: digitar código ficou barato, quase de graça. O que ficou caro é saber exatamente o que pedir.

E aí entra o vibe coding. Para um protótipo de fim de semana, é mágico: você descreve, a IA faz rápido. Você pede um ajuste, ela ajusta. O problema aparece quando o projeto cresce. A intenção fica espalhada em cinquenta mensagens de chat que ninguém vai reler. A IA esquece o que foi combinado lá atrás. Cada pedido novo conserta uma coisa e quebra outra. Já passei por isso e não foi bonito.

O próprio GitHub resumiu bem o problema quando lançou o Spec Kit: prompts soltos geram código que compila, mas que não faz o que você queria, ou que escolhe tecnologias que você jamais colocaria em produção. A proposta deles é transformar a spec na fonte de verdade compartilhada, contra a qual a IA executa e é validada a cada passo.

Eu gosto de pensar assim: o vibe coding é uma conversa; o Spec Driven Development é um contrato. A conversa é ótima para descobrir o que você quer. O contrato é o que garante que todo mundo, humano ou agente, entregue a mesma coisa.

Como funciona na prática

No dia a dia, o SDD é um ciclo bem simples. As ferramentas variam nos nomes, mas a lógica é a mesma: o Spec Kit, do GitHub, organiza o trabalho em spec, depois plano técnico, depois tarefas pequenas e testáveis que os agentes implementam. O Kiro faz algo parecido, gerando três arquivos: requirements.md, design.md e tasks.md.

O segredo está na seta tracejada. Quando um teste falha ou o cliente muda de ideia, eu não saio remendando o código. Eu volto na spec, ajusto o texto, e deixo o ciclo rodar de novo. Parece mais lento, mas é o que mantém spec e código dizendo a mesma coisa.

Uma dica que vale ouro: antes de tudo isso, muita gente escreve uma espécie de “constituição” do projeto, com os princípios que não se negociam (padrões de código, segurança, testes obrigatórios). O Spec Kit tem um comando só para isso. É como combinar as regras da casa antes de chamar os pedreiros.

O código virou consequência

Esta é a parte que mais mexeu com a minha cabeça. Durante a carreira inteira, eu tratei o código como a verdade. Documento mentia, reunião era esquecida, mas o código dizia exatamente o que o sistema fazia. No SDD essa relação se inverte: a spec é a verdade, e o código é um artefato derivado dela.

O próprio GitHub, ao apresentar o Spec Kit, diz que no SDD as especificações se tornam executáveis, gerando a implementação em vez de apenas orientá-la. Eu acho a comparação com o compilador perfeita. Ninguém abre o binário gerado para corrigir um bug; a gente corrige o fonte e compila de novo. No SDD, o “fonte” passou a ser a spec.

Na prática, isso traz umas vantagens que eu não esperava:

• Trocar de tecnologia fica menos assustador. Se a spec descreve o comportamento sem amarrar a stack, dá para regerar o serviço em outra linguagem e conferir contra os mesmos critérios.
• Gente nova entende o sistema mais rápido. Ler uma spec de duas páginas é bem mais fácil que ler cinco mil linhas de código.
• Quem não programa participa. Produto, design e negócio conseguem revisar uma spec. Código, nem tanto.

Nem tudo são flores

Seria desonesto da minha parte vender o SDD como bala de prata. Já tropecei em algumas armadilhas, e vale contar.

• A volta da cascata. Se eu exagero no detalhe, a spec vira aquele calhamaço dos anos 80, e o time trava esperando o documento perfeito. O consultor Gojko Adzic, que escreveu bastante sobre especificação, alerta justamente para isso: o SDD pode trazer de volta a rigidez da qual o Ágil fugiu. O antídoto, para mim, é spec pequena e por funcionalidade, nunca do sistema inteiro.
• Spec que mente. Se alguém corrige um bug direto no código e não atualiza a spec, as duas se separam e eu volto ao velho problema. A regra que adotei: mudou comportamento, mudou a spec primeiro.
• Revisar continua sendo obrigatório. A IA segue a spec, mas pode seguir errado. Ler o plano e o código gerado não é opcional, principalmente em segurança e desempenho.
• Nem tudo merece spec. Um script de dez linhas para renomear arquivos não precisa de cerimônia. O SDD brilha em funcionalidades que vão durar e ser mexidas por várias pessoas.

E tem uma coisa que continua sendo 100% nossa: o julgamento. Saber o que vale construir, quais trade-offs aceitar, o que o usuário realmente precisa. Nenhuma spec se escreve sozinha, e uma spec ruim gera, com muita eficiência, um software ruim.

Fechando: de digitador de código a autor de intenção

Quando eu olho a linha do tempo inteira, o SDD não me parece uma ruptura. Parece o próximo degrau de uma escada que a gente sobe desde 1957. O Fortran tirou o cientista do código de máquina; a IA está tirando o desenvolvedor da digitação. Em todas as viradas teve gente com medo de perder o ofício, e em todas o ofício só mudou de lugar.

O lugar novo, para mim, é este: entender o problema a fundo, escrever com clareza e revisar com olho crítico. Parece pouco técnico, mas não é. Escrever uma boa spec exige saber de arquitetura, de dados, de segurança e de gente. Só que agora esse conhecimento vai para o texto, e o texto vira software.

Se eu tivesse que deixar um conselho, seria: treine a escrita. Pegue a próxima funcionalidade que você for fazer e, antes de abrir o editor, escreva uma página dizendo o que ela faz, como você vai saber que ficou pronta e o que ela não pode fazer. Depois entregue essa página para um agente e veja o que acontece. Eu aposto que você vai se surpreender, e que vai começar a ver o código do jeito que eu vejo hoje: como consequência, não como ponto de partida.