Automatiser ses schémas techniques avec les LLM : workflow pro avec Mermaid, PlantUML et CI/CD

Créer un schéma technique à la main prend du temps. Entre le choix des symboles, la cohérence visuelle et la mise à jour, la tâche devient vite fastidieuse. Mais grâce aux LLM (Large Language Models) comme ChatGPT, Claude ou Gemini, il est désormais possible d’automatiser la génération et la maintenance des schémas techniques, en s’appuyant sur des outils open source comme Mermaid ou PlantUML.

Cet article s’adresse aux développeurs, architectes et rédacteurs techniques qui souhaitent mettre en place un workflow professionnel CI/CD pour documenter leurs projets avec des diagrammes à jour, versionnés et validés automatiquement.

---

De la génération manuelle à l’automatisation complète

Dans l’article précédent — Créer des schémas techniques avec l’IA : le guide simple pour débuter — nous avons vu comment produire un diagramme à partir d’un prompt. Ici, nous passons à la phase d’industrialisation : automatiser la génération, le rendu et la mise à jour continue de ces schémas.

L’objectif est simple :

Transformer vos diagrammes en artefacts versionnés, intégrés à votre documentation technique ou à votre pipeline de déploiement.

---

1. Pipeline de génération automatique

Un workflow professionnel repose sur cinq étapes principales :

1. Entrée – description textuelle, code source ou documentation Markdown.
2. Traitement IA – le LLM génère un code Mermaid, PlantUML ou XML Draw.io.
3. Rendu – conversion automatique en SVG ou PNG via CLI.
4. Vérification – contrôle syntaxique et validation logique.
5. Publication – intégration continue (Docs-as-Code, GitHub Pages, Notion…).

Ce modèle est recommandé par DiagrammingAI.com et Eraser.io, deux références du diagram-as-code. Il garantit la reproductibilité et la cohérence des schémas, même dans des environnements collaboratifs complexes.

---

2. Exemple concret : pipeline Mermaid dans un environnement CI/CD

Prenons un exemple concret avec Mermaid CLI, qui permet de transformer automatiquement le code Mermaid en image vectorielle.

Étape 1 — Génération IA

Un LLM reçoit un prompt structuré :

“Crée un diagramme Mermaid illustrant le flux CI/CD d’un projet web : Commit → Build → Test → Deploy.”

