Communitygithub.com

Architekturdiagramm

Architekturdiagramme als Text, in den eigenen Worten des Lesers. Blackbox-Blöcke, die Schnittstelle auf jeder Naht mit ihren Operationen, Datentypen und einem Beispiel dessen, was sie überquert, ein Zustand oder mehrere im Vergleich (Ist-Zustand, Ziel, Vorschlag); zuerst Text, dann LikeC4, wenn es für andere gedacht ist. Verwende dies, wenn der Benutzer darum bittet, zu zeichnen, zu diagrammen oder zu visualisieren, wie Code oder Systeme zusammenpassen oder was eine Änderung an ihrer Struktur bewirkt.

Was ist Architekturdiagramm?

Dieses Skill ermöglicht es, Architekturdiagramme vollständig als Text zu erstellen, die sich an den vorhandenen Kenntnissen des Lesers orientieren. Es definiert einen strukturierten Prozess, beginnend mit der Erfassung der vom Leser verwendeten Begriffe (Wortliste), über die Klärung der relevanten Fragen bis hin zur detaillierten Katalogisierung von Blöcken, Schnittstellen, Datentypen und Beispielen. Die Ausgabe kann in verschiedenen Formaten erfolgen: als Chat-Diagramm (bis zu 78 Spalten), als statische HTML-Seite oder als LikeC4-Modell für interaktive Darstellungen. Das Skill ist besonders nützlich, um komplexe Änderungen oder den Unterschied zwischen mehreren Architekturzuständen (Ist, Ziel, Vorschlag) zu visualisieren und die Kommunikation zwischen Entwicklerteams zu verbessern. Es unterstützt die Plattformen Claude Code, Cursor und Codex und legt großen Wert auf präzise Schnittstellenbeschreibungen und nachvollziehbare Quellenangaben.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NG-Bullseye/architecture-diagram-skill/tree/HEAD/skills/architecture-diagram

In Ihrer bevorzugten KI fragen

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

Dokumentation

Was macht Architekturdiagramm?

Ein Diagramm ist verstanden, wenn das, was es zeigt, an dem andockt, was der Leser bereits weiß. Ein Senior-Entwickler liest es für den Top-Level-Fluss und für die Nähte. Ein Block ist eine Blackbox: sein Entwurfsmuster, seine Verantwortlichkeit, sein Besitzer und sein Inneres verborgen. Was ein Block einem anderen über eine Naht hinweg anbietet, ist seine Schnittstelle: Operationen mit Parameter- und Rückgabetypen, Fehler, die Datentypen, die die Naht mit ihren Feldern überqueren, und ein Beispiel dessen, was genau überquert und wie es aussieht. Der Transport (REST, OPC UA, ein Prozessstart) ist ein Attribut einer Schnittstelle und ersetzt sie niemals.

Lies EXAMPLE.md vor dem Zeichnen: eine Änderung, vollständig, in beiden Formen.

Schritte

1. Die Worte des Lesers

Ein neuer Begriff dockt an nichts an. Sammle vor allem anderen die Worte, die der Leser bereits hat: aus seinen Nachrichten in diesem Gespräch, aus den Dokumenten, die er geschrieben hat (Projektanweisungen, Architekturseiten, Glossare, Nomenklaturtabellen), und aus jedem Modell, mit dem das Diagramm verglichen wird. Schreibe die Wortliste: das Ding, das Wort des Lesers dafür, das Wort jedes anderen Beteiligten, der das Diagramm lesen wird, der Name im Code und das Wort, das das Diagramm verwendet.

  • Beschrifte jeden Block und jede Schnittstelle mit dem Wort des Lesers; der Codename steht daneben.
  • Wo zwei Wörter kollidieren oder ein Wort für die falsche Sache verwendet wird, wähle eines aus, begründe dies in der Wortliste und nenne das andere einmal daneben.
  • Prägen nichts. Eine Schnittstelle ohne Namen im Code wird nach ihren beiden Enden benannt, Frontend -> Backend.
  • Beginne mit dem Bild, das der Leser bereits hat, seinem eigenen Diagramm mit seinen Ebenen und Namen, und platziere das Neue darin.

Fertig, wenn jede Beschriftung in einem Diagramm aus der Wortliste stammt und jeder Begriff, der für den Leser neu ist, im Glossar neben dem bekannten Wort steht, zu dem er gehört.

2. Fragen

Schreibe die Fragen des Lesers auf, eine pro Zeile. Sie wählen die Ansichten.

