Architecte Sirène : Compétence de diagrammes et documentation

Mermaid Architect - Compétence complète de diagrammes et documentation

Version 2.0 - Architecture hiérarchique avec orchestration intelligente

Une puissante compétence Claude Code pour créer des diagrammes Mermaid et des documents de conception en utilisant un chargement de guides à la demande, une génération de code à diagramme et des utilitaires Python.

Installation

Installation en un clic via le marché Skilz

Installez cette compétence instantanément depuis le Marché Skilz :

skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid

Installation manuelle

Clonez directement dans votre répertoire de compétences Claude Code :

# Accédez à votre répertoire de compétences
cd ~/.claude/skills

# Clonez le dépôt
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git

Vérifier l'installation

Après l'installation, vérifiez que la compétence est disponible :

# Lister les compétences installées
ls ~/.claude/skills/design-doc-mermaid

# Ou demandez à Claude Code
# "Liste mes compétences installées"

Ce que fait cette compétence

Génération intelligente de diagrammes :

• Diagrammes d'activité (flux de travail, processus, logique métier)
• Diagrammes de déploiement (infrastructure cloud, K8s, serverless)
• Diagrammes d'architecture (composants système, microservices)
• Diagrammes de séquence (flux API, interactions de services)
• Documents de conception complets avec diagrammes intégrés

Conversion code vers diagramme :

• Extraire l'architecture des applications Spring Boot
• Générer des diagrammes de déploiement à partir de fichiers de configuration
• Créer des diagrammes de séquence à partir d'appels de méthodes
• Documenter les pipelines ETL et les flux de données

Gestion des diagrammes :

• Extraire les diagrammes Mermaid de fichiers Markdown
• Valider la syntaxe des diagrammes avec mermaid-cli
• Convertir les diagrammes en images PNG/SVG
• Traiter par lots des répertoires entiers

Démarrage rapide

Créer un diagramme d'activité

Utilisateur : "Crée un diagramme d'activité pour l'enregistrement d'utilisateur avec vérification par e-mail"

La compétence va :

