Mermaid-Diagramme: Wie wir KI-native Diagramme für Entwickler entwickelt haben

Diese

Ich bin Hannah Knight, Produktmanager für Structured Diagrams with Mermaid bei Miro. Ich zeige dir, was Mermaid‑Diagramme sind, warum wir native Mermaid‑Unterstützung in Miro eingebaut haben und wie du sie heute praktisch nutzt. Diese Funktion ist in öffentlicher Betaversion, deshalb sage ich dir offen, was jetzt schon funktioniert und was noch kommt. In Aktion erleben: Ein Prompt bildet einen kompletten Incident direkt aus der Codebase ab und zeigt jeden Service sowie jeden Aufruf dazwischen. Das Team markiert Bereiche farblich, um zu zeigen, was ausgefallen ist, kommentiert direkt im Diagramm, um eine Behebung auszuarbeiten, und übergibt das dann an einen KI‑Agenten, der die gesamte Entscheidung als Pull Request in GitHub entwirft. 

Was Mermaid genau ist

Also, was ist ein Mermaid-Diagramm? Es ist ein Diagramm, das vollständig als Text beschrieben wird. Du schreibst etwas wie A --> B und bekommst zwei Kästen, A und B, die durch einen Pfeil verbunden sind. Das war's. Du kannst es nutzen, um fast jede Art von Diagramm zu beschreiben: Flussdiagramme, Sequenzdiagramme, Klassendiagramme, Entity-Relationship-Diagramme und mehr.

Entwickler nutzen Mermaid schon seit Jahren, um Diagramme in ihrer Codebase zu halten, direkt neben dem Code, den sie beschreiben. In letzter Zeit hat es aus einem einfachen Grund neues Leben bekommen: Große Sprachmodelle sind sehr gut darin, Mermaid zu schreiben. Bittest du einen KI‑Agenten, ein Diagramm deines Systems zu erstellen, ist die Chance groß, dass du Mermaid-Syntax zurückbekommst, weil es das Format ist, das sie besonders gut beherrschen.

Genau diese Kombination – Code, den sowohl Menschen als auch KI lesen und schreiben können – ist der Grund, warum wir Mermaid direkt in Miro integriert haben.

Das Problem, das immer wieder genannt wurde

Bevor wir das gebaut haben, tauchte Mermaid immer wieder in Kundengesprächen und Nutzerinterviews auf, völlig unaufgefordert. Ingenieure hatten bereits herausgefunden, dass KI-erstellte Diagramme besser wurden, wenn sie Mermaid statt eines Bildes anforderten. Diagramme sind schon immer zentral dafür gewesen, wie Ingenieure komplexe Systeme einfach erklären, und Mermaid zusammen mit KI ermöglichte es ihnen, hochwertige Diagramme schneller zu erstellen, als sie es jemals von Hand hätten tun können.

Die Unterscheidung „Diagramm als Code, nicht nur als Bild“ ist aus zwei Gründen wichtig. Existiert ein Diagramm nur als Bild, kann ein Entwickler Änderungen daran nicht so nachverfolgen wie Änderungen am Code. Und es gibt einen zweiten, technischeren Grund: große Sprachmodelle verstehen eindimensionalen Text deutlich besser als zweidimensionale Bilder, weil sie Eingaben auf diese Weise verarbeiten. Wenn ein Diagramm Code ist, kann ein KI-Agent es gezielt bearbeiten, statt alles von Grund auf neu zu generieren.

Ich habe mit den alten Tools genau dieses Szenario bei Entwicklern beobachtet. Die Codebase ändert sich und das Diagramm ist veraltet. Also öffnen sie Miro, ziehen Formen und Kästen manuell hin und her, um die tatsächlichen Änderungen abzubilden, und dokumentieren das. Das kann Stunden in Anspruch nehmen.

Jetzt können sie einfach einen KI-Agenten wie Claude Code bitten, ein Diagramm der Codebase zu erstellen, und es wird automatisch schön auf einem Miro-Board dargestellt.

Warum wir Strukturierte Diagramme mit Mermaid entwickelt haben

