Spec Driven Development (SDD)

Framework para desenvolvimento de software assistido por IA onde a spec é a fonte de verdade — código, testes e documentação são derivados dela, nunca o contrário.

Princípios

1. Spec primeiro, código depois. Toda funcionalidade começa como uma spec antes de qualquer linha de código ser escrita.
2. Spec viva. A spec evolui com o projeto. Quando o código e a spec divergem, a spec vence — até que seja explicitamente alterada.
3. Uma fonte de verdade. Requisitos, critérios de aceite e restrições vivem na spec. Issues, tickets e comments são efêmeros.
4. IA gera, humano decide. A IA escreve código, testes e docs a partir da spec. O humano revisa, aprova e merge.
5. Rastreabilidade. Cada commit referencia a spec que o originou. Cada spec referencia o requisito de negócio.
6. Valoração de teste. Toda spec define critérios de aceite testáveis. Sem teste, não está completo.
7. Incremental e iterável. Specs podem ser decompostas (project → feature → task) para permitir execução paralela e incremental.

Estrutura do Framework

spec-driven-development/
├── README.md              ← este arquivo — visão geral
├── docs/
│   ├── manifesto.md       ← princípios e filosofia
│   └── workflow.md         ← guia completo fases
├── specs/
│   ├── project/           ← spec global do projeto (1 por repo)
│   ├── features/          ← specs de funcionalidades (1 feature = 1 arquivo)
│   └── conventions/       ← convenções técnicas do projeto (não funcionais)
├── templates/
│   ├── project-spec.md    ← template para spec de projeto
│   ├── feature-spec.md    ← template para spec de feature
│   └── task-spec.md       ← template para spec de task (sub-feature)
└── agents/
    └── instructions.md    ← instrução base para qualquer agente de IA

Workflow (6 fases)

Discover → Spec → Plan → Generate → Validate → Review
    ↑                                                    │
    └────────────── Feedback loop ───────────────────────┘

Fase	O que acontece	Quem faz
Discover	Explorar domínio, restrições, viabilidade	Humano
Spec	Escrever spec da feature usando template	Humano
Plan	Quebrar spec em tasks, planejar arquitetura	IA propõe, humano aprova
Generate	Gerar código, testes e docs a partir da spec+plan	IA
Validate	Rodar testes, lint, build, type-check	IA + automação
Review	Revisar output contra spec, refinar	Humano

→ Volta para Discover quando há nova funcionalidade ou a spec evolui.

Uso Rápido

1. Inicializar no projeto

# Copiar framework para o repositório
cp -r ~/spec-driven-development/specs ./specs
cp -r ~/spec-driven-development/templates ./specs/templates
cp -r ~/spec-driven-development/agents ./agents

2. Escrever spec do projeto

cp specs/templates/project-spec.md specs/project/project-spec.md
# Editar com a visão geral, stack, convenções

3. Escrever spec de feature

cp specs/templates/feature-spec.md specs/features/minha-feature.md
# Preencher: contexto, requisitos, critérios de aceite, restrições

4. Alimentar o agente IA

# Claude Code
claude --instructions agents/instructions.md "Implemente specs/features/minha-feature.md"

# Cursor
# Adicionar agents/instructions.md como .cursorrules

# Codex
codex --instructions agents/instructions.md "Implemente specs/features/minha-feature.md"

# Hermes
# Usar skill spec-driven-development (em construção)

Compatibilidade de Agentes IA

O framework é agnóstico. A instrução base em agents/instructions.md usa uma linguagem neutra que funciona com:

• Claude Code (Anthropic) — passar via --instructions ou .claude/instructions.md
• Codex (OpenAI) — passar via --instructions ou AGENTS.md
• OpenCode — passar via instrução de sistema
• Cursor — usar como .cursorrules ou @ referência no chat
• GitHub Copilot — usar como instrução de chat
• Hermes Agent — usar como skill ou system prompt

A única adaptação necessária é o arquivo de entrada (.claude/instructions.md, AGENTS.md, .cursorrules, etc.) que aponta para o mesmo agents/instructions.md.

Por que SDD funciona melhor com IA?

Sem SDD (prompt ad-hoc)	Com SDD
"Faça um sistema de login"	Spec com requisitos, critérios, restrições
Resultado: imprevisto, retrabalho	Resultado: previsível, testável
Conhecimento perdido entre sessões	Spec persistente e versionada
Diffícil revisar (o que mudou?)	Diferença entre spec e implementação
Dívida técnica invisível	Convenções explícitas em specs/conventions/