Spec-Driven Development Framework (SDD)

🌐 Read this documentation in English.

Versão: 5.2.1 | Status: Production Ready | Última atualização: 2026-07-09

Orquestrador: Samantha Agent — gerencia o ciclo SDD completo

Visão Geral

O Spec-Driven Development Framework (SDD) implementa o ciclo completo de desenvolvimento orientado por especificações, orquestrado pelo agente Samantha: Constitution → Specify → Design → Plan → Execute → Validate → Reflect.

Por que usar?

• Disciplina forçada — GATEs impedem pular etapas críticas
• Aprendizado contínuo — knowledge base evolui com cada sessão
• Controle de execução — monitoramento de turns e custos
• Eficiência — Modo Lite reduz 60% tokens em tarefas simples
• Reprodutível — fluxo idêntico para qualquer tarefa
• Samantha Agent — Orquestradora SDD, gerencia transições entre fases
• Architect Agent — Subagente Sonnet para Design/Plan/Review (model escalation)
• 15 Skills — 14 skills + 1 agente orquestrador
• 6 ADRs — Architecture Decision Records documentados
• Ponytail — Filosofia YAGNI integrada
• 87 Testes — Cobertura automatizada (24 integração + 15 events + 11 dashboard + 26 unitários + 8 LITE)

Conceitos Fundamentais

Dois Modos de Operação

| Modo | Quando | Fluxo | Tokens | |---|---|---|---| | FULL | Tarefas M/G/XG | Completo com GATEs | ~15.000 | | LITE | Tarefas P (simples) | Compacto, sem GATEs | ~1.500 |

Detecção automática: Effort low = modo LITE

Modo LITE

🎯 CLASSIFY:P → EXECUTE → 📝 REFLECT:1L

• Spec inline (não cria arquivo)
• Plan automático (sem GATE)
• Reflect: 1 linha

Modo FULL — SDD

CONSTITUTION → SPECIFY → DESIGN → PLAN → EXECUTE → VALIDATE → REFLECT

GATEs (Modo FULL — SDD)

| GATE | Fase | Trigger | O que impede | |------|------|---------|--------------| | SPEC GATE | Specify | "aprovado" | Código sem spec aprovada | | DESIGN GATE | Design | "design ok" | Plan sem design aprovado | | PLAN GATE | Plan | "confirmar" | Código sem plano confirmado | | VALIDATE | Validate | automático | Merge sem verificar spec | | REFLECT GATE | Reflect | automático | Tarefa sem reflexão |

Effort Level

| Effort | Quando | Turns máx | Modo | |--------|--------|-----------|------| | low | Documentação, tarefas simples | 10 | LITE | | medium | Configuração, rotinas | 20 | FULL | | high | Implementação, correções | 40 | FULL | | xhigh | Debug, investigação | 60 | FULL |

Instalação

Pré-requisitos

• Claude Code instalado
• Node.js >= 18.0.0

npm (Recomendado)

npm install -g spec-driven-agent
npx sda init

CLI Local

npm install
node cli/bin/cli.js init /caminho/para/projeto

Comandos

CLI

| Comando | Função | |---------|--------| | sda init | Inicializar framework | | sda update | Atualizar framework | | sda status | Ver status da instalação | | sda dashboard | Dashboard de métricas (live, summary, json, build) | | sda metrics | Alias para sda dashboard --summary | | sda --version | Ver versão |

Framework (Claude Code) — Ciclo SDD

| Comando | Fase SDD | Função | |---------|----------|--------| | /context | Constitution | Mapear projeto + alimentar guardrails | | /spec | Specify | Criar especificação | | /design | Design | Decisões de arquitetura | | /plan | Plan | Gerar plano atômico | | /implement | Execute | Executar implementação | | /fix | Execute | Corrigir bug | | /debug | Execute | Investigar problema | | /refactor | Execute | Reestruturar código | | /review | Validate | Code review + validação contra spec | | /status | — | Ver estado atual | | /reflect | Reflect | Auto-avaliação | | /learn | Reflect | Consolidar conhecimento | | /socrates | Constitution | Coletar contexto ausente |

