Spec-Driven Development (SDD)

1. O que é Spec-Driven Development?

É comum iniciar a implementação antes de qualquer definição formal do comportamento esperado. Essa prática resulta em retrabalho, inconsistência de contratos de API e desalinhamento com as partes interessadas. O Spec-Driven Development (SDD) é uma metodologia de desenvolvimento de software na qual a especificação técnica constitui a única fonte de verdade (Single Source of Truth — SSoT).

Entende-se por Single Source of Truth (SSoT), em português fonte única de verdade, o princípio de arquitetura da informação segundo o qual cada informação relevante do sistema reside em um único artefato autoritativo, do qual todas as demais representações são derivadas. Artefato autoritativo é aquele que detém precedência formal em caso de conflito: quando duas versões da mesma informação divergem, a fonte única prevalece e as cópias devem ser reconciliadas com ela, jamais o inverso. No SDD, a especificação assume esse papel, de modo que código, testes e documentação permaneçam derivações verificáveis de um mesmo artefato, e não versões concorrentes sujeitas a divergência.

No SDD, antes de qualquer implementação, a equipe redige especificações que descrevem o comportamento planejado do sistema. Essas especificações contêm, no mínimo:

• Contratos de API — rotas, métodos, payloads (o corpo de dados transmitido em uma requisição ou resposta) e códigos de status, tipicamente descritos em OpenAPI/Swagger.
• Modelagem e esquemas de dados (tipos, chaves, restrições de integridade).
• Regras de negócio explícitas e fluxos de exceção.
• Metas de qualidade não funcional mensuráveis, não apenas requisitos funcionais.

2. Qualidade Não Funcional como Parte da Especificação

Uma especificação tecnicamente completa não se limita a descrever o que o sistema faz. Ela define também como o sistema deve se comportar sob variação de carga, falha, uso indevido ou mudança de contexto — as chamadas propriedades não funcionais.

A ISO/IEC 25010:2023, publicada conjuntamente pela International Organization for Standardization (ISO) e pela International Electrotechnical Commission (IEC), é a norma internacional que define um modelo de qualidade de produto de software, sucedendo a ISO/IEC 9126. Seu propósito não é apenas catalogar características, mas fornecer vocabulário e taxonomia comuns que permitam especificar, medir e avaliar atributos de qualidade de forma objetiva, impedindo que requisitos não funcionais permaneçam implícitos ou sujeitos a interpretação subjetiva. O modelo organiza a qualidade em nove características: a adequação funcional trata da correção das funções entregues; as oito restantes tratam de qualidade não funcional e são particularmente relevantes quando parte do código é gerada por IA:

Cada subcaracterística decompõe-se em critérios mensuráveis. Um requisito enunciado como "a aplicação deve restabelecer o serviço em até trinta segundos após a queda da conexão de rede" corresponde à confiabilidade, na subcaracterística de recuperabilidade, e passa a ser verificável por critério objetivo em lugar de permanecer expectativa tácita.

3. Os Pilares de uma Especificação Madura

Uma especificação madura no ecossistema de dados e software é composta por quatro pilares:

OpenAPI e Swagger. OpenAPI é uma especificação padronizada e legível por máquina, expressa em formato estruturado (YAML ou JSON), destinada a descrever de maneira formal APIs HTTP — tipicamente de estilo REST —, incluindo rotas, métodos HTTP, parâmetros, esquemas de payload e códigos de status de resposta. Swagger designa o conjunto de ferramentas associado a essa especificação, nome que historicamente identificava a própria especificação antes de esta ser doada à OpenAPI Initiative e renomeada; tais ferramentas geram documentação interativa, validadores e artefatos de código a partir do documento. A especificação constitui um contrato explícito entre o produtor e o consumidor da API, definindo com precisão a interface de cada operação — suas entradas, saídas e códigos de status —, e pode ser acordada antes da implementação. Um documento OpenAPI pode declarar, por exemplo, que a rota GET /usuarios/{id} recebe um identificador inteiro no caminho e retorna, com código 200, um objeto contendo os campos nome e e-mail, ou o código 404 quando o identificador não corresponde a nenhum registro.

Gherkin e BDD. O Behavior-Driven Development (BDD), ou desenvolvimento orientado a comportamento, descreve o comportamento esperado de um sistema por meio de cenários concretos, formulados em linguagem compreensível tanto por equipes técnicas quanto por partes interessadas sem formação técnica. Gherkin é a linguagem estruturada que materializa esses cenários no formato Dado/Quando/Então (Given/When/Then), simultaneamente legível por humanos e interpretável por ferramentas de automação: "Dado" estabelece o contexto inicial, "Quando" identifica a ação ou o evento e "Então" define o resultado esperado. Cada cenário expressa um critério de aceitação verificável e versionado, mantendo a especificação como fonte de verdade continuamente confrontada com a implementação. Exemplo: "Dado que uma conta possui saldo de 100 unidades; Quando o titular solicita um saque de 30 unidades; Então o saldo resultante deve ser de 70 unidades e a operação deve ser registrada como concluída."

