Communitygithub.com

diagramme-architecture

Diagrammes d'architecture sous forme de texte, dans les propres mots du lecteur. Boîtes noires, interfaces sur chaque jointure avec leurs opérations, types de données et un exemple de ce qui la traverse, un état ou plusieurs comparés (tel quel, cible, proposition) ; d'abord du texte, puis LikeC4 quand c'est destiné à d'autres. À utiliser lorsque l'utilisateur demande de dessiner, schématiser ou visualiser comment du code ou des systèmes s'assemblent, ou ce qu'un changement fait à leur structure.

Qu'est-ce que diagramme-architecture ?

Ce skill aide les agents d'IA et les développeurs à créer des diagrammes d'architecture textuels centrés sur la compréhension du lecteur. Il met l'accent sur l'utilisation du vocabulaire existant du lecteur, la définition des interfaces (opérations, types, exemples) à chaque jointure entre blocs boîte noire, et la comparaison de plusieurs états (actuel, cible, proposition). Le processus se déroule en plusieurs étapes : collecter les mots du lecteur, poser des questions pour déterminer les vues, cataloguer les blocs/interfaces/types/exemples, choisir un niveau d'abstraction (5 à 9 blocs par état), puis dessiner en utilisant trois formats (chat, canvas HTML, ou C4 avec LikeC4). Le skill est utile pour clarifier l'impact d'un changement, comparer des designs, ou documenter des systèmes complexes. Il supporte les conversations en chat, les pages HTML statiques, et les diagrammes LikeC4 interactifs. Il fonctionne en suivant une méthodologie rigoureuse qui garantit que chaque étiquette provient de la liste de mots du lecteur, que chaque référence pointe vers le code réel, et que chaque état est représenté de manière cohérente pour faciliter la comparaison visuelle.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NG-Bullseye/architecture-diagram-skill/tree/HEAD/skills/architecture-diagram

Demander à votre IA préférée

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

Documentation

Diagramme d'Architecture

Un diagramme est compris lorsque ce qu'il montre s'arrime à ce que le lecteur sait déjà. Un développeur senior le lit pour le flux de plus haut niveau et pour les jointures. Un bloc est une boîte noire : son motif de conception, sa responsabilité, son propriétaire, et son intérieur caché. Ce qu'un bloc offre à un autre à travers une jointure est son interface : des opérations avec leurs types de paramètres et de retour, les erreurs, les types de données qui la traversent avec leurs champs, et un exemple de ce qui traverse exactement et à quoi cela ressemble. Le transport (REST, OPC UA, un démarrage de processus) est un attribut d'une interface et ne la remplace jamais.

Lisez EXAMPLE.md avant de dessiner : un changement, complet, sous les deux formes.

Étapes

1. Les mots du lecteur