Structured Diagrams with Mermaid bringt Diagramm als Code direkt in Miro. Du schreibst oder erstellst Mermaid‑Syntax; sie wird als echte Miro‑Formen dargestellt, ihr arbeitet gemeinsam daran, und am Ende exportiert ihr alles wieder als Code. Es ist ein kompletter Roundtrip: Ein KI‑Agent kann ein Diagramm über den MCP‑Server von Miro erstellen, dein Team arbeitet visuell daran zusammen, und ein anderer KI‑Agent kann es über MCP wieder auslesen, um deine Codebase synchron zu halten.

Mermaid ist die Quelle der Wahrheit. Wenn du ein Diagramm visuell in Miro bearbeitest, aktualisiert sich der zugrunde liegende Mermaid‑Code entsprechend, sodass Code und Diagramm nie auseinanderdriften. Wir hätten diese Verbindung auflösen und das Diagramm nach dem Einfügen auf dem Board als eigenständiges Objekt behandeln können, wie es andere Tools tun. Wir haben uns dagegen entschieden. Mermaid als Quelle der Wahrheit zu belassen bedeutet, dass ein KI‑Agent dein Diagramm jederzeit verstehen und präzise bearbeiten kann, und du es nach GitHub, VS Code, Obsidian oder an jeden anderen Ort exportieren kannst, der Mermaid unterstützt.

Das ersetzt vollständig die alte Mermaid-App aus dem Miro Marketplace. Diese App erzeugte freiformige Formen, kein echtes Mermaid, und konnte keinen Round‑Trip durchführen: Ein KI‑Agent konnte ein Diagramm erstellen, aber deine Änderungen nicht wieder auslesen. Strukturierte Diagramme mit Mermaid vereint beides.

Was passiert, wenn du ein Diagramm erstellst

Kurz gesagt sieht der Round‑Trip so aus: Füge Mermaid‑Syntax auf ein Miro-Board ein, und das Diagramm wird sofort gerendert. Wenn du einen KI‑Agenten wie Claude Code, Claude Cowork, Codex oder Cursor bittest, ein Diagramm zu erstellen, nutzt er den MCP-Server von Miro, um dieselbe Mermaid‑Syntax direkt auf dein Board zu schreiben. In beiden Fällen erscheint das Diagramm fertig gerendert und einsatzbereit – nicht als grobe Skizze, die du erst aufräumen musst.

Welche Diagrammtypen als native Miro-Formen gerendert werden

Derzeit werden vier Diagrammtypen als native Miro-Formen gerendert:

• Flussdiagramme bilden Workflows, Entscheidungsbäume und Prozesse ab, damit du genau sehen kannst, wo ein Prozess ins Stocken geraten könnte.
• Sequenzdiagramme zeigen, wie Systeme oder Komponenten im Zeitverlauf miteinander kommunizieren, was praktisch für die Kommunikation zwischen Microservices oder für die Reihenfolge von API-Aufrufen ist.
• Klassendiagramme visualisieren Objekte, ihre Attribute und ihre Beziehungen zueinander.
• Entitäts-Beziehungsdiagramme (ER) bilden dein Datenbankschema und die Beziehungen zwischen Tabellen ab.

Wir haben viel Arbeit investiert, damit diese vier Diagrammtypen sofort gut aussehen und ohne zusätzlichen Formatierungsaufwand präsentationsreif sind.

Mermaid unterstützt außerdem viele weitere Diagrammtypen, darunter Gantt-Diagramme und C4-Diagramme für die Systemarchitektur. Sie werden derzeit als Mermaid.js-SVGs gerendert und nicht als native Miro-Formen. Du kannst sie trotzdem zu deinem Board hinzufügen, mit KI bearbeiten und exportieren, aber sie wirken nicht präsentationsreif, und du kannst sie nicht so anklicken und visuell bearbeiten wie beim Flussdiagramm. Wenn du das für dein Team evaluierst, ist dieser Unterschied wichtig: du solltest wissen, welche Diagramme du heute vollständig nativ bearbeiten kannst und welche du hauptsächlich nur ansehen und exportieren wirst.