FrageAnsicht
Was sind die Teile, wofür ist jedes verantwortlich, wer besitzt es, wer ruft wen?Bausteinansicht
Welche Schnittstelle verbindet zwei Teile, und was genau überquert sie?die Schnittstelle, ihre Datentypen und ein Beispiel auf jeder Naht
Was passiert in welcher Reihenfolge in dem Szenario, das wichtig ist?Laufzeitansicht: eine Sequenz
Wo läuft jeder Teil?host: auf jedem Block; eine Bereitstellungsansicht, wenn Netzwerke oder Vertrauensgrenzen die Frage sind
Was bewirkt eine Änderung, oder wie unterscheiden sich zwei Entwürfe?jeden Zustand in der gleichen Form, dann die Unterschiede

Fertig, wenn jede Ansicht ihre Frage hat und die Frage als ihre Bildunterschrift darüber steht.

3. Katalog

Fülle vor dem Zeichnen vier Listen aus den Quellen.

  • Blöcke: das Wort des Lesers und der Name im Code, Stereotyp, ein Satz Verantwortlichkeit, Besitzer, Host.
  • Schnittstellen, eine pro Naht: Anbieter, Konsumenten, jede Operation als Signatur name(param: Typ) -> Typ, Fehler, Transport.
  • Datentypen: jeder Typ, den eine Signatur benennt, mit seinen Feldern, Einheiten und Standardwerten.
  • Beispiele, eines pro Schnittstelle: eine Nachricht, wie sie überquert, Aufruf und Antwort in ihrem realen Format: eine Befehlszeile mit ihrer Ausgabe, ein JSON-Body, eine Tabellenzeile. Nimm es von einem Lauf, einer Aufzeichnung, einer Testvorrichtung oder den Daten. Ein aus dem Code zusammengestelltes Beispiel sagt dies in seiner ersten Zeile.

Jeder Eintrag trägt seinen Ursprung: eine Code-Referenz pfad:zeile oder ein Tag (unten). Ein Zustand, den jemand anders gezeichnet hat, eine Modelldatei oder eine Skizze, wird so reproduziert, wie er ist und in seinen eigenen Worten; was er auslässt, wird mit [undefined] getaggt, und was du hinzufügst, geht in einen eigenen Zustand ein.

Fertig, wenn jeder Block seinen Satz hat, jede Naht eine Schnittstelle, deren Signaturen aus dem Code kopiert oder getaggt sind, jeder Typ in einer Signatur seine Felder, jede Schnittstelle ihr Beispiel und jeder Eintrag eine Referenz oder einen Tag hat.

4. Ebene

Die Blöcke eines Zustands sind gleichrangig: Einheiten, die eigenständig bereitgestellt, besessen oder ersetzt werden, fünf bis neun davon. Dateien, Funktionen und die Schritte innerhalb eines Blocks sind sein Inneres. Ein Zoom ist ein weiteres Diagramm eine Ebene tiefer, gezeichnet für den einen Block, um den es bei der Frage geht.

Fertig, wenn kein Block eines Zustands innerhalb eines anderen liegt und jeder Zoom die Frage nennt, die ihn rechtfertigt.

5. Form

  • Chat-Form, bis zu 78 Spalten: die Bausteinansicht mit dem Namen der Schnittstelle und ihrer Hauptsignatur auf jeder Kante, dann der Katalog als Tabellen und die Beispiele als Codeblöcke. Für einen Zustand oder eine kleine Änderung.
  • Leinwand-Form, eine statische HTML-Seite mit Textdiagrammen, so breit wie nötig: neben jeder Kante ihre Schnittstelle vollständig, das Beispiel und die Datentypen mit ihren Feldern. Für mehrere Zustände oder wenn mehr als drei Nähte vollständig gezeigt werden. Die Seite wird von einem Generator-Skript erstellt, das daneben liegt; die Chat-Antwort nennt die Datei, sagt in ein paar Sätzen, was der Vergleich zeigt, und listet die offenen Entscheidungen auf.
  • C4-Form, das gleiche Modell gezeichnet mit LikeC4 auf einer Seite mit einem Tab pro Zustand, Kästchen zum Anklicken und zum Hineinzoomen. Die Textdiagramme sind sein Prototyp: kläre dort zuerst Wörter, Blöcke, Schnittstellen und Beispiele, dann rendere. Für ein Ergebnis, das andere Leute öffnen werden. Lies LIKEC4.md.

6. Zeichne

Zeichne mit den drei Dateien in diesem Ordner, damit Kästchen ausgerichtet sind und keine Zeile breiter ist als ihre Leinwand. Das Docstring jeder Datei ist seine Anleitung, und das Ausführen gibt eine Demo aus.