Reference Guides (10)

| Guia | Quando usar | |------|-------------| | bash-best-practices.md | Scripts bash, tratamento de erros | | ci-cd-patterns.md | GitHub Actions, Turborepo, caching | | documentation-templates.md | README, ADRs, CHANGELOG | | git-workflows.md | Conventional Commits, branch strategy | | project-structure.md | Monorepo layouts, convenções | | testing-patterns.md | TDD, mocking, cobertura | | security-best-practices.md | OWASP, auth, validação | | performance-optimization.md | Caching, bundle, Core Web Vitals |

Validação

Protocolo de Validação (v5.1+)

O framework inclui protocolo completo para validar:

1. Modo LITE — 10 tarefas P com coleta de métricas
2. Knowledge Base — 5 sessões com consolidação

Consulte VALIDATION-PROTOCOL.md para detalhes.

Testes Automatizados

node cli/test.js                          # 24 testes de integração
node cli/lib/__tests__/dashboard.test.js  # 11 testes do dashboard
node cli/lib/__tests__/events.test.js     # 18 testes do módulo events
node cli/test-unit.js                     # 26 testes unitários (sanitizePath)
node cli/test-lite.js                     # 8 testes do Modo LITE

Total: 87 testes — todos passando ✅

Segurança

| Medida | Status | |---|---| | Shell injection fix | ✅ execFileSync | | Path sanitization | ✅ Blocklist + path.resolve + 26 tests | | JSON injection (hooks) | ✅ json_build() com jq --arg — 12 chamadas, 7 hooks | | Cross-platform | ✅ mktemp_safe + find_jq + CRLF-safe | | SECURITY.md | ✅ Política definida | | CODE_OF_CONDUCT.md | ✅ Contributor Covenant |

Economia de Tokens

| Cenário | Antes | Depois | Economia | |---|---|---|---| | Tarefa P | 3.000 | 1.200 | -60% | | Tarefa M | 15.000 | 10.500 | -30% | | Sessão (5 tarefas) | 75.000 | 48.000 | -36% |

Roadmap

v5.1 (Legado) ✅

• [x] Modo Lite (-60% tokens)
• [x] Few-shot examples
• [x] Knowledge loading condicional
• [x] Observabilidade leve
• [x] 8 reference guides
• [x] Ponytail integration
• [x] npm publish automático
• [x] 53 testes automatizados (19 int + 8 LITE + 26 unit)
• [x] SECURITY.md + CODE_OF_CONDUCT.md
• [x] Validation protocol
• [x] Session templates

v5.2 (Atual) ✅

• [x] Dashboard de métricas (JSONL, snapshots, TUI live)
• [x] Event store append-only (events-YYYY-MM-DD.jsonl)
• [x] Token tracking real de subagentes via PostToolUse
• [x] 6 hooks reescritos em Node.js (post-tool, post-task, pre-tool, init-session, stop, check-gate)
• [x] JSON seguro nos hooks (json_build() com jq --arg)
• [x] Economy LITE vs FULL por modo (tagEventsWithMode)
• [x] Compaction automático (90d + snapshot mensal)
• [x] Architect Agent (model escalation Sonnet)
• [x] 6 ADRs documentados
• [x] 87 testes automatizados (24 int + 15 events + 11 dash + 26 unit + 8 LITE)

v5.3 (Planejado)

• [ ] Dashboard visual de métricas (web)
• [ ] Suporte a múltiplos modelos LLM
• [ ] Plugin system para skills customizadas

Créditos

Consulte CREDITS.md para atribuições detalhadas de skills, inspirações conceituais (YAGNI, KISS) e ferramentas de terceiros.

Contribuindo

Consulte CONTRIBUTING.md para guia completo.

Licença

MIT License. Consulte LICENSE.

Copyright (c) 2026 Meuphilim

Contato

• Autor: Meuphilim
• GitHub: @meuphilim
• Issues: GitHub Issues