Oitenta músicos, uma partitura
Beethoven em uníssono. Ninguém improvisa.
A orquestra executa a partitura
Regente coordena. Partitura comanda. Músicos executam.
A partitura já disse tudo
Nota
Compasso
Dinâmica
Andamento
Trinta agentes, uma spec
A mesma lógica, agora com inteligência artificial.
A spec dispara, todos executam
Uma fonte da verdade. Trinta agentes em sintonia.
A spec precisa ser
Escrita
Precisa
Modular
Executável
A abordagem se chama
Spec-Driven Development
SDD
O que é Spec-Driven Development?
A inversão central: o código vira consequência da spec.
Definição
A spec deixa de ser documentação. Vira o centro do projeto, e código, testes e arquitetura passam a derivar dela.
Antes, Code-Driven
- Código é o artefato central
- Spec descreve o que já existe
- Documentação envelhece sozinha
- IA gera código sem contrato claro
Agora, Spec-Driven
- A spec é o artefato central
- Código deriva da spec
- Spec é a fonte da verdade
- IA executa com contrato claro
Ponto de partida
Começa pelo comportamento esperado, não pelo código.
Interface operacional
Lida por humanos e por agentes de IA, lado a lado.
Restrição ativa
Se a spec erra, o erro aparece em código e testes.
A spec no centro do projeto
Arquitetura, testes, código, prompts e validação derivam dela.
Cinco artefatos, uma origem comum
O código deixa de ser o artefato central e vira consequência.
Tudo deriva da spec
Arquitetura
Testes
Validação
Prompts
Código
O que entra em uma spec moderna?
Oito blocos que substituem dezenas de documentos soltos.
01
Bloco
Requisitos funcionais
O que o sistema deve fazer, em comportamento observável.
02
Bloco
Critérios de aceitação
Como saber, sem dúvida, que um requisito foi cumprido.
03
Bloco
Contratos de API
Entradas, saídas, formatos e códigos de erro.
04
Bloco
Regras de negócio
Restrições de domínio que o código não pode violar.
05
Bloco
Estrutura de dados
Como as informações são modeladas e persistidas.
06
Bloco
Fluxos de UI
Sequência de telas, estados e transições.
07
Bloco
Estratégias de teste
O que testar, em que nível, com qual cobertura.
08
Bloco
Contexto para agentes
Instruções específicas para a IA entender o projeto.
SDD vs Agile: coordenação na era da IA
De conversa implícita para contexto explícito, dimensão por dimensão.
AGILE
conversa, ritual, humano
SDD
spec, contexto, humano + IA
Conversa entre humanos
Fonte da verdade
Spec versionada
Mínima, oral
Documentação
Viva, executável
Reuniões, rituais
Coordenação
Arquivos semânticos
Resolvida no diálogo
Ambiguidade
Reduzida na escrita
Humano
Implementador
Humano e IA juntos
Contínua no código
Refatoração
Contínua na spec
Dois meses de imersão
Onboarding
Leitura da spec
Spec-Driven Development é o próximo degrau
Cada degrau afastou o programador dos detalhes mecânicos.
A escada das abstrações
Sete degraus, e SDD é o próximo passo natural.
Sete degraus, uma trajetória
01
Máquina
02
Assembly
03
Estruturadas
04
OO
05
Frameworks
06
Low-code
07
SDD
Não é um doc. São quinze.
A spec virou pasta. Cada arquivo, um órgão especializado.
A anatomia da pasta specs/
Quinze arquivos especializados. O agente carrega só o que importa.
Três arquivos nasceram com a era dos agentes
AGENTS.md
PROMPTS.md
WORKFLOW.md
Abre o arquivo. Vê o esqueleto.
Cada spec tem a mesma anatomia: títulos, blocos previsíveis, exemplos curtos.
Raio-X de seis arquivos
A estrutura interna se repete. Previsibilidade é o que faz o agente acertar.
O esqueleto se repete porque o agente precisa achar
Título e propósito
Blocos nomeados
Exemplos curtos
Links cruzados
Não lê tudo. Lê o que precisa.
Recuperação contextual estilo RAG: o agente carrega apenas as specs relevantes à tarefa.
Pipeline de recuperação contextual
Seis estágios. A tarefa percorre, a spec evolui, o ciclo recomeça.
Três implicações para quem escreve spec
Título preciso
Roteador semântico decide pelo metadado
Arquivo focado
Pequeno e específico vence o monolítico
Cross-reference
Liga as specs e o agente expande sob demanda
Agentes de implementação
Do produto à entrega. Começar pelo programador inverte a cadeia.
Sete agentes, sete artefatos, uma cadeia
A saída de um vira a entrada do próximo.
A regra da cadeia
Produto antes de código
Sem usuário e critério, decisão técnica é chute
Artefato vira insumo
PRD alimenta domínio, domínio alimenta arquitetura
Inverter quebra tudo
Começar pelo programador produz código sem contrato
Specs vão além do software.
A mesma infraestrutura operacional atravessa seis domínios distintos.
Um prisma, seis feixes
A SPEC entra como insumo. Sai como artefato em cada domínio.
A spec deixou de ser coisa de programador
Mesma estrutura
Título, blocos nomeados, exemplos, links cruzados
Domínio agnóstico
Da pesquisa científica à operação da empresa
Agente entende todos
A IA opera onde houver spec bem escrita