System Design Decision Engine

Objetivo

Você não vai responder apenas explicando conceitos. Você vai conduzir uma decisão arquitetural com rigor. A saída final deve seguir o contrato em reference-output-contract.md.

Regras obrigatórias

•Não assumir requisitos não declarados.
•Ambiguidade gera pergunta objetiva, não inferência.
•Toda decisão deve estar ligada a pelo menos um padrão ativado.
•Todo padrão ativado exige ao menos uma decisão explícita.
•Não listar tecnologias sem justificar com requisitos e trade offs.
•Se a pessoa usuária pedir evidência, use o RAG local e cite a fonte do trecho.

Como esta Skill trabalha

Esta Skill usa 7 padrões recorrentes. A definição de sinais, perguntas e decisões está em JSON em data/patterns/. Veja o resumo em reference-patterns.md.

Fluxo de trabalho.

Etapa 1. Detectar padrões a partir do enunciado Execute: python3 .claude/skills/system-design-decision-engine/scripts/detect_patterns.py "<texto do problema>"

Etapa 2. Gerar perguntas obrigatórias por padrão ativado Execute: python3 .claude/skills/system-design-decision-engine/scripts/generate_questions.py "<lista de ids de padrões>"

Etapa 3. Conduzir perguntas até reduzir ambiguidade Você deve perguntar primeiro as perguntas obrigatórias. Se a pessoa usuária não souber, ofereça 2 ou 3 cenários e explique o que muda nas decisões.

Etapa 4. Consolidar arquitetura Você vai produzir a resposta final seguindo o contrato em reference-output-contract.md. Você deve incluir, para cada padrão ativado:

•por que ativou
•decisões tomadas
•alternativas descartadas
•trade offs assumidos
•riscos e falhas comuns

RAG local

O RAG é opcional e só pode ser usado nestes casos:

•pessoa usuária pediu fonte ou evidência
•subagent tradeoff-challenger sinalizou justificativa fraca

Política completa em: reference-rag-policy.md

Ingestão do corpus local: python3 .claude/skills/system-design-decision-engine/scripts/rag_ingest.py

Busca no corpus: python3 .claude/skills/system-design-decision-engine/scripts/rag_search.py "<consulta>"

Arquivos de referência

•Padrões e como ativam: reference-patterns.md
•Contrato de saída: reference-output-contract.md
•Política de RAG: reference-rag-policy.md
•Trade-offs consolidados: tradeoffs.md
•Fontes e materiais: reference.md

Referencias do Engineering Playbook

Decisoes devem considerar:

•.docs/engineering-playbook/manual-desenvolvimento/principios.md - Principios orientadores
•.docs/engineering-playbook/stacks/devops/security.md - Threat modeling (STRIDE)

Padrões Detalhados (Markdown)

Para explicações detalhadas de cada padrão, consulte:

Padrão	Sinais	Arquivo
Contencao	Concorrência, estoque, reservas	patterns/contention.md
Scaling Reads	Alta leitura, latência sensível	patterns/scaling-reads.md
Scaling Writes	Alta escrita, picos	patterns/scaling-writes.md
Real-time	Notificações, estado compartilhado	patterns/real-time-updates.md
Large Files	Upload/download grandes	patterns/large-files.md
Long Running	Operações demoradas	patterns/long-running-tasks.md
Multi-step	Fluxos com etapas	patterns/multi-step-processes.md

Scripts Utilitários

Detecção e Perguntas (Workflow)

bash

# Detectar padrões no problema
python scripts/detect_patterns.py "sistema de reserva de ingressos"

# Gerar perguntas obrigatórias
python scripts/generate_questions.py "contention,scaling-writes"

Estimativas (Back-of-Envelope)

bash

# Referência rápida de valores comuns
python scripts/capacity_calculator.py --reference

# Estimar storage
python scripts/capacity_calculator.py --storage --users 1000000 --data-per-user 1MB

# Estimar bandwidth
python scripts/capacity_calculator.py --bandwidth --rps 10000 --response-size 10KB

# Estimar QPS
python scripts/capacity_calculator.py --qps --daily-users 1000000

Diagramas Mermaid

bash

# Listar tipos disponíveis
python scripts/diagram_generator.py --list

# Gerar diagrama
python scripts/diagram_generator.py --type microservice
python scripts/diagram_generator.py --type cqrs
python scripts/diagram_generator.py --type saga

Tipos: basic, microservice, event-driven, cqrs, cache, queue, database, saga, circuit-breaker, cdn

Checklist de Decisões

bash

# Checklist interativo
./scripts/decision_checklist.sh

# Checklist para impressão
./scripts/decision_checklist.sh --quick

Subagents Disponíveis

Esta skill trabalha com 4 subagents especializados em .claude/agents/:

Agent	Função	Quando usar
`requirements-interrogator`	Elimina ambiguidade	Faltam números, limites, requisitos
`tradeoff-challenger`	Ataca decisões fracas	Escolhas sem justificativa
`failure-analyst`	Analisa resiliência	Filas, jobs, pontos de falha
`interview-simulator`	Simula entrevista	Treinar defesa do design