c4-plan

---

name: c4-plan description: Visuelle Architekturebene (C4-Stil) in einem navigierbaren Diagramm mit schrittweisen Abläufen. Zwei Anwendungsfälle. (1) Implementierungsplan: Nachdem ein Plan existiert und vor der Ausführung, damit der Mensch sehen kann, wie der Plan das Bestehende beeinflusst, Fragen stellen und Änderungen anfordern kann, bevor er im Chat zustimmt. (2) Das System dokumentieren, wie es heute ist, basierend auf dem Code, für das Onboarding oder zum Verständnis eines Repos. Aktiviere, wenn der Benutzer nach "Architektur des Plans anzeigen", "Struktur validieren", "C4 generieren", "Plan-Diagramm", "Architektur dokumentieren", "Erkläre, wie das System funktioniert", "Systemkarte", "Repo-Onboarding" fragt oder einen Link des C4 Plan Viewers einfügt (enthält "#v1.").

C4 Plan

Der Mensch versteht Struktur und Grenzen des Plans; der KI-Agent führt nach der Zustimmung im Chat aus. Diese Skill ersetzt nicht den Plan: Sie generiert die visuelle Ebene und ein Briefing für die Ausführung.

Sie dokumentiert auch das System, wie es heute ist (kind: system): das gleiche Diagramm und die gleichen Abläufe, ohne Status, Schritte oder Genehmigung. Siehe Abschnitt 5.

Der Chat ist die Quelle der Wahrheit. Der Viewer zeigt nur den Plan: Der Mensch bearbeitet dort nichts. Fragen und Änderungswünsche kommen als Kommentare (oder eingefügt in den Chat), du antwortest im Chat, und jede Änderung erfolgt über das YAML.

Du schreibst niemals HTML oder erstellst manuell eine URL. Du schreibst ein YAML; das Skript validiert, generiert den Link und generiert das Briefing.

Plan ─► arch.yaml ─► encode ─► Link ─► Mensch schaut und kommentiert ─► du passt das YAML an ─► ok im Chat ─► Briefing ─► Ausführung

Skript: python3 <dir-der-skill>/scripts/arch_url.py (nur stdlib + PyYAML; jsonschema optional).

1. Generiere die arch.yaml aus dem Plan

Speichere sie neben dem Plan als <plan-name>.arch.yaml. Schema: schema/arch.v1.json. Vollständiges Beispiel: examples/pix.arch.yaml.

Regeln:

• Es ist die Architektur des Plans, nicht des gesamten Systems. Füge das ein, was der Plan erstellt, ändert oder entfernt, plus den minimalen Kontext zum Verständnis (wer ruft auf, wer wird aufgerufen). Modelliere nicht das gesamte System.
• status: new / changed / removed / unchanged (Standard). Kontextelemente bleiben unchanged.
• C4-Hierarchie: person, system, external auf der obersten Ebene; container, database, queue innerhalb von system (oder auf der obersten Ebene); component innerhalb von container, database (Tabelle, Migration) oder queue (Ereignis); code nur innerhalb von component.
• Alles, was der Plan erstellt oder ändert, öffnet sich bis zum Code. Jedes system, container, database, queue und component mit status new/changed hat children, das bis code hinabreicht (die Validierung warnt, wenn etwas fehlt). Was sich nicht ändert, bleibt geschlossen: es ist Kontext.
• Ebene 4 (code): die Dateien, Klassen, Module oder Funktionen, die der Plan erstellt oder ändert, mit ausgefülltem path. Eine Datei, die bereits existiert und geändert wird, erhält status: changed. Liste auf, was sich ändert, nicht den gesamten Code des Komponenten (2 bis 4 pro Komponente reichen meist).
• Beziehungen verbinden die spezifischsten Elemente (Code → Code, wenn vorhanden). Der Viewer aggregiert für die höheren Ebenen.
• steps: einer pro Schritt des Plans, gleiche Reihenfolge und Überschrift. touches = Elemente, die der Schritt erstellt oder ändert.
• flows: wie das System funktioniert, nachdem der Plan umgesetzt ist (die steps sagen die Bau-Reihenfolge; die flows sagen die Ausführungs-Reihenfolge). 1 bis 3 Abläufe: der Hauptpfad und der wichtigste Fehlerpfad (z. B. "Kunde bezahlt mit PIX", "QR-Code läuft ab"). Jeder hops[] ist {from, to, label} und muss einer bestehenden Beziehung folgen, entweder in ihrer Richtung oder in der Gegenrichtung für eine Antwort. Verwende die spezifischsten Elemente (Code) und schreibe label als das, was passiert ("speichert die txid vor dem Aufruf des PSP"), nicht den Namen der Beziehung. Der Viewer zoomt von selbst auf die Ebene jedes Sprungs.
• constraints: was die Implementierung beachten muss, wie überprüfbare Regeln ("Idempotenz pro txid", "additive Migration, ohne Tabellensperre"), keine Beschreibungen. Platziere sie dort, wo eine Entscheidung wichtig ist: Verträge, Grenzen zu externen Systemen, Sicherheit, Daten, Migrationen, zentrale Geschäftsregel. Was keine Einschränkung hat, liegt in deinem Ermessen bei der Ausführung.
• Wenn ein Vertrag im Repo existiert, verweise in relations[].contract darauf.

