Spec-Driven Development

1. Por que especificar antes

Iniciar a implementação sem uma definição formal do comportamento esperado produz um conjunto previsível de consequências: retrabalho, contratos de API inconsistentes entre times, desalinhamento com quem pediu o sistema, testes que cobrem o que foi construído em vez do que era exigido e dívida técnica acumulada por decisões nunca registradas.

O ponto não é falta de capacidade técnica. É que a ambiguidade só se manifesta quando o código já existe, e nesse momento corrigi-la custa muito mais do que teria custado resolvê-la por escrito.

Spec-Driven Development (SDD) é a metodologia na qual a especificação técnica é a única fonte de verdade — Single Source of Truth, SSoT. O código deriva da especificação, os testes a verificam, a documentação a reflete e a geração assistida por inteligência artificial opera dentro dos seus limites.

2. Vocabulário: SSoT, requisito funcional e não funcional

Single Source of Truth

Princípio de arquitetura da informação segundo o qual cada informação relevante reside em um único artefato autoritário, do qual todas as demais representações derivam. Quando duas versões divergem, a fonte única prevalece: as cópias são reconciliadas com ela, jamais o inverso.

Requisito funcional (RF)

Descreve o que o sistema deve fazer — funções e comportamentos observáveis. Exemplo: "O sistema deve permitir o registro de usuário a partir de nome e endereço de e-mail."

Requisito não funcional (RNF)

Descreve como o sistema deve se comportar — qualidade, desempenho, segurança, operação. Exemplo: "O registro deve concluir em no máximo 2 segundos sob carga nominal."

SDD e TDD não competem

TDD (Test-Driven Development) escreve testes antes do código e fixa a correção interna da implementação. SDD descreve interfaces, contratos e metas antes, e é o que fundamenta o TDD. A especificação define a verdade; o TDD a implementa. Um projeto pode ter TDD sem SDD — e nesse caso testa corretamente a coisa errada.

3. Qualidade não funcional: ISO/IEC 25010:2023

A norma ISO/IEC 25010 define um modelo de qualidade de produto de software com nove características. Sua função em uma especificação é impedir que requisitos de qualidade permaneçam implícitos ou subjetivos: para cada característica pertinente ao componente, atribui-se uma métrica, um limite e um instrumento.

4. Anatomia de uma especificação

Uma especificação madura tem seis seções. A ordem importa: cada uma restringe a seguinte.

Seção 1 — Visão e escopo

Por que o sistema existe, quem são os usuários e qual problema resolve. Inclui o que está fora de escopo. Exemplo: "Sistema de cotação que reduz o tempo de resposta ao cliente de 24 h para menos de 5 min."

Seção 2 — Requisitos funcionais

Numerados (RF-001, RF-002) para que testes e código possam citá-los. Cada um declara descrição, pré-condições e pós-condições. Exemplo: "RF-001: usuário autenticado cria cotação. Pré: sessão válida. Pós: quoteId gerado e persistido."

Seção 3 — Requisitos não funcionais

Numerados (RNF-001), cada um com métrica, limite numérico e instrumento de verificação. Exemplo: "RNF-001: latência p95 ≤ 100 ms, medida no gateway, em janela de 30 dias."

Seção 4 — Contrato de API

Rotas, métodos, parâmetros, payloads, códigos de status e exemplos, expressos em OpenAPI 3.1. Deve incluir ao menos um caminho de erro por rota.

Seção 5 — Modelo de dados

Entidades, atributos, tipos, chaves e restrições de integridade — sem citar produto. Exemplo: Quote { id: UUID, chave primária; customerId: UUID, chave estrangeira; total: Decimal, não nulo; createdAt: Timestamp }.

Seção 6 — Cenários de teste

Critérios de aceite em Gherkin, um por regra de negócio. Cada cenário deve falhar antes de a implementação existir.

5. ADR — Architecture Decision Record

Um ADR registra uma decisão arquitetural significativa: o contexto que a motivou, as alternativas consideradas, a escolha feita e as consequências assumidas. Captura o porquê da estrutura, não o como da implementação.

Estrutura