4. Da Análise de Negócio à Especificação: um Pipeline em Seis Estágios

A especificação não nasce pronta. Ela resulta de um processo estruturado de elicitação — a atividade sistemática de levantar, extrair e explicitar requisitos junto aos stakeholders (usuários, clientes, especialistas de domínio e demais partes interessadas), convertendo necessidades tácitas e frequentemente ambíguas em enunciados verificáveis. Constitui a etapa inicial da engenharia de requisitos e recorre a técnicas como entrevistas, questionários, observação direta, análise de documentos e prototipação. Quando organizada em etapas encadeadas de coleta, refinamento e validação, a elicitação assume a forma de um pipeline. Um pipeline consolidado segue seis estágios sequenciais, dos quais apenas o último admite participação de Inteligência Artificial:

1. Modelagem de processos de negócio: análise as-is do domínio, usando técnicas de decomposição funcional (ex.: IDEF0) para identificar stakeholders, entradas, saídas, controles e mecanismos dos processos que o software deve apoiar. Este estágio responde a o que a organização faz e onde estão as lacunas, não qual deve ser a aparência do software.
2. Modelagem arquitetural: casos de uso, modelos estáticos (entidades de domínio, esquemas de dados, decomposição em módulos) e modelos dinâmicos (diagramas de sequência, fluxos de eventos, transições de estado). Para sistemas com múltiplas perspectivas de interesse, frameworks como o RM-ODP organizam a arquitetura em viewpoints.
3. Esqueleto do software: estrutura de diretórios, limites de módulo, arquivos de configuração, descritores de implantação (ex.: Docker Compose) e contratos de interface — um projeto vazio, porém estruturalmente completo.
4. Documentos de especificação: consolidação das saídas anteriores em documentos legíveis por máquina (Markdown, YAML, JSON), incluindo metas mensuráveis para cada característica não funcional aplicável (Seção 2). A autoria destes documentos é inteiramente humana; a IA não participa deste estágio.
5. Desenvolvimento guiado por testes (TDD): elaboração de casos de teste que consolidam os contratos comportamentais definidos nos estágios anteriores. Todos os testes devem falhar inicialmente (fase vermelha), confirmando que nenhuma lógica foi implementada e que os testes de fato verificam comportamento.
6. Implementação: somente neste estágio o código é gerado — manualmente ou com apoio de IA —, com o objetivo de fazer os testes do estágio anterior passarem (fase verde) e, simultaneamente, satisfazer as metas de qualidade não funcional definidas no estágio 4.

Análise as-is. A expressão as-is, do inglês "como está", designa a representação do estado atual de um processo ou sistema, tal como opera antes de qualquer intervenção. A análise as-is documenta os fluxos, atores, regras e limitações vigentes, constituindo uma linha de base factual que se contrapõe ao estado futuro desejado, denominado to-be. Sua finalidade é assegurar que toda especificação de mudança parta de uma compreensão rigorosa daquilo que efetivamente existe, evitando suposições descoladas da realidade operacional. Ao modelar a emissão de segunda via de um documento, por exemplo, a análise as-is registra que a solicitação é hoje recebida por correio eletrônico, conferida manualmente e respondida em até dois dias úteis, sem automação — o estado atual, não a solução pretendida.

Contratos comportamentais. Os contratos comportamentais mencionados no estágio 5 constituem a especificação formal das obrigações e garantias de uma operação ou módulo, conforme a abordagem de projeto por contrato (Design by Contract). Compõem-se de três cláusulas: a pré-condição, que estabelece o que deve ser verdadeiro antes da invocação e cuja satisfação é responsabilidade do chamador; a pós-condição, que descreve o que a operação garante ao terminar, desde que a pré-condição tenha sido satisfeita; e a invariante, propriedade que deve valer em todos os estados observáveis do objeto — após sua construção e entre as operações públicas —, podendo ser temporariamente violada durante a execução interna de uma operação. Em uma pilha de capacidade fixa, a inserção tem por pré-condição que a pilha não esteja cheia, por pós-condição que o elemento inserido ocupe o topo e o tamanho seja incrementado em uma unidade, e por invariante que o número de elementos permaneça entre zero e a capacidade máxima. Tais cláusulas tornam explícita a distribuição de responsabilidades entre chamador e operação chamada, delimitando de forma inequívoca a origem de uma falha.