1. Charger references/guides/diagrams/activity-diagrams.md
2. Utiliser le modèle de motif d'enregistrement
3. Ajouter des symboles Unicode (🔐 pour la sécurité, 📧 pour l'e-mail, ✅ pour le succès)
4. Appliquer un style à haut contraste
5. Produire le diagramme Mermaid complet

Générer à partir de code

Utilisateur : "Voici mon application.yml Spring Boot - génère un diagramme de déploiement"

La compétence va :

1. Analyser la configuration (source de données, cache, sécurité)
2. Charger references/guides/diagrams/deployment-diagrams.md
3. Charger examples/spring-boot/README.md
4. Mapper la configuration aux ressources cloud
5. Générer le diagramme de déploiement avec les spécifications des ressources

Créer un document de conception

Utilisateur : "Crée un document de conception d'API pour l'API contacts"

La compétence va :

1. Charger assets/api-design-template.md
2. Charger les guides de diagrammes pertinents (séquence, ER, architecture)
3. Générer le document complet avec des diagrammes intégrés
4. Sauvegarder dans docs/design/api-contacts-v1-2025-01-13.md

Structure

Organisation hiérarchique

mermaid-architect/
├── SKILL.md                          # Orchestrateur principal avec arbre de décision
├── README.md                         # Ce fichier
├── CLAUDE.md                         # Instructions Claude Code
│
├── references/                       # Matériaux de référence
│   ├── mermaid-diagram-guide.md     # Guide général hérité
│   └── guides/                       # Guides spécialisés (chargés à la demande)
│       ├── diagrams/
│       │   ├── activity-diagrams.md      # ✅ Complet
│       │   ├── deployment-diagrams.md    # ✅ Complet
│       │   ├── architecture-diagrams.md  # ✅ Complet
│       │   └── sequence-diagrams.md      # ✅ Complet
│       ├── code-to-diagram/
│       │   └── README.md                 # ✅ Complet (guide maître)
│       ├── unicode-symbols/
│       │   └── guide.md                  # ✅ Complet (100+ symboles)
│       └── troubleshooting.md        # ✅ Complet (28 erreurs courantes)
│
├── scripts/                          # Utilitaires Python
│   ├── extract_mermaid.py           # ✅ Extraire et valider des diagrammes
│   └── mermaid_to_image.py          # ✅ Convertir en PNG/SVG
│
├── examples/                         # Modèles spécifiques au langage
│   ├── spring-boot/                 # ✅ Complet
│   ├── fastapi/                     # ✅ Complet
│   ├── react/                       # ✅ Complet
│   ├── python-etl/                  # ✅ Complet
│   ├── node-webapp/                 # ✅ Complet
│   └── java-webapp/                 # ✅ Complet
│
└── assets/                           # Modèles de documents de conception
    ├── architecture-design-template.md
    ├── api-design-template.md
    ├── feature-design-template.md
    ├── database-design-template.md
    └── system-design-template.md

Fonctionnalités clés

1. Symboles Unicode sémantiques

Chaque diagramme utilise des symboles Unicode significatifs :

graph TB
    User[👤 Client] --> Gateway[🌐 Passerelle API]
    Gateway --> Auth[🔐 Service d'authentification]
    Gateway --> API[⚙️ Service API]
    API --> DB[(💾 Base de données)]
    API --> Cache[(⚡ Redis)]
    API --> Queue[📬 File de messages]
    Queue --> Worker[⚙️ Travailleur de fond]

Catégories de symboles :

• Infrastructure : ☁️ 🌐 🔌 📡 🗄️
• Calcul : ⚙️ ⚡ 🔄 🚀 💨
• Données : 💾 📦 📊 📈 🗃️
• Messagerie : 📨 📬 📤 📥 🐰
• Sécurité : 🔐 🔑 🛡️ 🚪 👤
• Surveillance : 📝 📊 🚨 ⚠️ ✅ ❌

2. Style à haut contraste

Tous les diagrammes utilisent des couleurs accessibles à haut contraste - voir SKILL.md pour plus de détails.

3. Utilitaires Python

Extraire des diagrammes

# Lister tous les diagrammes dans un fichier
python scripts/extract_mermaid.py document.md --list-only

# Extraire vers des fichiers .mmd séparés
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# Valider tous les diagrammes
python scripts/extract_mermaid.py document.md --validate

# Remplacer les diagrammes par des références d'images (pour Confluence)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

Convertir en images

# Fichier unique
python scripts/mermaid_to_image.py diagram.mmd output.png

# Thème et taille personnalisés
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# Conversion par lots d'un répertoire
python scripts/mermaid_to_image.py diagrams/ output/ \
  --format png --recursive

# Depuis stdin
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png

Prérequis

Pour la génération de diagrammes

• Système de compétences Claude Code (automatique)
• Guides et modèles (inclus dans cette compétence)

Pour la validation et la conversion d'images

# Installer mermaid-cli globalement
npm install -g @mermaid-js/mermaid-cli

# Vérifier l'installation
mmdc --version

Pour les scripts Python

• Python 3.7+
• Aucun paquet supplémentaire requis (utilise uniquement la bibliothèque standard)

Parcours d'apprentissage

Nouveau dans les diagrammes Mermaid ?

1. Commencez par les diagrammes d'activité - Lisez references/guides/diagrams/activity-diagrams.md
2. Apprenez les symboles Unicode - Lisez references/guides/unicode-symbols/guide.md
3. Essayez un exemple - Utilisez les motifs de examples/spring-boot/
4. Validez votre travail - Exécutez python scripts/extract_mermaid.py --validate

Besoin de documenter du code existant ?

1. Identifiez le framework - Spring Boot, FastAPI, React, etc.
2. Chargez le guide d'exemple - Lisez examples/{votre-framework}/README.md
3. Faites correspondre les motifs - Trouvez des motifs de code similaires dans les exemples
4. Générez les diagrammes - Utilisez les modèles des guides
5. Validez - Utilisez les scripts de validation

Créer des documents de conception ?

1. Choisissez le type de modèle - Architecture, API, Fonctionnalité, Base de données, ou Système
2. Chargez le modèle - Lisez assets/{type}-design-template.md
3. Remplissez les sections - Remplacez les espaces réservés par le contenu réel
4. Ajoutez des diagrammes - Chargez les guides de diagrammes selon les besoins pour chaque section
5. Utilisez des symboles - Améliorez avec des symboles Unicode tout au long
6. Sauvegardez - Placez dans docs/design/ avec un horodatage

Comment fonctionne le système hiérarchique

Approche traditionnelle (inefficace)

• Charger toute la documentation de la compétence (~50 Ko)
• L'IA traite tous les modèles et exemples
• Utilisation élevée de jetons
• Temps de réponse lent

Approche hiérarchique (efficace)

1. L'utilisateur fait une demande → L'IA analyse l'intention
2. L'arbre de décision s'active → Détermine les guides nécessaires
3. Charge uniquement ce qui est nécessaire → Lit le guide spécifique (~2-5 Ko)
4. Génère la sortie → Utilise des modèles ciblés
5. Efficace en jetons → 10 fois moins de contexte nécessaire

Exemple de flux

Utilisateur : "Crée un diagramme de déploiement pour ma configuration Docker Compose"

Arbre de décision :

1. Analyser : "diagramme de déploiement" + "Docker Compose"
2. Déterminer : deployment-diagrams.md nécessaire
3. Charger : references/guides/diagrams/deployment-diagrams.md (2 Ko)
4. Trouver le motif : le modèle Docker Compose existe
5. Générer : en utilisant le modèle + les symboles Unicode
6. Sortie : Diagramme complet en <30 secondes

Jetons utilisés : ~2 000 (contre ~10 000 avec l'approche traditionnelle)

Statut d'achèvement

✅ Complet :

• Orchestrateur d'arbre de décision hiérarchique
• Guide de diagramme d'activité avec modèles
• Guide de diagramme de déploiement (AWS, GCP, K8s, serverless, Docker)
• Guide des symboles Unicode (100+ symboles)
• Script d'extraction Mermaid avec validation
• Script de conversion Mermaid en image
• Exemples Spring Boot de conversion code à diagramme
• Modèles de documents de conception (5 types)
• Système de style à haut contraste

🚧 En cours :

• Exemples FastAPI
• Exemples d'architecture de composants React
• Exemples de pipeline Python ETL

📋 Prévu :

• Guide des diagrammes d'architecture
• Guide des diagrammes de séquence
• Guide maître de conversion code à diagramme
• Exemples Node.js/Express
• Exemples d'application web Java

Contribuer

Pour ajouter un nouveau guide de type de diagramme :

1. Créez un guide dans references/guides/diagrams/{type}-diagrams.md
2. Incluez :
   • Quand utiliser
   • Syntaxe de base
   • Motifs courants (3-5 modèles)
   • Exemples de symboles Unicode
   • Meilleures pratiques
3. Mettez à jour l'arbre de décision de SKILL.md
4. Ajoutez des exemples avec des correspondances de code

Pour ajouter un nouvel exemple de langage :

1. Créez un répertoire dans examples/{framework}/
2. Ajoutez README.md avec :
   • Aperçu du framework
   • Diagramme d'architecture à partir de la structure
   • Diagramme de déploiement à partir de la configuration
   • Diagramme de séquence à partir du code
   • Diagramme d'activité à partir de la logique
3. Mettez à jour la table de conversion code à diagramme de SKILL.md

Licence

Fait partie de Claude Code Skills - Licence MIT

Compétences associées

• confluence - Télécharger des diagrammes vers Confluence
• plantuml - Format de diagramme alternatif

Liens

• Dépôt GitHub
• Liste du Marché Skilz
• Documentation officielle Mermaid

Version : 2.0.0 Mise à jour : 2025-01-13 Maintenu par : SpillwaveSolutions