O que é Desenvolvimento Orientado por Especificação? A Especificação como Fonte da Verdade

“A especificação como fonte da verdade, não um documento secundário.”

Conteúdo da página

O Desenvolvimento Orientado por Especificação (Spec-Driven Development) é uma daquelas ideias para as quais engenheiros de software já se voltaram no passado e depois abandonaram quando o esforço deixou de se pagar.

O que mudou em 2025 é que os agentes de codificação por IA chegaram e tornaram a ausência de intenção explícita cara. Os prompts são efêmeros. As sessões dos agentes são reiniciadas. O código muda, mas o raciocínio por trás dele desaparece. A especificação é o artefato que impede que isso aconteça.

O que é o Desenvolvimento Orientado por Especificação – a especificação como fonte de verdade para a codificação por IA

A Especificação Está se Tornando a Fonte de Verdade

Para a maior parte da história do desenvolvimento de software, a especificação era um artefato de planejamento temporário ou uma preocupação posterior. Os requisitos viviam em tickets, as decisões de design viviam em threads de chat e o código era a verdade absoluta. A documentação descrevia o que existia a posteriori.

O Desenvolvimento Orientado por Especificação inverte essa relação. A especificação se torna o artefato primário. O código é o que é gerado ou verificado em relação à especificação, e não o contrário.

Esta não é uma ideia nova. Métodos formais, design-by-contract (projeto por contrato) e BDD (Behavior-Driven Development) contêm versões disso. O que é novo é a motivação prática: agentes de codificação por IA precisam de contexto explícito e durável para produzir saída correta e consistente. Prompts são muito efêmeros. A especificação é o único artefato capaz de carregar a intenção entre sessões de agentes, entre membros da equipe e ao longo do tempo.

O Que o Desenvolvimento Orientado por Especificação Realmente Significa

O Desenvolvimento Orientado por Especificação, geralmente abreviado como SDD (Spec-Driven Development), é um fluxo de trabalho em que uma especificação versionada guia ou gera a implementação. A especificação é escrita e revisada antes que o agente escreva o código. Ela captura:

  • O que construir – problema do usuário, objetivos e não-objetivos
  • Como o comportamento correto se parece – critérios de aceitação, casos extremos (edge cases), estados de erro
  • Como construí-lo – decisões de arquitetura, modelo de dados, contratos de API, restrições de segurança
  • Como verificá-lo – estratégia de testes, regras de validação, rastreabilidade até os requisitos

Aquele último item é fácil de escrever e fácil de ignorar na prática. Mantendo Especificações, Testes e Código Sincronizados no Desenvolvimento com IA cobre como a rastreabilidade até os requisitos se parece realmente como dados: IDs de requisitos, IDs de decisões de design e testes vinculados aos pull requests que os implementaram.

A especificação não é um documento de uso único. Ela é atualizada quando a realidade difere do design. Quando o agente descobre algo durante a implementação que a especificação errou, a especificação é corrigida antes de continuar. A especificação permanece honesta porque é tratada como código.

Trabalho acadêmico recente formaliza esse enquadramento: pesquisadores descrevem o SDD como tratar as especificações como fonte de verdade e o código como gerado ou verificado em relação a elas. A interpretação prática é que a especificação é o registro durável e revisado da intenção que qualquer ferramenta humana ou de IA pode ler e confiar.

Três termos capturam diferentes pontos no espectro de uso da especificação:

Spec-first (Especificação primeiro) significa escrever a especificação completa antes que qualquer implementação comece. Esta é a interpretação mais estrita e a mais próxima do modelo em cascata (waterfall) se não for feita com cuidado.

Spec-ancored (Ancorado na especificação) significa manter uma especificação sincronizada com a implementação ao longo de todo o ciclo de vida do recurso. A especificação é atualizada à medida que as decisões mudam. Esta é a versão mais prática para a maioria das equipes.

Spec-as-source (Especificação como fonte) significa gerar ou validar a implementação a partir da especificação, seja através de agentes de IA ou através de ferramentas que verificam o código em relação às restrições da especificação. Esta é a direção para a qual ferramentas como GitHub Spec Kit e Kiro estão se movendo, cada uma com um tradeoff diferente entre portabilidade e orientação integrada de IDE. Pacotes de skills como Superpowers estão mais próximos da extremidade spec-anchored – eles impõem a disciplina de revisão automaticamente em vez de gerar código diretamente da especificação.

Por Que o SDD Importa Agora

A resposta honesta é que o SDD não é convincente para um desenvolvedor solitário construindo um script de um dia. O overhead não vale a pena.

O SDD se torna valioso quando três condições estão presentes: o recurso é grande o suficiente para abarcar múltiplas sessões, o agente precisa tomar decisões que afetam a arquitetura e o trabalho será revisado ou continuado por outra pessoa.

Todas as três condições estão cada vez mais comuns com o desenvolvimento assistido por IA.

LLMs precisam de contexto, não apenas de prompts. Um modelo que recebe um prompt vago toma decisões vagas. Um modelo que recebe uma especificação revisada com restrições explícitas, não-objetivos e critérios de aceitação toma melhores decisões e é mais fácil de corrigir quando ele se desvia. Isso se conecta a como recuperação e representação funcionam: dar a um agente uma especificação versionada é uma forma de recuperação estruturada da intenção do projeto.