Especificações legíveis por máquina. Os documentos do estágio 4 são redigidos em formato estruturado — tipicamente Markdown, YAML ou JSON —, cuja sintaxe permite processamento automático por ferramentas e por modelos de linguagem, em oposição ao texto livre em prosa. Ao adotar estrutura formal, com campos, chaves nomeadas, hierarquia e tipos declarados, tais documentos reduzem a ambiguidade interpretativa da linguagem natural e servem simultaneamente como comunicação inteligível para humanos e como entrada consumível por processos automatizados, habilitando validação, versionamento e geração de artefatos derivados.

Docker Compose e conteinerização. A conteinerização, referida no estágio 3, é a técnica de empacotar uma aplicação em conjunto com suas dependências, bibliotecas e configurações em uma unidade isolada denominada contêiner, a qual compartilha o núcleo (kernel) do sistema operacional hospedeiro e executa de maneira consistente na maioria dos ambientes compatíveis. O Docker Compose é uma ferramenta que descreve, por meio de um arquivo declarativo em YAML, a definição e a execução coordenada de múltiplos contêineres em um único host — por exemplo, uma aplicação e seu banco de dados —, especificando serviços, redes e volumes; a orquestração distribuída em escala pertence a ferramentas como Kubernetes ou Docker Swarm. Seu emprego favorece a reprodutibilidade: uma vez que o ambiente de execução passa a ser especificado explicitamente em código, a implantação torna-se mais previsível entre as máquinas de desenvolvimento, teste e produção. No SDD, o arquivo de composição atua como especificação executável do ambiente, convertendo a infraestrutura de conhecimento tácito em artefato versionado e verificável.

5. Spec-Driven Development e Inteligência Artificial

Com o avanço de assistentes de codificação por IA, o SDD tornou-se ainda mais relevante. Modelos de linguagem geram código sintaticamente correto com facilidade, mas o resultado frequentemente carece de alinhamento com requisitos não funcionais quando a instrução recebida é vaga ou informal.

Uma especificação bem estruturada cumpre três papéis simultâneos diante de um modelo generativo: restringe o espaço de soluções possíveis, evitando decisões arquiteturais improvisadas; codifica conhecimento de domínio que o modelo não possui; e define metas de qualidade verificáveis, conferíveis após a geração. Nenhum desses papéis é cumprido por um prompt informal.

6. Verificação e Refinamento Iterativo

Gerar código a partir de uma especificação não encerra o processo. O resultado deve ser verificado contra as metas definidas para cada característica não funcional, usando ferramental apropriado a cada uma:

Perfilamento (profiling). Entende-se por perfilamento a medição, em tempo de execução, do consumo de tempo de processamento e de recursos (memória, chamadas de sistema, operações de entrada e saída) atribuído a cada trecho de um programa. A técnica instrumenta ou amostra a execução para associar esses custos a funções, laços ou linhas específicas, revelando onde o programa concentra seu esforço. Distingue-se da análise estática por operar sobre a execução real, e não sobre o texto do código. Requisitos não funcionais de eficiência de desempenho só podem ser verificados objetivamente por meio dele, que converte as metas declaradas na especificação em medições comparáveis.

Injeção de falhas (fault injection). Constitui a técnica de teste que introduz deliberadamente condições anômalas em um sistema em execução — indisponibilidade de um serviço, latência excessiva, erro de rede —, a fim de observar seu comportamento sob adversidade. Exercita explicitamente as rotas de tratamento de erro e os mecanismos de contingência que os testes de caminho feliz não alcançam, evidenciando se o sistema degrada de forma controlada e retorna a um estado consistente após a remoção da falha. Em um serviço que consome uma API externa de câmbio, suspende-se temporariamente o contêiner dessa dependência durante os testes e verifica-se se o serviço aplica timeout, retorna valor em cache e registra o incidente, em vez de propagar a falha ao usuário.

Degradação graciosa (graceful degradation) e fallback. Degradação graciosa é a propriedade pela qual um sistema mantém operação parcial, com funcionalidade reduzida, quando um de seus componentes ou dependências falha, torna-se indisponível ou é submetido a sobrecarga, em vez de interromper por completo. O fallback é o comportamento alternativo acionado nesse cenário: um caminho substituto que preserva a continuidade do serviço, ainda que sob garantias menores. Um serviço de recomendação que consulta uma API externa de preferências pode, ao detectá-la indisponível, retornar uma lista padrão armazenada localmente — resultado menos personalizado, porém funcional. A especificação deve declarar de forma explícita o comportamento esperado diante da falha de cada dependência, convertendo a degradação graciosa em requisito verificável.

Análise estática de código. É o exame do código-fonte sem execução do programa, com o objetivo de detectar defeitos, vulnerabilidades e violações de padrão. A técnica inspeciona a estrutura textual e sintática — declarações, fluxos de controle, dependências, expressões — para identificar problemas como segredos codificados diretamente no fonte, uso de construções perigosas (por exemplo, a função eval()) e ausência de validação de entradas. Distingue-se da análise dinâmica, que avalia o comportamento durante a execução: a estática opera antes e independentemente da execução, alcançando caminhos que os testes dinâmicos podem não exercitar. Ambas são complementares. No SDD, a análise estática constitui um gate automatizado que verifica se o código respeita as restrições de segurança e de padrão fixadas na especificação.

