Spec driven development: o que é e como aplicar
Spec driven development é uma abordagem em que a especificação, e não o código, passa a ser a principal fonte da verdade de um projeto. Em vez de pedir código diretamente a um agente de IA, você descreve antes o que precisa ser construído e por que isso importa.
Neste artigo, você vai entender a origem do conceito, os níveis de adoção e as etapas do fluxo. Além disso, vai conhecer as ferramentas mais usadas e os cenários em que a prática compensa de fato.
O que é spec driven development
Em uma definição direta, spec driven development (SDD) é um processo em que uma especificação estruturada e versionada conduz todo o trabalho de desenvolvimento. Ela registra o comportamento esperado, as restrições, os casos de borda e os critérios de aceite antes da primeira linha de código.
Na prática, o time deriva um plano técnico e uma lista de tarefas a partir desse documento. Em seguida, escreve ou gera o código necessário para cumprir o que a especificação descreve.
Quando um requisito muda, a especificação muda primeiro. Só depois o código acompanha a alteração, nunca o contrário.
Isso inverte o padrão tradicional, em que o código nasce antes e a documentação, quando existe, fica para trás. Por isso, muita gente resume o spec driven development como uma prática de documentação primeiro.
Contudo, a especificação não tem papel decorativo nesse modelo. Ela funciona como um contrato entre a intenção de negócio e a implementação técnica.
Em outras palavras, o código vira um detalhe de implementação da especificação. Enquanto a especificação define o quê e o porquê, o plano técnico define o como.
Por que o spec driven development ganhou força com a IA
A ideia de especificar antes de codificar não é nova. Documentos de requisitos, desenvolvimento orientado a modelos e design por contrato já seguiam esse raciocínio há décadas.
No entanto, o interesse pelo spec driven development cresceu de forma acentuada a partir de 2025. O principal motivo foi a popularização dos agentes de programação baseados em IA.
Além disso, a Thoughtworks incluiu a técnica no anel Assess do seu Technology Radar em novembro de 2025. Na leitura do radar, isso indica uma prática que vale explorar, e não uma recomendação de adoção imediata.
Os limites do vibe coding
Em fevereiro de 2025, Andrej Karpathy popularizou o termo vibe coding. Ele descreve a prática de pedir algo à IA, aceitar o código que volta e ajustar o resultado por tentativa e erro.
Esse estilo funciona muito bem para protótipos e experimentos rápidos. Porém, em projetos reais, ele costuma gerar código inconsistente, decisões perdidas no histórico do chat e retrabalho constante.
Afinal, o contexto de uma conversa com o agente desaparece quando a sessão termina. Assim, a próxima sessão começa sem saber o que o time decidiu antes.
Outro problema é que o agente tende a gerar código que parece correto, mas que erra a intenção original. Sem um documento de referência, ninguém consegue provar o desvio com rapidez.
A especificação como memória do projeto
O spec driven development resolve esse problema ao transformar a especificação em um artefato persistente e versionado. Na prática, ela funciona como um grande prompt que não se perde quando o chat fecha.
Dessa forma, quando o agente se desvia do objetivo, você aponta de volta para o documento. Quando o requisito muda, você atualiza a especificação e gera novamente apenas o que for necessário.
Em resumo, o vibe coding otimiza a velocidade, enquanto o spec driven development otimiza o alinhamento com a intenção. Uma abordagem não elimina a outra, porque cada uma atende a um tipo diferente de problema.
Os três níveis do spec driven development
Como o termo ainda está em evolução, nem toda implementação segue o mesmo grau de rigor. Por isso, Birgitta Böckeler, da Thoughtworks, propôs uma divisão em três níveis que a comunidade adotou amplamente.
A classificação aparece no artigo Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl, publicado no site de Martin Fowler em outubro de 2025. Mais tarde, um artigo acadêmico no arXiv retomou os mesmos três níveis como um espectro de rigor.
Spec first
No nível spec first, você escreve uma especificação bem pensada antes de começar a tarefa. Em seguida, usa esse documento para guiar o agente durante a implementação inicial.
Depois que a funcionalidade fica pronta, no entanto, a especificação perde importância e o código passa a evoluir sozinho. A maioria dos times começa por esse nível, porque ele exige pouca mudança de processo.
Spec anchored
No nível spec anchored, a especificação continua viva depois da entrega. Ela evolui junto com o código e orienta a manutenção e as mudanças futuras da funcionalidade.
Nesse caso, testes de contrato e verificações automáticas ajudam a manter código e especificação alinhados. Sem esse cuidado, o documento envelhece e volta a ser apenas documentação.
Spec as source
No nível spec as source, a especificação é o único artefato que as pessoas editam diretamente. O código vira um produto de build, gerado a partir dela, que ninguém altera à mão.
Esse é o nível mais ambicioso e também o menos comprovado na prática. Ferramentas como o Tessl apostam nessa visão, mas ela ainda enfrenta desafios de determinismo, revisão e custo.
Como funciona o fluxo de spec driven development
Embora cada ferramenta tenha particularidades, o fluxo de spec driven development segue uma sequência bem definida. Ele parte da especificação e passa por plano técnico, tarefas, implementação e validação.
A grande vantagem dessa sequência fixa é tornar o trabalho do agente fácil de inspecionar. Afinal, cada etapa gera um artefato que você revisa antes de seguir para a próxima.
Constituição do projeto
Antes das funcionalidades, muitos fluxos começam com uma constituição. Ela reúne os princípios que não mudam, como padrões de qualidade, estratégia de testes, convenções de código e restrições de arquitetura.
Por exemplo, a constituição pode exigir testes de integração para todo endpoint ou proibir bibliotecas sem manutenção ativa. Assim, todas as especificações futuras herdam essas regras automaticamente.
Especificação da funcionalidade
Na etapa de especificação, você descreve o que o sistema deve fazer e por que isso importa para o usuário. O foco fica no comportamento e no valor entregue, sem decidir ainda a tecnologia.
Uma boa prática é registrar histórias de usuário, critérios de aceite e casos de borda. Também vale marcar explicitamente os pontos ambíguos que ainda precisam de esclarecimento.
Plano técnico
Com a especificação aprovada, o próximo passo é o plano técnico. Nele, você define stack, arquitetura, modelo de dados, contratos de API e decisões de infraestrutura.
É aqui que entram instruções como usar .NET 10 com Minimal APIs e PostgreSQL. Dessa forma, a decisão técnica fica registrada e separada da intenção de negócio.
Quebra em tarefas
Em seguida, o plano vira uma lista de tarefas pequenas, ordenadas e verificáveis. Cada tarefa precisa caber em um ciclo curto, para que o agente consiga concluí-la e você consiga revisá-la com tranquilidade.
Essa granularidade reduz o risco de o agente tentar resolver tudo de uma vez. Além disso, facilita a criação de pull requests menores e mais fáceis de aprovar.
Implementação e validação
Por fim, o agente executa as tarefas uma a uma, sempre com a especificação como contexto. Ao final de cada ciclo, você confere se o resultado atende aos critérios de aceite.
Testes automatizados, revisão humana e avaliações do agente fecham o ciclo. Para aprofundar essa etapa, vale ler o artigo sobre dez evals para agentes de IA, que mostra como medir a qualidade das entregas.
Quando o resultado diverge do documento, você corrige o código ou a própria especificação e repete o ciclo. Em outras palavras, no spec driven development a validação compara a entrega com a promessa registrada, e não com a memória de quem pediu.
Anatomia de uma boa especificação
Uma especificação ruim produz código ruim, mesmo com o melhor modelo disponível. Por isso, a qualidade do documento define boa parte do resultado no spec driven development.
Em geral, uma especificação pronta para o agente cobre os seguintes elementos:
- Objetivo: o problema que a funcionalidade resolve e para quem.
- Comportamento esperado: histórias de usuário e fluxos principais.
- Critérios de aceite: condições objetivas e testáveis para considerar a tarefa concluída.
- Casos de borda: entradas inválidas, limites, falhas de rede e concorrência.
- Restrições: requisitos de segurança, desempenho, conformidade e compatibilidade.
- Fora de escopo: o que a funcionalidade não deve fazer nesta versão.
Alguns times usam a notação EARS para escrever requisitos sem ambiguidade. Nela, cada requisito segue o formato QUANDO um evento ocorrer, O SISTEMA DEVE responder de determinada forma.
O exemplo abaixo mostra uma especificação curta para uma funcionalidade de exportação de pedidos. Repare que o documento não cita banco de dados, framework nem linguagem de programação.
# Feature: Order export
## Goal
Store managers need to export orders to reconcile payments with the bank.
## User stories
- As a store manager, I want to export orders for a date range so that I can reconcile payments.
## Acceptance criteria
- WHEN the manager requests an export for a valid date range, THE SYSTEM SHALL generate a CSV file with one row per order.
- WHEN the date range exceeds 90 days, THE SYSTEM SHALL reject the request with a validation error.
- WHEN no orders exist in the range, THE SYSTEM SHALL return an empty file with headers only.
## Edge cases
- Refunded orders must appear with a negative amount.
- Orders created exactly at midnight belong to the day that starts at midnight.
## Out of scope
- Excel and PDF formats.
- Scheduled exports.
## Open questions
- [NEEDS CLARIFICATION] Which time zone defines the date range?
Note que cada critério de aceite pode virar um teste automatizado quase sem tradução. Além disso, a seção de fora de escopo impede que o agente invente formatos que ninguém pediu.
A seção de perguntas abertas também tem papel importante. Ela torna a dúvida visível, em vez de deixar o agente escolher um fuso horário por conta própria.
Também vale lembrar que especificação longa não significa especificação boa. Documentos extensos demais ficam difíceis de revisar e acabam escondendo decisões importantes.
Como aplicar spec driven development com o GitHub Spec Kit
O GitHub Spec Kit é hoje a ferramenta open source mais conhecida para aplicar spec driven development. O GitHub abriu o código do projeto em setembro de 2025, sob licença MIT.
Desde então, o repositório ultrapassou 130 mil estrelas e passou a funcionar com dezenas de agentes, entre eles o GitHub Copilot, o Claude Code e o Gemini CLI.
Instalação e primeiro projeto
Para começar, você precisa do Python 3.11 ou superior, do gerenciador de pacotes uv e de um agente compatível. A instalação e a criação do projeto acontecem no terminal, em Linux, macOS ou Windows:
# instala a CLI do Spec Kit
uv tool install specify-cli
# cria o projeto já integrado ao GitHub Copilot
specify init order-export --integration copilot
cd order-export
O parâmetro --integration indica o agente que vai receber os comandos. Para usar outro agente, basta trocar copilot pela chave correspondente, conforme a documentação oficial do Spec Kit.
Se o projeto já tem código, o Spec Kit oferece um guia específico para bases existentes. Assim, você adota a prática apenas nas novas funcionalidades, sem reescrever o que já funciona.
Comandos do fluxo
Depois da instalação, você abre o agente na pasta do projeto e chama cada etapa pelo chat. Os comandos são skills do agente, e não comandos de terminal.
/speckit-constitution Create principles focused on code quality, testing, and maintainability.
/speckit-specify Build an order export feature that generates a CSV file for a date range.
/speckit-plan Use .NET 10 with Minimal APIs, EF Core, and PostgreSQL.
/speckit-tasks
/speckit-implement
/speckit-converge
A constituição acontece uma vez por projeto. Já o ciclo de especificar, planejar, quebrar, implementar e convergir se repete para cada funcionalidade.
Na reta final, você alterna implementação e convergência até o relatório indicar que o código atende à especificação. Além disso, o Spec Kit oferece etapas opcionais de esclarecimento, checklists e análise de consistência, que funcionam como portões de qualidade extras.
Vale notar que versões anteriores usavam comandos com ponto, como /speckit.specify. Portanto, se você encontrar tutoriais antigos, adapte a sintaxe para a versão instalada.
Correção de bugs e avaliação de ideias
Além do fluxo principal, o Spec Kit passou a oferecer outros processos como extensões opcionais. Um deles separa diagnóstico, correção e verificação de bugs, enquanto outro avalia se uma ideia merece investimento antes de virar software.
Para instalar essas extensões, você usa os comandos specify extension add bug e specify extension add assess. Dessa forma, a mesma ferramenta cobre o ciclo completo, da ideia à manutenção.
Outras ferramentas de spec driven development
O Spec Kit não é a única opção do mercado. Na verdade, o spec driven development é um processo, e não uma ferramenta específica.
- Kiro: IDE da AWS que conduz o trabalho por requisitos, design e tarefas.
- Tessl: plataforma que persegue o nível spec as source e mantém um registro de especificações.
- OpenSpec: CLI focada em mudanças incrementais por propostas, alinhada ao nível spec anchored.
- Fluxo manual: arquivos markdown no repositório e um agente qualquer, sem ferramenta dedicada.
Esse último ponto merece atenção. Muitos times aplicam o spec driven development apenas com arquivos versionados, um template de especificação e um bom prompt.
Se você usa o Claude Code, por exemplo, pode empacotar esse fluxo em comandos e hooks próprios. O artigo sobre como criar seu primeiro mod no Claude Code mostra esse caminho passo a passo.
Spec driven development, TDD e BDD
O spec driven development não surgiu do nada. Ele continua uma linhagem que começou com o TDD no fim dos anos 1990 e passou pelo BDD.
No TDD, o teste define o comportamento antes do código. Já no BDD, cenários em linguagem próxima do negócio descrevem o comportamento esperado e facilitam a conversa com pessoas de produto.
O SDD leva essa ideia um passo adiante, porque a especificação passa a guiar plano, tarefas, testes e documentação. Ou seja, os testes derivam da especificação, assim como o código.
Na prática, as abordagens se complementam muito bem. Por exemplo, você pode pedir que o agente escreva os testes a partir dos critérios de aceite antes de implementar cada tarefa.
Quando usar spec driven development
Como toda prática, o spec driven development tem custo. Por isso, a pergunta certa não é se você deve usar sempre, mas se o problema justifica o esforço.
Cenários em que o spec driven development compensa
A abordagem traz mais retorno quando o trabalho envolve ambiguidade ou impacto amplo. Entre os cenários mais comuns, estão:
- Funcionalidades novas com regras de negócio relevantes.
- Mudanças que tocam vários módulos ou serviços.
- Decisões de arquitetura que afetam o projeto por muito tempo.
- Times com várias pessoas e agentes trabalhando no mesmo código.
- Tarefas que levariam mais de meia hora de implementação.
Nesses casos, quinze minutos de especificação evitam horas de retrabalho. Além disso, o documento serve como registro de decisão para quem chegar depois.
Cenários em que vira burocracia
Por outro lado, existem situações em que a especificação só atrasa a entrega. Correções de uma linha, ajustes de texto e mudanças sem ambiguidade raramente precisam de um documento formal.
O mesmo vale para protótipos descartáveis e provas de conceito. Nesse contexto, o vibe coding entrega mais rápido e com custo menor.
Também existe o risco de aplicar a prática com exagero. A própria Thoughtworks alertou que algumas ferramentas geram arquivos de especificação longos e difíceis de revisar, o que anula parte do benefício.
Erros comuns ao adotar spec driven development
Mesmo com boas ferramentas, alguns erros aparecem com frequência nos primeiros projetos. Conhecer esses problemas com antecedência evita boa parte das frustrações.
O primeiro erro é deixar o agente escrever a especificação sozinho e aprovar sem ler. Nesse caso, você terceiriza justamente a parte que exige julgamento humano.
Outro erro comum é misturar decisões técnicas com requisitos de negócio na mesma etapa. Quando a especificação já cita banco de dados e framework, o plano técnico perde sua função.
Há também o problema das especificações gigantes, que ninguém consegue revisar. Prefira uma especificação por funcionalidade, curta e objetiva.
Por fim, muitos times esquecem de atualizar a especificação depois da entrega. Sem essa disciplina, o documento perde a sincronia com o código e deixa de ser confiável.
Conclusão
O spec driven development muda o centro de gravidade do desenvolvimento com IA. Em vez de conversas soltas com o agente, você trabalha com artefatos versionados, revisáveis e persistentes.
Com isso, o agente ganha contexto, o time ganha previsibilidade e as decisões ficam registradas. O código continua importante, mas passa a ser consequência de uma intenção clara.
Para começar, não é preciso abraçar o nível mais radical da prática. Comece pelo spec first em uma funcionalidade real, avalie o resultado e evolua aos poucos para o spec anchored.
Se você quer ver o spec driven development na prática, participe do Workshop Spec Driven Development no balta.io, com a construção de um projeto real do início ao fim.
FAQ
Spec driven development substitui o vibe coding?
Não. O vibe coding continua útil para protótipos e experimentos, enquanto o spec driven development atende projetos que precisam de previsibilidade e manutenção.
Preciso do Spec Kit para aplicar spec driven development?
Não. O Spec Kit facilita o processo com templates e comandos, mas você pode aplicar a mesma lógica com arquivos markdown e qualquer agente.
Qual o tamanho ideal de uma especificação?
O suficiente para eliminar ambiguidades sem virar um documento impossível de revisar. Em geral, uma especificação por funcionalidade funciona melhor do que um documento único para todo o sistema.
Spec driven development funciona em projetos existentes?
Sim. Você pode adotar a prática apenas nas novas funcionalidades, e o próprio Spec Kit tem um guia específico para bases que já possuem código.
Quem deve escrever a especificação?
O agente pode ajudar a redigir, mas uma pessoa precisa revisar e aprovar o documento. A responsabilidade pela intenção do sistema continua sendo do time.
Qual nível de spec driven development devo adotar primeiro?
Comece pelo spec first, que exige pouca mudança de processo. Depois que o time ganhar confiança, evolua para o spec anchored e mantenha a especificação viva.