2. Validieren und den Link ausliefern

python3 scripts/arch_url.py encode <plan>.arch.yaml

• Fehler: Korrigiere das YAML und führe es erneut aus. Liefere keinen Link, der die Validierung nicht besteht.
• Warnungen: Korrigiere, wenn sinnvoll (z. B. etwas Neues, das sich nicht bis zum Code öffnet).
• Liefere den Link an den Menschen in einer Zeile aus, mit einer kurzen Zusammenfassung der Änderungen durch den Plan (z. B. "3 neue Elemente, 2 geänderte"). Sage ihm, dass er C (oder Kommentieren) drücken, auf die Karten klicken und Fragen oder Änderungswünsche äußern kann, und dass die Genehmigung hier im Chat erfolgt.

Viewer: Der encode generiert Links zur veröffentlichten Version, https://gustavorana25.github.io/c4-model-skill/ (statisch; der Plan geht in den #hash und erreicht den Server nicht). $C4PLAN_VIEWER_URL ändert den Host, und --local verwendet den lokalen Build viewer/dist/index.html (nur zum Testen von Änderungen am Viewer selbst).

2b. Wenn du einen eingebetteten Browser hast: Höre auf die Seite

Wenn du über Browser-Tools verfügst (das Browser-Panel von Claude Code, der Browser von Cursor, Claude in Chrome), öffne den Link dort anstatt ihn nur auszuliefern, und höre auf die Seite, während der Mensch den Plan betrachtet.

Der Chat ist die Quelle der Wahrheit. Die Seite ist nur eine Abkürzung: Der Mensch zeigt auf eine oder mehrere Karten und kommentiert, und du antwortest im Chat, niemals auf der Seite. Das Einzige, was du auf der Seite änderst, ist der Plan, mit load(), wenn das Gespräch die Struktur verändert.

Öffne den vom encode generierten Link so, wie er ist: er ist bereits https://. (Mit --local serviere das viewer/dist/ über http://, z. B.: python3 -m http.server; einige eingebettete Browser verwerfen den #hash von file://-Links.)

Die Seite gibt window.c4plan frei (führe es mit dem JavaScript-Tool des Browsers aus):

