O que é Desenvolvimento Orientado por Especificações? A Especificação como Fonte de Verdade

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

Conteúdo da página

Desenvolvimento Orientado por Especificação é uma daquelas ideias para as quais os engenheiros de software tentaram alcançar antes e depois abandonaram quando o esforço deixou de ser compensador.

O que mudou em 2025 é que os agentes de codificação com IA chegaram e tornaram a ausência de intenção explícita cara. 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 IA

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

Na 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 em 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 em relação à especificação, e não o inverso.

Esta não é uma ideia nova. Métodos formais, design-by-contract 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. 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 membros da equipe e ao longo do tempo.

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

O Desenvolvimento Orientado por Especificação, geralmente abreviado para SDD, é 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 teste, regras de validação, rastreabilidade de volta aos requisitos

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

Trabalhos acadêmicos recentes formalizam esse enquadramento: pesquisadores descrevem o SDD como tratar especificações como a 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 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:

Especificação em primeiro lugar (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 em cascata (waterfall), se não for feita com cuidado.

Especificação ancorada (Spec-anchored) significa manter uma especificação sincronizada com a implementação durante 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.

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 as restrições da especificação. Esta é a direção para a qual ferramentas como GitHub Spec Kit e Kiro estão se movendo.

Por Que o SDD Importa Agora

A resposta honesta é que o SDD não é atraente para um desenvolvedor solo 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 abranger 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 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 se desvia. Isso se conecta com o funcionamento da recuperação e representação: fornecer 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.

Prompts são efêmeros. O agente não lembra do que você disse a ele na última sessão. Uma especificação versionada armazenada no repositório sim. 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 funciona até que pare de funcionar. Para protótipos e trabalho descartável, o prompting ad-hoc é mais rápido e apropriado. Assim que um recurso exigir restrições de segurança, decisões de arquitetura multi-arquivo ou uma transição de equipe, a ausência de uma especificação torna-se a principal fonte de deriva e defeitos. Veja a comparação em SDD vs Vibe Coding para saber quando cada abordagem se aplica.

Artefatos Principais

Um fluxo de trabalho SDD prático produz quatro artefatos principais. Cada um reduz um tipo específico de ambiguidade antes que ela chegue ao agente.

Especificação de requisitos. O enunciado do problema, os usuários afetados, os objetivos, os não-objetivos explícitos e os critérios de aceitação. Os não-objetivos são tão importantes quanto os objetivos – eles dizem ao agente o que não construir e previnem o aumento de escopo (scope creep). Os critérios de aceitação são precisos o suficiente para que cada um mapeie para pelo menos um teste.

Especificação de design. As decisões de arquitetura relevantes para este recurso: módulos afetados, mudanças no modelo de dados, contratos de API, migrações, restrições de segurança, requisitos de observabilidade e modos de falha conhecidos. Este não é um documento completo de design do sistema – é o subconjunto de decisões de arquitetura necessárias para implementar este recurso corretamente.

Plano de tarefas. Uma sequência de pequenas tarefas de implementação, cada uma com dependências explícitas, mudanças de arquivo esperadas e critérios de validação. As tarefas são pequenas o suficiente para serem implementadas em uma única sessão do agente e verificadas com um diff focado. Cada tarefa tem um ponto de verificação de revisão humana.

Registro de rastreabilidade. Um mapeamento dos critérios de aceitação para testes, das decisões de design para os arquivos afetados e das tarefas para commits. É isso que separa o SDD da documentação que se torna obsoleta: a rastreabilidade torna possível verificar que a especificação foi realmente implementada, não apenas escrita.

Esses artefatos não precisam ser pesados. Um recurso simples pode produzir um único documento markdown de duas páginas cobrindo todas as quatro áreas. O formato importa menos do que o hábito de escrever a intenção antes que a implementação comece.

Como o SDD Diferencia-se da Documentação

A confusão mais comum é tratar os artefatos 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 é permitido construir e o que 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 SDD são próximas o suficiente do legível 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 requisições não autenticadas com uma resposta 401” são uma especificação executável; “o endpoint é seguro” é documentação.

Registros de Decisão](https://www.glukhov.org/pt/app-architecture/documentation/decision-records-ai-driven-development/ “Registros de Decisão para Desenvolvimento de Software Orientado por IA”) – ADRs, PDRs e DDRs – são complementares aos artefatos 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 SDD capturam o que construir e como verificá-lo. Ambos pertencem ao repositório. Juntos, eles dão aos agentes de IA o panorama completo: a intenção atual e o raciocínio por trás dela.

Como o SDD Diferencia-se do TDD

O Desenvolvimento Orientado por Testes e o 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 esse 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 nisso: o SDD impulsiona 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 Diferencia-se do BDD

O 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 SDD. A especificação é o recipiente; os cenários BDD são uma maneira de escrever o que vai dentro dele.

A distinção importa na prática: as ferramentas BDD focam em tornar os cenários executáveis. A prática 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 Diferencia-se 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 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 mínimo viável)
  • 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 deriva de intenção. A especificação é a referência. Quando o agente se desvia – e ele vai – o revisor tem algo para comparar a implementação. Sem uma especificação, a deriva é invisível até que algo quebre.

Melhores saídas de IA. Agentes dados com restrições explícitas, não-objetivos e critérios de aceitação produzem implementações mais próximas do que foi pretendido e 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 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?

Transição durável. Quando um recurso muda de mãos – entre engenheiros, entre sessões de agentes, entre sprints – a especificação é o artefato de transição. 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.

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

Especificações obsoletas. As 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.

Venda casada de ferramentas (Lock-in). Algumas ferramentas SDD são opinivas 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

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

A disciplina é simples: escreva 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 transição.

A especificação não é mágica. Uma especificação que não é validada torna-se o tipo mais caro de documentação: aquele 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 individual de agente.

O SDD está na interseção da prática de documentação, arquitetura de teste 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.