sdd-kit

Português · English

Specification-Driven Development para desenvolvimento assistido por IA, com verificação por ferramentas independentes.

O agente (Claude Code, Codex, Cursor, Copilot...) escolhe como implementar. A spec define o que é correto. O sdd decide se está pronto, rodando fora do LLM, na sua máquina e no CI.

LLMs propõem e implementam. Especificações definem os contratos. Ferramentas independentes verificam. Humanos governam as decisões de maior risco.

O sdd-kit combina orientação ao agente com verificação executável: cada critério precisa de um teste identificado passando, código não muda sem a spec mudar junto, testes fracos são expostos por mutação, e comportamento de LLM é medido com critério estatístico. Checks de código usam ferramentas externas ao agente. Evals com juiz LLM exigem política explícita e são identificadas como evidência probabilística.

Instalação

O comando é sdd. O nome do pacote no pyproject.toml é sdd-kit-ai.

pipx install git+https://github.com/lucianoon/sdd-kit    # da fonte, sempre atualizado
uv tool install git+https://github.com/lucianoon/sdd-kit # equivalente com uv
# pipx install sdd-kit-ai                                # do PyPI, quando publicado

Python 3.10+. Funciona com qualquer linguagem cujo runner de testes gere JUnit XML (pytest, jest, vitest, Go, JUnit...); veja examples/.

Começo em 5 minutos

sdd init                                   # 4 arquivos: config, spec de exemplo, AGENTS.md, CI
sdd specify criar-pedido --acs 2           # esqueleto da spec com IDs livres
# preencha os campos marcados com PREENCHER:, escreva os testes com o ID no nome
sdd validate && sdd check                  # pronto = verde

$ sdd specify criar-pedido --acs 2
criado   specs/features/FEATURE-002/spec.yaml
IDs      REQ: REQ-002  AC: AC-002, AC-003

def test_ac_002_pedido_persistido(): ...   # o ID do critério no nome liga teste e spec

$ sdd check
OK         AC-002   criar-pedido: pedido é persistido
SEM_TESTE  AC-003   criar-pedido: pedido é rejeitado
ERRO  AC-003 (criar-pedido): SEM_TESTE

REPROVADO — relatório em .sdd/report.md

Fluxo guiado para o agente

Depois de criar a spec, prepare o contexto da feature para o agente de sua escolha:

sdd guide criar-pedido --stage clarify     # perguntas abertas e critérios a esclarecer
sdd guide criar-pedido --stage plan        # design e tarefas rastreáveis
sdd analyze                               # diagnósticos e matriz critério → tarefas
sdd guide criar-pedido --stage implement   # contexto e dependências declaradas das tarefas
sdd check
sdd guide criar-pedido --stage converge    # instruções para revisar lacunas após implementar

O guide imprime instruções e contexto; o agente trabalha sobre eles. Não chama LLM, não altera arquivos nem executa testes. analyze preserva as fontes e grava relatórios estáticos em .sdd/analyze.json e .md, inclusive quando há erros. Ambos aceitam --json. Implementação e convergência ficam bloqueadas por erros estáticos; clarificação e plano continuam disponíveis para corrigir a spec. Veja fluxo guiado.

Adote aos poucos

Comece no mínimo e ligue camadas quando fizerem sentido:

sdd init --preset minimo      # spec, check e diff (padrão)
sdd init --preset padrao      # + design, tarefas, constituição, arquitetura, decisões
sdd init --preset completo    # + evals, mutação, critério estrito

sdd enable design tasks       # liga camadas num projeto existente
sdd enable agentes            # perfil de agentes de IA (61 requisitos, incluindo LGPD)

Aplicações de agentes de IA

