sk-system-design

Concevoir ou évaluer un système distribué à partir de ses contraintes — limites des services, communication synchrone ou événementielle, cohérence, comportement en cas de panne et capacité — et énoncer les compromis que chaque choix implique. À utiliser pour scinder ou fusionner des services, choisir entre un appel et un événement, décider où placer les données, examiner une proposition d'architecture ou répondre à une question de conception système.

Qu'est-ce que sk-system-design ?

Cette compétence fournit un cadre méthodique pour la conception de systèmes distribués, en mettant l'accent sur les contraintes avant les composants. Elle guide l'utilisateur à travers six étapes clés : définir les contraintes (charge, données, cohérence, disponibilité, latence, propriété), établir les limites des services, choisir entre communication synchrone et événementielle, gérer les échecs des appels distants, assurer la cohérence des données, et documenter les décisions de conception. L'approche évite les pièges courants comme l'ajout de composants sans mesure préalable ou la conception pour une charge 100x alors qu'on est à 1x. Elle met en avant l'importance des compromis et des alternatives rejetées. Compatible avec tout agent IA (Claude Code, Cursor, Codex) pour analyser ou concevoir des architectures distribuées, cette compétence est utile lors de revues d'architecture, de scission ou fusion de services, ou de questions d'entretien sur la conception système.

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

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Conception système

Le mode d'échec est de sauter directement aux composants. Une conception qui nomme les services avant de nommer les contraintes est une supposition entourée de boîtes, et elle ne peut pas être évaluée car rien ne dit ce qu'elle était censée accomplir.

1. Contraintes avant composants

Écrivez-les d'abord. Chacune élimine des conceptions :

  • Charge — requêtes par seconde au pic, et ratio lectures/écritures. Les lectures et les écritures évoluent par des moyens complètement différents, donc le ratio décide plus que le nombre absolu.
  • Données — volume total, taux de croissance, et taille d'un élément unique.
  • Cohérence — ce qui doit être immédiatement correct, et ce qui peut être obsolète. Presque jamais « tout » ; nommer la petite partie qui doit être stricte est ce qui rend le reste bon marché.
  • Disponibilité — ce qu'il advient de l'activité pendant une panne de ce composant, et quel comportement dégradé est acceptable.
  • Latence — le budget pour le chemin utilisateur, à un centile plutôt qu'à une moyenne.
  • Propriété — quelle équipe déploie et est de garde pour chaque partie. Une limite qui traverse une équipe devient un coût de coordination à chaque changement.

Estimez approximativement et dites-le. Un ordre de grandeur suffit pour choisir une architecture, et la précision que vous n'avez pas ne vaut pas la peine d'être calculée.

2. Limites

Divisez par ce qui change ensemble et qui possède les données, pas par nom. Un service qui ne peut pas être déployé sans qu'un autre service soit déployé en même temps est un service dans deux dépôts, avec des appels réseau ajoutés.

Chaque donnée a exactement un propriétaire qui l'écrit. Tous les autres lisent via l'interface du propriétaire ou via une copie que le propriétaire publie. Deux services écrivant dans la même table est le monolithe distribué : déploiements indépendants, panne partagée, et aucun endroit clair pour appliquer une invariant.

Préférez moins de services, plus gros, jusqu'à ce qu'une force réelle nécessite une scission — mise à l'échelle indépendante, propriété séparée, besoins de disponibilité vraiment différents. Scinder est peu coûteux à faire et coûteux à annuler, et chaque limite convertit un appel de fonction en un appel réseau qui peut échouer, être relancé, et arriver deux fois.

3. Synchrone ou événementiel

Appelez de manière synchrone lorsque l'appelant ne peut pas continuer sans la réponse et que l'utilisateur attend. Chaque dépendance synchrone ajoute son temps d'arrêt au vôtre et sa latence à votre budget, alors comptez-les : une requête qui touche cinq services de manière synchrone est moins disponible que n'importe lequel d'entre eux.

Publiez un événement lorsque d'autres parties du système ont besoin de savoir que quelque chose s'est produit, mais que l'appelant n'a pas besoin de leur réponse. Cela découple la disponibilité — le consommateur peut être hors service sans échouer l'écriture.

Soyez honnête sur le coût. Un événement vous donne une cohérence éventuelle, une livraison hors ordre et en double, et un chemin de débogage qui n'apparaît plus dans une seule trace de pile. Acceptez ce compromis lorsque vous avez besoin du découplage, pas parce que cela semble moderne.

Lorsqu'une écriture doit mettre à jour l'état local et informer quelqu'un d'autre, les deux ne doivent pas pouvoir diverger. Écrivez l'événement dans la même transaction que le changement d'état et publiez-le à partir de là, plutôt que d'écrire la ligne puis d'appeler le courtier — l'écart entre ces deux appels est l'endroit où le message perdu se trouve.

4. Supposez que chaque appel à distance échoue

Pour chacun, décidez à l'avance :

  • Délai d'attente — un délai explicite, plus court que le propre budget de l'appelant. Un appel sans délai d'attente transforme une dépendance lente en panne lorsque les threads s'accumulent.
  • Nouvelle tentative — uniquement pour les échecs transitoires, uniquement avec backoff et gigue, et uniquement lorsque l'opération est idempotente. Relancer une écriture non idempotente la duplique ; les nouvelles tentatives synchronisées de chaque client transforment un incident en déferlante.
  • Idempotence — une clé fournie par l'appelant, afin qu'une nouvelle tentative après un délai d'attente soit reconnue. L'appelant ne peut pas distinguer une requête perdue d'une réponse perdue, donc il réessaiera.
  • Dégradation — ce que l'utilisateur voit lorsque ce service reste hors service. Servir un résultat mis en cache ou partiel est généralement mieux qu'une page d'erreur, et le décider au moment de la conception est ce qui le rend possible.

5. Cohérence

Identifiez l'invariant qui ne doit jamais être rompu — argent conservé, stock non sur-vendu, pas de double facturation — et gardez-le à l'intérieur d'une seule transaction dans un seul service. Cette contrainte, plus que toute autre, devrait décider de vos limites.

Tout ce qui se trouve en dehors de cet invariant peut être éventuellement cohérent. Lorsqu'un workflow traverse plusieurs services, modélisez-le comme une séquence de transactions locales avec une action compensatoire pour chaque étape, et acceptez que les états intermédiaires soient visibles.

Les transactions distribuées entre services sont un dernier recours. La conception d'actions compensatoires est plus difficile à conceptualiser et beaucoup plus facile à exploiter.

6. Écrivez-le

Contraintes    <charge, données, cohérence, disponibilité, latence, propriété>
Conception     <composants et ce que chacun possède>
Flux           <les deux ou trois chemins importants, dans l'ordre>
Échec          <ce qui se passe lorsque chaque dépendance est hors service, et ce que l'utilisateur voit>
Compromis      <ce que cette conception rend difficile, et ce que vous changeriez d'abord à 10x>
Rejeté         <l'alternative et pourquoi pas>

Les lignes Échec et Rejeté sont ce qui sépare une conception d'un dessin. Une proposition qui ne décrit que le chemin heureux n'a pas été évaluée.

À ne pas faire

  • N'ajoutez pas de file d'attente, de cache ou de partition pour une charge que vous n'avez pas mesurée ou estimée.
  • Ne concevez pas pour 100x lorsque vous êtes à 1x. Concevez de manière à ce que la prochaine étape connue soit possible, et dites ce qui se casse en premier au-delà.
  • Ne présentez pas une seule option comme inévitable. Nommez ce que vous avez rejeté.

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 associés