Diagrammes Mermaid : comment nous avons construit une prise en charge native de l’IA pour les ingénieurs

En bref

Je suis Hannah Knight, responsable de produit pour Structured Diagrams with Mermaid chez Miro. Je vais vous expliquer ce que sont les diagrammes Mermaid, pourquoi nous avons intégré un support natif de Mermaid dans Miro, et comment l’utiliser concrètement aujourd’hui. Cette fonctionnalité est en bêta publique, je vais vous expliquer ce qui fonctionne maintenant et ce qui est encore en cours de développement. Voir en pratique : un seul prompt génère la carte complète d’un incident directement à partir du codebase, en affichant chaque service et chaque appel entre eux. L’équipe colore le diagramme pour indiquer ce qui a dysfonctionné, commente directement le diagramme pour élaborer une correction, puis le renvoie à un agent, qui rédige l’ensemble de la décision sous forme de pull request sur GitHub. 

Qu’est-ce que Mermaid ?

Qu’est‑ce qu’un diagramme Mermaid ? C’est un diagramme décrit entièrement par du texte. Vous écrivez quelque chose comme A --> B, et vous obtenez deux blocs, A et B, reliés par une flèche. C’est tout.

Les ingénieurs utilisent Mermaid depuis des années pour conserver les diagrammes dans leur codebase, juste à côté du code qu’ils décrivent. Mais Mermaid a pris un nouvel essor récemment pour une raison simple : les grands modèles de langage sont très efficaces pour l’écrire. Demandez à un agent de codage IA de schématiser votre système, et il y a de fortes chances qu’il vous renvoie la syntaxe Mermaid, car c’est le format qu’il a appris à bien rédiger.

Cette combinaison, un code que peuvent lire et écrire aussi bien les humains que l’IA, est exactement la raison pour laquelle nous avons intégré la prise en charge native de Mermaid directement dans Miro.

Le problème récurrent

Avant que nous développions cette fonctionnalité, Mermaid revenait sans cesse dans les appels clients et les entretiens utilisateurs, sans aucune sollicitation. Les ingénieurs avaient déjà compris que les diagrammes générés par l’IA étaient meilleurs lorsqu’ils demandaient du Mermaid plutôt qu’une image. Les diagrammes ont toujours été essentiels pour permettre aux ingénieurs d’expliquer simplement des systèmes complexes, et l’association de Mermaid et de l’IA leur a permis de générer des diagrammes de haute qualité plus rapidement qu’ils ne pourraient jamais le faire manuellement.

Cette distinction « diagramme comme code, pas seulement une image » est importante pour deux raisons. Si un diagramme n’existe que sous forme d’image, un ingénieur ne peut pas en suivre les modifications comme il suit les modifications de son code. Et il y a une seconde raison, plus technique : les grands modèles de langage comprennent bien mieux le texte linéaire que les images en deux dimensions, en raison de la façon dont ils traitent les entrées. Lorsqu’un diagramme est du code, un agent IA peut apporter une modification précise et ciblée au lieu de régénérer l’ensemble depuis zéro.

J’ai vu des ingénieurs confrontés exactement à ce scénario avec les anciens outils. Leur codebase change, et le diagramme devient obsolète. Ils ouvrent alors Miro, déplacent manuellement les formes et les boîtes pour refléter les changements réels, puis documentent le résultat. Cela peut leur prendre des heures.

Désormais, il suffit qu’ils demandent à un agent de codage comme Claude Code de générer un diagramme de la codebase, et celui‑ci s’affiche automatiquement et de manière élégante sur un tableau Miro. Si le code évolue rapidement, ils peuvent même configurer une skill planifiée pour tenir le tableau à jour régulièrement.

Pourquoi nous avons conçu les Diagrammes structurés avec Mermaid

Structured Diagrams with Mermaid intègre le diagram-as-code directement dans Miro. Vous écrivez ou générez la syntaxe Mermaid, elle s’affiche sous forme de formes Miro réelles, vous et votre équipe itérez dessus ensemble, et vous l’exportez ensuite vers du code lorsque vous avez terminé. Il s’agit d’un aller‑retour complet : un agent peut générer un diagramme via le serveur MCP de Miro, votre équipe collabore visuellement dessus, et un autre agent peut le relire via MCP pour maintenir votre codebase synchronisée.