DateiGibt
grid.pyGrid (Kästchen mit Abteilen, Linien, Pfeilen), sequence (eine Laufzeitansicht), table
canvas.pyglance (jeder Zustand in einer Zeile), overview (Zustände nebeneinander, eine Zeile pro Ebene), panel (ein Zustand: Blöcke, Schnittstellen mit Beispielen, Datentypen)
page.pyhtml_page: die Seite um die Diagramme herum, mit den Farben und den Verknüpfungen zwischen IDs
likec4/für die C4-Form: template.c4, build.sh, die Tab-Seite index.html mit tabs.js und clicktest.py

Eine Seite geht vom Zehn-Sekunden-Bild bis ins Detail: auf einen Blick, die Wortliste, die Leseanleitung, die Übersicht, ein Panel pro Zustand, die Unterschiede pro Naht als Tabelle, die offenen Entscheidungen, Glossar, Quellen.

7. Prüfung

  • Jedes Kästchen ist ein Block des Katalogs, jede Kante eine Schnittstelle, jedes Typ-Kästchen ein Datentyp; ein Eintrag, der aus einem Diagramm ausgelassen wird, ist absichtlich ausgelassen.
  • Jede Code-Referenz ist auflösbar: die Datei existiert und die Zeile zeigt den Namen.
  • Der gleiche Block steht an der gleichen Stelle in jedem Zustand. Ein Block, der in einem Zustand fehlt, ist dort ein gepunktetes Kästchen.
  • Screenshots der gesamten Seite, Kachel für Kachel gelesen: Grenzen treffen zusammen, nichts ist abgeschnitten, Farben tragen ihre Bedeutung.
  • Die Quellen nennen, was gelesen wurde, bei welchem Commit, welche Beispiele echt sind und was nicht gelesen wurde.

Zustände

Ein Zustand ist der Code, wie er ist, ein Ziel, das jemand gezeichnet hat, oder ein Vorschlag. Vergleiche Zustände nach Position: der gleiche Block in der gleichen Spalte von glance und der gleichen Zeile von overview, damit die Lücken zweier Zustände zeigen, wo sie sich ergänzen.

Eine Naht hat eine ID aus einem Buchstaben für ihren Zustand und einer Zahl, (I4). Eine Schnittstelle oder ein Datentyp, der an einer Naht definiert ist, wird überall sonst mit dieser ID referenziert; ihre Felder werden einmal geschrieben.

Die Unterschiede sind eine Tabelle mit einer Zeile pro Naht und einer Spalte pro Zustand. Die offenen Entscheidungen sind eine Tabelle: die Frage, die Optionen, wer entscheidet.

Tags und Stereotypen

TagBedeutung
[code]existiert im Code; die Referenz steht daneben
ein Quell-Tag, z.B. [c4]von einem Quellmodell angegeben; nenne das Tag in der Leseanleitung
[proposed]hier vorgeschlagen, existiert noch nirgendwo
[new] [changed] [moved]was eine Änderung bewirkt, wenn es nur Ist und Soll gibt
[undefined]der Zustand lässt es offen
[?1]eine offene Entscheidung, aufgelistet mit ihrer Nummer

Stereotypen benennen das Entwurfsmuster, das ein Block spielt: <<ui>>, <<client>>, <<gateway>>, <<facade>>, <<service>>, <<port>>, <<adapter>>, <<repository>>, <<external>>. Verwende eines, wo der Code diese Rolle spielt; ein Block ohne Stereotyp ist besser als einer mit einem falschen. Ein Port ist eine Schnittstelle, die der Konsument besitzt und der Anbieter implementiert: <<port>> steht auf der Schnittstelle, <<adapter>> auf dem Block, der sie implementiert. Die eigenen Arten eines Quellmodells werden so zitiert, wie es sie schreibt.

Erklärungsmittel

Jedes dieser Mittel verdient seinen Platz, indem es etwas beantwortet, das der Leser sonst fragen müsste. Verwende sie sparsam.

  • Leseanleitung: ein kleines Diagramm, das zeigt, wie ein Panel gelesen wird, und die Tags.
  • Code-Referenzen: auf jeder Schnittstelle und jedem Datentyp, damit der Leser es nachschlagen kann.
  • Kurze Texte: ein Absatz über einem Zustand, der die eine Sache sagt, die darin zu sehen ist; eine Notiz in einem Schnittstellen-Kästchen, wo der Leser nach dem Warum fragen würde.
  • Glossar: die Begriffe, die die Wortliste nicht abdeckt, eine Zeile pro Begriff.
  • Farbe: nur für die Tags, die IDs und ein oder zwei key-Namen, die über alle Zustände hinweg gleich bleiben. Farbe markiert, was Zustände gemeinsam haben und wo sie sich unterscheiden; nichts anderes wird eingefärbt.

Prosa ist in der Sprache des Gesprächs. Namen aus Code und aus Quellmodellen werden wörtlich übernommen.

Verwandte Skills