CommunityBildgithub.com

C4-Diagramme

Wird ausgelöst beim Erstellen, Überprüfen, Aktualisieren oder Erklären von Softwarearchitektur-Diagrammen mit dem C4-Modell (Systemkontext L1, Container L2, Komponente L3, Code L4, Systemlandschaft, Dynamik oder Deployment), insbesondere in Markdown/Mermaid.

Was ist C4-Diagramme?

Diese Skill-Anweisung definiert, wie ein KI-Agent (z. B. für Claude Code, Cursor oder Codex) Softwarearchitekturdiagramme mit dem C4-Modell erstellen, überprüfen oder erklären soll. Es deckt die vier Abstraktionsebenen (Person, Softwaresystem, Container, Komponente, Code) sowie ergänzende Diagrammtypen (Systemlandschaft, Dynamik, Deployment) ab und legt Regeln für konsistente Notation, Elementbeschriftung und Beziehungsrichtung fest. Der Skill enthält vorgefertigte Mermaid-Vorlagen für Systemkontext-, Container-, Deployment- und Sequenzdiagramme, die sich nahtlos in Markdown-Dokumentation einfügen. Er ist plattformunabhängig und für Entwicklerteams nützlich, die Architekturentscheidungen in ADRs, PR-Beschreibungen oder technischen Dokumentationen festhalten möchten.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/fsodano/writing-skills/tree/HEAD/skills/c4-diagrams

Installed? Explore more Bild skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht C4-Diagramme?

Quelle: Das offizielle C4-Modell unter https://c4model.com/. Wende diese Regeln an, wann immer ein C4-Diagramm gezeichnet, überprüft oder erklärt wird. Lade ebenfalls die Skill writing, wenn die Ausgabe Prosa enthält (ADRs, Dokumentation, PR-Beschreibungen).

1. Zweck

C4 ist eine Reihe von „Landkarten Ihres Codes" auf vier Zoom-Ebenen: Kontext, Container, Komponenten, Code. Simon Brown hat es in Anlehnung an UML und das 4+1-Sichtmodell entwickelt, um ad-hoc-Kästchen-und-Linien-Diagramme zu ersetzen. Typische Fehler, die es behebt: fehlende Legende, gemischte Abstraktionen, unbeschriftete Pfeile, fehlende Technologie und vage Bezeichnungen wie „Geschäftslogik".

C4 ist notations- und werkzeugunabhängig. Die Abstraktionen und die unten stehenden Regeln sind entscheidend; die Formen nicht.

2. Abstraktionen

Hierarchie: Person -> Softwaresystem -> Container -> Komponente -> Code. Jede Ebene zoomt in ein Element der darüber liegenden Ebene.

AbstraktionDefinitionBeispiele
PersonEin menschlicher Benutzer, Akteur, Rolle oder Persona des SystemsKunde, Support-Mitarbeiter, Administrator
SoftwaresystemHöchste Abstraktionsebene; liefert Nutzen für Benutzer. Wird typischerweise von einem einzelnen Team entwickelt und betrieben. Es ist kein Produktbereich, begrenzter Kontext, Tribe oder SquadTicketing-Plattform, Zahlungssystem
ContainerEine eigenständig lauffähige/einsetzbare Anwendung oder Datenhaltung innerhalb eines SoftwaresystemsServer-seitige Web-App, SPA, Desktop-App, mobile App, serverlose Funktion, Batch-/Konsolen-App, Microservice-API, Datenbankschema, S3/Blob-Speicher, CDN, Dateisystem, Shell-Skript
KomponenteEine Gruppierung verwandter Funktionalität hinter einer klar definierten Schnittstelle, innerhalb eines Containers. Nicht separat einsetzbar: alle Komponenten eines Containers teilen sich einen ProzessraumOrderController, PaymentService, EmailSender
CodeKlassen, Schnittstellen, Funktionen oder DB-Tabellen innerhalb einer Komponenteclass OrderValidator, orders-Tabelle