• Título — identificador e enunciado. ADR-001: processamento assíncrono de cotações via fila.
• Status — proposto, aceito, substituído ou obsoleto.
• Contexto — a restrição real que exige uma decisão.
• Decisão — a escolha, em termos estruturais, sem produto.
• Alternativas — ao menos uma opção descartada, com o motivo.
• Consequências — o que fica pior, não apenas o que melhora.

Exemplo mínimo

# ADR-001 — Processamento assíncrono de cotações
Status: aceito

Contexto:   RNF-002 exige resposta em menos de 2 s. O cálculo de
            desconto por volume percorre o catálogo e não cabe na
            janela síncrona.

Decisão:    A criação da cotação responde imediatamente com o
            identificador; o cálculo ocorre fora do ciclo de
            requisição, em fila de processamento.

Descartado: Cálculo síncrono com cache do catálogo — o cache
            invalidaria a cada alteração de preço, sem ganho
            estável.

Consequências: introduz um componente de fila e um estado
            intermediário "em processamento" visível ao cliente.
            Exige garantia de entrega e política de reprocessamento.

6. A sequência documental

Antes de qualquer linha de código, e antes de qualquer escolha de tecnologia, cinco artefatos se sucedem. Cada um responde a uma pergunta distinta.

7. Pipeline de elicitação

Da análise do negócio até a implementação, seis estágios:

1. Modelagem de processos (IDEF0). Análise as-is: o que a organização faz hoje, quais são os atores, os fluxos e as lacunas.
2. Modelagem arquitetural (RM-ODP). Casos de uso, entidades e diagramas de sequência, organizados em pontos de vista.
3. Esqueleto do software. Estrutura de diretórios, limites de módulo, composição de ambiente. Projeto vazio, mas estruturalmente completo.
4. Documentos de especificação. Consolidação em Markdown e YAML, formatos legíveis por máquina — autoria integralmente humana.
5. Testes que falham (TDD). Contratos comportamentais expressos como pré-condições, pós-condições e invariantes.
6. Implementação. Somente aqui o código é escrito, manualmente ou com apoio de IA, para fazer os testes passarem e atender às metas não funcionais.

RM-ODP e os cinco pontos de vista

O modelo ISO/IEC 10746 descreve sistemas distribuídos em cinco perspectivas complementares, o que evita misturar intenção de negócio, modelo de dados e detalhe tecnológico no mesmo documento:

• Enterprise — propósito, papéis e políticas.
• Information — semântica e estrutura da informação.
• Computational — decomposição funcional e interfaces.
• Engineering — distribuição, comunicação e infraestrutura.
• Technology — escolhas concretas de produto.

8. Linguagens de contrato: OpenAPI e Gherkin

OpenAPI 3.1

Especificação padronizada, legível por máquina, expressa em YAML ou JSON. Descreve rotas, métodos, parâmetros, schemas e códigos de status, constituindo o contrato explícito entre quem produz e quem consome a API. A partir dela é possível gerar documentação navegável, validadores de requisição e esqueletos de cliente.

paths:
  /api/v1/quotes/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200': { description: Cotação encontrada }
        '403': { description: Cotação pertence a outro cliente }
        '404': { description: Cotação inexistente }

Gherkin

Linguagem estruturada de cenários no formato Dado/Quando/Então, legível pelo negócio e interpretável por ferramenta de teste. Cada cenário corresponde a um critério de aceite verificável.

Cenário: desconto por volume
  Dado um pedido com 12 unidades do produto A
  Quando calculo o total da cotação
  Então o desconto aplicado é de 5%

Cenário: cliente inativo
  Dado um cliente com cadastro inativo
  Quando solicito uma cotação
  Então a resposta é 400 e nenhuma cotação é persistida

9. Modelagem como código

Entende-se por modelagem como código (modeling as code) a prática de descrever os modelos do sistema em notação textual — Mermaid, PlantUML ou Structurizr DSL — mantida no mesmo repositório da especificação. O diagrama é gerado a partir do texto por ferramenta; a fonte de verdade é o texto, não a imagem.

A consequência prática é dupla: o modelo passa a ser revisado por diff em pull request, como qualquer outro artefato, e a divergência entre o que foi modelado e o que foi implementado torna-se visível no histórico. Um diagrama exportado como imagem e anexado a um documento não oferece nenhuma dessas garantias.