A geração de código é barata; decidir o que construir ainda é difícil. O gargalo no desenvolvimento assistido por IA não é mais a digitação – é saber o que construir e como restringir o agente. O SDD desloca o esforço para onde importa: especificar a intenção claramente antes que a geração comece.

Prompts são efêmeros. O agente não lembra do que você lhe disse na última sessão. Uma especificação versionada armazenada no repositório lembra. Cada nova sessão pode ler a mesma especificação e implementar em relação à mesma intenção sem reestabelecer o contexto do zero.

**Vibe coding é mais rápido para trabalho descartável; SDD vs Vibe Coding cobre quando adicionar especificações e quando continuar criando prompts livremente.

Artefatos Principais

O SDD produz quatro tipos de artefatos. Cada um reduz um tipo diferente de ambiguidade antes que o agente toque no código:

  • Especificação de requisitos – problema, usuários, objetivos, não-objetivos, critérios de aceitação
  • Especificação de design – arquitetura, modelo de dados, contratos de API, restrições de segurança para este recurso
  • Plano de tarefas – pequenas fatias de implementação com dependências e critérios de validação
  • Registro de rastreabilidade – mapeamento dos critérios de aceitação para testes, decisões de design para arquivos, tarefas para commits

Como produzir e revisar esses artefatos passo a passo – especificar, planejar, tarefas, implementar, validar – é coberto em Fluxo de Trabalho de Desenvolvimento Orientado por Especificação: De Requisitos a Código. Um recurso simples pode cobrir as quatro áreas em um arquivo markdown curto. O hábito importa mais do que o formato.

Como o SDD Difere da Documentação

A confusão mais comum é tratar os artefatos de SDD como documentação. Eles não são documentação no sentido convencional.

Documentação descreve. Ela diz o que o sistema faz, como usá-lo e o que ele contém. É escrita a posteriori e atualizada quando o sistema muda.

Especificações restringem. Uma especificação diz ao agente o que ele é permitido construir e o que ele não é permitido fazer. Ela é autoritativa antes que a implementação comece. Ela é validada após a implementação ser concluída. Uma especificação que descreve o que foi realmente construído – em vez de restringir o que deveria ser construído – já falhou em seu propósito.

Especificações executáveis guiam a geração e a validação. As melhores especificações de SDD são próximas o suficiente de serem legíveis por máquina para que um agente possa implementar em relação a elas e uma suíte de testes possa verificá-las. Critérios de aceitação escritos como “o endpoint deve rejeitar solicitações não autenticadas com uma resposta 401” é uma especificação executável; “o endpoint é seguro” é documentação.

Registros de Decisão – ADRs, PDRs e DDRs – são complementares aos artefatos de SDD, mas servem a um propósito diferente. Registros de decisão capturam por que uma escolha foi feita e o que foi rejeitado. As especificações de SDD capturam o que construir e como verificá-lo. Ambos pertencem ao repositório. Juntos, eles dão aos agentes de IA o quadro completo: a intenção atual e o raciocínio por trás dela.

Como o SDD Difere do TDD

O Desenvolvimento Orientado a Testes (Test-Driven Development) e o Desenvolvimento Orientado por Especificação (Spec-Driven Development) são frequentemente confundidos porque ambos produzem artefatos explícitos antes que o código exista. A diferença é o ponto de partida.

TDD começa com testes. Você escreve um teste que falha que descreve o comportamento que deseja, e então escreve o código mínimo para fazê-lo passar. O TDD é um loop de feedback no nível da unidade. Ele produz bons testes, mas não responde à pergunta de se você está construindo a coisa certa.

SDD começa com a intenção. Antes que os testes existam, antes que a arquitetura seja decidida, a especificação responde: quem tem esse problema, como o comportamento correto se parece, o que está explicitamente fora do escopo. A especificação então informa quais testes escrever, o que é por que um bom SDD e um bom TDD são complementares em vez de concorrentes.

Uma forma prática de pensar sobre isso: o SDD dirige o TDD. Os critérios de aceitação na especificação se tornam os cenários de teste. A especificação de design identifica as fronteiras de integração que precisam de testes de contrato. O plano de tarefas identifica quais comportamentos de unidade precisam de cobertura de testes antes que o agente os implemente.

Como o SDD Difere do BDD

O Desenvolvimento Orientado a Comportamento (Behavior-Driven Development) usa cenários em linguagem natural – tipicamente em formato Gherkin – para descrever o comportamento esperado da perspectiva do usuário. Esses cenários fazem a ponte entre a intenção de negócios e a implementação técnica.

O SDD é mais amplo. Ele inclui descrições de comportamento (que podem usar linguagem estilo BDD ou prosa simples), mas também cobre decisões de arquitetura, modelos de dados, restrições de segurança, planejamento de tarefas e rastreabilidade. O BDD pode ser um formato útil para escrever critérios de aceitação dentro de uma especificação de requisitos de SDD. A especificação é o recipiente; os cenários BDD são uma forma de escrever o que vai dentro dele.