Container-Regeln (C4 FAQ)

  • Ein C4-Container ist kein Docker. Es ist eine lauffähige/einsetzbare Anwendung oder Datenhaltung, unabhängig von der Verpackung.
  • Eine serverseitig gerenderte HTML-App ist 1 Container. Ein Server plus eine SPA oder ein mobiler Client sind 2 Container, die über eine entfernte API kommunizieren.
  • JARs, DLLs, Assemblies und Module sind keine Container. Sie organisieren Code innerhalb eines Containers.
  • Verwaltete Datendienste (S3, RDS, CDN) sind Container innerhalb Ihrer Systemgrenze, wenn Sie die Buckets oder Schemas besitzen oder kontrollieren. Sie sind keine externen Systeme.

Komponenten-Regeln

  • Eine Komponente ist kein Ordner, Paket oder JAR. Sie ist eine funktionale Gruppierung mit einer Schnittstelle.
  • Komponenten sind nicht unabhängig einsetzbar. Wenn sie separat bereitgestellt wird, ist sie ein Container.

Terminologie anpassen

Teams können sprachspezifische Namen (z. B. Modul oder Funktion in funktionalem Code) verwenden, wenn sie den Begriff im Diagramm oder in dessen Dokumentation explizit definieren. Erfinde keine zusätzlichen Abstraktionsebenen, es sei denn, jede ist streng definiert.

3. Spezielle Modellierungsmuster

Warteschlangen und Topics

  • Falsch: ein riesiger „Message Bus"-Container in der Mitte mit jedem verbundenen Dienst (Stern-Topologie). Es versteckt, wer was produziert und konsumiert.
  • Option 1 (bevorzugt): modelliere jede Warteschlange oder jedes Topic als eigenen Container (einen Nachrichtendatenspeicher). Produzenten schreiben darauf, Konsumenten lesen oder abonnieren davon.
  • Option 2: für direkte Punkt-zu-Punkt-Kopplung die Warteschlangen-Box weglassen und die Beziehung beschriften „Veröffentlicht Bestellereignisse via Warteschlange orders [AMQP]". Optional diese Linien anders gestalten als HTTP-Aufrufe (in der Legende erklären).

Beispiel: Order API --„Veröffentlicht OrderPlaced an [Kafka]"--> [(orders topic)] --„Liest OrderPlaced von [Kafka]"--> Fulfilment Worker.

Microservices (Conway’s Law Regel)

  • Ein Team besitzt das gesamte Softwaresystem: modelliere jeden Microservice als Gruppe von Containern innerhalb der Grenze dieses Systems (API-Container plus eigenes Datenbankschema-Container oder ein einzelner zustandsloser Lambda-Container).
  • Getrennte Teams besitzen jeden Dienst: befördere jeden unabhängig besessenen Dienst zu einem eigenen Softwaresystem, jedes mit eigenem Systemkontext- und Container-Diagramm. Gib den Besitz von Warteschlangen/Topics explizit über Systemgrenzen hinweg an.

4. Diagrammkatalog

Kern-Statische Ebenen

EbeneDiagrammEmpfohlenBereichZielgruppeZeigen / Weglassen
1SystemkontextJa1 SoftwaresystemTechnisch & nicht-technischPersonen und externe Systeme um das System herum. Niedrige Technologie und Protokolle weglassen
2ContainerJa1 SoftwaresystemTechnisch, BetriebWichtige Technologieauswahl und Interprozessprotokolle. Clustering, Load Balancer, Failover weglassen
3KomponenteNein: nur wenn es klaren Mehrwert bringt, idealerweise automatisiert1 ContainerArchitekten, EntwicklerKomponenten innerhalb eines Containers und ihre Interaktionen
4CodeNein: bei Bedarf in der IDE generieren1 KomponenteEntwicklerUML-Klassendiagramm oder ERD

Ergänzende Diagramme

