CommunityProgramación y desarrollogithub.com

sk-system-design

Diseña o evalúa un sistema distribuido a partir de sus restricciones: límites de servicio, comunicación síncrona frente a basada en eventos, consistencia, comportamiento ante fallos y capacidad, indicando la compensación que implica cada elección. Úsalo al dividir o fusionar servicios, elegir entre una llamada y un evento, decidir dónde residen los datos, revisar una propuesta de arquitectura o responder una pregunta de diseño de sistemas.

¿Qué es sk-system-design?

**sk-system-design** es una habilidad para agentes de IA especializada en el diseño y evaluación de sistemas distribuidos. Su enfoque principal es evitar el error común de saltar directamente a los componentes sin definir primero las restricciones. Para ello, guía al usuario a través de un proceso estructurado que comienza con la identificación de restricciones clave como carga, datos, consistencia, disponibilidad y latencia, antes de definir los límites de servicio. Luego, ayuda a decidir entre comunicación síncrona o basada en eventos, modelar fallos de red, garantizar la consistencia y documentar el diseño final. La habilidad es útil en escenarios como dividir o fusionar servicios, elegir entre una llamada y un evento, decidir dónde residen los datos, revisar una propuesta de arquitectura o responder una pregunta de diseño de sistemas. Es compatible con plataformas como Claude Code, Cursor y Codex, y su documentación (SKILL.md) proporciona pautas claras, ejemplos y advertencias sobre prácticas comunes que se deben evitar. El resultado es un diseño evaluado, con compensaciones explícitas y alternativas rechazadas, en lugar de un simple dibujo.

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

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Diseño de sistemas

El modo de fallo es saltar a los componentes. Un diseño que nombra servicios antes de nombrar restricciones es una suposición con cajas dibujadas a su alrededor, y no se puede evaluar porque nada dice lo que se suponía que debía lograr.

1. Restricciones antes que componentes

Escríbelas primero. Cada una elimina diseños:

  • Carga — solicitudes por segundo en el pico y la proporción de lecturas a escrituras. Las lecturas y escrituras escalan por medios completamente diferentes, por lo que la proporción decide más que el número absoluto.
  • Datos — volumen total, tasa de crecimiento y el tamaño de un solo elemento.
  • Consistencia — qué debe ser correcto de inmediato y qué puede estar obsoleto. Casi nunca "todo"; nombrar la pequeña parte que debe ser estricta es lo que abarata el resto.
  • Disponibilidad — qué le sucede al negocio durante una interrupción de este componente y qué comportamiento degradado es aceptable.
  • Latencia — el presupuesto para la ruta orientada al usuario, en un percentil en lugar de una media.
  • Propiedad — qué equipo despliega y se responsabiliza de cada parte. Un límite que atraviesa un equipo se convierte en un costo de coordinación en cada cambio.

Estima de forma aproximada y dilo. Un orden de magnitud es suficiente para elegir una arquitectura, y la precisión que no tienes no vale la pena realizarla.

2. Límites

Divide por lo que cambia junto y quién posee los datos, no por un sustantivo. Un servicio que no se puede implementar sin que otro servicio se implemente al mismo tiempo es un servicio en dos repositorios, con llamadas de red añadidas.

Cada pieza de datos tiene exactamente un propietario que la escribe. Todos los demás leen a través de la interfaz del propietario o a través de una copia que el propietario publica. Dos servicios escribiendo en la misma tabla es el monolito distribuido: despliegues independientes, fallo compartido y ningún lugar claro para hacer cumplir una invariante.

Prefiere menos servicios, más grandes, hasta que una fuerza real requiera una división — escalado independiente, propiedad separada, necesidades de disponibilidad genuinamente diferentes. Dividir es barato de hacer y caro de deshacer, y cada límite convierte una llamada a función en una llamada de red que puede fallar, reintentarse y llegar dos veces.

3. Síncrono o basado en eventos

Llama de forma síncrona cuando el llamante no puede continuar sin la respuesta y el usuario está esperando. Cada dependencia síncrona añade su tiempo de inactividad al tuyo y su latencia a tu presupuesto, así que cuéntalas: una solicitud que toca cinco servicios de forma síncrona es menos disponible que cualquiera de ellos.

Publica un evento cuando otras partes del sistema necesitan saber que algo sucedió pero el llamante no necesita su respuesta. Esto desacopla la disponibilidad — el consumidor puede estar caído sin fallar la escritura.

Sé honesto sobre el costo. Un evento te da consistencia eventual, entrega fuera de orden y duplicada, y una ruta de depuración que ya no aparece en un solo rastreo de pila. Acepta esa compensación cuando necesites el desacoplamiento, no porque suene moderno.

Cuando una escritura debe actualizar el estado local y decírselo a alguien más, los dos no deben poder divergir. Escribe el evento en la misma transacción que el cambio de estado y publícalo desde allí, en lugar de escribir la fila y luego llamar al broker — el espacio entre esas dos llamadas es donde vive el mensaje perdido.

4. Asume que cada llamada remota falla

Para cada una, decide de antemano:

  • Tiempo de espera (timeout) — uno explícito, más corto que el presupuesto del propio llamante. Una llamada sin tiempo de espera convierte una dependencia lenta en una interrupción a medida que se acumulan los hilos.
  • Reintento (retry) — solo para fallos transitorios, solo con retroceso (backoff) y fluctuación (jitter), y solo cuando la operación es idempotente. Reintentar una escritura no idempotente la duplica; los reintentos sincronizados desde cada cliente convierten un destello en una estampida.
  • Idempotencia — una clave que proporciona el llamante, para que un reintento después de un tiempo de espera sea reconocido. El llamante no puede distinguir una solicitud perdida de una respuesta perdida, por lo que reintentará.
  • Degradación — lo que ve el usuario cuando esto permanece caído. Servir un resultado en caché o parcial suele ser mejor que una página de error, y decidirlo en el momento del diseño es lo que lo hace posible.

5. Consistencia

Identifica la invariante que nunca debe romperse — dinero conservado, stock no sobregirado, sin doble cobro — y mantenla dentro de una sola transacción en un solo servicio. Esta restricción, más que cualquier otra, debería decidir tus límites.

Todo lo que esté fuera de esa invariante puede ser eventualmente consistente. Cuando un flujo de trabajo abarca servicios, modélalo como una secuencia de transacciones locales con una acción compensatoria para cada paso, y acepta que los estados intermedios son visibles.

Las transacciones distribuidas entre servicios son un último recurso. El diseño de acciones compensatorias es más difícil de pensar y mucho más fácil de operar.

6. Escríbelo

Restricciones   <carga, datos, consistencia, disponibilidad, latencia, propiedad>
Diseño         <componentes y lo que cada uno posee>
Flujos         <los dos o tres caminos importantes, en orden>
Fallo          <lo que sucede cuando cada dependencia está caída y lo que ve el usuario>
Compensaciones <lo que este diseño dificulta y qué cambiarías primero a 10x>
Rechazado      <la alternativa y por qué no>

Las filas Fallo y Rechazado son lo que separa un diseño de un dibujo. Una propuesta que solo describe el camino feliz no ha sido evaluada.

No hagas

  • No añadas una cola, caché o fragmento para una carga que no hayas medido o estimado.
  • No diseñes para 100x cuando estás en 1x. Diseña para que el siguiente paso conocido sea posible y di qué se rompe primero más allá de eso.
  • No presentes una única opción como inevitable. Nombra lo que rechazaste.

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.

Skills relacionados