Visual Explainer: Visuelle Dokumentation für Agentic Coding Workflows

Wer mit Claude Code, Cursor oder vergleichbaren Harnesses arbeitet, kennt das Muster: Du fragst nach einer Architekturübersicht, einem Diff-Review oder einem Plan-Abgleich, und der Agent antwortet mit Box-Drawing-Zeichen, Monospace-Tabellen und Pfeilen aus Bindestrichen. Für drei Kästen reicht das. Sobald Datenflüsse, Risiken und mehrere Services ins Spiel kommen, wird aus der „Skizze“ ein unleserlicher Terminalblock.

Visual Explainer ist ein Open-Source-Agent Skill, der genau dieses Problem adressiert: Statt ASCII-Kunst erzeugt er selbstständige HTML-Seiten mit echter Typografie, Dark- und Light-Theme sowie interaktiven Diagrammen, die sich im Browser öffnen lassen. Das Projekt von Nico Bailón findest Du auf GitHub. Für Teams, die KI-gestütztes Coding im Unternehmen mit steigenden Autonomiestufen betreiben, ist das weniger Spielerei als ein Baustein für verständliche Übergabe-Dokumentation.

Was Visual Explainer technisch leistet

Visual Explainer ist kein separates SaaS-Dashboard, sondern ein Skill-Paket, das Deinen Coding-Agenten anweist, visuelle Erklärgrafiken nach festen Designprinzipien zu bauen. Der Skill enthält Referenz-Templates (Architektur-Übersichten, Mermaid-Flowcharts, Datentabellen, Slide-Decks), CSS-Muster und Slash-Commands wie /generate-web-diagram, /diff-review, /plan-review oder /project-recap.

Die Ausgabe landet standardmäßig unter ~/.agent/diagrams/ als portable HTML-Datei ohne Build-Schritt. Der Skill wählt je nach Aufgabe die passende Darstellung: Mermaid für Flowcharts und Sequenzdiagramme, CSS Grid für Architektur-Overviews, HTML-Tabellen für Vergleiche und optional Chart.js für Kennzahlen. Ab vier Tabellenzeilen oder drei Spalten greift der Skill oft automatisch ein und rendert HTML statt Terminal-Wand.

Damit verschiebt sich die Rolle der Visualisierung: Sie ist nicht primär Input für den nächsten Agent-Lauf, sondern Output für Menschen, die Freigaben geben, Compliance prüfen oder nach einem Wochenende wieder in ein Projekt einsteigen.

Warum Terminal-Diagramme bei Agentic Docs scheitern

Agentic Coding erzeugt Text in hohem Tempo: READMEs, ADRs, Kommentare, Prompt-Ketten. Was fehlt, sind gemeinsame mentale Modelle, besonders wenn Product Owner, Security oder Audit mitlesen. ASCII-Diagramme skalieren schlecht: Zeilenumbrüche zerstören Ausrichtung, Labels werden abgeschnitten, und ein Diff-Review mit 15 Anforderungen gegen einen Refactor-Plan wird zur Pipe-Tabelle ohne Scanbarkeit.

Visual Explainer setzt auf Lesbarkeit wie in einem kuratierten Tech-Artikel: Sticky Inhaltsverzeichnisse für lange Seiten, Zoom und Pan bei Mermaid-SVGs, konsistente Farbpaletten über Templates. Der Trade-off ist bewusst: Du verlässt das reine Git-Markdown-Ökosystem für abgeleitete HTML-Artefakte, die Du gezielt teilen oder archivieren kannst (optional per /share-page über Vercel, sofern die Umgebung das unterstützt).

Einbindung in Claude Code und Cursor

Für Claude Code ist Visual Explainer als Marketplace-Plugin vorgesehen; Commands erscheinen namespaced, etwa /visual-explainer:diff-review. Pi, Codex CLI und OpenCode kopieren den Skill in die jeweiligen Skill-Verzeichnisse. Cursor behandelt das Projekt bewusst anders: Es gibt keine native Agent-Skills-API, sondern eine Rules-Datei (visual-explainer.mdc), die den Editor auf den kanonischen Skill-Pfad hinweist. Praktisch heißt das: Du installierst die Regel im Projekt und bittest den Agenten explizit, Visual Explainer für komplexe Erklärungen zu nutzen.