Aufruf	Funktion
await c4plan.next(30000)	Wartet bis zu 30s auf das nächste Ereignis. Gibt das Ereignis oder null zurück. Das Maximum beträgt 40s (das Tool kappt nach ~45s).
await c4plan.state()	Aktueller Zustand: url, plan, focus (geöffnete Ebene), selected (was der Mensch gerade betrachtet), idleMs (wie lange er die Seite nicht mehr berührt hat), doc.
c4plan.load(urlOderHash)	Tauscht das Diagramm gegen eine neue Version aus, ohne die Seite neu zu laden.
c4plan.stop()	Teilt der Seite mit, dass du aufgehört hast zuzuhören.

Ereignisse von next():

• {event:"comment", targets:[{id,name}], view, text}: Der Mensch hat über diese Elemente einen Kommentar abgegeben (es können keine, eines oder mehrere sein; view ist die geöffnete Ebene). Antworte im Chat, beginnend mit den Namen: "Über API Pix und Abwicklungs-Warteschlange: ...". Wenn es sich um einen Änderungswunsch handelt, ändere das YAML, führe encode aus, rufe load(neuerLink) auf und teile im Chat mit, was sich geändert hat. Höre dann weiter zu.
• {event:"stop", reason:"idle"}: Der Mensch hat die Seite 10 Minuten lang nicht berührt und das Lauschen wurde automatisch beendet. Sage den Stopp-Satz (Schritt 3) und verlasse die Schleife.

Die Schleife:

1. Sage vor Beginn im Chat in einer Zeile: "Ich habe das Diagramm im Browser geöffnet und höre zu, während du darin herumklickst. Drücke C (oder Kommentieren), klicke auf die Karten und schreibe: Ich antworte hier. Sobald alles fertig ist, sag mir hier, dass du zustimmst." Ohne diese Ankündigung klickt der Mensch auf der Seite herum, es erscheint nichts im Chat, und er versteht nicht, was passiert.
2. Wiederhole await c4plan.next(30000) und behandle jedes Ereignis. null bedeutet nur "noch nichts": rufe es erneut auf, ohne es im Chat zu kommentieren. Das Lauschen dauert an, solange der Mensch mit der Seite interagiert (jeder Klick, Tastendruck oder Scrollen setzt die Uhr zurück); wer das Ende bestimmt, ist die Seite, mit stop.
3. Stoppe, wenn ein stop eintrifft. Sage bei stop im Chat: "Ich habe aufgehört, auf das Diagramm zu lauschen, weil es inaktiv war. Kommentiere im Chat, wenn du möchtest, oder bitte mich, wieder zuzuhören." Wenn du aus einem anderen Grund vorher anhalten musst, rufe c4plan.stop() auf und sage dasselbe.
4. Wenn der Mensch während des Lauschens eine Nachricht im Chat sendet, endet die Schleife: Antworte auf die Nachricht. Lies dann (await c4plan.state()).idleMs: wenn es weniger als 10 Minuten beträgt, ist er noch auf der Seite, also kehre zur Schleife zurück, ohne erneut zu warnen. Wenn er zustimmt, rufe c4plan.stop() auf und folge Abschnitt 3.
5. Wenn der Mensch im Chat nach "dem hier" oder "diesem Element" fragt, lese state().selected, um zu wissen, wovon er spricht.
6. Ohne dass du zuhörst, kopiert der Kommentar-Button einen Text wie Über "API Pix" (pix-api) im Diagramm: ... für den Menschen, um ihn in den Chat einzufügen. Die IDs in Klammern sind die aus dem YAML.

3. Wenn der Mensch im Chat zustimmt

Nur er stimmt zu, und zwar nur im Chat ("genehmigt", "kann losgehen", "ok, führe aus"). Schweigen, Ende des Lauschens oder Fehlen von Kommentaren ist keine Genehmigung.

1. Setze approved: true im <plan>.arch.yaml und generiere das Briefing aus der Datei:

   python3 scripts/arch_url.py brief <plan>.arch.yaml -o <plan>.arch.md
   

2. Fasse in wenigen Zeilen zusammen, was sich seit dem ersten Link aufgrund des Gesprächs geändert hat (Einschränkungen, Struktur, Abläufe).
3. Füge dem Plan einen Verweis auf das <plan>.arch.md hinzu und fahre mit der Ausführung fort.