Três modelos são exigidos em toda especificação: o modelo de dados, que fundamenta o schema de persistência; o modelo estático, que delimita responsabilidades entre classes; e o modelo dinâmico, que fixa a ordem das interações e os caminhos de erro. Os exemplos a seguir descrevem um sistema de biblioteca com três entidades persistidas e cinco classes de domínio.

9.1 Modelo de dados: entidade-relacionamento

O diagrama entidade-relacionamento declara entidades, atributos, chaves primárias e estrangeiras e cardinalidades. É o antecedente do schema: nenhuma tabela deve existir sem correspondência aqui.

# modelos/dados.mmd
erDiagram
  LIVRO  ||--o{ EMPRESTIMO : origina
  LEITOR ||--o{ EMPRESTIMO : realiza
  LIVRO {
    uuid id PK
    text isbn UK
    text titulo
    int exemplares
  }
  LEITOR {
    uuid id PK
    text email UK
    bool ativo
  }
  EMPRESTIMO {
    uuid id PK
    uuid livro_id FK
    uuid leitor_id FK
    date prevista
    date efetiva
  }

9.2 Modelo estático: diagrama de classes

O diagrama de classes descreve a estrutura do domínio em memória: atributos, operações e dependências entre classes. Nem toda classe corresponde a uma tabela — a distinção entre estrutura persistida e estrutura de comportamento é uma das razões de existir o modelo estático.

# modelos/estatico.mmd
classDiagram
  direction LR
  class Livro {
    +UUID id
    +String isbn
    +int exemplares
    +disponivel() bool
  }
  class Leitor {
    +UUID id
    +bool ativo
  }
  class Emprestimo {
    +Date prevista
    +Date efetiva
    +emAtraso(hoje) bool
  }
  class PoliticaEmprestimo {
    +int prazoDias
    +int limitePorLeitor
    +validar(leitor, livro)
  }
  class ServicoEmprestimo {
    +registrar(leitor, livro)
    +devolver(emprestimo)
  }
  ServicoEmprestimo --> PoliticaEmprestimo
  ServicoEmprestimo --> Emprestimo
  Emprestimo --> Livro
  Emprestimo --> Leitor

Das cinco classes, três correspondem às entidades persistidas e duas existem apenas em memória. PoliticaEmprestimo concentra as regras de prazo e limite, que mudam por decisão institucional e não devem exigir alteração de esquema; ServicoEmprestimo orquestra a operação sem conhecer detalhes de persistência.

9.3 Modelo dinâmico: diagrama de sequência

O diagrama de sequência fixa a ordem das mensagens trocadas em uma operação e, sobretudo, os caminhos de erro. O bloco alt representa a bifurcação entre recusa e aprovação; cada ramo corresponde a um cenário Gherkin e a um código de status declarado no contrato OpenAPI.

# modelos/dinamico.mmd
sequenceDiagram
  actor A as Atendente
  participant API as POST /emprestimos
  participant S as ServicoEmprestimo
  participant P as PoliticaEmprestimo
  participant R as Repositorio
  A->>API: leitor_id, livro_id
  API->>S: registrar(leitor, livro)
  S->>P: validar(leitor, livro)
  alt limite excedido ou sem exemplar
    P-->>S: recusa(motivo)
    S-->>API: 422 motivo
  else apto
    P-->>S: aprovado(prazo 14d)
    S->>R: salvar(emprestimo)
    R-->>S: emprestimo
    S-->>API: 201 emprestimo
  end

10. Especificação e inteligência artificial

Modelos generativos produzem código sintaticamente correto com facilidade. O que não produzem, a partir de instrução vaga, é aderência a requisitos não funcionais e a conhecimento de domínio ausente do enunciado. Diante disso, a especificação cumpre três papéis:

• Restringe — limita o espaço de soluções e impede decisões arquiteturais improvisadas pelo modelo.
• Codifica — carrega conhecimento de domínio que o modelo não possui internamente.
• Verifica — define metas mensuráveis aplicadas depois da geração.

Comportamentos que o modelo não infere

Há classes de requisito que nunca emergem de uma instrução em linguagem livre. O processamento de eventos complexos é o caso típico: análise de fluxos contínuos que correlacionam múltiplos eventos ao longo do tempo — sequências, ausência de evento, agregações em janela. Um requisito como "alertar após três falhas de autenticação em menos de um minuto" depende de janela, ordem e critério de reinício que precisam estar declarados na especificação.

11. Verificação e refinamento iterativo

Cada característica de qualidade tem estratégia própria de verificação. Associar cada RNF a um instrumento é o que separa uma meta de uma intenção.

O ciclo

O código é gerado, verificado contra as metas e, havendo desvio, o relatório retorna ao modelo acompanhado da especificação original e da instrução de correção. Segue-se nova geração e nova verificação, até que todas as metas sejam atendidas ou até o limite de iterações definido — momento em que o caso é escalado e o trade-off, registrado.

12. Exemplo completo: endpoint de cotação

Especificação reduzida, mas completa nas seis seções, do endpoint usado como referência na aula.

# POST /api/v1/quotes — Criar cotação

## Visão
Permitir que o cliente obtenha o preço de um conjunto de itens
sem intervenção humana, reduzindo o tempo de resposta comercial.

## Requisitos funcionais
RF-001  Criar cotação a partir de customerId e lista de itens.
RF-002  Aplicar desconto de 5% quando a quantidade do item for ≥ 10.
RF-003  Rejeitar cotação de cliente inativo.

## Requisitos não funcionais
RNF-001 Latência p95 ≤ 100 ms, medida no gateway.
RNF-002 Idempotência garantida pelo cabeçalho Idempotency-Key.
RNF-003 Erro de banco resulta em 500 genérico, sem stack trace.
RNF-004 Lógica de desconto isolada em função própria e testável.

## Contrato
POST /api/v1/quotes
Cabeçalho: Idempotency-Key (UUID, obrigatório)
Corpo: { customerId: uuid,
         items: [ { productId: uuid, quantity: int ≥ 1,
                    priceUnit: decimal > 0 } ] }
201 → { quoteId: uuid, total: decimal }
400 → payload inválido ou cliente inativo
500 → erro interno

## Modelo de dados
Quote     { id UUID PK, customerId UUID FK, total Decimal NOT NULL,
            createdAt Timestamp NOT NULL }
QuoteItem { quoteId UUID FK, productId UUID, quantity Int,
            priceUnit Decimal, PK (quoteId, productId) }

## Cenários
Dado 12 unidades a 10,00, Quando crio a cotação,
  Então o total é 114,00 e o desconto aplicado é de 5%.
Dado a mesma Idempotency-Key de uma cotação existente,
  Quando repito a requisição, Então retorna o mesmo quoteId
  e nenhuma cotação nova é criada.

13. Aplicação após a aula

A aula reserva o encerramento para a demonstração conduzida pelo professor sobre o sistema de biblioteca. A aplicação do método pelo estudante ocorre após a aula, sobre o projeto do próprio grupo, no roteiro abaixo.

1. Escolha uma funcionalidade do projeto do seu grupo — por exemplo, cancelamento de pedido ou consulta de faturamento.
2. Escreva a especificação em Markdown com as seis seções: visão, RF numerados, RNF numerados, contrato, modelo de dados e cenários. No mínimo três metas não funcionais verificáveis, cada uma com métrica, limite e instrumento.
3. Registre em um ADR curto a principal decisão estrutural, incluindo a alternativa descartada e a consequência assumida.
4. Produza os três modelos em Mermaid, versionados junto da especificação: entidade-relacionamento, diagrama de classes e diagrama de sequência da operação principal, este último com o caminho de erro explícito.
5. Escreva os cenários Gherkin que fixam as regras. Confirme que todos falham antes de existir implementação.
6. Passe a especificação e os testes como contexto para um modelo generativo e peça a implementação do endpoint.
7. Execute análise estática, perfilamento de latência e um teste de falha para validar as metas não funcionais.
8. Havendo desvio, devolva o resultado medido ao modelo e peça refinamento sem alterar a especificação original.

14. Referências

• ISO/IEC 25010:2023 — Systems and software Quality Requirements and Evaluation: product quality model.
• ISO/IEC 10746 — Reference Model for Open Distributed Processing (RM-ODP).
• OpenAPI Specification 3.1 — OpenAPI Initiative.
• Cucumber — Gherkin Reference.
• MADR — Markdown Any Decision Records.
• Nygard, M. — Documenting Architecture Decisions.