A distinção importa na prática: as ferramentas de BDD focam em tornar os cenários executáveis. A prática de SDD foca em tornar a intenção durável – entre ferramentas, entre sessões e entre membros da equipe.

Como o SDD Difere dos Métodos Formais

Os métodos formais usam notação matemática e verificação automatizada para provar propriedades de sistemas de software. Eles são extremamente rigorosos e extremamente caros para a maioria dos contextos de desenvolvimento de produção.

O SDD não requer notação formal. Um arquivo markdown com critérios de aceitação e decisões de arquitetura é uma especificação. Ele restringe sem ser matematicamente formal. O nível de rigor escala com os riscos: uma especificação para um serviço de faturamento deve ser mais precisa e mais cuidadosamente revisada do que uma especificação para uma página de documentação.

A relação é um espectro:

  • Especificação em prosa informal (SDD viável mínimo)
  • Markdown estruturado com critérios de aceitação e não-objetivos
  • Especificação legível por máquina com validação de schema
  • Testes de contrato derivados diretamente da especificação
  • Especificação formal com prova automatizada

A maioria das equipes opera no meio desse espectro. O objetivo não é o rigor matemático – é tornar a intenção explícita o suficiente para que um agente de IA possa implementar em relação a ela e um revisor humano possa verificar o resultado.

Benefícios do Desenvolvimento Orientado por Especificação

Menos deriva de intenção. A especificação é a referência. Quando o agente se desvia – e ele vai – o revisor tem algo com o qual comparar a implementação. Sem uma especificação, a deriva é invisível até que algo quebre.

Saídas de IA melhores. Agentes dados restrições explícitas, não-objetivos e critérios de aceitação produzem implementações que estão mais próximas do que foi pretendido e são mais fáceis de corrigir quando erram. A qualidade do contexto determina diretamente a qualidade da saída.

Revisão mais fácil. Um pull request anexado a uma especificação é mais fácil de revisar do que um pull request que requer que o revisor reconstrua a intenção a partir do código. A especificação é a lista de verificação da revisão.

Alinhamento da equipe. Quando várias pessoas ou agentes estão trabalhando no mesmo recurso, a especificação é o contrato compartilhado. Sem ela, cada contribuidor otimiza localmente e as peças podem não se encaixar.

Planejamento de testes melhor. Os critérios de aceitação na especificação mapeiam diretamente para casos de teste. A cobertura de testes se torna uma questão de cobertura de especificação: todo critério de aceitação está coberto por pelo menos um teste?

Handoff durável. Quando um recurso muda de mãos – entre engenheiros, entre sessões de agentes, entre sprints – a especificação é o artefato de handoff. Ela captura o que foi decidido, o que estava fora do escopo e o que resta para ser validado.

Custos do Desenvolvimento Orientado por Especificação

Esforço inicial. Escrever uma boa especificação antes de escrever qualquer código leva tempo. Para recursos pequenos, esse overhead é real e às vezes não vale a pena.

Falsa confiança. Uma especificação que existe mas não é validada em relação à implementação dá uma falsa sensação de correção. Especificações desatualizadas às vezes são piores do que nenhuma especificação: elas enganam revisores e agentes que as leem.

Especificações desatualizadas. Especificações derivam quando a equipe as trata como artefatos de planejamento em vez de documentos vivos. Atualizar a especificação quando a implementação difere do design não é opcional – é o que separa o SDD da documentação que se acumula e apodrece.

Burocracia gerada. Agentes de IA podem gerar listas de tarefas exaustivas e especificações verbosas rapidamente. Uma especificação de 200 tarefas gerada em trinta segundos não é uma especificação útil – é um gerador de burocracia. Um bom SDD requer julgamento sobre o que especificar e o que deixar implícito.

Lock-in de ferramentas. Algumas ferramentas de SDD têm opiniões sobre formato, estrutura de arquivos e fluxo de trabalho. Uma especificação escrita em um formato proprietário é mais difícil de carregar entre ferramentas do que um arquivo markdown com cabeçalhos claros e critérios de aceitação.

Conclusão

O Desenvolvimento Orientado por Especificação não é uma nova metodologia. É uma antiga disciplina tornando-se prática novamente porque o custo da intenção implícita agora é visível no código gerado por IA.

A disciplina é simples: escrever o que se pretende construir, revisado e versionado, antes que o agente o construa. Manter esse registro honesto atualizando-o quando a realidade difere. Usá-lo como referência para revisão, testes e handoff.

A especificação não é mágica. Uma especificação que não é validada se torna o tipo mais caro de documentação: uma que engana com confiança. Um bom SDD é a prática de manter as especificações honestas – pequenas o suficiente para manter, precisas o suficiente para restringir e duráveis o suficiente para sobreviver a qualquer sessão de agente individual.

O SDD se situa na interseção da prática de documentação, arquitetura de testes e design de código – tudo coberto no cluster Arquitetura de Aplicação em Produção junto com registros de decisão, design de API e padrões de acesso a dados.

Subscrever

Receba novos artigos sobre sistemas, infraestrutura e engenharia de IA.