Complexidade ciclomática. Métrica proposta por McCabe que quantifica o número de caminhos linearmente independentes no grafo de fluxo de controle de um módulo ou função. Cada estrutura de decisão — condicional, laço ou operador lógico de curto-circuito — introduz uma ramificação e incrementa o valor. Seu valor corresponde ao número de casos de teste de um conjunto-base de caminhos independentes: opera como limite superior para a cobertura de ramos e como limite inferior para a cobertura de todos os caminhos de execução possíveis. Uma função que apenas retorna a soma de dois parâmetros tem complexidade 1; ao acrescentar duas condicionais que tratam valores nulos e negativos, o número de caminhos independentes sobe para 3, exigindo três casos de teste para cobrir o conjunto-base. Valores elevados indicam lógica mais ramificada, o que eleva o esforço de teste e dificulta a compreensão e a alteração seguras — constituindo, assim, um proxy quantitativo de testabilidade e manutenibilidade verificável por análise estática.

Taxa de duplicação de código. Métrica que quantifica a proporção de trechos idênticos ou substancialmente semelhantes presentes em uma base de código, em relação ao seu volume total. É um indicador de manutenibilidade, comumente obtido por análise estática. Valores elevados sinalizam que uma mesma lógica se encontra replicada em múltiplos pontos, de modo que a correção de um defeito ou a alteração de uma regra deve ser propagada a todas as ocorrências, sob pena de inconsistência. Uma rotina de validação de e-mail copiada em cinco módulos exige, ao corrigir uma falha, a edição das cinco cópias; a omissão de qualquer uma mantém o defeito ativo. A especificação pode estabelecer um limiar máximo tolerado, assegurando que o código derivado dela preserve a manutenibilidade prescrita.

Quando a verificação aponta desvio — um teste que falha, uma meta de complexidade excedida, um segredo codificado diretamente no código —, o relatório de qualidade retorna à IA geradora junto às especificações originais, com instrução explícita sobre o que corrigir. O código é regenerado e reverificado. O ciclo se repete até que todas as metas sejam atendidas ou até que um número máximo de iterações seja atingido.

7. Exemplo Prático de uma Spec

Abaixo, um exemplo simplificado de especificação técnica em Markdown para um endpoint de criação de cotações em um microsserviço de faturamento, incluindo metas de qualidade não funcional.

# Especificação: Endpoint de Cotação (Billing Service)

## Informações Gerais
*   **Rota:** `/api/v1/quotes`
*   **Método:** `POST`
*   **Content-Type:** `application/json`
*   **Cabeçalho `Idempotency-Key`:** UUID único da requisição, obrigatório. Requisições repetidas com a mesma chave não geram cotações duplicadas.

## Payload de Requisição
```json
{
  "customerId": "uuid (obrigatório)",
  "items": [
    {
      "productId": "string (obrigatório)",
      "quantity": "integer (obrigatório, mínimo 1)",
      "priceUnit": "float (obrigatório, positivo)"
    }
  ]
}
```

## Regras de Negócio e Validações
1.  **Validação de Cliente:** o `customerId` deve ser um UUID válido e pertencer a um cliente ativo no banco de dados. Caso contrário, retornar `400 Bad Request` com o erro correspondente.
2.  **Cálculo do Total:** o microsserviço deve calcular o valor total da cotação multiplicando `quantity` * `priceUnit` para cada item e somando os resultados.
3.  **Desconto por Quantidade:** se a quantidade de qualquer item for maior ou igual a 10, deve ser aplicado um desconto de 5% sobre o preço unitário desse item.

## Respostas Esperadas
*   `201 Created`: cotação gerada com sucesso. Retorna o ID da cotação criada e o total final.
*   `400 Bad Request`: payload inválido ou falha em regra de negócio.
*   `500 Internal Server Error`: erro inesperado do servidor.

## Metas de Qualidade Não Funcional
*   **Segurança:** nenhum segredo codificado diretamente; validação de `customerId` obrigatória antes de qualquer cálculo.
*   **Manutenibilidade:** lógica de desconto isolada em função própria, testável isoladamente do cálculo do total.
*   **Confiabilidade:** falha de acesso ao banco de dados deve retornar `500` com mensagem genérica, sem expor stack trace ao cliente.
*   **Confiabilidade (idempotência):** a submissão repetida de uma mesma cotação, identificada pelo cabeçalho `Idempotency-Key`, não deve gerar registros duplicados.

8. Desafio Prático de Autoestudo

Esta seção propõe um exercício de aplicação do Spec-Driven Development.