DiagrammEmpfohlenVerwendung
SystemlandschaftJa, für Organisationen und PortfoliosUnternehmens- oder Abteilungskarte aller Systeme und Personen. Ein Kontextdiagramm ohne einzelnes Fokussystem
DynamikNein: sparsam verwendenKomplexe Laufzeit-Kollaborationen. Nummerierte Kollaborations- oder UML-Sequenzstil
DeploymentJa1 Umgebung (Produktion, Staging, Entwicklung). Verschachtelte Deployment-Knoten (physisch, VM, Docker, Kubernetes, Laufzeit) mit System-/Container-Instanzen, plus Infrastrukturknoten (DNS, Load Balancer, Firewalls)

Kompatibilität

  • arc42: Kontext & Umfang -> L1; Baustein Ebene 1 -> L2; Baustein Ebene 2 -> L3; Baustein Ebene 3 -> L4.
  • UML: ergänze C4 mit UML-Zustands-, Sequenz- und ERD-Diagrammen für Workflows, Zustandsmaschinen und Datenmodelle.

Skalierungsregel

Wenn ein Diagramm überladen wird, stopfe nicht Dutzende von Boxen in eine Leinwand. Teile auf derselben Abstraktionsebene nach Geschäftsbereich, begrenztem Kontext, Feature oder Einzeldienst-Fokus auf (der Fokusdienst plus seine eingehenden und ausgehenden Nachbarn).

5. Notationsregeln

Diagramm

  • Der Titel gibt Diagrammtyp und Bereich an: Container-Diagramm für das Checkout-System.
  • Füge immer eine Legende bei, die Formen, Farben, Ränder, Linientypen, Pfeilspitzen und Abkürzungen erklärt.
  • Halte strenge Abstraktionsreinheit: Mische niemals Abstraktionsebenen (z. B. keine Komponenten-Boxen innerhalb eines L2-Container-Diagramms) und setze niemals Protokolle oder interne Implementierungsschritte ([HTTPS], maskiertes Paket, tool_runner) in ein L1-Systemkontext-Diagramm.
  • Beim Vergleich konkurrierender oder historischer Architekturen beschrifte Grenztitel explizit (Option A (Ersetzt) vs. Option B (Aktuell)) und aktualisiere alle Diagramme im Dokument, wann immer sich Anforderungen oder Annahmen ändern.

Element

  • Name, expliziter Elementtyp (Person, Softwaresystem, Container, Komponente, Datenbank, Deployment-Knoten) und eine präzise Aufgabenbeschreibung.
  • Explizite Technologie auf jedem Container, jeder Komponente und jedem Deployment-Knoten.

Beziehung

  • Nur unidirektionale Pfeile. Niemals <-->. Wenn Daten in beide Richtungen fließen, zeige die Richtung des Initiators und beschreibe die Antwort in der Beschriftung.
  • Spezifische aktive Verb-Beschriftungen. Niemals nacktes „Verwendet". Schreibe Sendet Bestellungen an, Liest Sitzplan von.
  • Protokoll/Technologie auf Container-zu-Container-Beziehungen: [JSON/HTTPS], [SQL], [gRPC], [AMQP].

6. Mermaid in Markdown

Standardmäßig flowchart (flowchart TB oder LR), nicht Mermaids native C4Context/C4Container. Die native C4-Syntax ist experimentell und rendert oft nicht in Markdown-Viewern. Verwende sie nur, wenn der Benutzer explizit danach fragt und die Renderer-Unterstützung bestätigt.

