📋 O que é um SPEC e por que ele vem antes do código
Um SPEC é um documento que define o sistema em texto antes de qualquer implementação. Não é um plano vago — é um contrato escrito que especifica componentes, responsabilidades, invariantes e o critério de sucesso. Sem SPEC, cada prompt reinventa a arquitetura. Com SPEC, cada prompt navega por um mapa já definido.
📋 O que um SPEC contém
- •Objetivo: o que o sistema faz em uma frase
- •Componentes: as partes do sistema e suas responsabilidades únicas
- •Invariantes: propriedades que nunca podem ser violadas
- •Interface pública: como o sistema é invocado e o que retorna
- •Critérios de aceitação: como verificar que está correto
💡 Por que antes do código?
Bugs arquiteturais descobertos no SPEC custam 30 minutos de reflexão. Os mesmos bugs descobertos no prompt 5 custam horas de reescrita. O SPEC não é burocracia — é o investimento que mais economiza tempo em LLM coding.
🎯 As 3 perguntas que todo SPEC deve responder
Um SPEC incompleto é perigoso — dá falsa sensação de clareza enquanto deixa lacunas que prompts subsequentes vão preencher com suposições. Três perguntas, quando respondidas completamente, garantem que o SPEC é suficiente para guiar o build.
O quê? — Comportamento esperado
O que o sistema faz em termos de entradas e saídas observáveis
Descreve o comportamento do sistema sem mencionar implementação. "Dado X, o sistema produz Y dentro de Z milissegundos." Esta pergunta define o contrato externo.
Por quê? — Justificativa de design
Por que cada decisão arquitetural existe
Documenta a razão por trás de cada escolha. "Usamos escrita atômica porque Claude Code pode ser interrompido a qualquer momento." Sem o porquê, futuros prompts podem inadvertidamente remover uma proteção crítica.
Como verificar? — Critério de aceitação
Como confirmar que o sistema está correto
Define os testes que provam que o sistema satisfaz o contrato. "Executar X deve produzir Y. Interromper durante Z deve deixar o sistema em estado recuperável." Sem critérios concretos, não há forma objetiva de aceitar uma entrega.
🔒 As garantias de segurança
Invariantes de segurança são propriedades que o sistema nunca pode violar — independente do estado, carga ou falha. Declará-las no SPEC antes de qualquer código garante que cada prompt as respeita por design, não por acidente.
🔒 As 6 primitivas invariantes
- •Fail-open: falha do plugin não bloqueia o sistema host
- •Escrita atômica: estado nunca fica parcialmente escrito
- •CAS: transições de estado são verificadas antes de aplicadas
- •Lockfile: seções críticas têm execução exclusiva
- •ERR trap: falhas silenciosas são capturadas
- •Idempotência: re-execução não causa efeitos duplicados
⚠️ O custo de invariantes implícitos
Quando invariantes não estão no SPEC, eles existem apenas na cabeça do desenvolvedor. O modelo não tem acesso a esse contexto implícito — e vai produzir código que viola as garantias não declaradas. O prompt 5 que remove a escrita atômica porque "parece desnecessária" é o exemplo clássico.
📐 SPEC vs. README vs. comentário
Três tipos de documentação, três propósitos distintos. Confundir os três é um dos erros mais comuns — e resulta em invariantes em comentários (ignorados), comportamento esperado no README (desatualizado), e SPEC vazio (inútil).
📋 SPEC
Escrito antes do código
- • Define o que deve ser
- • Declara invariantes
- • Estabelece critérios
- • É um contrato
📖 README
Escrito depois do código
- • Explica como usar
- • Documenta a interface
- • Guia instalação
- • É um guia de usuário
💬 Comentário
Dentro do código
- • Explica como funciona
- • Contexto local
- • Decisões pontuais
- • É uma nota de implementação
✍️ Como escrever um SPEC em 30 minutos
Um SPEC não precisa ser extenso para ser útil. Um template de seis seções, preenchido em 30 minutos, é suficiente para a maioria dos plugins de Claude Code. A chave é ser específico onde importa — invariantes e critérios de aceitação — e conciso no resto.
Template: 6 seções obrigatórias
💡 Proporcionalidade
Um SPEC para um plugin de 5 prompts não precisa de mais de uma página. Um SPEC para um sistema de 20 prompts pode ter 3-5 páginas. A seção mais crítica — invariantes — deve ser a mais detalhada, independente do tamanho total.
🧪 Como usar o SPEC para verificar cada prompt
Um SPEC sem uso ativo é decorativo. Sua função real é ser o checklist de aceitação para cada entrega — transformando critérios abstratos em verificações concretas que confirmam que o trabalho está correto antes de avançar.
✓ Usando o SPEC corretamente
- ✓Verificar invariantes após cada entrega
- ✓Comparar comportamento com critérios de aceitação
- ✓Atualizar o SPEC quando requisitos mudam
- ✓Referenciar o SPEC em cada prompt
✗ Erros comuns
- ✗Escrever o SPEC e nunca mais abrir
- ✗Ajustar critérios para encobrir falhas
- ✗Aceitar entregas sem verificar invariantes
- ✗Manter SPEC desatualizado após mudanças
O protocolo de verificação por prompt
- 1.Confirmar que os arquivos esperados foram criados
- 2.Executar o critério de aceitação do SPEC para esta camada
- 3.Verificar que nenhum invariante foi violado
- 4.Só então marcar a camada como verificada e avançar
✅ Resumo do Módulo 3.1
Próximo Módulo:
3.2 — A Sequência Obrigatória: esqueleto, estado, lógica, segurança