Erste Schritte mit Mermaid-Diagrammen in Miro

So sieht das in der Praxis aus:

1. Öffne die Creation bar, wähle Formate, dann Diagramm, und klicke auf „Build with code“.
2. Füge vorhandenen Mermaid‑Code ein, wähle eine Vorlage oder sende deinem KI‑Agenten einen Prompt, damit er in Sekunden ein Diagramm direkt aus deiner Codebase erstellt und alle Services sowie die Aufrufe zwischen ihnen abbildet.
3. Sieh zu, wie es als native Miro‑Formen gerendert wird, mit einem sauberen, automatischen Layout, sodass du nicht manuell Boxen positionieren musst, damit sich Linien nicht kreuzen.
4. Öffne das Diagramm im Fokusmodus, um es zu bearbeiten. Du kannst eine Form, eine Linie oder ein Label/Text auswählen und direkt anpassen, die Layout‑Richtung ändern (von oben nach unten, von links nach rechts usw.) oder den Abstand von eng bis weit einstellen. Du kannst auch das Code‑Feld öffnen und die Mermaid‑Syntax direkt bearbeiten oder den Link des Diagramms in dein KI‑Tool einfügen und deinen KI‑Agenten bitten, die Änderung für dich vorzunehmen. Egal wie du es bearbeitest: Mermaid‑Code und Diagramm bleiben synchron.
5. Füge dem Diagramm mehr Aussagekraft hinzu. Markiere es farblich, um einen Status oder einen Vorfall anzuzeigen, oder bitte deinen KI-Agenten, die Änderung vorzunehmen. Wenn ein KI-Agent ein Diagramm bearbeitet, kann er sogar eine Legende hinzufügen, die zeigt, was er hinzugefügt, entfernt oder geändert hat.
6. Lade dein Team ein, das Diagramm direkt im Kontext des aktuellen Zustands und der von dir vorgeschlagenen Korrektur oder Änderung zu kommentieren, statt irgendwo anders einen separaten Thread zu starten.
7. Schließe den Kreis. Kopiere die Mermaid-Syntax zurück in deine Codebase, exportiere das Diagramm als Bild (JPG, SVG oder PDF), teile einen Fokusmodus-Link mit Mitwirkenden, oder lass deinen KI-Agenten das Diagramm und die Kommentare deines Teams über MCP auslesen und ein Dokument entwerfen, zum Beispiel einen Eintrag zur Architekturentscheidung, der bereit ist, als Pull Request geöffnet zu werden.

Wenn du die Mermaid-Syntax schon kennst, kannst du sofort loslegen. Wenn du noch nie mit Mermaid gearbeitet hast, fang mit einer Vorlage an, bearbeite Formen visuell oder beschreibe einfach deinem KI-Agenten, was du willst, und lass ihn die Syntax für dich schreiben. Eine Sache, die du wissen solltest, wenn du im Enterprise-Preisplan bist: Ein Unternehmens-Admin muss Miro MCP aktivieren, bevor sich jemand in deinem Team ein KI-Tool damit verbinden kann.

Ein Fehler, den ich am Anfang oft sehe

Manche versuchen, Formen frei zu verschieben, so wie du es auf einem normalen Miro-Canvas tun würdest, doch so funktioniert das nicht. Wir nennen diese „strukturierte“ Diagramme, weil sie durch Code gestützt werden, und einer der echten Vorteile ist, dass Miro sie automatisch anordnet. Wenn du wirklich mehr Formen oder vollständige freie Bewegung brauchst, kannst du ein Diagramm in die freie Bearbeitung umschalten, aber beachte: das ist eine Einbahnstraße – sobald du umgeschaltet hast, wird dieses Diagramm nicht mehr mit dem Mermaid‑Code synchronisiert, und weder du noch dein KI‑Agent können es über MCP bearbeiten. Wenn du dir noch unsicher bist, erkunde zuerst die vielen Funktionen, die wir für Structured Diagrams anbieten, oder arbeite mit einer Kopie in der freien Bearbeitung weiter, statt das Original umzuwandeln.