Un nouveau terme ne s'arrime à rien. Avant toute chose, recueillez les mots que le lecteur possède déjà : à partir de ses messages dans cette conversation, des documents qu'il a écrits (instructions du projet, pages d'architecture, glossaires, tables de nomenclature), et de tout modèle auquel le diagramme est comparé. Rédigez la liste de mots : la chose, le mot du lecteur pour celle-ci, le mot de chaque autre partie qui lira le diagramme, le nom dans le code, et le mot utilisé par le diagramme.

  • Étiquetez chaque bloc et interface avec le mot du lecteur ; le nom du code se tient à côté.
  • Là où deux mots s'opposent, ou qu'un mot est utilisé pour la mauvaise chose, choisissez-en un, dites pourquoi dans la liste de mots, et nommez l'autre à côté une fois.
  • N'inventez rien. Une interface sans nom dans le code est appelée par ses deux extrémités, Frontend -> Backend.
  • Partez de l'image que le lecteur possède déjà, son propre diagramme avec ses niveaux et ses noms, et placez ce qui est nouveau à l'intérieur.

Terminé lorsque chaque étiquette sur un diagramme provient de la liste de mots, et que chaque terme nouveau pour le lecteur se trouve dans le glossaire à côté du mot connu auquel il appartient.

2. Questions

Rédigez les questions du lecteur, une par ligne. Ce sont elles qui choisissent les vues.

QuestionVue
Quelles sont les parties, de quoi chacune est-elle responsable, qui la possède, qui appelle qui ?vue des blocs de construction
Quelle interface relie deux parties, et qu'est-ce qui la traverse exactement ?l'interface, ses types de données et un exemple sur chaque jointure
Que se passe-t-il, dans quel ordre, dans le scénario qui importe ?vue d'exécution : une séquence
Où chaque partie s'exécute-t-elle ?host: sur chaque bloc ; une vue de déploiement lorsque les réseaux ou les limites de confiance sont la question
Que fait un changement, ou en quoi deux conceptions diffèrent-elles ?chaque état sous la même forme, puis les différences

Terminé lorsque chaque vue a sa question et que la question se trouve au-dessus d'elle comme légende.

3. Catalogue

Remplissez quatre listes à partir des sources avant tout dessin.

  • Blocs : le mot du lecteur et le nom dans le code, stéréotype, une phrase de responsabilité, propriétaire, hôte.
  • Interfaces, une par jointure : fournisseur, consommateurs, chaque opération comme signature nom(param: Type) -> Type, erreurs, transport.
  • Types de données : chaque type nommé par une signature, avec ses champs, unités et valeurs par défaut.
  • Exemples, un par interface : un message tel qu'il traverse, appel et réponse dans leur format réel : une ligne de commande avec sa sortie, un corps JSON, une ligne de tableau. Prenez-le à partir d'une exécution, d'un enregistrement, d'un fichier de test ou des données. Un exemple assemblé à partir du code le dit dans sa première ligne.

Chaque entrée porte son origine : une référence de code chemin:ligne, ou une balise (ci-dessous). Un état dessiné par quelqu'un d'autre, un fichier de modèle ou une esquisse, est reproduit tel quel et dans ses propres mots ; ce qu'il omet est balisé [non défini], et ce que vous ajoutez va dans un état qui vous est propre.

Terminé lorsque chaque bloc a sa phrase, chaque jointure une interface dont les signatures sont copiées du code ou balisées, chaque type dans une signature ses champs, chaque interface son exemple, et chaque entrée une référence ou une balise.

4. Niveau

Les blocs d'un état sont des pairs : des unités qui sont déployées, possédées ou remplacées indépendamment, de cinq à neuf d'entre eux. Les fichiers, fonctions et étapes à l'intérieur d'un bloc sont son intérieur. Un zoom est un diagramme supplémentaire un niveau plus bas, dessiné pour le seul bloc concerné par la question.

Terminé lorsqu'aucun bloc d'un état ne se trouve à l'intérieur d'un autre, et que chaque zoom nomme la question qui le justifie.

5. Forme

  • Forme de discussion, jusqu'à 78 colonnes : la vue des blocs de construction avec le nom de l'interface et sa signature principale sur chaque arête, puis le catalogue sous forme de tableaux et les exemples sous forme de blocs de code. Pour un état ou un petit changement.
  • Forme Canvas, une page HTML statique de diagrammes textuels aussi larges que nécessaire : à côté de chaque arête, son interface en entier, l'exemple, et les types de données avec leurs champs. Pour plusieurs états, ou lorsque plus de trois jointures sont montrées en entier. La page est construite par un script générateur qui se trouve à côté ; la réponse dans le chat nomme le fichier, dit en quelques phrases ce que la comparaison montre et liste les décisions ouvertes.
  • Forme C4, le même modèle dessiné avec LikeC4 sur une page avec un onglet par état, des boîtes cliquables et dans lesquelles zoomer. Les diagrammes textuels sont son prototype : fixez les mots, blocs, interfaces et exemples d'abord, puis rendez. Pour un résultat que d'autres personnes ouvriront. Lisez LIKEC4.md.

6. Dessinez

Dessinez avec les trois fichiers de ce dossier, afin que les boîtes soient alignées et qu'aucune ligne ne soit plus large que son canevas. Le docstring de chaque fichier est son manuel, et son exécution imprime une démo.

FichierDonne
grid.pyGrille (boîtes avec compartiments, lignes, flèches), séquence (une vue d'exécution), tableau
canvas.pycoup_doeil (chaque état sur une ligne), aperçu (états côte à côte, une ligne par niveau), panneau (un état : blocs, interfaces avec exemples, types de données)
page.pypage_html : la page autour des diagrammes, avec les couleurs et les liens entre les identifiants
likec4/pour la forme C4 : template.c4, build.sh, la page à onglets index.html avec tabs.js, et clicktest.py

Une page va de l'image en dix secondes au détail : d'un coup d'œil, la liste de mots, le guide de lecture, l'aperçu, un panneau par état, les différences par jointure sous forme de tableau, les décisions ouvertes, le glossaire, les sources.

7. Vérification

  • Chaque boîte est un bloc du catalogue, chaque arête une interface, chaque boîte de type un type de données ; une entrée omise d'un diagramme est omise intentionnellement.
  • Chaque référence de code se résout : le fichier existe et la ligne montre le nom.
  • Le même bloc se trouve à la même place dans chaque état. Un bloc manquant dans un état est une boîte en pointillés à cet endroit.
  • Captures d'écran de la page entière, lues tuile par tuile : les bordures se rejoignent, rien n'est coupé, les couleurs portent leur signification.
  • Les sources nomment ce qui a été lu, à quel commit, quels exemples sont réels, et ce qui n'a pas été lu.

États

Un état est le code tel qu'il est, une cible dessinée par quelqu'un, ou une proposition. Comparez les états par position : le même bloc dans la même colonne de coup_doeil et la même ligne de aperçu, de sorte que les lacunes de deux états montrent où ils se complètent.

Une jointure a un identifiant composé d'une lettre pour son état et d'un numéro, (I4). Une interface ou un type de données défini à une jointure est référencé par cet identifiant partout ailleurs ; ses champs sont écrits une seule fois.

Les différences sont un tableau avec une ligne par jointure et une colonne par état. Les décisions ouvertes sont un tableau : la question, les options, qui décide.

Balises et stéréotypes

BaliseSignification
[code]existe dans le code ; la référence se tient à côté
une balise source, p. ex. [c4]déclaré par un modèle source ; nommez la balise dans le guide de lecture
[proposé]proposé ici, n'existe nulle part encore
[nouveau] [modifié] [déplacé]ce qu'un changement fait, lorsqu'il n'y a que l'actuel et le futur
[non défini]l'état le laisse ouvert
[?1]une décision ouverte, listée avec son numéro

Les stéréotypes nomment le motif de conception qu'un bloc joue : <<ui>>, <<client>>, <<passerelle>>, <<façade>>, <<service>>, <<port>>, <<adaptateur>>, <<référentiel>>, <<externe>>. Utilisez-en un là où le code joue ce rôle ; un bloc sans stéréotype vaut mieux qu'un bloc avec un mauvais. Un port est une interface que le consommateur possède et que le fournisseur implémente : <<port>> se tient sur l'interface, <<adaptateur>> sur le bloc qui l'implémente. Les propres types d'un modèle source sont cités tels qu'il les écrit.

Dispositifs d'explication

Chacun d'eux mérite sa place en répondant à quelque chose que le lecteur aurait autrement dû demander. Utilisez-les avec parcimonie.

  • Guide de lecture : un petit diagramme qui montre comment lire un panneau, et les balises.
  • Références de code : sur chaque interface et type de données, afin que le lecteur puisse les consulter.
  • Textes courts : un paragraphe au-dessus d'un état qui dit la chose à y voir ; une note à l'intérieur d'une boîte d'interface là où le lecteur demanderait pourquoi.
  • Glossaire : les termes que la liste de mots ne couvre pas, un par ligne.
  • Couleur : uniquement pour les balises, les identifiants, et un ou deux noms clé qui restent les mêmes dans tous les états. La couleur marque ce que les états partagent et où ils diffèrent ; rien d'autre n'est coloré.

La prose est dans la langue de la conversation. Les noms provenant du code et des modèles sources sont reproduits textuellement.

Skills associés