Loop de Desenvolvimento Orientado por Especificação (SDDL)

Código Aberto: https://github.com/xt-mahh/sddl (2026-08-06, Licença MIT) Metodologia completa + scripts de verificação + projetos de exemplo no repositório GitHub.

Visão Geral

O SDDL eleva a programação com IA de "orientada a diálogo" para "orientada a especificação". A promessa central: defina claramente o que fazer antes de escrever código — com a Spec estruturada como única fonte da verdade, fechando um Loop Duplo para garantir qualidade e auditabilidade.

Loop de Formação (responde "o que fazer")       Loop de Derivação (responde "como fazer certo")
Requisitos ──▶ Entrevista ──▶ Rascunho Spec ──▶ Congelar Spec ──▶ tests/code/docs ──▶ Convergência
                    └─▶ Verificação SQC ──┘                          └─▶ Verificação C1-C4 ──┘
                    └─▶ Confirmação de Decisões ──┘

Por que usar o SDDL: As dores da programação conversacional — desvio de contexto (50 rodadas de conversa e o acordo da 3ª é esquecido), artefatos múltiplos fora de sincronia (código muda mas testes/documentação não acompanham), aceitação subjetiva ("parece certo" em vez de "está de acordo com a especificação"). O SDDL resolve os três com uma Spec estável e totalmente carregável + verificação de consistência em camadas.

Quando Usar

Acionamento:

O usuário quer começar um novo projeto, escrever funcionalidades principais, projetar arquitetura de sistema
O usuário diz "planeje primeiro", "projete primeiro", "escreva a especificação", "como fazer esta funcionalidade"
O usuário precisa de múltiplos artefatos (código + testes + documentação) produzidos de forma síncrona
Projeto com ≥ 5 interfaces, ou ≥ 5 critérios de aceitação "must", expectativa de vida > 2 semanas

Não aplicável (escreva código diretamente, não use este skill):

Scripts descartáveis / protótipos / POCs / código de pesquisa exploratória
Ferramentas pequenas de arquivo único (< 5 interfaces, sem necessidade de múltiplos artefatos)
O usuário explicitamente diz "escreva diretamente", "faça rápido"

Comandos Faseados (forma principal de interação deste skill):

Comando	Fase	O que Faz	Saída
`/sddl:init`	Inicialização	Criar estrutura de diretórios, ler código/requisitos existentes	Esqueleto `sddl/` + `state.yaml`
`/sddl:interview`	Formação	Entrevista de requisitos em camadas (L0-L2 obrigatórias)	Declaração de requisitos
`/sddl:spec`	Formação	Gerar rascunho da spec L1-L5 + marcação de pontos de decisão	`specs/<dominio>/spec.yaml`
`/sddl:confirm`	Formação	Resumo dos pontos de decisão e confirmação clarify	`decisions/<dominio>-confirmation.yaml`
`/sddl:freeze`	Formação	Verificação SQC + congelamento	`spec_status: frozen`
`/sddl:derive`	Derivação	Derivar tests/code/docs a partir da spec	`src/ tests/ docs/`
`/sddl:verify`	Derivação	Verificação de consistência C1-C4 + julgamento de convergência	`checks/*.json` + convergência/roteamento
`/sddl:archive`	Arquivamento	Arquivar mudanças, mesclar spec	Atualização `specs/` + CHANGELOG

Princípios Centrais

Spec é o oráculo, mas pode ser questionada: Defeitos encontrados na derivação → descongelar → voltar ao Loop de Formação para revisão → recongelar (passando pelo gateway de qualidade completo, sem atalhos)
Determinismo primeiro: Se pode ser resolvido com análise estática / schema / execução de testes, nunca use o LLM para adivinhar
Convergência é um sistema de engenharia: Gateway de condições rígidas + taxa de consenso de condições flexíveis + restrições de orçamento + fallback humano
Pontos de decisão não são silenciosos: Áreas ambíguas: AI dá valor padrão + marca ponto de decisão; usuário confirma antes de congelar
Progresso é o diretório: Fase concluída = arquivo existe (Convenção sobre Configuração), recuperação de interrupção gratuita

Diretório como Estado (Convenção sobre Configuração)

Não olhe o arquivo de estado, olhe o diretório para saber o progresso. Este é o mecanismo de visibilidade de progresso deste skill (com git commit como checkpoint).

<projeto>/
├── sddl/
│   ├── specs/                    # Existe = entrevista concluída, spec gerada
│   │   └── <dominio>/spec.yaml    # status: frozen = congelamento concluído
│   ├── changes/                  # Propostas de mudança (desenvolvimento incremental, paralelo possível)
│   ├── decisions/                # Registro de confirmação de pontos de decisão
│   │   └── <dominio>-confirmation.yaml
│   ├── checks/                   # Relatórios de verificação arquivados (JSON legível por máquina)
│   │   ├── sqc-<dominio>-v1.json
│   │   └── c1-c4-<dominio>-v1.json
│   └── state.yaml                # Único metadado: ponteiro de fase + orçamento + última verificação
├── src/                          # Aparece após o Loop de Derivação
├── tests/                        # Aparece após o Loop de Derivação
├── docs/                         # Aparece após o Loop de Derivação (com partições current/planned)
└── (git commit a cada conclusão de fase)

