Explorateur d'Architecture

Que fait Explorateur d'Architecture ?

Produit un fichier HTML autonome par explorateur : runtime, topologie, prose, police de caractères et styles intégrés, aucun appel réseau à l'exécution. Hébergez-le n'importe où, ouvrez-le hors ligne, intégrez-le via <iframe> dans une page, ou joignez-le à un e-mail.

Le modèle

Une topologie, plusieurs projections. Le système est écrit une fois, en profondeur. Tout le reste n'est qu'un sélecteur sur ce graphe unique — jamais un deuxième diagramme.

TOPOLOGIE   nœuds + arêtes + métadonnées        ← la seule chose que vous rédigez
──────────────────────────────────────
PERSONA    politique de résolution — vocabulaire, profondeur de réduction, faits affichés
AXE        couche de préoccupation — arêtes existantes, fait que chaque nœud annonce
ÉPOQUE     passé / présent / planifié — présence et style d'état
ÉTAPES     narration — caméra, focus, prose, en séquence

Deux règles que le runtime applique et auxquelles vous ne devez pas déroger :

1. La couleur appartient à l'axe. Le type de nœud est véhiculé par la forme — coin plié pour une source, colonne vertébrale pour un stockage, figure pour une étape humaine, chanfreiné pour une passerelle. Ne réintroduisez jamais un schéma couleur-par-type ; cela transforme le diagramme en arc-en-ciel et rend le changement d'axe inutile.
2. Un diagramme sans visite guidée n'est pas terminé. Le linter échoue la build avec zéro étape. C'est la règle qui rend ces diagrammes auto-explicatifs plutôt que simplement jolis.

Flux de travail — suivez dans l'ordre

1. Entretien. N'inventez pas le système.

Le plus grand échec est de générer une architecture plausible que l'utilisateur n'a jamais décrite. Demandez avant d'écrire quoi que ce soit. Utilisez l'outil de questions structurées de votre agent s'il en possède un.

Couvrez :

• Les couches. Quelles sont les 5 à 8 étapes ou groupes de premier niveau ? Ce sont les boîtes L1.
• Composants par couche. Seulement ce qui mérite d'être montré. "Postgres" est une boîte ; ses tables ne le sont pas.
• Le cycle de vie. Parcourez une requête ou un travail représentatif de bout en bout. Cela produit les arêtes.
• Qui le lit. Cadre / architecte / ingénieur est l'ensemble habituel, mais demandez — cela peut être "client / notre équipe", ou "étudiant / praticien".
• Quels sujets importent. Flux de données plus 2 à 4 parmi : coût, latence, confiance & gouvernance, modes de défaillance, propriété, sécurité. Chaque axe a besoin de ses propres arêtes ou faits.
• S'il y a un historique. v0 → aujourd'hui → planifié est l'axe le plus utile pour les travaux clients et les feuilles de route. Ignorez-le si le système n'a pas de passé significatif.
• L'argument. Que devrait croire un lecteur après l'avoir lu ? Cela devient les étapes. Si l'utilisateur n'a pas d'argument, l'explorateur n'a pas de colonne vertébrale — insistez pour en avoir un.

2. Choisissez l'axe principal

La profondeur est rarement l'axe intéressant. Demandez à quoi sert le diagramme :

Objectif	Axe principal
Enseigner son fonctionnement	Temps — étapes parcourant une requête
Pitch client / partie prenante	Époque — ce qui existe, ce qui est proposé
Revue de conception, risque	Axe — modes de défaillance, frontières de confiance
Intégration, référence	Profondeur — couches puis composants

3. Rédigez le cahier des charges

Lisez references/spec-format.md en entier avant d'en rédiger un. C'est la référence complète des nœuds, arêtes et étapes avec tous les champs optionnels.

