sk-system-design

Projete ou avalie um sistema distribuído a partir de suas restrições — limites de serviço, comunicação síncrona versus orientada a eventos, consistência, comportamento de falha e capacidade — e declare a compensação que cada escolha traz.

O que é sk-system-design?

Esta habilidade capacita agentes de IA a projetar ou avaliar sistematicamente arquiteturas de sistemas distribuídos, concentrando-se primeiro nas restrições (carga, dados, consistência, disponibilidade, latência, propriedade) antes de nomear componentes. Ela orienta o agente através de limites de serviço, escolhas de comunicação síncrona versus orientada a eventos, tratamento de falhas remotos (timeouts, retentativas, idempotência) e técnicas de consistência de dados (invariantes dentro de uma única transação, consistência eventual). O agente aprende a documentar compensações explicitamente, rejeitar alternativas e evitar armadilhas comuns como projetar para 100x quando se está em 1x. Útil para dividir ou mesclar serviços, escolher entre uma chamada e um evento, decidir onde os dados residem, revisar uma proposta de arquitetura ou responder a uma pergunta de design de sistema. Suportado por qualquer agente de IA que possa seguir um processo estruturado de tomada de decisão.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-system-design

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Design de sistema

O modo de falha é pular para componentes. Um design que nomeia serviços antes de nomear restrições é um palpite com caixas desenhadas ao redor, e não pode ser avaliado porque nada diz o que ele deveria alcançar.

1. Restrições antes de componentes

Escreva estas primeiro. Cada uma elimina designs:

  • Carga — requisições por segundo no pico, e a relação leitura/escrita. Leituras e escritas escalam por meios completamente diferentes, então a relação decide mais do que o número absoluto.
  • Dados — volume total, taxa de crescimento e o tamanho de um único item.
  • Consistência — o que deve estar correto imediatamente, e o que pode estar desatualizado. Quase nunca "tudo"; nomear a pequena parte que deve ser estrita é o que torna o restante barato.
  • Disponibilidade — o que acontece com o negócio durante uma falha deste componente, e qual comportamento degradado é aceitável.
  • Latência — o orçamento para o caminho voltado ao usuário, em um percentil, não na média.
  • Propriedade — qual equipe implanta e paga por cada parte. Um limite que corta uma equipe se torna um custo de coordenação em cada mudança.

Estime aproximadamente e diga isso. Uma ordem de magnitude é suficiente para escolher uma arquitetura, e precisão que você não tem não vale a pena ser calculada.

2. Limites

Divida pelo que muda junto e por quem possui os dados, não por substantivo. Um serviço que não pode ser implantado sem que outro serviço seja implantado ao mesmo tempo é um serviço em dois repositórios, com chamadas de rede adicionadas.

Cada dado tem exatamente um dono que o escreve. Todos os outros leem através da interface do dono ou de uma cópia que o dono publica. Dois serviços escrevendo na mesma tabela é o monólito distribuído: implantações independentes, falha compartilhada e nenhum lugar claro para impor uma invariante.

Prefira serviços mais enxutos e maiores até que uma força real exija uma divisão — escalonamento independente, propriedade separada, necessidades de disponibilidade genuinamente diferentes. Dividir é barato de fazer e caro de desfazer, e cada limite converte uma chamada de função em uma chamada de rede que pode falhar, repetir e chegar duas vezes.

3. Síncrono ou orientado a eventos

Chame de forma síncrona quando o chamador não pode prosseguir sem a resposta e o usuário está esperando. Cada dependência síncrona adiciona seu tempo de inatividade ao seu e sua latência ao seu orçamento, então conte-as: uma requisição que toca cinco serviços sincronamente é menos disponível do que qualquer um deles.

Publique um evento quando outras partes do sistema precisam saber que algo aconteceu, mas o chamador não precisa da resposta delas. Isso desacopla a disponibilidade — o consumidor pode estar inativo sem falhar a escrita.

Seja honesto sobre o custo. Um evento lhe dá consistência eventual, entrega fora de ordem e duplicada, e um caminho de depuração que não aparece mais em uma única stack trace. Aceite essa troca quando precisar do desacoplamento, não porque parece moderno.

Quando uma escrita deve atualizar o estado local e informar alguém, os dois não podem divergir. Escreva o evento na mesma transação que a mudança de estado e publique a partir dela, em vez de escrever a linha e depois chamar o broker — a lacuna entre essas duas chamadas é onde a mensagem perdida vive.

4. Assuma que toda chamada remota falha

Para cada uma, decida com antecedência:

  • Timeout — um explícito, menor que o próprio orçamento do chamador. Uma chamada sem timeout transforma uma dependência lenta em uma paralisação, à medida que as threads se acumulam.
  • Retentativa — apenas para falhas transitórias, apenas com backoff e jitter, e apenas quando a operação é idempotente. Tentar novamente uma escrita não idempotente a duplica; retentativas sincronizadas de todos os clientes transformam um pico em uma debandada.
  • Idempotência — uma chave que o chamador fornece, para que uma retentativa após um timeout seja reconhecida. O chamador não pode distinguir uma requisição perdida de uma resposta perdida, então tentará novamente.
  • Degradação — o que o usuário vê quando isso fica inativo. Servir um resultado em cache ou parcial geralmente é melhor que uma página de erro, e decidir isso no momento do design é o que torna isso possível.

5. Consistência

Identifique a invariante que nunca deve ser quebrada — dinheiro conservado, estoque não vendido em excesso, nenhuma cobrança duplicada — e mantenha-a dentro de uma única transação em um único serviço. Essa restrição, mais do que qualquer outra, deve decidir seus limites.

Tudo fora dessa invariante pode ser eventualmente consistente. Quando um fluxo de trabalho abrange serviços, modele-o como uma sequência de transações locais com uma ação compensatória para cada etapa, e aceite que os estados intermediários são visíveis.

Transações distribuídas entre serviços são um último recurso. O design de ação compensatória é mais difícil de pensar e muito mais fácil de operar.

6. Escreva

Restrições    <carga, dados, consistência, disponibilidade, latência, propriedade>
Design        <componentes e o que cada um possui>
Fluxos        <os dois ou três caminhos importantes, em ordem>
Falha         <o que acontece quando cada dependência está inativa, e o que o usuário vê>
Compensações  <o que este design torna difícil, e o que você mudaria primeiro em 10x>
Rejeitado     <a alternativa e por que não>

As linhas Falha e Rejeitado são o que separa um design de um desenho. Uma proposta que apenas descreve o caminho feliz não foi avaliada.

Não faça

  • Não adicione uma fila, cache ou shard para uma carga que você não mediu ou estimou.
  • Não projete para 100x quando você está em 1x. Projete para que o próximo passo conhecido seja possível, e diga o que quebra primeiro além disso.
  • Não apresente uma única opção como inevitável. Nomeie o que você rejeitou.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-go-service

Implement, extend or debug a handler, service or repository in a Go backend service, covering context propagation, error wrapping, transaction boundaries, tenancy scoping and table-driven tests. Use when writing or changing Go server code, adding an endpoint or gRPC method, touching a repository query, or diagnosing a panic, leak or flaky test in a Go service.

sk-python

Write and debug Python with attention to the traps that produce silent wrong behaviour — mutable defaults, late-binding closures, shallow copies, swallowed exceptions — plus typing, environment and packaging with uv or venv, and pytest structure. Use when writing a Python script, service or library, setting up a Python project, or debugging behaviour that looks impossible.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

Habilidades Relacionadas