Es gibt auch nicht den einen „richtigen“ Weg, Mermaid zu schreiben. Denk beim ersten Diagramm nicht zu lange nach. Fang einfach an, und iteriere dann – egal, ob du es bearbeitest, ein Teamkollege es verfeinert oder ein KI‑Agent es wieder aufnimmt.

Wie das im großen Maßstab funktioniert

Wir unterstützen Mermaid-Dateien mit bis zu 30.000 Codezeilen und haben Diagramme mit 500 oder mehr Knoten in komplexen Flussdiagrammen getestet, ohne Leistungseinbußen. Es gibt kein festes Limit, wie viele Mermaid-Diagramme du auf einem Board haben kannst.

Wie das zu deinen bestehenden Tools passt

Wenn ein anderes Tool Mermaid‑Syntax exportiert, kannst du sie direkt auf ein Miro-Board einfügen. Willst du ein Diagramm unter Versionskontrolle halten? Exportiere es als Markdown‑ oder .mmd‑Datei und committe sie in dein Repository, genauso wie du auch anderen Code versionierst. Du kannst sogar einen Workflow einrichten, in dem dein KI‑Agent das Diagramm erstellt, exportiert, commitet und beim Ändern deines Codes automatisch wieder aktualisiert – ganz ohne manuelles Eingreifen.

Beispiele und Inspiration für Mermaid-Diagramme

Das ist abstrakt wenig hilfreich  – hier Beispiele, wofür Teams es in der Praxis nutzen:

Architektur-Onboarding

Statt einem neuen Entwickler eine seit dem letzten Quartal veraltete Wiki-Seite zu geben, lass deinen KI-Agenten die aktuelle Microservices‑Architektur direkt aus der Codebase erstellen – so bekommt er ein Diagramm, das zeigt, was tatsächlich läuft, und nicht den Stand von vor sechs Monaten.

Schemaänderung prüfen

Erstelle vor einer großen Migration ein ER‑Diagramm des neuen Schemas, damit Reviewer die strukturelle Änderung auf einen Blick sehen können, statt sie aus einem Textdiff zu entwirren.

Incident‑Review – von Anfang bis Ende

Erstelle sofort nach Auftreten eines Fehlers aus der Codebase ein Diagramm der betroffenen Services. Färbe es ein oder versehe es mit Anmerkungen, um zu zeigen, was ausgefallen ist und warum, und lade dann dein Team ein, direkt am Diagramm zu kommentieren, um die Lösung zu erarbeiten. Wenn das Team zustimmt, bitte deinen KI-Agenten, Diagramm und Kommentare über MCP auszulesen und die Entscheidung als Dokument zu entwerfen, zum Beispiel als Architecture Decision Record, das bereit ist, als Pull Request geöffnet zu werden.

Eine API dokumentieren

Erstelle ein Sequenzdiagramm deiner Service‑Aufrufe, lege den Mermaid‑Quelltext in deinem Repo ab und lass deinen KI‑Agenten es bei jeder API‑Änderung aktualisieren, statt es bei jedem Release manuell neu zu zeichnen.

Datenmodell vor der Implementierung abbilden

Skizziere früh ein ER‑ oder Klassendiagramm, solange dein Datenmodell noch nur eine Idee ist. Es ist deutlich günstiger, eine fehlerhafte Beziehung im Diagramm zu entdecken, als erst nach der Migration.

Pull Request prüfen

Wenn du einen Pull Request prüfst, bitte deinen KI‑Agenten, ein Mermaid‑Diagramm zu erstellen, das den Codezustand vor und nach den Änderungen zeigt, damit du dich schnell ins Thema einarbeitest. Mit KI prüfen Entwickler heute deutlich mehr Codeänderungen als je zuvor, und Visualisierungen können diesen Prozess beschleunigen.

Best Practices für Mermaid‑Diagramme

Lass deinen KI‑Agenten den ersten Entwurf erstellen

Wenn dein KI-Agent bereits den Kontext hat, sei es deine Codebase, eine Reihe von Anforderungen oder ein vorhandenes Dokument, bitte ihn, das Diagramm zu erstellen, statt Mermaid‑Syntax von Hand zu schreiben. Verfeinere es anschließend.