Wenn der Mensch einen Link des Viewers einfügt (z. B. in einem normalen Browser geöffnet), dient dieser nur zum Ansehen: Die gültige Version ist dein <plan>.arch.yaml.

4. Ausführung unter Beachtung des Briefings

Das <plan>.arch.md ist während der Ausführung obligatorisch:

• Befolge die Struktur (Elemente, Beziehungen, Abläufe) und alle Einschränkungen. Wenn die Implementierung eine Änderung der Struktur oder eine Verletzung einer Einschränkung erfordert, stoppe und frage nach.
• Referenzierte Verträge (contract) werden ohne Rückfrage nicht geändert.
• Außerhalb der Einschränkungen bevorzuge das Einfachste und folge dem Muster des vorhandenen Codes.
• Was der Mensch im Chat verlangt hat, hat Vorrang vor deinem ursprünglichen Vorschlag.
• Vergleiche am Ende die implementierte Lösung mit dem YAML und melde Abweichungen (unvorhergesehene neue Komponente, Abhängigkeit außerhalb der Beziehungen, geänderter Vertrag).

5. Dokumentiere das System, wie es heute ist (kind: system)

Wenn die Anfrage darin besteht, das Bestehende zu verstehen oder zu dokumentieren ("Architektur dokumentieren", "Wie funktioniert dieses System?", Onboarding), gibt es keinen Plan: Du liest das Repository und generierst das gleiche YAML mit kind: system. Vollständiges Beispiel: examples/loja.arch.yaml.

version: 1
kind: system
title: Online-Shop
description: Ein oder zwei Sätze darüber, was das System tut.

So erstellst du es:

• Lies, bevor du schreibst. Einstiegspunkte (Routen, Handler, Konsumenten, Jobs), Manifests (package.json, docker-compose, Infrastruktur), Migrationen und Clients externer Dienste zeigen, welche Container, Datenbanken, Warteschlangen und externen Systeme es gibt. Erfinde keine Teile, die der Code nicht zeigt; wenn etwas unsicher ist, teile es im Chat mit.
• Keine status, steps und approved. Alles ist so, wie das System ist (die Validierung warnt, wenn etwas übrig bleibt).
• Abläufe sind das Wichtigste. 2 bis 4: der für das Geschäft wichtigste Pfad, die wichtigste Hintergrundaufgabe und der häufigste Fehlerfall. An ihnen versteht der Neuankömmling das System.
• Tiefe: Gehe nur bis code bei dem, was die Abläufe durchqueren, mit echtem path (überprüfe, ob die Datei existiert). Der Rest bleibt auf container- oder component-Ebene, geschlossen.
• constraints werden zu den Hausregeln, die jeder kennen muss, der Änderungen vornimmt (Idempotenz, wer in welche Tabelle schreiben darf, unveränderlicher Vertrag).
• Beziehungen und Abläufe folgen denselben Regeln wie beim Plan (Abschnitt 1).

Auslieferung: encode generiert den Link wie beim Plan. Sage in einer Zeile, was das System enthält ("5 Container, 2 externe Systeme, 2 Abläufe") und dass man den Abläufen im Reiter Abläufe folgen und mit C Fragen stellen kann. Wenn du einen Browser hast, höre auf die Seite (Abschnitt 2b): Kommentare sind Fragen, die du im Chat beantwortest, oder Korrekturen der Dokumentation, die du im YAML vornimmst und mit load() neu lädst.

Für einen versionierbaren Text im Repository generiert brief die Dokumentation in Markdown (Elemente, Beziehungen und Abläufe):

python3 scripts/arch_url.py brief docs/architektur.arch.yaml -o docs/architektur.md

Später kann ein Plan über dieses System von diesem YAML ausgehen: Kopiere es, ändere kind in plan und markiere das, was sich ändert, mit status.