state.yaml minimizado (só guarda ponteiro, não detalhes de progresso):

spec_status: frozen          # interviewing | drafting | reviewing | frozen | evolved
current_phase: derivation    # formation | derivation | complete
budget: { formation: 40%, implementation: 12%, revision: 100% }
last_check: { type: sqc, spec: auth-v0.1.0, result: pass, at: 2026-08-06T16:00 }

Regra de Recuperação: Ao recarregar o skill, escaneie o diretório — specs/ vazio = começar da entrevista; specs/ existe mas sem decisions/ = começar da confirmação; decisions/ existe mas spec não frozen = começar do congelamento; src/ existe mas sem checks/ = começar da derivação; checks/ existe = começar da verificação.

Conclusão de fase = git commit (auxiliado por IA): Após cada comando bem-sucedido, commit (feat(sddl): entrevista concluída), garantindo rastreabilidade.

Orquestração do Loop Duplo

Loop de Formação (Fazer a Coisa Certa) — 5 comandos

/sddl:interview → /sddl:spec → /sddl:confirm → /sddl:freeze
     │              │              │              │
     └─ Revisão ────┴──────┴──────┘
       (SQC falhou / usuário mudou ponto de decisão → voltar um passo, max 5 rodadas)

Comando	Ação Chave	Ponto de Verificação
interview	Perguntas em camadas L0-L2 (≤10 obrigatórias), produz declaração de requisitos	Declaração de requisitos completa
spec	Gerar spec L1-L5 + marcação de pontos de decisão (áreas ambíguas registram DP)	Esqueleto SQC-def aprovado
confirm	Resumo dos pontos de decisão → clarify item por item (inclui entrada personalizada)	Nenhum ponto de decisão pendente
freeze	Verificação SQC completa + assinatura do registro de confirmação	SQC sem blocker + frozen

Loop de Derivação (Fazer a Coisa Certa) — 3 comandos

/sddl:derive → /sddl:verify → (convergência) → Concluído
     │              │
     └─ Roteamento ─┘
       (violação → rederivar code/tests/docs ou descongelar e voltar ao Loop de Formação)

Comando	Ação Chave	Ponto de Verificação
derive	Derivar tests/code/docs a partir da spec	Artefatos executáveis
verify	Verificação em camadas C1-C4 + julgamento de convergência	Gateway rígido + consenso flexível + cobertura must
archive	Arquivar mudanças, mesclar spec	CHANGELOG + atualização da spec

Scripts de Verificação (scripts/) — Evidência Determinística, Não Julgamento Semântico

Os scripts só cuidam de evidência determinística (verificação de tipos / execução de testes / tabela de símbolos / YAML), a revisão semântica é feita pela capacidade LLM do agente:

# Verificação determinística SQC (gateway do Loop de Formação) — scripts fornecem fatos
python3 scripts/check_sqc.py sddl/specs/<dominio>/spec.yaml --verbose

# Verificação determinística C1-C4 (gateway do Loop de Derivação) — scripts fornecem fatos
python3 scripts/check_c1_c4.py . --verbose

# Recuperação de estado (após interrupção) — escaneia diretório e mostra progresso + próximo comando
python3 scripts/sddl_status.py .

Código de saída: 0 = pass/convergiu, 1 = falhou (pode ser usado em CI)
--json saída de evidência legível por máquina (para referência na revisão do LLM)

Princípio de Divisão de Trabalho (importante):

Camada	Responsável
Evidência determinística (condições rígidas): schema válido / interface existe / testes passam / tabela de símbolos	Scripts
Revisão semântica (condições flexíveis): cobertura de comportamento / THEN é assertável / testes realmente cobrem / documentação real	LLM do agente (ver `references/llm-review.md`)

Não use scripts heurísticos para julgamento semântico — correspondência de strings causará explosão de falsos negativos (teste T1 mostrou C1-sem 0.48). Scripts são coletores de evidência, o agente é o juiz.

Quando Ler Cada Referência

Carregar sob demanda, não ler tudo de uma vez (divulgação progressiva):

Cenário	Ler
Executar entrevista	`references/formation-loop.md` (fase 1)
Gerar spec	`references/spec-schema.md` + `templates/spec-template.yaml`
Verificação SQC	`references/sqc-checklist.md` (def com script, sem com LLM)
Confirmação de pontos de decisão	`templates/decision-summary.md`
Derivar artefatos	`references/derivation-loop.md` (fases 1-2)
Verificação C1-C4	`references/checker-matrix.md` (def com script, sem com LLM)
Revisão semântica operacional	`references/llm-review.md` (central: como o LLM faz revisão)
Roteamento/reescrita/orçamento	`references/derivation-loop.md` (fases 3-5)
Proposta de mudança	`references/formation-loop.md` (gerenciamento de mudanças)