Copiez assets/runtime/specs/llm-eval.js comme exemple fonctionnel — il utilise toutes les fonctionnalités et est une bonne forme à imiter. Écrivez le nouveau cahier dans specs/<nom>.js, puis pointez src/spec.js vers lui (une ligne — le point d'entrée et le linter le lisent tous les deux via ce fichier).

4. Construction

Copiez d'abord assets/runtime dans un répertoire de travail et construisez-y. N'exécutez pas npm install dans le dossier d'installation du skill — c'est souvent un emplacement partagé ou lié symboliquement.

cp -R <dossier-skill>/assets/runtime ./explainer
cd explainer
npm install            # nécessite le réseau ; ~20s
npm run build          # lint le cahier des charges d'abord, puis génère dist/index.html

La sortie du lint vous indique le nombre de projections. Si elle échoue, corrigez le cahier des charges — n'affaiblissez jamais le linter. Chaque règle qu'il applique existe parce qu'un vrai diagramme a été livré sans elle et était moins bon. Voir references/spec-format.md pour la signification de chaque règle.

5. Vérification visuelle — obligatoire, les deux formats

C'est l'étape la plus négligée et la plus importante. Les calculs de mise en page sont complexes et les échecs sont silencieux : une étiquette coupée, une arête traversant cinq boîtes, une caméra qui cadrait un espace vide. Ne déclarez pas terminé sans avoir regardé.

node scripts/shots.mjs        # matrice bureau → shots/

Ensuite, prenez une capture d'écran en taille téléphone (390 × 844) et ouvrez et inspectez les images. Vérifiez :

• Chaque combinaison persona × époque s'affiche sans chevauchement ni coupure.
• Chaque axe change réellement l'image — si deux axes se ressemblent, leurs ensembles d'arêtes sont erronés.
• Cadrage des étapes. Parcourez les étapes ; chacune doit cadrer son focus avec un contexte visible, ni espace vide ni le système entier.
• Étiquettes. Rien de coupé, rien positionné sur une boîte.
• Téléphone. Réorganisé en une colonne, lisible à 100 %, contrôles sans débordement.
• Console. Zéro erreur, y compris à l'intérieur d'un iframe sandboxé.

Si quelque chose semble incorrect, lisez references/troubleshooting.md avant de modifier le code de mise en page.

6. Livraison

Donnez à l'utilisateur le fichier dist/index.html construit. Dites-lui que le fichier est autonome et peut être hébergé, intégré ou ouvert hors ligne.

Claude Code / applications Claude uniquement. Envoyez le fichier avec SendUserFile. Si l'utilisateur y reviendra — la plupart des explorateurs le sont — persistez-le également avec create_artifact.

Non-négociables

• Chaque nœud a un why — une phrase expliquant pourquoi la boîte existe, pas ce qu'elle est.
• Tout ce qu'un cadre peut voir a un detail de niveau cadre dans le vocabulaire cadre.
• Au moins 6 étapes, chacune avec une véritable prose. Des étapes minces produisent un diaporama, pas un argument.
• ≤34 nœuds feuilles. Au-delà, divisez en plusieurs explorateurs plutôt que de tasser.
• Un thème par build. Les lecteurs obtiennent un bouton clair/sombre, rien de plus.

Adaptation

• Direction visuelle différente — src/themes.js en contient cinq (house, swiss, editorial, draft, shadcn). Changez THEME_ID dans src/App.jsx. Si vous ajoutez une police de caractères, vous devez définir metrics.charFactor correctement, sinon chaque étiquette sera coupée ; voir references/troubleshooting.md.
• Plus de personas / axes / époques — purement des données de spécification, aucun changement de code.
• Génération à partir du source — un script qui parcourt un dépôt et émet l'arbre DIAGRAM est une extension raisonnable, mais les champs why, detail et les étapes doivent toujours venir d'un humain.

Périmètre

Ce skill construit des figures explicatives, pas des tableaux de bord en direct, pas des outils de dessin libre, et pas des inventaires d'infrastructure. Si l'utilisateur veut un diagramme modifiable qu'il continuera à déplacer, il veut drawio à la place. S'il veut un nombre sur une page, il veut un graphique.