Por que SDD: problema, motivação, conceitos-chave (SSoT, RF, RNF), qualidade ISO 25010.
Anatomia da spec: 6 seções (Visão, RF, RNF, API, Schema, Testes). ADR: rastreabilidade arquitetural. Pipeline de elicitação: 6 estágios.
Modelagem como código: OpenAPI e Gherkin; entidade-relacionamento, diagrama de classes e diagrama de sequência em Mermaid.
SDD e IA: verificação iterativa e demonstração ao vivo sobre um sistema de biblioteca.
Objetivo: ao final da aula, o estudante deve ser capaz de escrever uma especificação executável com anatomia clara, rastreada em ADRs, que orienta a implementação, os testes e a geração de código assistida por IA.
Iniciar a implementação sem definição formal do comportamento esperado resulta em:
Spec-Driven Development é a metodologia na qual a especificação técnica é a única fonte de verdade (Single Source of Truth — SSoT):
Princípio de arquitetura da informação: cada informação relevante reside em um único artefato autoritário, do qual todas as demais representações são derivadas. Quando duas versões divergem, a fonte única prevalece; as cópias devem ser reconciliadas com ela, jamais o inverso.
O que o sistema deve fazer: funções e comportamentos observáveis.
Ex: "O sistema deve permitir registro de usuário por nome e e-mail."
Como o sistema deve se comportar: qualidade, desempenho, segurança.
Ex: "Registro deve concluir em ≤2 segundos sob carga nominal."
TDD (Test-Driven Development) escreve os testes antes do código e fixa a correção interna. SDD descreve interfaces e contratos antes dos testes e fundamenta o TDD. As duas práticas são complementares: o TDD implementa o comportamento definido pela especificação.
Um modelo internacional que define qualidade de forma objetiva, impedindo que requisitos permaneçam implícitos ou subjetivos:
Tempo de resposta, uso de recursos, capacidade.
Coexistência e interoperabilidade com outros sistemas.
Apreensibilidade, operabilidade, proteção contra erro do usuário.
Ausência de falhas, disponibilidade, tolerância a falhas.
Confidencialidade, integridade, autenticidade.
Modularidade, testabilidade, modificabilidade.
Adaptabilidade, escalabilidade, instalabilidade.
Restrição operacional, falha segura, alerta de perigo.
Completude, correção e pertinência das funções.
Rotas, métodos HTTP, códigos de status e payloads de requisição/resposta usando OpenAPI v3.
Exemplo: GET /usuarios/{id} retorna {nome, email} ou 404.
Tipos, chaves, índices e restrições de integridade no banco de dados.
Exemplo: users.id PK, users.email UNIQUE NOT NULL.
Critérios de aceite em linguagem Gherkin/BDD (Dado/Quando/Então).
Exemplo: "Dado saldo 100, Quando saque 30, Então saldo=70."
Critérios mensuráveis para cada característica ISO 25010 aplicável.
Exemplo: "Latência ≤100ms p95, complexidade ciclomática ≤5."
Por que o sistema existe, quem são os usuários, qual problema resolve e o que fica fora de escopo.
"Cotação que reduz a resposta de 24h para <5min."
Numerados (RF-001) para que testes e código possam citá-los. Descrição, pré e pós-condições.
"RF-001: cria cotação. Pré: autenticado. Pós: quoteId."
Numerados (RNF-001), cada um com métrica, limite numérico e instrumento de verificação.
"RNF-001: p95 ≤100ms, medida no gateway."
Rotas, métodos, parâmetros, payloads e códigos de status em OpenAPI 3.1 — com caminho de erro.
POST /api/v1/quotes → 201 {quoteId, total} | 400
Entidades, atributos, tipos, chaves e restrições de integridade — sem citar produto.
Quote {id UUID PK, total Decimal NOT NULL}
Dado/Quando/Então, um por regra de negócio. Cada cenário deve falhar antes da implementação.
"Dado 12 unidades, Quando cotar, Então desconto 5%."
Documento que registra uma decisão arquitetural significativa: contexto, opções consideradas, decisão tomada e justificativa. O ADR registra o porquê da decisão; o detalhe de implementação permanece fora dele. Decisões estruturais e escolhas de tecnologia (ADR-Tech) são registradas em ADRs distintos.
ADR-001: Fila de Processamento
Decision: Processamento assíncrono de cotações via fila.
Rationale: RNF-002 exige latência <2s na resposta. Cálculo de desconto é custoso. Fila desacopla lógica de negócio.
Consequences: +1 componente (fila). RNF: taxa de processamento ≥1000 msgs/min.
ADR → Spec → Implementação. O ADR justifica a estrutura e os padrões que aparecem na spec e torna rastreável a origem de cada um. Exemplo: a presença da fila na spec remete ao ADR-001.
Contexto de negócio, lacunas, restrições e métricas de sucesso.
Produto e stakeholders. Registro de negócio: "o que não funciona e por quê".
Decisões estruturais: padrões, decomposição, limites de módulo.
Arquitetura. Sem tecnologia: "como estruturamos a solução?".
RF, RNF, contrato de API, modelo de dados e cenários de aceite.
Arquitetura e time. Ainda sem tecnologia: "qual o comportamento esperado?".
Linguagem, banco e framework, justificados contra a especificação.
Só aqui se escolhe produto. A spec não muda; a tecnologia a implementa.
Classes, funções e fluxo, abstraídos da sintaxe.
Time com apoio de IA: "quais módulos realizam a spec?".
Invariante: Problema → ADR → Spec → Tecnologia → Implementação, sem supressão de etapas. A spec não contém escolhas de produto ("use Node.js", "use PostgreSQL"); essas escolhas são registradas em ADR-Tech.
Especificação padronizada legível por máquina, expressa em YAML ou JSON.
Descreve rotas, métodos HTTP, parâmetros, schemas, códigos de status. Contrato explícito entre produtor e consumidor da API.
GET /usuarios/{id} → 200 {nome, email} | 404
Linguagem estruturada de cenários: Dado/Quando/Então (Given/When/Then).
Legível por humanos e interpretável por ferramentas. Cada cenário = critério de aceite verificável.
Dado saldo 100; Quando saque 30; Então saldo=70.
Modelo ISO/IEC 10746 que descreve sistemas distribuídos em 5 pontos de vista complementares, evitando mistura de intenção de negócio, modelo de dados e detalhe tecnológico: Enterprise (propósito, papéis), Information (semântica, estrutura), Computational (decomposição funcional), Engineering (distribuição), Technology (escolhas concretas).
Entende-se por modelagem como código a prática de descrever os modelos do sistema em notação textual — Mermaid, PlantUML, Structurizr DSL — armazenada junto da especificação. O diagrama é derivado do texto por ferramenta; a fonte de verdade é o texto.
erDiagram).classDiagram).sequenceDiagram).Exemplo conduzido nos próximos slides: sistema de biblioteca — três entidades persistidas e cinco classes de domínio.
// 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 }
A cardinalidade ||--o{ fixa a regra: um livro origina zero ou muitos empréstimos. efetiva nula identifica empréstimo em aberto; essa convenção deve constar da especificação.
// modelos/estatico.mmd classDiagram 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
Três classes correspondem às entidades persistidas; duas existem apenas em memória. PoliticaEmprestimo isola as regras de prazo e limite, que mudam por decisão institucional sem exigir alteração de esquema.
// 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
O bloco alt torna o caminho de recusa parte do modelo. Cada ramo corresponde a um cenário Gherkin e a um código de status no contrato OpenAPI.
A IA gera código sintaticamente correto com facilidade, mas sem alinhamento com requisitos não funcionais quando a instrução é vaga. Uma spec bem estruturada:
Limita o espaço de soluções possíveis, evitando decisões arquiteturais improvisadas.
Encapsula conhecimento de domínio que o modelo não possui internamente.
Define metas de qualidade verificáveis após geração.
Processamento de Eventos Complexos (CEP): análise de fluxos contínuos que correlacionam múltiplos eventos ao longo do tempo (sequências, ausência de eventos, agregações em janelas). Exemplo: alerta após 3 falhas de autenticação em <1 minuto. Essas janelas e ordens devem ser definidas explicitamente na especificação.
| Característica | Estratégia de Verificação |
|---|---|
| Eficiência de desempenho | Perfilamento (profiling) de tempo e recursos |
| Confiabilidade | Injeção de falhas, teste de fallback |
| Segurança | Análise estática, auditoria de código |
| Manutenibilidade | Complexidade ciclomática, taxa de duplicação |
Ciclo de Verificação: código é gerado → verificado contra metas → desvios → relatório retorna à IA com spec original + instrução de correção → regeneração → reverificação até que todas as metas sejam atendidas (máx. N iterações).
Importante: a verificação é etapa obrigatória e integrante do método. Sem verificação instrumentada, o atendimento à especificação permanece não confirmado.
Metodologia na qual a especificação técnica é a única fonte de verdade (SSoT), fundamentando código, testes, documentação e geração por IA.
Sempre que há múltiplos stakeholders, requisitos não funcionais críticos ou envolvimento de IA na geração de código.
1. Contrato de API (OpenAPI)
2. Schema de Dados
3. Regras e Cenários (Gherkin)
4. Metas de Qualidade (ISO 25010)
Documento Markdown estruturado, ADR, especificação OpenAPI v3, cenários Gherkin, modelos em Mermaid (dados, classes, sequência), testes automatizados.
1. Processos (IDEF0) → 2. Arquitetura (RM-ODP) → 3. Esqueleto sem tecnologia → 4. Spec (100% humana) → ADR-Tech → 5. TDD → 6. Implementação (IA-assistida)
Cliente: Hoje anotamos em caderno quem levou o quê. Some livro, e ninguém sabe com quem está. Queria um sistema para cadastrar o acervo e controlar os empréstimos.
Analista: Por quantos dias o livro fica com o leitor?
Cliente: Duas semanas, acho. Mas para professor podia ser mais, né?
Analista: Existe renovação ou reserva?
Cliente: Isso eu não tinha pensado. Renovar acho que sim, se ninguém estiver esperando.
Analista: E quando o leitor atrasa?
Cliente: Multa não dá, a biblioteca é comunitária. Talvez bloquear até devolver. Ah, e tem título com dois ou três exemplares iguais. E precisa ser rápido, o computador da recepção é antigo.
ADR da decisão estrutural, especificação com RF e RNF mensuráveis, os três modelos em Mermaid — três entidades e cinco classes —, contrato OpenAPI, cenários Gherkin e verificação do código gerado.
Spec-Driven Development · 04/08/2026 · Prof. Afonso
Ao final do encontro, o estudante deve ser capaz de escrever uma especificação executável com anatomia clara, rastreada em ADRs, que orienta a implementação, os testes e a geração de código assistida por modelos generativos.
Exposição em quatro blocos com construção incremental de uma especificação de referência; o encerramento é uma demonstração conduzida pelo professor sobre um sistema de biblioteca, e a aplicação ao projeto do grupo ocorre após a aula, conforme roteiro do material.