---
name: system-visualisieren
description: Erstellt und pflegt kleine verständliche Diagramme mit C4 oder einer passenden UML-Teilmenge direkt in Markdown. Verwenden, wenn Systemgrenzen, fachliche Beziehungen, Zustände, Abläufe, Interaktionen oder Deployments in Text allein schwer verständlich sind.
---

# System visualisieren

Wähle das kleinste Diagramm, das eine konkrete Frage besser beantwortet als
Text. Das Diagramm ergänzt die Aussage; es ersetzt weder Fachtext noch Tests.

## Fachliche Grundlage

- [OMG – Unified Modeling Language](https://www.omg.org/spec/UML/) ist die
  formale Grundlage für UML.
- [Simon Brown – C4 Model](https://c4model.com/diagrams) beschreibt
  Systemkontext, Container, Komponenten sowie unterstützende Diagramme und
  empfiehlt, nur wertschöpfende Ebenen zu erstellen.
- Mermaid dokumentiert textbasierte
  [Klassen-](https://mermaid.js.org/syntax/classDiagram.html),
  [Sequenz-](https://mermaid.js.org/syntax/sequenceDiagram.html) und
  [Zustandsdiagramme](https://mermaid.js.org/syntax/stateDiagram.html).

## Darstellung wählen

| Frage | Darstellung |
| --- | --- |
| Wer nutzt das System und welche Fremdsysteme gibt es? | C4-Systemkontext |
| Welche Anwendungen und Datenspeicher gehören dazu? | C4-Container |
| Welche Bounded Contexts hängen zusammen? | Context Map |
| Welche fachlichen Konzepte und Beziehungen sind wichtig? | UML-Klassendiagramm |
| Welche Zustände und Übergänge gibt es? | UML-Zustandsdiagramm |
| Wie arbeiten Beteiligte oder Systeme in einem Slice zusammen? | UML-Sequenzdiagramm |
| Wie läuft das System in einer Umgebung? | Deploymentdiagramm |

Erstelle kein Komponentendiagramm oder detailliertes Codeklassendiagramm, wenn
Systemkontext, Container oder Text ausreichen.

## Vorgehen

1. Benenne Frage, Zielgruppe und Geltungsbereich des Diagramms.
2. Lies die Fachsprache aus `docs/domain/DOMAIN.md` und vorhandene
   Architekturentscheidungen. Erfinde keine Elemente oder Beziehungen.
3. Wähle genau eine Abstraktionsebene und möglichst eine Diagrammart.
4. Speichere Mermaid direkt bei der zugehörigen Aussage:
   - Domain und Context Map in `docs/domain/DOMAIN.md`,
   - Systemkontext und Container in `docs/architecture/ARCHITECTURE.md`,
   - entscheidungsspezifische Diagramme im ADR,
   - kurzlebige Slice-Abläufe im Task.
   Muss `docs/architecture/ARCHITECTURE.md` erstmals angelegt werden, verwende
   `docs/templates/architecture-template.md` und fülle nur benötigte Ansichten.
5. Verwende fachliche Bezeichnungen, beschriftete Beziehungen und bei
   unbekannter Notation eine kleine Legende.
6. Zeige nur Elemente, die für die Frage nötig sind. Mische keine fachlichen
   Konzepte, Laufzeiteinheiten und Codeklassen in derselben Ansicht.
7. Kennzeichne bei sicherheits- oder datenschutzrelevanten Ansichten Datenflüsse
   und Vertrauensgrenzen nach `sicherheit-und-datenschutz-pruefen`.
8. Rendere und prüfe das Diagramm, sofern ein vorhandenes Werkzeug dies
   ermöglicht. Fehlt dafür ein Werkzeug, befolge `werkzeuge-verwalten` vor
   einer Installation.
9. Lass Fachdiagramme fachlich bestätigen. Halte Status und Bestätigungsdatum
   im umgebenden Markdown fest.
10. Aktualisiere oder entferne ein Diagramm zusammen mit der Aussage, die es
   erklärt. Ein veraltetes Diagramm ist schlechter als keines.

## Zusammenarbeit mit KI

Die KI darf aus Text und Gesprächen einen Entwurf erzeugen, Inkonsistenzen
benennen und fehlende Fälle erfragen. Sie darf fachliche Beziehungen,
Systemgrenzen oder Bestätigungen nicht selbst erfinden. Text und Diagramm
werden gemeinsam geprüft; Tests bleiben der ausführbare Nachweis des
implementierten Verhaltens.

## Fertig, wenn

- das Diagramm eine benannte Frage für seine Zielgruppe beantwortet.
- Begriffe mit Fachtext, Code und anderen Diagrammen übereinstimmen.
- Beziehungen beschriftet und Abstraktionsebenen nicht vermischt sind.
- der Quelltext im Repository lesbar, renderbar und gemeinsam mit der Aussage
  versioniert ist.