Orçamento e Degradação

Três orçamentos: formation (2M tokens / 5 rodadas) / implementation (15M / 4 sessões) / revision (5M, L2 custa 10%, L3 custa 25%, primeira L3 grátis)
Orçamento registrado em state.yaml, atualizado a cada comando
Orçamento esgotado → modo manual, sem degradação automática (qualidade da spec é a fundação)
Caminho de degradação: D1 degradação semântica → D2 mover should/could para lista de riscos → D3 reduzir variantes → D4 dividir spec → D5 entrega de melhor esforço

Normas de Experiência (Importante)

Comandos faseados: Nunca execute o Loop Duplo inteiro em uma única resposta — cada comando é uma unidade de interação independente, com pontos de verificação entre eles
Pontos de decisão usam clarify, entrada personalizada visível: Cada ponto de decisão um clarify, com descrição de impacto; opções de negócio ≤3, 4ª posição fixa "Entrada personalizada (Outro)" (clarify não tem auto-Outro, limite de choices é 4, deve ser explicitamente reservado); texto da pergunta: "Para outros valores, selecione Entrada personalizada"; valor personalizado do usuário segue protocolo de captura (gravar value+reason → sincronizar spec → registro de confirmação marcado como modified); pontos de decisão abertos usam clarify sem choices
Progresso visível: No início/fim de cada comando, reportar fase atual + próximo passo
Escrita de estado: Ao final de cada comando, escrever state.yaml + git commit
Relatórios de verificação: Cada verificação (SQC/C1-C4) escrever checks/*.json, relatório com resumo legível + detalhes legíveis por máquina

Armadilhas Comuns

Pular o Loop de Formação e ir direto para a Derivação — Spec não congelada e escrever código = voltar à programação conversacional. /sddl:freeze é um limite rígido; sem congelamento, não há derivação.
Decisões silenciosas sobre pontos de decisão — Áreas ambíguas sem marcar DP e escrever valor padrão = distorção da intenção do usuário. Qualquer "escolha pelo usuário" deve registrar DP.
Círculo vicioso de verificação — Confiar em etiquetas da IA. C1-def deve fazer retroanálise estrutural (parsear AST do teste), não confiar em etiquetas.
Pontuação absoluta de verificação semântica — LLM dando nota 0-100 não é confiável. Usar Checklist binário + taxa de consenso de votação (contagem objetiva).
Reescrita contornando gateway de qualidade — spec_error alterar spec diretamente = rebaixar o padrão próprio. Deve descongelar → voltar ao Loop de Formação → recongelar.
Inchaço do arquivo de estado — Escrever todo o progresso em state.yaml = voltar à "mentira documental". state.yaml só guarda ponteiros; detalhes estão nos próprios arquivos.
Orçamento não registrado — Não atualizar orçamento em state.yaml = custos fora de controle. Atualizar ao final de cada comando.
Verificação semântica com correspondência de strings grosseira — Teste T1: correspondência de palavras-chave levou C1-sem a 0.48 (explosão de falsos negativos). Priorizar votação LLM com Checklist; heurística apenas como fallback, e deve ser semântica (extrair asserções do AST + palavras-chave estruturadas), resultado inicial não confiável, requer revisão humana.
Vazamento de estado compartilhado entre testes — Teste T1: store em memória compartilhada entre testes causou falha de asserção. Na derivação, adicionar fixture de isolamento (autouse reset); asserções de teste pela interface pública, não acessar _store interno.
Funções puramente de consulta com efeito colateral — Teste T1: detectDiscrepancy alterou status internamente, violando B006 da spec (deve manter draft). Interfaces de consulta pura (relatório/consulta) não devem modificar estado; C2-sem deve verificar.

Checklist de Verificação

Receitas Únicas

Novo projeto do zero

/sddl:init → /sddl:interview → /sddl:spec → /sddl:confirm → /sddl:freeze
           → /sddl:derive → /sddl:verify → /sddl:archive

Preencher spec para código existente (projeto de reforma)

/sddl:init (ler código existente) → /sddl:spec (extrair status atual reversamente + marcar pontos de decisão)
  → /sddl:confirm → /sddl:freeze → /sddl:verify (verificar consistência spec↔código)

Desenvolvimento incremental de funcionalidade (spec já congelada)

/sddl:init → escrever proposta changes/<nome>/ → /sddl:confirm (pontos de decisão afetados)
  → /sddl:freeze → /sddl:derive → /sddl:verify → /sddl:archive

Skills Relacionados

writing-plans: Escrever planos de implementação (pode usar changes/tasks.md do SDDL)
test-driven-development: TDD é o meio de verificação do SDDL (execução de testes C3)
hermes-agent-skill-authoring: Normas de criação do próprio skill

sddl

O que é sddl?

Perguntar na sua IA favorita

Documentação