Mermaid est la source de vérité. Lorsque vous modifiez un diagramme visuellement dans Miro, le code Mermaid sous‑jacent se met à jour en conséquence, de sorte que le code et le diagramme ne divergent jamais. Nous aurions pu rompre ce lien et considérer le diagramme comme un objet distinct une fois placé sur le tableau, comme le font certains autres outils. Nous avons choisi de ne pas le faire. Conserver Mermaid comme source de vérité permet à un agent IA de toujours comprendre votre diagramme et d’y apporter des modifications précises, et vous pouvez l’exporter vers GitHub, VS Code, Obsidian ou tout autre outil prenant en charge Mermaid.

Cela remplace entièrement l’ancienne application Mermaid du Marketplace de Miro. Cette application créait des formes en mode libre, pas du vrai Mermaid, et elle ne permettait pas l’aller‑retour : un agent pouvait générer un diagramme, mais il ne pouvait pas relire vos modifications. Diagrammes structurés avec Mermaid offre les deux.

Que se passe-t-il lorsque vous générez un diagramme

Concrètement, voici à quoi ressemble l’aller‑retour : collez la syntaxe Mermaid sur un tableau Miro, et le diagramme s’affiche immédiatement. Demandez à un agent IA, comme Claude Code, Claude Cowork, Codex ou Cursor, de générer un diagramme, et il utilise le serveur MCP de Miro pour écrire cette même syntaxe Mermaid directement sur votre tableau. Dans les deux cas, le diagramme s’affiche rendu et prêt à l’emploi, pas comme un croquis que vous devez retoucher.

Quels types de diagrammes s’affichent comme des formes Miro natives

Actuellement, quatre types de diagrammes s’affichent comme des formes Miro natives :

• Diagrammes de flux représentent les workflows, les arbres de décision et les processus, afin que vous puissiez voir précisément où un processus risque de se bloquer.
• Diagrammes de séquence montrent comment des systèmes ou des composants communiquent entre eux au fil du temps, ce qui est utile pour la communication entre microservices ou pour l’ordre des appels d’API.
• Diagrammes de classes visualisent les objets, leurs attributs et les relations entre eux.
• Diagrammes entité-relation (ER) représentent le schéma de votre base de données et les relations entre les tables.

Nous avons beaucoup investi pour que ces quatre types soient prêts à l’emploi, afin que vous obteniez un rendu prêt à présenter sans travail de mise en forme supplémentaire.

Mermaid prend en charge de nombreux autres types de diagrammes, notamment les diagrammes de Gantt et les diagrammes C4 pour l’architecture système. Ceux-ci sont actuellement rendus au format SVG par Mermaid.js plutôt que comme formes Miro natives. Vous pouvez néanmoins les ajouter à votre tableau, les modifier avec l’IA et les exporter, mais ils ne sont pas prêts pour une présentation et vous ne pouvez pas cliquer dessus pour les modifier visuellement comme vous pouvez le faire avec un diagramme de flux. Si vous évaluez cette fonctionnalité pour votre équipe, cette distinction est importante : sachez quels diagrammes bénéficieront aujourd’hui d’une édition native complète et lesquels vous utiliserez principalement pour les consulter et les exporter.

Commencer avec les diagrammes Mermaid dans Miro

Voici comment ça se passe en pratique :

1. Ouvrez la Creation bar, sélectionnez formats, puis Diagram, et cliquez sur "Build with code."
2. Collez le code Mermaid que vous avez déjà, choisissez un modèle, ou envoyez à votre agent un prompt pour générer un diagramme directement depuis votre codebase, cartographiant chaque service et chaque appel entre eux en quelques secondes.
3. Observez-le s’afficher sous forme de formes Miro natives, avec une mise en page automatique et épurée, afin d’éviter d’espacer manuellement les boîtes pour empêcher le croisement des lignes.
4. Passez en mode immersif pour modifier le diagramme. Vous pouvez sélectionner une forme, une ligne ou un badge de texte et la modifier directement, changer la direction de la mise en page (de haut en bas, de gauche à droite, etc.), ou ajuster l’espacement, de serré à large. Vous pouvez aussi ouvrir le panneau de code et modifier directement la syntaxe Mermaid, ou coller le lien du diagramme dans votre outil d’IA et demander à votre agent d’effectuer la modification pour vous. Quelle que soit la manière dont vous modifiez le diagramme, le code Mermaid et le diagramme restent synchronisés.
5. Donnez du sens au diagramme. Codez-le par couleur pour indiquer un état ou un incident, ou demandez à votre agent d’apporter la modification. Lorsqu’un agent modifie un diagramme, il peut même ajouter une légende indiquant ce qu’il a ajouté, supprimé ou modifié.
6. Invitez votre équipe à commenter directement le diagramme, dans le contexte de l’état actuel et des corrections ou modifications que vous proposez, plutôt que d’ouvrir une discussion séparée ailleurs.
7. Bouclez la boucle. Copiez la syntaxe Mermaid dans votre codebase, exportez le diagramme au format image (JPG, SVG ou PDF), partagez un lien du mode immersif avec des collaborateurs, ou laissez votre agent lire le diagramme et les commentaires de votre équipe via MCP et rédiger un document, par exemple un document de décision d’architecture prêt à être ouvert en tant que pull request.