sdd enable agentes (ou sdd init --profile agentes) traz um catálogo de requisitos de referência para agentes, derivado da SPEC-BASE v0.1: 12 módulos (núcleo, ferramentas e efeitos, recuperação, memória, humano no laço, delegação, produção, LGPD/PL 2338...), 61 requisitos. Cada requisito ativo é cobrado por evidência — um AC ou NFR com teste passando, uma regra ARCH executável ou um EVAL com critério estatístico — ou justificado com not_applicable + motivo; "acho que cobre" não satisfaz. O sdd profile mostra a matriz com o estado real de cada evidência. Detalhes e tabela completa em docs/agentes.md.

Complementos para o fluxo

sdd integrate all                          # entradas locais para Codex, Claude Code e Cursor
sdd adequacy template criar-pedido         # revisão separada da adequação dos testes
sdd lesson list                            # lições propostas e aceitas
sdd change propose ajustar-pedido --feature criar-pedido --reason 'Nova regra'
sdd import-spec referencias/spec.md --format speckit --feature pagamentos

Revisões usam referências com hashes; lições aceitas atuais entram no guide. Propostas preservam baseline e histórico; arquivar exige check novo. Importações de Spec Kit/OpenSpec são rascunhos com fonte preservada e revisão obrigatória. Veja complementos e limites e a demonstração executável de falha e correção.

Revisão escalonada por risco

sdd risk --base origin/main --author "$AUTOR"   # tier da mudança e aprovações humanas exigidas
sdd findings                                    # achados de um revisor LLM externo
sdd fixes --base v0.15.0                        # correções SDD-Fix como casos de avaliação

O piso vem de regras declaradas: globs por tier, specs/ e a severidade dos riscos das specs donas. Um classificador ou revisor LLM externo pode elevar o tier por arquivo, nunca reduzi-lo. Achados de LLM exigem política explícita, são evidência probabilística e não contam como aprovação humana. Veja revisão escalonada.

Comandos

O ciclo

guide --stage converge orienta uma revisão do agente após implementar, com lacunas rastreáveis e tarefas adicionais. Essa revisão não substitui os comandos de verificação.

O AGENTS.md gerado ensina esse ciclo ao agente, com o que fazer e o que não fazer.

Exemplos de IA sem ampliar o núcleo

examples/rag demonstra recuperação autorizada, revogação de cache, fallback, orçamentos, traces, manifesto reproduzível e comparação de avaliações usando check, eval e gates existentes. É offline: não mede qualidade ou latência de um LLM. Veja também a avaliação de complexidade e regra de simplicidade.

Documentação

• Changelog: o que mudou em cada versão
• Especificação: specs, rastreio, convenções por stack, size, premissas, tarefas
• Verificação contínua: diff, SDD-Fix, mutate
• Fluxo guiado: analyze, contexto por etapa e limites da convergência
• Desenho arquitetural: números, alternativas, riscos, modos de falha
• Arquitetura e constituição: arch, princípios executáveis
• Arquitetura interna: módulos, proteção de IO e testes da distribuição
• Auditoria de outubro de 2026: achado corrigido, alcance, validação e limites
• Comportamento de LLM: eval, intervalo de confiança, juiz LLM
• Perfil de agentes: matriz de módulos, requisitos críticos, LGPD
• Revisão escalonada: piso de risco, achados de LLM, correções como eval
• Configuração: todas as chaves e camadas
• Limites, origem e créditos

Este repositório verifica a si mesmo com onze specs: verificação, diff, mutação, evals, arquitetura, governança, adoção, perfil de agentes, fluxo guiado, artefatos e complementos. sdd validate mostra a contagem atual de critérios; sdd check roda os testes, a constituição e as regras de arquitetura.

Os relatórios JSON e Markdown identificam a versão do kit, o formato e o comando. Princípios dependentes de comandos separados ficam PENDENTE no check; uma regra declarada não comprova execução. Veja estados de evidência.

Licença

MIT. O perfil de agentes deriva da SPEC-BASE v0.1 e o ciclo de sete etapas do Guia SDD para Agentes de IA, ambos de Luciano Oliveira Nunes; detalhes em créditos.