Typische Workflows in der Praxis:

• Nach einem größeren Refactor: /diff-review mit Architektur-Vorher/Nachher und Code-Hinweisen.
• Vor Sprint-Start: /plan-review gegen den Ist-Stand im Repo, inklusive Risiko-Einschätzung.
• Context Switch: /project-recap als mentales Modell-Snapshot (optional als Slide-Deck mit --slides).
• Stakeholder-Update: Architektur-Flow als Web-Diagramm statt Screenshot aus dem Terminal.

Das passt zu Context Engineering: Neue Teammitglieder und Reviewer verstehen Grenzen und Datenflüsse, bevor Autonomiestufen steigen. Visualisierungen ergänzen Tests und Traces, ersetzen sie aber nicht.

Alternativen: Mermaid, C4, Figma und mehr

Visual Explainer steht nicht allein. Die Einordnung hilft bei der Tool-Wahl:

• Mermaid oder PlantUML in Markdown: versionierbar im Repo, diffbar in PRs, ideal für Entwickler. Weniger „designed“, keine interaktive Browser-UX out of the box.
• Structurizr / C4-Model: enterprise-tauglich für langfristige Architektur-Governance, höherer Pflegeaufwand, weniger spontan aus einem Agent-Prompt.
• Figma oder FigJam: maximale gestalterische Kontrolle, manuell oder halbautomatisch; teuer in der Pflege, schlecht als Single Source of Truth neben Code.
• LLM-generierte SVGs ohne Skill-Rahmen: schnell, aber inkonsistent in Layout, Farben und Semantik.

Visual Explainer nutzt Mermaid intern, packt es aber in einen kuratierten HTML-Rahmen mit festen Patterns. Für Teams, die Agentic Pipelines ohnehin in Claude Code oder Cursor fahren, ist das der naheliegende Mittelweg zwischen „nur Markdown“ und „eigenes Design-System“.

Grenzen und Governance

• Abgeleitete Wahrheit: Source of Truth bleiben Code, Tests und versionierte Specs. Bei Drift gewinnt der Code, nicht das schönste Diagramm.
• Umgebungsabhängigkeit: Auto-Open im Browser hängt von Sandbox, Harness und Rechten ab; in eingeschränkten CI-Umgebungen bleibt nur die HTML-Datei.
• Modellqualität: Labels und Kanten können halluzinieren; /fact-check hilft beim Abgleich mit dem Repo, ersetzt aber keine Review-Disziplin.
• Kein Compliance-Nachweis allein: In regulierten Branchen sind Diagramme Review-Hilfen, nicht der alleinige Audit-Beleg.
• Theme und Sharing: OS-Theme-Wechsel erfordert bei Mermaid-SVGs ggf. Reload; /share-page setzt zusätzliche Deploy-Skills voraus.

Wer Agentic Coding skaliert, sollte Erklärformate für Menschen genauso automatisieren wie Code-Scaffolding, aber mit klarer Rolle im Governance-Modell: wer Diagramme erzeugt, wer sie freigibt, und wie oft sie nach größeren Merges neu generiert werden.

Fazit

Visual Explainer macht aus Agent-Antworten visuelle Erklärgrafiken, die Du wirklich lesen willst: HTML statt ASCII, Mermaid mit Zoom, Tabellen ohne Terminal-Wrap. Für Claude Code, Cursor und verwandte Workflows ist es ein pragmatischer Hebel, um Architektur, Diffs und Pläne für Menschen außerhalb des Terminals verständlich zu machen. Kombiniere es mit Guardrails, Tests und klarer Ownership, dann wird visuelle Dokumentation ein echter Beschleuniger für Agentic Coding, kein Ersatz für ingenieurische Sorgfalt.