Spec-Driven Development (SDD)

1. Visão Geral do Conceito e Problema Sistêmico

O erro mais comum entre desenvolvedores iniciantes em vibe coding é a abordagem "Prompt-and-Pray" (escrever um prompt vago no chat e esperar que o modelo acerte a arquitetura). Quando o pedido soa como "Faça o billing via Stripe para assinantes", o modelo escolhe aleatoriamente esquemas de banco de dados, usa bibliotecas desatualizadas, ignora webhooks, esquece a idempotência e não considera casos extremos de cancelamento de pagamento. Quando o engenheiro pede para corrigir um bug, o modelo começa a fazer remendos frenéticos, transformando definitivamente a base de código em spaghetti code (AI Slop).

Spec-Driven Development (SDD, desenvolvimento orientado por especificações) é uma disciplina de engenharia que separa a etapa de design sistêmico da etapa de geração de código. Antes de tocar na base de código, cria-se um documento formalizado de especificação (spec.md ou RFC.md). Este documento torna-se a única fonte da verdade (Single Source of Truth) e o contrato contra o qual o agente executa e verifica cada passo subsequente.

2. Taxonomia Arquitetural e Modelo Mental

A estrutura arquitetural do SDD baseia-se em uma hierarquia clara de artefatos de design:

┌─────────────────────────────────────────────────────────────┐
│             HIERARQUIA DE ARTEFATOS PARA DESENVOLVIMENTO     │
│                    ORIENTADO POR ESPECIFICAÇÕES              │
├─────────────────────────────────────────────────────────────┤
│ 1. Contexto do Produto: Problema do usuário e objetivo       │
│    de negócio                                                │
├─────────────────────────────────────────────────────────────┤
│ 2. Contratos Técnicos:                                      │
│    • Esquemas de dados (Schemas Drizzle / Prisma, SQL DDL)   │
│    • Contratos de API (Zod Schemas, OpenAPI, tipos           │
│      TypeScript)                                             │
│    • Invariantes & Regras de Segurança (Idempotência, RBAC,  │
│      Autenticação)                                           │
├─────────────────────────────────────────────────────────────┤
│ 3. Checklist de Tarefas Atômicas (DAG):                     │
│    • Etapa 1 ➔ Etapa 2 ➔ Etapa 3                            │
│      (Ordem estrita de dependências)                         │
├─────────────────────────────────────────────────────────────┤
│ 4. Predicados de Verificação: Critérios de prontidão         │
│    automatizados                                             │
└─────────────────────────────────────────────────────────────┘

1. Contratos Técnicos (Interface-First):
   • Descrevem a interação dos sistemas antes da implementação da lógica interna. São definidas as estruturas de requisição/resposta, esquemas de validação e estados de erro.
2. Grafo Atômico de Tarefas (Task Decomposition DAG):
   • A tarefa é decomposta em uma sequência de subtarefas pequenas e independentemente verificáveis. Cada subtarefa deve modificar no máximo 1–3 arquivos.
3. Critérios Verificáveis por Máquina (Acceptance Predicates):
   • Em vez de um subjetivo "verifique se tudo funciona", a especificação contém comandos de verificação concretos: "pnpm test auth.test.ts passa com sucesso, cobertura de branches > 90%".
4. Rastreador de Status do Ciclo de Vida (Lifecycle Tracker):
   • A especificação contém checkboxes interativos ([ ] ➔ [x]), que o agente atualiza após a execução e verificação de cada etapa.

3. Pipeline Técnico e Mecânica Interna

O ciclo de vida do desenvolvimento sob a metodologia SDD:

1. Entrevista e Síntese da Especificação (Interview Phase): O engenheiro formula a tarefa. O modelo faz perguntas esclarecedoras sobre detalhes não triviais: qual comportamento é esperado em caso de queda de rede, como tratar duplicatas, quais são os limites de rate limiting.
2. Fixação da Especificação no Repositório: Cria-se um artefato (por exemplo, .specs/004-billing-integration.md), que é adicionado ao sistema de controle de versão Git.
3. Auditoria Humana e Aprovação (Spec Approval): O engenheiro revisa os esquemas de dados e contratos propostos. Se a decisão arquitetural contiver falhas, elas são corrigidas no nível do texto da especificação em 2 minutos, evitando horas de reescrita de código.
4. Delegação Passo a Passo ao Agente (Step-by-Step Execution): O agente é invocado para implementar uma etapa específica da especificação:
   • O agente lê o contexto da especificação.
   • Escreve testes de acordo com os contratos (TDD).
   • Implementa a funcionalidade.
   • Executa os testes e registra a conclusão da subtarefa.
5. Verificação Final e Arquivamento: Quando todos os itens da especificação estão marcados como concluídos, realiza-se uma auditoria ponta a ponta, e a especificação permanece no repositório como documentação viva da feature.

4. Cenários Práticos de Engenharia em Produção

01. Desenvolvimento de Módulo de Pagamento Crítico com Idempotência

Antes de escrever o código de integração do gateway de pagamento, o engenheiro cria uma especificação:

• Registra a estrutura da tabela idempotency_keys com campos key, response_payload, status, expires_at.
• Descreve o algoritmo exato de comportamento ao receber um webhook repetido com o mesmo transaction_id.
• O agente implementa o módulo estritamente conforme a especificação; nenhum caso extremo é perdido.

02. Trabalho Paralelo de Agentes Backend e Frontend

A equipe cria um novo dashboard de analytics:

• Primeiro, na especificação, descrevem-se os esquemas Zod e interfaces TypeScript para todos os gráficos e métricas.
• O agente frontend usa esses esquemas para construir componentes com dados mockados.
• O agente backend implementa simultaneamente as consultas SQL reais e as rotas API sob o mesmo contrato.
• A integração ocorre sem qualquer conflito de incompatibilidade de tipos.

03. Migração Segura e Escalável de Módulo Legacy

Substituição da antiga autenticação caseira por Better Auth:

• A especificação descreve a preservação da compatibilidade retroativa das sessões no Redis e um plano passo a passo para migrar hashes de senha de bcrypt para Argon2id.
• O agente divide a migração em 7 etapas isoladas, cada uma testada individualmente.

5. Armadilhas, Erros Comuns e Segurança

• Paralisia por Over-Engineering: Escrever uma especificação de 20 páginas para uma pequena correção de indentação ou mudança de cor de botão é um desperdício absurdo de tempo. Aplique o SDD para tarefas que abrangem mais de 2 módulos ou contêm lógica de negócio crítica.
• Dessincronização entre Código e Especificação (Spec Rot): Se durante o desenvolvimento surgir a necessidade de alterar o esquema, os engenheiros frequentemente corrigem o código diretamente, esquecendo de atualizar o spec.md. Isso confunde os agentes subsequentes, que lerão novamente a especificação obsoleta.
• Uso de Formulações Vagas: Frases como "o sistema deve ser rápido" ou "garantir confiabilidade" são catastróficas para IA. A especificação deve operar com valores concretos: "latência p99 < 150ms", "retornar HTTP 429 ao exceder 100 rpm".
• Ignorar o Versionamento das Especificações: Os arquivos de especificação devem fazer parte do repositório Git junto com o código, permitindo rastrear a evolução das decisões arquiteturais através do histórico de commits.