Spec-Driven Development (SDD)

Regra de Ouro: A Especificação (Spec) vem antes do código.

O Problema: Modo "Tentativa e Erro" com IA

Até agora, muitas pessoas usam ferramentas de IA no modo "tentativa e erro":

Você digita um prompt rápido e vago
A IA gera algo pela metade
Você pede correções
Ela quebra outra coisa
Vira uma bagunça — loop infinito de correções

Consequências

Gasto excessivo de tokens (créditos da IA)
Perda de contexto a cada iteração
Ciclo vicioso de prompts de correção
IA "alucina" e gera resultados inconsistentes
Mais estresse, menos produtividade

A Solução: Spec-Driven Development

O SDD inverte a lógica. Em vez de pedir para a IA sair programando do zero, primeiro documentamos de forma estruturada exatamente o que queremos.

Fluxo do SDD

1. Especificação do Projeto (PRD.md)
           ↓
2. Prompt (com a Spec como contexto)
           ↓
3. Aprovado?
   ├── NÃO → Editar com base na Spec
   └── SIM → Design (PRD.md)
                ↓
4. Aprovado?
   ├── NÃO → Editar com base na Spec
   └── SIM → ✅ Done! Menos stress, menos token, sem alucinação

O que é a Especificação (Spec / PRD.md)?

É um documento de texto puro que se torna a "lei" do projeto. Deve conter:

Elemento	Descrição
Objetivo	O que queremos construir
Regras	Regras de negócio e comportamento esperado
Restrições	Limitações técnicas, bibliotecas permitidas, performance
Entradas	O que entra no sistema (dados, formatos, fontes)
Saídas	O que sai do sistema (resultados, relatórios, arquivos)
Critérios de Aprovação	Quando sabemos que está pronto

Comparação: Sem SDD vs Com SDD

Aspecto	Sem SDD	Com SDD
Prompt	Vago e genérico	Baseado na especificação
Iteração	Correções em loop infinito	Edição na spec antes de gerar
Tokens	Gasta muitos	Economia significativa
Resultado	IA "alucina"	Preciso e padronizado
Experiência	Estressante	Organizada e previsível

Princípios Fundamentais

1. Spec antes do Código

Nunca peça para a IA programar sem antes ter uma especificação clara.

2. Especifique Melhor, Resultado Melhor

"Especifique melhor para ter um resultado melhor!"

3. Não Precisa Saber Programar

Você não precisa ser programador para automatizar processos manuais, mas precisa saber especificar.

4. A Spec é a Lei

Quando a IA recebe a especificação como contexto, ela segue as regras de forma precisa e padronizada.

Exemplo Prático

❌ Sem SDD (Prompt Vago)

"Crie um script Python pra mim"

→ IA gera algo genérico → Você pede alterações → Loop infinito

✅ Com SDD (Especificação Estruturada)

Crie um PRD.md com:

# PRD - Script de Processamento de Dados

## Objetivo
Automatizar a leitura de arquivos CSV e gerar relatório consolidado.

## Entradas
- Arquivo CSV localizado em: `./dados/entrada.csv`
- Colunas: data, produto, quantidade, valor_unitario

## Processamento
1. Ler o CSV
2. Calcular valor_total = quantidade * valor_unitario
3. Agrupar por produto somando quantidade e valor_total
4. Ordenar por valor_total decrescente

## Saídas
- Arquivo CSV em: `./saida/relatorio.csv`
- Colunas: produto, quantidade_total, valor_total

## Restrições
- Usar apenas a biblioteca pandas
- Tratar linhas com valores nulos (ignorar)
- Performance: processar até 100k linhas em menos de 5 segundos

→ IA lê a spec → Gera solução precisa de primeira ✅

Agentes de IA Compatíveis

O SDD funciona com qualquer agente de IA avançado:

Claude Code
Gemini
Antigravity
Qwen Code
Cursor
GitHub Copilot

Resumo Visual

┌─────────────────────────────────────────────────────────────────┐
│                    SEM SDD (Looping Infinito)                   │
│                                                                 │
│  Prompt → IA Gera Código → Aprovado? ──NÃO──→ Gera prompt      │
│                ↑                            correção → Volta    │
│                └────────────────────────────────────────────────┘
│                                                                 │
│  Resultado: Gasto de tokens, perda de contexto, estresse        │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    COM SDD (Fluxo Estruturado)                  │
│                                                                 │
│  Especificação (PRD.md) → Prompt → Aprovado?                    │
│                              │                                    │
│                          ┌───┴───┐                               │
│                         NÃO     SIM                              │
│                          │       ↓                               │
│                    Editar Spec  Design (PRD.md) → Aprovado?      │
│                                           │                      │
│                                       ┌───┴───┐                 │
│                                      NÃO     SIM                │
│                                       │       ↓                 │
│                                 Editar Spec  ✅ Done!           │
│                                                                 │
│  Resultado: Menos stress, menos token, sem alucinação           │
└─────────────────────────────────────────────────────────────────┘

Checklist: Criando uma Boa Spec

Objetivo do projeto está claro?
Regras de negócio estão documentadas?
Entradas e saídas estão definidas?
Restrições técnicas estão listadas?
Critérios de aprovação estão explícitos?
O documento está em texto puro (markdown)?

Referências

Discussão: "Pílula de IA"
Contribuidores: Lucas Castro De Carvalho, Leonardo Taveira, Matheus Welber, Victor Eduardo dos Santos, Nadia Nara Da Silva Araujo

Lembre-se: A qualidade do resultado da IA é diretamente proporcional à qualidade da sua especificação.

Especifique melhor para ter um resultado melhor!

FilesExpand file tree

spec-driven-development.md

Latest commit

History