Quem já pediu a uma ferramenta de IA para “criar a tela de cadastro” conhece o resultado: sai uma tela, rápido, e quase certa. O que faltou não estava no código, estava no pedido. Ninguém disse quais campos são obrigatórios, o que acontece com o CPF repetido nem quem pode apagar um registro. A IA preencheu as lacunas com palpites razoáveis, e palpite razoável em produção vira retrabalho.
O spec-driven development nasceu para fechar essas lacunas antes que o código exista. Este guia explica o que é, como o fluxo funciona nas ferramentas mais usadas, o que a avaliação independente diz e, principalmente, a parte que os guias costumam pular: quem na empresa escreve, aprova e guarda a especificação, e quando ela é só peso morto.
O que é spec-driven development?
Spec-driven development, ou desenvolvimento orientado por especificação, é um jeito de trabalhar com assistentes de código em que a especificação é o ponto de partida e a referência de tudo o que vem depois. Em vez de conversar com a IA até o código parecer certo, a equipe escreve antes um documento estruturado com o que deve ser construído, para quem e com quais regras.
Dessa especificação saem, em ordem, um plano técnico, uma lista de tarefas e a implementação. Quando surge dúvida no meio do caminho, a pergunta deixa de ser “o que o código faz?” e passa a ser “o que a spec diz?”. Se a spec estiver errada, corrige-se a spec, e o código é gerado de novo a partir dela.
A Thoughtworks descreve a prática como uma abordagem emergente para fluxos de programação assistida por IA, que geralmente começa por uma especificação funcional estruturada e a quebra em partes menores, soluções e tarefas. A spec pode ser um documento só, vários documentos ou artefatos estruturados que cobrem aspectos diferentes do sistema.
Por que especificar antes voltou a fazer sentido?
Documentar requisitos antes de programar não é novidade em engenharia de software. A novidade é o custo. Escrever uma especificação detalhada sempre foi caro, e a especificação envelhecia assim que o código mudava. Com IA, a mesma ferramenta que gera o código ajuda a escrever a spec, o plano e as tarefas, e consegue regenerar o código quando a spec muda.
Há também uma razão de qualidade. Um assistente de código responde ao que recebe. Pedido vago gera solução genérica; pedido com regras de negócio, restrições e critérios de aceite gera solução que pode ser conferida. A spec é, no fundo, o contexto que a IA não tem como adivinhar, escrito uma vez e reaproveitado em todas as tarefas.
E há uma razão de controle. Quando a IA escreve parte relevante do código de produção, a revisão linha por linha deixa de dar conta do volume. Revisar a intenção, antes, é mais barato do que revisar mil linhas depois, desde que a intenção esteja escrita num tamanho que alguém consiga ler.
Qual a diferença entre spec-driven development e vibe coding?
São quase opostos no mesmo espectro. No vibe coding, a pessoa descreve o que quer em linguagem natural, aceita o que a IA gera e vai ajustando pela conversa, sem ler linha por linha. No SDD, a conversa vira documento, o documento é revisado e só então a IA implementa.
Nenhum dos dois é “o certo”. O vibe coding é ótimo para descobrir o que se quer; o SDD é melhor para construir o que já se sabe que se quer. A diferença prática está no que sobra quando o projeto acaba: no vibe coding sobra o código; no SDD sobram o código e a explicação de por que ele é assim.
| Vibe coding | Spec-driven development | TDD | |
|---|---|---|---|
| Ponto de partida | Um pedido em linguagem natural | Uma especificação escrita e revisada | Um teste automatizado que falha |
| O que é revisado | O resultado, quando é revisado | A intenção, antes do código | O comportamento, teste a teste |
| Unidade de trabalho | A conversa | A funcionalidade inteira | O pequeno comportamento |
| Melhor para | Protótipo e exploração | Funcionalidade crítica ou com vários times | Lógica que precisa de garantia contínua |
| Risco típico | Código que ninguém entende | Spec longa que ninguém lê | Teste que cobre o caso errado |
| O que fica depois | O código | Código + spec versionada | Código + suíte de testes |
Comparativo elaborado pela Alliance Comunicação com base nas três práticas.
Qual a diferença entre SDD e TDD?
O TDD (desenvolvimento orientado por testes) escreve primeiro um teste que falha, depois o código mínimo que o faz passar, e repete. O foco é o comportamento de pequenas unidades de código. O SDD trabalha um nível acima: descreve a funcionalidade inteira, com contexto de negócio, antes de qualquer teste ou código.
Eles não competem. Uma boa spec diz o que precisa ser verdade; os testes provam que é. Na prática, a lista de tarefas gerada a partir da spec pode, e deve, incluir os testes, e os critérios de aceite da spec são a matéria-prima natural desses testes. Quem já pratica TDD tem meio caminho andado: só falta subir um degrau e escrever o porquê.
O que uma spec precisa ter?
Não existe formato único, e cada ferramenta tem o seu. Mas uma spec que serve tanto para a IA quanto para o revisor humano costuma responder a seis perguntas:
- Problema e objetivo: o que está sendo resolvido, para quem e como se saberá que funcionou.
- Comportamento esperado: cenários escritos como “quando acontece X, o sistema faz Y”, incluindo os casos de erro.
- Regras de negócio: limites, permissões, cálculos e exceções que nenhum modelo tem como adivinhar.
- Fora do escopo: o que a funcionalidade deliberadamente não faz. É a seção que mais evita retrabalho.
- Restrições técnicas: sistemas com que precisa conversar, dados sensíveis envolvidos, requisitos de desempenho.
- Critérios de aceite: a lista objetiva que o revisor usa para dizer “está pronto”.
Repare no que não está na lista: a solução técnica detalhada. Ela pertence ao plano, não à spec. Misturar as duas é o caminho mais curto para o documento longo e difícil de revisar de que trata a próxima seção.
Como o fluxo de trabalho muda na prática?
O Spec Kit, kit de código aberto do GitHub sob licença MIT, é o exemplo mais explícito do fluxo, porque transforma cada etapa num comando dentro do assistente de código:
A “constituição” merece atenção. É o conjunto de princípios que valem para todas as funcionalidades do projeto, como padrões de qualidade, de teste e de manutenção. A Thoughtworks destaca justamente esse documento como o diferencial do Spec Kit: regras que precisam ser sempre seguidas, escritas uma vez, em vez de repetidas em cada pedido.
O que muda para a equipe é onde o tempo vai. Antes, ia para escrever código e depois corrigir o que a IA interpretou mal. Agora vai para escrever e revisar a spec e o plano. Se essa revisão for feita de verdade, a implementação vira a parte curta. Se for feita por cima, o fluxo só ganhou mais documentos para ninguém ler.
O mesmo vale para a etapa final. O comando de convergência compara o resultado com o que foi pedido, mas quem decide se o pedido estava certo é a pessoa que aprovou a spec. Por isso a revisão de código em duas camadas, IA e humano, continua necessária mesmo com spec.
O que a avaliação independente diz sobre o SDD?
É aqui que a maioria dos artigos para. Eles explicam o conceito, listam as ferramentas e terminam. A avaliação mais citada do mercado é mais cautelosa:
O mesmo texto registra que muitos desenvolvedores já adotaram o estilo e que a própria Thoughtworks tem uma versão interna que compartilha dentro da empresa. Ou seja: não é um veredito contra a técnica, é um aviso sobre o estágio dela. A consultoria ainda levanta a hipótese de que o setor esteja reaprendendo uma lição antiga da IA: escrever à mão regras detalhadas demais para o modelo não escala.
Para quem decide o processo de um time, a leitura prática é esta: o risco do SDD não está na IA, está na revisão. Uma spec de vinte páginas gerada pela ferramenta e aprovada sem leitura dá a mesma falsa segurança de um código aprovado sem leitura, só que com um documento a mais para apontar depois.
Quem escreve, quem aprova e onde a spec fica guardada?
Essa é a lacuna que as ferramentas não resolvem, porque é uma decisão de organização, não de software. Três papéis precisam estar definidos antes do primeiro comando:
1. Quem escreve: quem conhece o problema, com apoio da IA
A primeira versão da spec pode ser gerada pela ferramenta, mas o conteúdo de negócio tem de vir de quem conhece a regra: o produto, a área demandante ou o líder técnico que conversou com ela. A IA organiza e completa a forma; não deveria inventar a regra de desconto nem a política de acesso.
2. Quem aprova: uma pessoa nominal, com prazo e critério
Aprovação de spec precisa de dono, como aprovação de código. Em funcionalidade crítica, o ideal são duas assinaturas: uma de negócio (o comportamento está certo?) e uma técnica (o plano é viável e seguro?). “O time revisou” não é aprovação; é a garantia de que ninguém leu inteiro.
3. Onde fica: no repositório, ao lado do código
A spec deve morar no mesmo repositório do código, versionada, e mudar pelo mesmo processo de pull request. Assim, qualquer alteração de comportamento aparece como alteração de texto, com autor, data e revisor. Spec guardada numa pasta compartilhada à parte envelhece em semanas e deixa de ser fonte da verdade.
4. Quanto pode ter: o tamanho que o aprovador lê de verdade
Uma regra simples evita o problema que a Thoughtworks apontou: a spec de uma funcionalidade não pode ser maior do que o aprovador consegue ler com atenção numa sentada. Se a ferramenta gerou mais do que isso, ou a funcionalidade é grande demais e deve ser quebrada, ou a spec está carregando detalhe que pertence ao plano.
Essas decisões conversam com as regras de uso do próprio assistente, como as permissões que a empresa define para o agente de código. Spec diz o que construir; a política de permissões diz o que o agente pode tocar enquanto constrói.
Quando o spec-driven development compensa?
O critério mais útil não é o tamanho do projeto, e sim duas perguntas: quanto custa o erro e quantas pessoas ou times precisam entender a mesma coisa. Quando as duas respostas são baixas, a spec é peso. Quando as duas são altas, a falta dela é o risco.
- Compensa: funcionalidade que mexe com dinheiro, dado pessoal, permissão de acesso ou integração com outro sistema; trabalho dividido entre mais de um time ou com fornecedor externo; IA gerando boa parte do código que vai para produção.
- Compensa com spec leve: funcionalidade interna com regra de negócio clara, em que basta uma página com objetivo, cenários e critérios de aceite.
- Dispensa: protótipo descartável, prova de conceito, script de uso único, experimento para descobrir se a ideia funciona. Aqui, o vibe coding é mais honesto: a spec seria escrita para algo que ainda não se sabe o que é.
O erro clássico é o contrário do esperado: protótipo que deu certo e foi para produção sem nunca ganhar spec. É nesse momento, na passagem do experimento para o sistema de verdade, que a especificação mais se paga.
Spec Kit, Kiro ou OpenSpec: qual usar?
As três seguem a mesma ideia com pesos diferentes. Segundo a Thoughtworks, o Kiro, da AWS, conduz o usuário por requisitos, design e criação de tarefas; o Spec Kit segue um processo parecido, com orquestração mais rica, prompts configuráveis e a constituição. O OpenSpec, também de código aberto sob licença MIT, se apresenta como uma camada mais leve, voltada também a sistemas que já existem.
| Spec Kit (GitHub) | Kiro (AWS) | OpenSpec | |
|---|---|---|---|
| Formato | Kit de linha de comando, código aberto (MIT) | Ambiente de desenvolvimento e CLI da AWS | Kit de código aberto (MIT) |
| Fluxo | Constituição → especificação → plano → tarefas → implementação → convergência | Requisitos → design → tarefas | Explorar → propor mudança → aplicar → arquivar |
| Quem mantém | GitHub | AWS | Fission AI; specs vigentes em openspec/specs/ e uma pasta por mudança |
| Ponto forte | Princípios do projeto escritos uma vez e cobrados em tudo | Fluxo guiado dentro da ferramenta | Proposta enxuta por mudança, pensada para código existente |
| Ponto de atenção | O próprio OpenSpec o descreve como completo, mas pesado | Segundo o OpenSpec, prende o time ao ambiente da AWS | Não aparece na avaliação da Thoughtworks de 2025 |
Thoughtworks Technology Radar (nov. 2025), README do github/spec-kit e README do Fission-AI/OpenSpec, consultados em novembro de 2026.
Na escolha, pese menos a ferramenta e mais o hábito. Equipe que já usa o GitHub e quer regras de projeto explícitas tende a se dar bem com o Spec Kit. Quem está na AWS e vem do Amazon Q Developer vai encontrar o Kiro de qualquer jeito, já que os plugins do Q Developer estão sendo substituídos por ele. Quem trabalha sobre um sistema grande e antigo pode preferir a proposta por mudança do OpenSpec.
Em qualquer uma delas, a pergunta decisiva é a mesma: o arquivo que a ferramenta gera é algo que o seu aprovador consegue ler e assinar? Se não for, a ferramenta está certa e o processo, errado.
Quais os erros mais comuns ao adotar SDD?
- Aprovar a spec gerada sem ler. É o erro que a Thoughtworks apontou e o mais caro: dá ao time a sensação de processo sem o benefício dele.
- Usar SDD para tudo. Exigir spec formal para um ajuste de texto ou um protótipo de dois dias faz o time burlar o processo, e então ele deixa de valer também onde importa.
- Misturar spec e plano. Quando a especificação já decide banco, biblioteca e estrutura de pastas, ela fica longa, envelhece rápido e ninguém de negócio consegue aprová-la.
- Guardar a spec fora do repositório. Ela deixa de acompanhar o código, e na primeira divergência todos voltam a confiar só no código.
- Não ter dono da aprovação. Sem nome e prazo, a spec fica “em revisão” para sempre ou é aprovada por cansaço.
- Esquecer o “fora do escopo”. Sem essa seção, a IA tende a completar a funcionalidade com o que parece razoável, e o razoável dela nem sempre é o seu.
Vale adotar spec-driven development agora?
Vale testar, com escopo controlado. A técnica resolve um problema real, o da IA que preenche lacunas com palpites, e as ferramentas são gratuitas e de código aberto. Mas a própria avaliação de mercado a coloca em fase de experimento, e isso pede piloto, não decreto.
- Escolha uma funcionalidade real, de risco médio, que envolva pelo menos duas pessoas.
- Defina antes quem escreve, quem aprova e onde a spec ficará no repositório.
- Rode o fluxo completo numa ferramenta e cronometre o tempo gasto em spec, revisão e implementação.
- Compare retrabalho e dúvidas de entendimento com uma funcionalidade parecida feita sem spec.
- Só então decida a regra: em quais tipos de funcionalidade a spec passa a ser obrigatória.
Se a empresa está estruturando o uso de IA no desenvolvimento e quer esse desenho de processo, papéis e revisão feito junto com quem implementa, esse é o trabalho do serviço de desenvolvimento assistido por IA da Alliance. E se a dúvida é anterior, sobre o quanto a operação de marketing e tecnologia já está madura para automação, o diagnóstico de marketing gratuito leva cerca de 30 minutos e mostra onde estão as maiores lacunas.