vibbs/agent-skills

Architekturerklärung

Erzeugt eine eigenständige HTML-Datei pro Erklärung: Laufzeit, Topologie, Prosa, Schriftart und Styling inline, keine Netzwerkaufrufe zur Laufzeit. Überall hosten, offline öffnen, in eine Seite einbetten (<iframe>) oder an eine E-Mail anhängen.

Das Modell

Eine Topologie, viele Projektionen. Das System wird einmal in voller Tiefe erfasst. Alles andere ist ein Selektor über diesen einen Graphen – nie ein zweites Diagramm.

TOPOLOGIE   Knoten + Kanten + Metadaten          ← das Einzige, was du erstellst
──────────────────────────────────────
PERSONA    Auflösungsstrategie – Vokabular, Faltungstiefe, welche Fakten sichtbar sind
LINSE      Betroffenheits-Overlay – welche Kanten existieren, welche Fakten jeder Knoten anzeigt
EPOCHE     Vergangenheit / Gegenwart / Geplant – Präsenz und Status-Styling
BEATS      Erzählung – Kamera, Fokus, Prosa, in Reihenfolge

Zwei Regeln, die die Laufzeit durchsetzt und die du nicht umgehen darfst:

1. Farbe gehört zur Linse. Die Knotenart wird durch Form getragen – gefaltete Ecke für eine Quelle, Rücken für einen Speicher, Figur für einen menschlichen Schritt, gefaste Kante für ein Tor. Führe niemals ein Farbe-pro-Knotentyp-Schema ein; es verwandelt das Diagramm in einen Regenbogen und macht den Linsenwechsel sinnlos.
2. Ein Diagramm ohne geführte Tour ist nicht fertig. Der Linter schlägt beim Bau fehl, wenn es null Beats gibt. Diese Regel stellt sicher, dass diese Erklärungen selbsterklärend und nicht nur hübsch sind.

Arbeitsablauf – in der Reihenfolge befolgen

1. Befragen. Erfinde das System nicht.

Der größte Fehler ist die Erzeugung einer plausibel aussehenden Architektur, die der Benutzer nie beschrieben hat. Frage, bevor du etwas schreibst. Verwende das strukturierte Fragen-Werkzeug deines Agenten, falls vorhanden.

Erfasse:

• Die Ebenen. Was sind die 5–8 obersten Stufen oder Gruppen? Diese werden die L1-Kästen.
• Komponenten pro Ebene. Nur was es wert ist, gezeigt zu werden. „Postgres“ ist ein Kasten; seine Tabellen sind es nicht.
• Der Lebenszyklus. Gehe eine repräsentative Anfrage oder einen Job von Anfang bis Ende durch. Das erzeugt die Kanten.
• Wer es liest. Management / Architekt / Entwickler ist die übliche Gruppe, aber frage nach – es könnte „Kunde / unser Team“ oder „Student / Praktiker“ sein.
• Welche Belange wichtig sind. Datenfluss plus 2–4 von: Kosten, Latenz, Vertrauen und Governance, Fehlermodi, Eigentum, Sicherheit. Jede Linse braucht ihre eigenen Kanten oder Fakten.
• Ob es eine Geschichte gibt. v0 → heute → geplant ist die wertvollste Achse für Kundenarbeit und Roadmaps. Überspringe sie, wenn das System keine bedeutende Vergangenheit hat.
• Das Argument. Was soll ein Leser glauben, nachdem er es gelesen hat? Das werden die Beats. Wenn der Benutzer kein Argument hat, hat die Erklärung kein Rückgrat – dränge auf eines.

2. Wähle die primäre Achse

Tiefe ist selten die interessante Achse. Frage, wofür das Diagramm ist:

Zweck	Primäre Achse
Lehren, wie es funktioniert	Zeit – Beats, die eine Anfrage durchlaufen
Präsentation vor Kunden / Stakeholdern	Epoche – was existiert, was vorgeschlagen wird
Design-Review, Risiko	Linse – Fehlermodi, Vertrauensgrenzen
Onboarding, Referenz	Tiefe – Ebenen dann Komponenten

3. Schreibe die Spezifikation

Lies references/spec-format.md vollständig, bevor du eine schreibst. Es enthält die vollständige Knoten-/Kanten-/Beat-Referenz mit allen optionalen Feldern.

Kopiere assets/runtime/specs/llm-eval.js als funktionierendes Beispiel – es übt jedes Feature aus und hat eine gute Form, die man nachahmen kann. Schreibe die neue Spezifikation in specs/<name>.js und setze dann src/spec.js darauf (eine Zeile – der Einstiegspunkt und der Linter lesen beide darüber).