Le modèle produit un fichier *ci_cd.mmd`.

Étape 2 — Conversion automatique

Dans votre pipeline (GitHub Actions, GitLab CI ou Jenkins), ajoutez :

# Conversion automatique du code Mermaid en SVG
npx @mermaid-js/mermaid-cli -i ci_cd.mmd -o ci_cd.svg

Étape 3 — Intégration dans la doc

Le SVG est ajouté à la documentation Markdown, commit automatique, puis publication. Chaque modification du fichier source ou du prompt déclenche une mise à jour instantanée du schéma.

C’est le principe même du diagram-as-code, popularisé par ByteByteGo : le diagramme devient un composant du code source.

---

3. Intégration dans vos outils de documentation

L’automatisation ne se limite pas à la ligne de commande. Les principaux outils de documentation supportent déjà Mermaid ou PlantUML nativement.

Obsidian, Notion, GitHub

Il suffit d’insérer le code dans un bloc :

```mermaid
graph TD
A[Dev] --> B[CI/CD Pipeline]
B --> C[Production]
```

Mermaid se charge du rendu automatiquement, idéal pour les notes de conception ou les documentations internes.

VS Code

Installez l’extension Markdown Preview Mermaid Support ou PlantUML Preview. Vous pouvez même créer une commande personnalisée :

{
  "command": "openai.generateDiagram",
  "args": {
    "promptFile": "diagram.prompt",
    "outputFile": "diagram.mmd"
  }
}

Cette configuration permet à ChatGPT ou Claude d’écrire le diagramme directement dans votre dépôt.

Docs-as-Code (MkDocs, Docusaurus)

Ces frameworks prennent en charge Mermaid. Un simple plugin suffit pour rendre automatiquement tous les schémas à la génération du site. C’est la méthode utilisée par AddJam.com pour documenter ses architectures logicielles.

---

4. Comparatif technique : Mermaid, PlantUML et D2Lang

Format	Syntaxe	Points forts	Limites	Cas d’usage
Mermaid	Markdown-like	Simple, intuitif, compatible web	Personnalisation limitée	Docs, blogs, systèmes agiles
PlantUML	Langage UML dédié	Très complet, précis, flexible	Courbe d’apprentissage plus raide	Architectures complexes, ingénierie
D2Lang	YAML-like	Syntaxe rapide, CLI intégrée	Moins supporté par les LLM	Schémas simples et infra légères

Selon PlantUML.cn (2024), Mermaid est plus adapté à la documentation agile, tandis que PlantUML reste la norme en entreprise pour les architectures logicielles et systèmes distribués.

---

5. Contrôle qualité et validation

Même les meilleurs LLM peuvent produire du code incorrect. Un système de validation est donc essentiel.

Vérification syntaxique

• Mermaid linter : npm install -g mermaid-linter
• PlantUML CLI : vérifie la validité du bloc UML avant rendu.

Vérification sémantique

Des scripts Python ou Node.js peuvent contrôler la présence d’éléments clés :

if "graph" not in diagram_code:
    raise ValueError("Le diagramme est incomplet")

Revue humaine

La validation finale doit toujours passer par un humain : un architecte ou développeur qui connaît la logique métier.

Cette étape garantit que le schéma correspond à la réalité du système documenté.

---

6. Sécurité et confidentialité

Automatiser ne signifie pas exposer ses données sensibles. Quelques précautions :

• N’envoyez jamais de secrets (tokens, IP, credentials) dans les prompts.
• Utilisez des modèles IA locaux (via Ollama ou LM Studio) pour les schémas confidentiels.
• Préférez les outils open source : Mermaid CLI ou PlantUML local.
• Évitez les API SaaS pour les diagrammes d’infrastructure.

DataScienceCentral rappelle qu’un schéma d’architecture est souvent aussi sensible que le code source lui-même.

---

7. Automatiser la documentation avec CI/CD

L’automatisation s’intègre naturellement à un pipeline CI/CD. Voici un exemple avec Makefile et Mermaid CLI :

# Conversion automatique des .mmd en .svg
%.svg: %.mmd
	npx @mermaid-js/mermaid-cli -i $< -o $@

Chaque commit sur un fichier .mmd régénère automatiquement le .svg. L’image est ensuite publiée dans la documentation HTML (MkDocs, Docusaurus, GitHub Pages…).

C’est la philosophie du Docs-as-Code : la documentation devient un livrable versionné, au même titre que le code.

---

8. Génération hybride : IA + édition manuelle

Pour les diagrammes complexes (systèmes multi-cloud, réseaux neuronaux, pipelines IA), une approche hybride reste la plus efficace.

1. Étape IA : génération du squelette via LLM (Mermaid/PlantUML).
2. Étape manuelle : retouche dans Draw.io, Figma ou Eraser.io.
3. Étape finale : export en SVG/PDF et intégration dans la doc.

Cette méthode combine productivité IA et contrôle humain. Selon Lucidchart AI (2025), les équipes hybrides économisent en moyenne 40 % de temps sur la documentation d’architecture.

---

9. Conversion ASCII → SVG pour environnements légers

Certains environnements (README GitHub, terminaux CI) nécessitent des schémas textuels. Deux outils majeurs :

• aasvg (GitHub officiel) aasvg < schema.txt > schema.svg → Conversion ASCII en SVG clair et vectoriel.
• Svgbob (éditeur en ligne) → Rendu direct depuis le navigateur.

Ces solutions sont idéales pour les documentations minimalistes, en ligne ou hors connexion.

---

10. Bonnes pratiques professionnelles

Pour un workflow de documentation fiable :

• Conservez toujours vos prompts dans le dépôt (diagram.prompt).
• Versionnez le code généré (diagram.mmd, diagram.puml).
• Automatisez le rendu via CI/CD.
• Vérifiez la logique avant la publication.
• Exportez uniquement en SVG pour un rendu net et scalable.

Mermaid AI Blog (2025) souligne qu’un bon diagramme automatisé repose sur trois piliers : prompt clair, pipeline stable, revue humaine.

---

11. Génération à partir du code source

Les LLM savent désormais analyser du code pour en déduire automatiquement un schéma.

Exemples :

• Classes Python/Java → diagramme UML de classes.
• Fichier Docker Compose → diagramme d’architecture cloud.
• Logs CI/CD → diagramme de flux d’exécution.

Des outils comme Microsoft GenAIScript et PlantUML AI explorent cette approche, où la documentation se régénère automatiquement à chaque build.

---

12. Limites actuelles

Malgré les progrès, l’automatisation complète n’est pas encore parfaite :

• Le positionnement automatique peut être imprécis.
• Certains LLM produisent du code Mermaid invalide.
• Les diagrammes trop denses nécessitent toujours un ajustement manuel.
• La cohérence visuelle varie d’un modèle à l’autre.

Des recherches en diagram reasoning et LLM visual planning visent à améliorer ces points.

---

13. Synthèse du workflow optimal

Étape	Action	Outil recommandé
1	Rédiger un prompt structuré	ChatGPT / Claude
2	Générer le code diagramme (Mermaid, PlantUML)	LLM
3	Vérifier et itérer	LLM + revue humaine
4	Rendre le diagramme (SVG/PDF)	Mermaid CLI / PlantUML CLI
5	Intégrer dans la doc	Markdown / Docs-as-Code
6	Versionner et automatiser	Git / CI/CD

Ce pipeline garantit rapidité, fiabilité et cohérence sur l’ensemble du cycle documentaire.

---

14. Conclusion

Les LLM ne sont plus seulement des assistants rédactionnels : ce sont de véritables agents de documentation technique. En les associant à des outils comme Mermaid et PlantUML, vous pouvez générer, valider et maintenir automatiquement vos schémas techniques sans perdre en qualité ni en traçabilité.

Cette approche s’inscrit dans la philosophie Docs-as-Code : la documentation devient un artefact de production, versionné et automatisé au même titre que le code source.

Pour les curieux ou les équipes qui découvrent ce concept, commencez par le guide de base : 👉 Créer des schémas techniques avec l’IA : le guide simple pour débuter avec ChatGPT et Claude

---