Erwarte nur, was heute visuell bearbeitbar ist

Flowcharts sind derzeit der flexibelste Diagrammtyp. Sequenz-, Klassen- und ER‑Diagramme werden nativ gerendert und sehen gut aus, aber behandle sie als codebasiert, bis die visuelle Bearbeitung auch für sie verfügbar ist.

Sammle Feedback am Diagramm, nicht verstreut

Kommentiere direkt am Diagramm, anstatt in Slack oder per E‑Mail einen Nebenthread zu starten. So bleiben Entscheidung und Kontext an einem Ort, und dein KI‑Agent kann die gesamte Unterhaltung über MCP zurücklesen.

Versioniere deine Diagramme wie deinen Code

Exportiere sie als Markdown oder .mmd und committe sie. Das ist eine kleine Gewohnheit und sorgt dafür, dass der Verlauf deiner Diagramme genauso verlässlich ist wie der Verlauf deines Codes.

Sag uns Bescheid, wenn etwas fehlt

Wenn du auf ein Darstellungsproblem stößt oder einen Diagrammtyp brauchst, der noch nicht visuell bearbeitbar ist, sag es uns. Diese Betaversion ist genau dafür da, damit Feedback wie dieses noch beeinflussen kann, was als Nächstes ausgeliefert wird.

Kurz und ehrlich zur Betaversion

Das ist eine öffentliche Betaversion, und ich möchte offen darlegen, wo wir stehen. Visuelles Bearbeiten funktioniert derzeit nur für Flussdiagramme; Sequenz-, Klassen- und ER-Diagramme werden zwar als native Formen dargestellt, unterstützen aber noch nicht denselben Klick‑zum‑Bearbeiten‑Workflow. Visuelles Bearbeiten und das Code‑Panel funktionieren nur im Fokusmodus, nicht in der geteilten Ansicht auf dem Canvas. Und Drag‑and‑drop für Formen ist noch in Arbeit, sodass du vorerst Formen über die Plus‑Schaltfläche an einer bestehenden Form hinzufügen oder per kopieren, einfügen und duplizieren arbeiten kannst.

Worauf ich mich als Nächstes wirklich freue:

• Mermaid-Diagramme direkt über KI-Kollegen und Flow generieren und iterieren, einschließlich des Einlesens freier Diagramme als Mermaid direkt vom Board
• Visuelle Bearbeitung für ER- und Klassendiagramme
• Als native Mermaid-Datei exportieren
• Einfachere Wege, Fehler in deinem Code zu finden und zu beheben, sowie ein insgesamt komfortableres Coderlebnis
• Kommentare und Anmerkungen, die KI-Agenten tatsächlich lesen können
• Breitere Layout-Unterstützung, einschließlich Swimlanes

Das große Ganze

Das gilt über Diagramme hinaus. Es ist ein echtes Beispiel dafür, wie KI-Agenten und Personen gemeinsam auf demselben Canvas arbeiten, statt dass ein KI-Agent dir nur ein statisches Ergebnis liefert und dann verschwindet. Da Mermaid portabel bleibt, kann jede Bearbeitung, die du in Miro vornimmst, von deinem KI-Agenten verstanden und weiterverarbeitet werden. Er kann das Diagramm, das du bereits verfeinert hast, gezielt anpassen, statt das Ganze neu zu erstellen und dabei deine hinzugefügten Details zu verlieren.

In einem Jahr möchte ich, dass jeder Ingenieur Miro als echten Teil seines Workflows zum Teilen, zur Zusammenarbeit und zur Verfeinerung technischer Architektur nutzt, und nicht nur als Ort, um ein einmal erstelltes Bild zu speichern.

Wenn du nur eins daraus mitnimmst: Sobald du innerhalb von Sekunden ein Diagramm direkt aus deiner Codebase erstellt hast, willst du nicht mehr zurück zum Zeichnen von Hand.

Bist du bereit, es auszuprobieren? Öffne die Creation bar, wähle Diagramme und erstelle heute dein erstes Mermaid-Diagramm.