4. Bauen

Kopiere zuerst assets/runtime in ein Arbeitsverzeichnis und baue dort. Führe npm install nicht im installierten Skill-Ordner aus – dies ist oft ein gemeinsamer oder symbolisch verlinkter Installationsort.

cp -R <skill-verzeichnis>/assets/runtime ./explainer
cd explainer
npm install            # benötigt Netzwerk; ~20s
npm run build          # lintet die Spezifikation zuerst, gibt dann dist/index.html aus

Die Lint-Ausgabe teilt dir die Projektionsanzahl mit. Wenn sie fehlschlägt, repariere die Spezifikation – schwäche nie den Linter. Jede Regel, die er durchsetzt, existiert, weil ein echtes Diagramm ohne sie ausgeliefert wurde und schlechter war. Siehe references/spec-format.md für die Bedeutung jeder Regel.

5. Visuell überprüfen – zwingend, beide Formfaktoren

Dies ist der am häufigsten übersprungene Schritt und der folgenreichste. Die Layout-Berechnungen sind nicht trivial und Fehler sind still: eine abgeschnittene Bezeichnung, eine Kante, die durch fünf Kästen verläuft, eine Kamera, die leeren Raum einfängt. Erkläre nicht für fertig, ohne hinzusehen.

node scripts/shots.mjs        # Desktop-Matrix → shots/

Mache dann selbst einen Screenshot in Telefongröße (390×844) und öffne und inspiziere die Bilder. Prüfe:

• Jede Persona × Epoche-Kombination wird ohne Überlappung oder Abschneiden gerendert.
• Jede Linse verändert tatsächlich das Bild – wenn zwei Linsen identisch aussehen, sind ihre Kantensets falsch.
• Beat-Framing. Gehe die Beats Schritt für Schritt durch; jeder sollte seinen Fokus mit sichtbarem Kontext rahmen, nicht mit leerem Raum und nicht dem gesamten System.
• Bezeichnungen. Nichts abgeschnitten, nichts auf einem Kasten sitzend.
• Telefon. Auf eine Spalte umgebrochen, bei 100% lesbar, Bedienelemente nicht überlaufend.
• Konsole. Null Fehler, auch in einem sandboxed iframe.

Wenn etwas falsch aussieht, lies references/troubleshooting.md, bevor du Layout-Code änderst.

6. Ausliefern

Gib dem Benutzer die erstellte dist/index.html. Sage ihm, dass die Datei eigenständig ist und gehostet, eingebettet oder offline geöffnet werden kann.

Nur Claude Code / Claude Apps. Sende die Datei mit SendUserFile. Wenn es etwas ist, das der Benutzer wieder aufrufen wird – die meisten Erklärungen sind es –, persistiere sie auch mit create_artifact.

Nicht verhandelbar

• Jeder Knoten hat ein why – ein Satz, warum der Kasten überhaupt existiert, nicht was er ist.
• Alles, was eine Führungskraft sehen kann, hat auf Führungsebene detail in Management-Vokabular.
• Mindestens 6 Beats, jeder mit echter Prosa. Dünne Beats erzeugen eine Diashow, kein Argument.
• ≤34 Blattknoten. Darüber hinaus in mehrere Erklärungen aufteilen, anstatt zu überfüllen.
• Ein Thema pro Build. Leser erhalten einen Hell/Dunkel-Umschalter, sonst nichts.

Anpassen

• Andere visuelle Richtung – src/themes.js enthält fünf (house, swiss, editorial, draft, shadcn). Ändere THEME_ID in src/App.jsx. Wenn du eine Schriftart hinzufügst, musst du metrics.charFactor korrekt setzen, sonst wird jede Bezeichnung abgeschnitten; siehe references/troubleshooting.md.
• Mehr Personas / Linsen / Epochen – reine Spezifikationsdaten, keine Codeänderungen.
• Aus Quellcode generieren – ein Skript, das ein Repo durchläuft und den DIAGRAM-Baum ausgibt, ist eine vernünftige Erweiterung, aber das why, detail und die Beats müssen immer noch von einem Menschen kommen.

Umfang

Dies erstellt erklärende Abbildungen, kein Live-Dashboard, kein Freihand-Zeichenwerkzeug und keine Infrastruktur-Inventare. Wenn der Benutzer ein bearbeitbares Diagramm möchte, das er immer wieder verschieben kann, will er drawio stattdessen. Wenn er eine einzelne Zahl auf einer Seite möchte, will er ein Diagramm.