Flowchart-Konventionen:

  • subgraph für die Systemgrenze (Container/Komponenten) oder Deployment-Knoten.
  • [(...)] für Datenbanken, Datenspeicher, Warteschlangen und Topics.
  • HTML-Beschriftungen in Anführungszeichen: "<b>Name</b><br/>«Container: Tech»<br/>Kurze Beschreibung".
  • Pfeile mit Beschriftungen in Anführungszeichen: A -->|"Aktion [Protokoll]"| B.
  • Ein classDef pro Elementtyp, konsistent angewendet.
  • Eine kompakte Legend-Subgraph (nicht verbundene Knoten, unten verankert mit unsichtbarer bottomNode ~~~ Legend-Verbindung, wenn Dagre sie oben platziert) ist erforderlich, wann immer Farben, Zylinderformen oder mehrere Linienstile verwendet werden; platziere einen Titel als Überschrift oder Title: ...-Zeile direkt über dem Codeblock.
  • Dynamische Diagramme: sequenceDiagram oder ein flowchart mit nummerierten Pfeilbeschriftungen (1. Sendet Bestellung [JSON/HTTPS]).
  • Deployment-Diagramme: verschachtelte subgraphs in einem flowchart.
  • Setze Beschriftungen, die Klammern, eckige Klammern oder Doppelpunkte enthalten, immer in Anführungszeichen.
  • Verwende niemals unescaped Semikolons (;) in sequenceDiagram- oder stateDiagram-v2-Beschriftungen (Mermaid behandelt ; als Anweisungsterminator und teilt den restlichen Text in falsche Zustände oder Parse-Fehler auf); umschließe lange Note-Blöcke in sequenceDiagram mit <br/>, sodass Text niemals am Rand des Viewports abgeschnitten wird.

Vorlage: L1 Systemkontext

Titel: Systemkontext-Diagramm für Ticketing-Plattform

flowchart TB
    kunde["<b>Kunde</b><br/>«Person»<br/>Kauft Tickets für Veranstaltungen"]
    ticketing["<b>Ticketing-Plattform</b><br/>«Softwaresystem»<br/>Ermöglicht Kunden das Durchsuchen von Veranstaltungen und den Ticketkauf"]
    zahlung["<b>Zahlungsdienstleister</b><br/>«Softwaresystem, extern»<br/>Belastet Kreditkarten"]
    email["<b>E-Mail-Dienst</b><br/>«Softwaresystem, extern»<br/>Sendet Bestätigungs-E-Mails"]

    kunde -->|"Durchsucht Veranstaltungen und kauft Tickets mit"| ticketing
    ticketing -->|"Fordert Kreditkartenbelastungen an von"| zahlung
    ticketing -->|"Sendet Bestätigungs-E-Mails mit"| email
    email -->|"Liefert Bestätigungs-E-Mails an"| kunde

    classDef person fill:#08427b,stroke:#052e56,color:#fff
    classDef system fill:#1168bd,stroke:#0b4884,color:#fff
    classDef external fill:#999,stroke:#6b6b6b,color:#fff
    class kunde person
    class ticketing system
    class zahlung,email external

    subgraph Legende
        l1["Person"]:::person
        l2["Softwaresystem (im Fokus)"]:::system
        l3["Softwaresystem (extern)"]:::external
    end

Vorlage: L2 Container (mit Warteschlangen-Container)

Titel: Container-Diagramm für Ticketing-Plattform

flowchart TB
    kunde["<b>Kunde</b><br/>«Person»<br/>Kauft Tickets für Veranstaltungen"]
    zahlung["<b>Zahlungsdienstleister</b><br/>«Softwaresystem, extern»<br/>Belastet Kreditkarten"]

    subgraph grenze["Ticketing-Plattform [Softwaresystem]"]
        spa["<b>Web-App</b><br/>«Container: React SPA»<br/>UI zum Durchsuchen von Veranstaltungen und Checkout"]
        api["<b>Bestell-API</b><br/>«Container: Java, Spring Boot»<br/>Validiert und platziert Bestellungen"]
        db[("<b>Bestell-DB</b><br/>«Container: PostgreSQL»<br/>Speichert Bestellungen und Tickets")]
        topic[("<b>orders topic</b><br/>«Container: Kafka-Topic»<br/>OrderPlaced-Ereignisse")]
        worker["<b>Fulfilment-Worker</b><br/>«Container: Python»<br/>Stellt Tickets aus und sendet E-Mails"]
    end

    kunde -->|"Durchsucht und kauft mit [HTTPS]"| spa
    spa -->|"Sendet Bestellungen an [JSON/HTTPS]"| api
    api -->|"Schreibt Bestellungen in [SQL/TCP]"| db
    api -->|"Veröffentlicht OrderPlaced an [Kafka]"| topic
    worker -->|"Liest OrderPlaced von [Kafka]"| topic
    worker -->|"Aktualisiert Ticketstatus in [SQL/TCP]"| db
    api -->|"Fordert Kreditkartenbelastungen an von [JSON/HTTPS]"| zahlung

    classDef person fill:#08427b,stroke:#052e56,color:#fff
    classDef container fill:#438dd5,stroke:#2e6295,color:#fff
    classDef store fill:#2e6da4,stroke:#1b4f72,color:#fff
    classDef external fill:#999,stroke:#6b6b6b,color:#fff
    class kunde person
    class spa,api,worker container
    class db,topic store
    class zahlung external

    subgraph Legende
        l1["Person"]:::person
        l2["Container"]:::container
        l3[("Datenspeicher / Warteschlange / Topic")]:::store
        l4["Externes System"]:::external
    end