Si vous connaissez déjà la syntaxe Mermaid, vous pouvez commencer à l’écrire tout de suite. Si vous n’avez jamais utilisé Mermaid auparavant, commencez par un modèle, modifiez visuellement les formes, ou décrivez simplement ce que vous voulez à votre agent IA et laissez‑le écrire la syntaxe pour vous. Une chose à savoir si vous avez un forfait Enterprise : un admin d’entreprise doit activer Miro MCP avant que quiconque de votre équipe puisse y connecter un outil d’IA.

Évitez cette erreur fréquente au départ

Des utilisateurs essaient de déplacer les formes librement, comme sur un canevas Miro classique, mais cela ne fonctionne pas ainsi. Nous appelons ces diagrammes « structurés » parce qu’ils reposent sur du code, et l’un des vrais avantages est que Miro les organise automatiquement. Si vous avez vraiment besoin de plus de formes ou d’un déplacement totalement libre, vous pouvez basculer un diagramme en édition en mode libre, mais sachez que c’est irréversible : une fois basculé, le diagramme n’est plus synchronisé avec le code Mermaid, et ni vous ni votre agent ne pouvez plus le modifier via MCP. Si vous n’êtes pas encore sûr, commencez par explorer les nombreuses fonctionnalités que nous proposons pour Structured Diagrams, ou travaillez sur une copie en mode libre plutôt que de convertir votre original.

Il n’existe pas non plus une seule « bonne » manière d’écrire Mermaid. Ne cherchez pas à trop réfléchir pour votre premier diagramme. Commencez par en créer une version, puis itérez : que ce soit vous qui la modifiez, un coéquipier qui l’affine, ou un agent qui la reprend.

Comportement à grande échelle

Nous prenons en charge les fichiers Mermaid jusqu’à 30 000 lignes de code, et nous avons testé des diagrammes comportant 500 nœuds ou plus dans des diagrammes de flux complexes sans aucune baisse des performances. Il n’y a pas de limite stricte au nombre de diagrammes Mermaid que vous pouvez avoir sur un tableau.

Où cela s’intègre à vos outils existants

Si un autre outil exporte la syntaxe Mermaid, vous pouvez la coller directement sur un tableau Miro. Vous souhaitez conserver un diagramme sous contrôle de version ? Exportez-le au format Markdown ou .mmd et enregistrez‑le dans votre dépôt, de la même manière que vous versionnez tout autre code. Vous pouvez même configurer un workflow où votre agent génère le diagramme, l’exporte, l’enregistre dans le dépôt et le met à jour au fur et à mesure que votre code évolue, le tout sans intervention manuelle de votre part.

Exemples et inspiration pour les diagrammes Mermaid

Tout cela n’est pas utile en soi, voici où les équipes l’appliquent concrètement :

Onboarding d’architecture

Au lieu de remettre à un nouvel ingénieur une page wiki obsolète depuis le dernier trimestre, demandez à votre agent de schématiser l’architecture actuelle des microservices directement depuis la codebase. Le schéma reflétera ce qui est réellement en production, et non ce qui l’était il y a six mois.

Examiner une modification de schéma

Avant une migration majeure, générez un diagramme ER du nouveau schéma afin que les examinateurs puissent percevoir la modification structurelle d’un coup d’œil, au lieu de la démêler dans un diff textuel.

Analyser un incident du début à la fin

Schématisez les services affectés directement depuis la codebase dès qu’un incident survient. Mettez-les en couleur ou annotez-les pour indiquer ce qui a échoué et pourquoi, puis invitez votre équipe à commenter directement le diagramme pour élaborer une correction. Une fois l’équipe d’accord, demandez à votre agent de lire le diagramme et les commentaires via MCP et de rédiger la décision sous forme de document, par exemple un Architecture Decision Record (ADR) prêt à être soumis en tant que pull request.

Documenter une API

Générez un diagramme de séquence de vos appels de service, conservez la source Mermaid dans votre dépôt et laissez votre agent le mettre à jour à chaque modification de l’API, au lieu de le redessiner manuellement à chaque version.

