SDD em 1 página: cheatsheet do Spec-Driven Development

Versão de bolso do Spec-Driven Development. Pra cobertura completa, leia SDD: o método completo ou o ebook 215p grátis.

A regra de ouro

“Investir tempo pensando antes de fazer economiza tempo total.”

Specs são memória externa do agente. Sem elas, você refaz o briefing toda sessão e cada execução sai diferente.

Os 4 pilares (em sequência)

#	Fase	Artefato	Pergunta central	Output
1	Requirements (O QUÊ)	requirements.md	Que comportamento o sistema deve ter?	EARS + MoSCoW + glossário + escopo negativo
2	Design (COMO)	design.md	Como vamos construir?	Arquitetura + Prisma + endpoints + decisões
3	Tasks (QUANTO)	tasks.md	Quais unidades de 2-4h e em que ordem?	Decomposição com dependências
4	Implementation	código	Implementar exatamente a spec	Código + testes + commits

Entre cada fase: gate humano obrigatório. Agente não avança sozinho.

Estrutura .claude/ mínima

projeto/
├── .claude/
│   ├── commands/          # /spec-new, /spec-requirements, etc.
│   ├── steering/          # contexto persistente (tech-stack, conventions)
│   ├── specs/             # 1 pasta por feature
│   │   └── 001-auth/
│   │       ├── requirements.md
│   │       ├── design.md
│   │       ├── tasks.md
│   │       └── .status    # requirements:approved
│   └── agents/            # architect, implementer, reviewer
└── CLAUDE.md              # entry point, < 300 linhas

Formato EARS (5 padrões + 1)

Padrão	Sintaxe	Exemplo
Ubiquitous	Sistema DEVE [comportamento]	Sistema DEVE validar permissões em todas as operações
Event-driven	QUANDO [evento], sistema DEVE [ação]	QUANDO tarefa concluída, sistema DEVE registrar timestamp
Unwanted	SE [condição], sistema DEVE [proteção]	SE >50 subtasks, sistema DEVE exibir erro
State-driven	ENQUANTO [estado], sistema [NÃO] DEVE [comportamento]	ENQUANTO arquivada, sistema NÃO DEVE permitir edição
Optional	ONDE [feature ativa], sistema DEVE [comportamento]	ONDE notificações habilitadas, sistema DEVE notificar
Complex	combinado	QUANDO X E Y, sistema DEVE Z ANTES DE W

Slash commands (Claude Code)

Comando	Função
/spec-new <slug>	Cria estrutura .claude/specs/XXX-slug/ vazia
/spec-requirements	Agente entrevista você, gera EARS
/spec-design	Agente propõe arquitetura baseada nos requirements aprovados
/spec-tasks	Agente decompõe em tasks de 2-4h
/spec-implement <task-id>	Agente implementa task, escreve teste, marca [x]

Regra: cada comando NÃO avança status sem aprovação humana explícita.

Subagentes (3 papéis essenciais)

Agente	Responsabilidade	Regra principal
Architect	Decisões técnicas, trade-offs, riscos	NUNCA escreve código de implementação
Implementer	Código + testes seguindo spec	PARA se encontrar ambiguidade — não assume
Reviewer	Qualidade, segurança, convenções	Compara código vs spec, não vs preferência pessoal

Anatomia de requirements.md (6 seções obrigatórias)

1. Visão geral — o quê e por quê
2. User stories com critérios de aceitação observáveis
3. Requisitos funcionais (RF) com prioridade MoSCoW
4. Requisitos não-funcionais (RNF) — performance, segurança, escalabilidade
5. Glossário — termos do domínio
6. Fora do escopo — delimitação NEGATIVA explícita ← maior fonte de bug evitado

12 critérios de spec boa

1. Comportamento observável (não implementação)
2. Linguagem de negócio (sem jargão técnico)
3. Critério de aceitação testável
4. Formato EARS
5. Prioridade MoSCoW explícita
6. Escopo NEGATIVO explícito
7. Glossário de termos
8. Métricas numéricas (não adjetivos)
9. Exemplos concretos pra cada validação
10. FAQ inline antecipando perguntas óbvias
11. Rastreabilidade requirements → design → tasks → code
12. Spec versionada (git-friendly)

Aprofundamento dos 12 critérios

Quando usar / quando NÃO usar

✅ Use SDD	❌ Pula SDD
Projeto > poucos dias	Script de 1 hora
Múltiplas features	Prototype exploratório
Vai pra produção	One-off automation
Multi-dev OU multi-sessão	Single dev + sessão única
RNF críticos (perf, segurança)	Spike de 1-3 dias

Anti-patterns que matam SDD

• ❌ Pular gates “só dessa vez”
• ❌ Spec genérica copy-paste de outro projeto
• ❌ CLAUDE.md > 500 linhas (vira ruído)
• ❌ Modificar spec sem refletir no código (spec vira ficção)
• ❌ Implementer “esperto” que improvisa quando spec é ambígua (PARA e ESPECIFICA)

Tempo de investimento por feature

Tarefa	Tempo
/spec-new + estrutura	5 min
/spec-requirements interativo	30-60 min
Gate humano + ajuste	15 min
/spec-design interativo	20-40 min
Gate humano	10 min
/spec-tasks	10-20 min
/spec-implement × N tasks	30-90 min/task

Total feature média: 2-3h pré-implementação + 3-8h implementação. Compara com 8-16h iterando sem spec.

Próximos passos

→ SDD: o método completo (cornerstone) → Anatomia de uma spec (12 critérios) → Ebook SDD: O Guia Definitivo (215p grátis) → Formação Consultor AI — Academy