Legendenhinweis: Pfeile zeigen vom Initiator zum Ziel. Die Beschriftung gibt die Aktion und [Protokoll] an.

Vorlage: Deployment

Titel: Deployment-Diagramm für Ticketing-Plattform (Produktion)

flowchart TB
    benutzer["<b>Kundenbrowser</b><br/>«Deployment-Knoten: Chrome»"]

    subgraph aws["AWS «Deployment-Knoten: Cloud, us-east-1»"]
        dns["<b>Route 53</b><br/>«Infrastrukturknoten: DNS»"]
        lb["<b>Load Balancer</b><br/>«Infrastrukturknoten: ALB»"]
        subgraph eks["EKS «Deployment-Knoten: Kubernetes-Cluster»"]
            subgraph pod["order-api Pod «Deployment-Knoten: Docker, x3»"]
                api["<b>Bestell-API</b><br/>«Container-Instanz: Java, Spring Boot»"]
            end
        end
        subgraph rds["RDS «Deployment-Knoten: PostgreSQL 16»"]
            db[("<b>Bestell-DB</b><br/>«Container-Instanz: PostgreSQL-Schema»")]
        end
    end

    benutzer -->|"Löst Hostnamen auf via [DNS]"| dns
    benutzer -->|"Sendet Anfragen an [HTTPS]"| lb
    lb -->|"Leitet Anfragen weiter an [HTTP]"| api
    api -->|"Liest und schreibt Bestellungen in [SQL/TCP]"| db

Füge eine Legenden-Subgraph hinzu, wenn du Farben oder Stile über die Standardeinstellungen hinaus verwendest.

Vorlage: Dynamik (Sequenz)

Titel: Dynamik-Diagramm (Sequenzstil) für Bestell-Checkout in Ticketing-Plattform

sequenceDiagram
    autonumber
    actor kunde as Kunde
    participant spa as Web-App (React SPA)
    participant api as Bestell-API (Spring Boot)
    participant zahlung as Zahlungsdienstleister
    participant db as Bestell-DB (PostgreSQL)
    participant topic as orders topic (Kafka)

    kunde->>spa: Klickt „Bestellung aufgeben"
    spa->>api: POST /orders [JSON/HTTPS]
    api->>zahlung: Belastet Karte [JSON/HTTPS]
    zahlung-->>api: Zahlung autorisiert
    api->>db: Fügt Bestellzeile ein [SQL/TCP]
    api->>topic: Veröffentlicht OrderPlaced [Kafka]
    api-->>spa: 201 Created (Bestellbestätigung)
    spa-->>kunde: Zeigt Bestellbeleg

Halte sequenceDiagram-Teilnehmer- und Nachrichtenbeschriftungen frei von unescape-slashes, Semikolons (;, die Mermaid als Anweisungsterminatoren parst) oder rohen Zeilenumbrüchen für maximale Kompatibilität mit Markdown-Viewern.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Verwandte Skills