Cartographiez le modèle de données avant de le construire

Esquissez dès le départ un diagramme ER ou de classes, tant que le modèle de données n’est encore qu’une idée. Il est bien moins coûteux de détecter une mauvaise relation sur un diagramme qu’après avoir écrit la migration.

Réviser une Pull Request

Lors de la révision d’une Pull Request, demandez à votre agent de générer un diagramme Mermaid montrant l’état du code avant et après pour faciliter la prise en main. Avec l’IA, les ingénieurs examinent beaucoup plus de modifications de code qu’auparavant, et les visualisations peuvent accélérer ce processus.

Bonnes pratiques pour les diagrammes Mermaid

Laissez l’IA rédiger le premier jet

Si votre agent dispose déjà du contexte, qu’il s’agisse de votre codebase, d’un ensemble d’exigences ou d’un document existant, demandez‑lui de générer le diagramme plutôt que d’écrire la syntaxe Mermaid à la main. Affinez ensuite.

Adaptez vos attentes à ce qui est modifiable visuellement aujourd’hui

Les flowcharts sont, pour l’instant, le type de diagramme le plus flexible. Les diagrammes de séquence, de classes et ER s’affichent nativement et sont lisibles, mais considérez‑les comme basés d’abord sur du code tant que l’édition visuelle ne leur est pas encore déployée.

Centralisez les retours sur le diagramme, ne les dispersez pas

Commentez directement le diagramme au lieu d’ouvrir une discussion parallèle dans Slack ou par e-mail. Ainsi, la décision et le contexte restent au même endroit, et votre agent peut relire l’ensemble de la conversation via MCP.

Versionnez vos diagrammes comme vous versionnez votre code

Exportez le diagramme au format Markdown ou .mmd et commitez‑le. C’est une petite habitude, et cela garantit que l’historique de vos diagrammes est aussi fiable que celui de votre code.

Signalez‑nous si quelque chose manque

Si vous rencontrez un problème de rendu, ou si vous avez besoin d’un type de diagramme qui n’est pas encore modifiable visuellement, signalez‑le. Cette bêta existe précisément pour que ce type de retours puisse encore influencer ce qui sera livré ensuite.

Soyons clairs au sujet de la bêta

Il s’agit d’une bêta publique, et je tiens à être transparent sur l’état actuel des choses. L’édition visuelle ne fonctionne pour l’instant que pour les diagrammes de flux ; les diagrammes de séquence, de classes et ER s’affichent comme des formes natives mais ne prennent pas encore en charge le même workflow visuel d’édition par clic. L’édition visuelle et le panneau de code ne fonctionnent que dans le mode immersif, pas en vue scindée sur le canevas. Le glisser‑déposer pour les formes est encore en cours de développement, donc pour l’instant vous ajoutez des formes avec le bouton + d’une forme existante, ou en copiant, collant et dupliquant.

Voici ce qui m’enthousiasme vraiment pour la suite :

• Générer et itérer des diagrammes Mermaid directement via les partenaires d’IA et les flux, y compris lire les diagrammes libres au format Mermaid directement depuis le tableau
• Permettre l’édition visuelle des diagrammes ER et de classes
• Exporter au format Mermaid natif
• Faciliter la détection et la correction des erreurs dans votre code, et améliorer globalement l’expérience d’écriture de code
• Rendre les commentaires et annotations lisibles par les agents
• Étendre la prise en charge des mises en page, y compris les couloirs

La vue d’ensemble

Cela dépasse les diagrammes. C’est un exemple concret d’agents d’IA et de personnes travaillant sur le même canevas, au lieu d’un agent qui vous remet un résultat statique puis s’éclipse. Comme Mermaid reste portable, toute modification que vous effectuez dans Miro est quelque chose que votre agent peut comprendre et exploiter. Il peut reprendre le diagramme que vous avez déjà affiné et y apporter une modification ciblée, plutôt que de tout régénérer et de perdre les détails que vous aviez ajoutés.

Dans un an, je veux que chaque ingénieur utilise Miro comme un véritable élément de son workflow pour partager, collaborer et affiner l’architecture technique, et pas seulement comme un endroit où stocker une image créée une fois.

Si vous ne retenez qu’une chose : une fois que vous aurez généré un diagramme directement à partir de votre codebase en quelques secondes, vous ne voudrez plus le dessiner à la main.

Prêt à l’essayer ? Ouvrez la barre de création, sélectionnez Diagrammes et générez aujourd’hui votre premier diagramme Mermaid.