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

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

Conteúdo da página

Desenvolvimento Orientado por Especificação é uma daquelas ideias que os engenheiros de software buscaram anteriormente e depois abandonaram quando o esforço deixou de gerar retorno.

O que mudou em 2025 é que os agentes de codificação com IA chegaram e tornaram a ausência de intenção explícita custosa. 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 é Desenvolvimento Orientado por Especificação – a especificação como fonte de verdade para a IA

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

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

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

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

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

Desenvolvimento Orientado por Especificação, geralmente abreviado como SDD (do inglês Spec-Driven Development), é um fluxo de trabalho onde 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 de borda, 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 de volta aos requisitos

Este último ponto é fácil de escrever e fácil de pular na prática. Manter Especificações, Testes e Código Sincronizados no Desenvolvimento com IA cobre como a rastreabilidade de volta aos requisitos realmente se parece 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.

Trabalhos acadêmicos recentes formalizam essa estrutura: pesquisadores descrevem o SDD como tratar especificações como a fonte de verdade e o código como gerado ou verificado contra elas. A interpretação prática é que a especificação é o registro revisado e durável da intenção que qualquer humano ou ferramenta de IA pode ler e confiar.

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

Primeiro a especificação (Spec-first) 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 waterfall (cascata) se não for feita com cuidado.

Ancorado na especificação (Spec-anchored) significa manter uma especificação sincronizada com a implementação ao longo do 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.

Especificação como fonte (Spec-as-source) 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 contra 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 uma compensação diferente entre portabilidade e orientação de IDE integrada.

Por Que o SDD Importa Agora

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

O SDD torna-se valioso quando três condições estão presentes: o recurso é grande o suficiente para se estender por várias 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 são cada vez mais comuns com o desenvolvimento assistido por IA.

Os 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 desvia. Isso se conecta com o funcionamento de recuperação e representação: dar ao 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.

Os 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 contra a 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 usando 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 – fatias pequenas de implementação com dependências e critérios de validação
  • Registro de rastreabilidade – mapeamento de critérios de aceitação para testes, decisões de design para arquivos, tarefas para commits

Como produzi-los e revisá-los passo a passo – especificar, planejar, tarefas, implementar, validar – é coberto em Fluxo de Trabalho de Desenvolvimento Orientado por Especificação de Requisitos para Código. Um recurso simples pode cobrir todas 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 do 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 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 conclusão da implementação. Uma especificação que descreve o que foi realmente construído – em vez de restringir o que deve ser construído – já falhou em seu propósito.

Especificações executáveis guiam a geração e validação. As melhores especificações de SDD são próximas o suficiente de legíveis por máquina para que um agente possa implementar contra 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” são 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

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

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

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

Uma maneira prática de pensar sobre isso: o SDD direciona o TDD. Os critérios de aceitação na especificação tornam-se 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 teste antes que o agente os implemente.

Como o SDD Difere do BDD

Desenvolvimento Orientado por Comportamento usa cenários de linguagem natural – tipicamente no formato Gherkin – para descrever o comportamento esperado da perspectiva do usuário. Esses cenários preenchem a lacuna 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 container; os cenários BDD são uma maneira 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 – através de ferramentas, através de sessões e através de membros da equipe.

Como o SDD Difere dos Métodos Formais

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. Ela restringe sem ser matematicamente formal. O nível de rigor escala com as apostas: 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 esquema
  • 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 é rigor matemático – é tornar a intenção explícita o suficiente para que um agente de IA possa implementar contra ela e um revisor humano possa verificar o resultado.

Benefícios do Desenvolvimento Orientado por Especificação

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

Melhores saídas de IA. Agentas 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 vinculado a uma especificação é mais fácil de revisar do que um pull request que exige que o revisor reconstrua a intenção a partir do código. A especificação é a lista de verificação de revisão.

Alinhamento de 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.

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

Transferência durável. Quando um recurso muda de mãos – entre engenheiros, entre sessões de agente, entre sprints – a especificação é o artefato de transferência. 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 pequenos recursos, esse overhead é real e às vezes não vale a pena.

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

Especificações desatualizadas. As especificações desviam 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 exaustivas de tarefas 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.

Venda casada de ferramentas (Lock-in). Algumas ferramentas de SDD são opinativas sobre formato, estrutura de arquivos e fluxo de trabalho. Uma especificação escrita em um formato proprietário é mais difícil de transportar entre ferramentas do que um arquivo markdown com cabeçalhos claros e critérios de aceitação.

Conclusão

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

A disciplina é simples: anote o que você pretende construir, revisado e versionado, antes que o agente o construa. Mantenha esse registro honesto atualizando-o quando a realidade diferir. Use-o como referência para revisão, teste e transferência.

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

O SDD está 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 ao lado de registros de decisão, design de API e padrões de acesso a dados.

Assinar

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