Unfold

Was macht Unfold?

Erzeugt eine einzige, eigenständige HTML-Seite: eine Übersicht, die sich Ebene für Ebene in die Teile eines Systems entfaltet. Die Engine (assets/template.html) zeichnet, layoutet, zoomt, verfolgt und editiert. Ihre Aufgabe ist es, den Code zu verstehen und die Diagrammdaten (JSON) zu schreiben, so dass ein Leser, der nichts über das Projekt weiß, es am Ende erklären kann.

Auf jeder Ebene beantwortet die Seite drei Fragen: Was kommt herein, was passiert damit, was kommt heraus.

Qualitätsanspruch

• Korrekt. Jeder Knoten und jede Kante basiert auf Code, den Sie tatsächlich angesehen haben. Sein source gibt an, wo: path/datei.py:symbol. Markieren Sie confidence auf jedem Knoten: read, peeked oder inferred. Alles, was abgeleitet wurde, wird dem Nutzer aufgelistet.
• An den Codebestand angepasst. Verwenden Sie die eigene Terminologie des Projekts (Modulnamen, Themen- und Routennamen wörtlich) und den Diagrammtyp, der zu jedem Teil passt (siehe Schritt 4).
• Leise. Beschriftungen haben 2 bis 4 Wörter, Bildunterschriften eine Zeile, Notizen 1 bis 3 Sätze und nichts weiter. Details liegen einen Klick oder einen Hover entfernt, niemals auf der Zeichenfläche.
• Von Null aus navigierbar. meta.summary sagt in einem Satz, wofür das System ist. Ein kurzes meta.glossary definiert das Fachjargon des Projekts. Notizen beginnen mit einem Satz, der als Hover-Hinweis fungiert.

Arbeitsablauf

1. Die Anfrage einrahmen

Die Absicht kommt zuerst: Wofür die Karte ist. Sie legt den Umfang, die Tiefe, die Ebenentypen, die Tour, die Medien und das Glossar fest; references/intents.md enthält die Vorgaben für jede Absicht.

• Fragen Sie nicht, wenn die Eingabeaufforderung es bereits sagt. „Führe mich durch dieses Projekt“ bedeutet lernen. „Wie funktioniert die Wiederholungslogik?“ bedeutet erklären. „Was ändert dieser PR?“ bedeutet reviewen. „Ich präsentiere das am Freitag“ bedeutet demonstrieren.
• Fragen Sie andernfalls eine Frage vor dem Scannen, mit diesen Optionen: Den Codebestand lernen, Meine Arbeit demonstrieren, Ein bestimmtes Detail erklären, Eine Änderung reviewen oder Sonstiges (dokumentieren oder übergeben, einen Pfad debuggen, einen Refaktor planen, Datenfluss auditieren).
• Stellen Sie dann maximal zwei Folgefragen, ausgewählt für diese Absicht in references/intents.md. Überspringen Sie jede, die die Konversation bereits beantwortet.
• Notieren Sie die Antwort als meta.intent und meta.audience. Wenn Sie eine bestehende Seite erweitern, verwenden Sie deren meta.intent erneut, anstatt erneut zu fragen.

Dann, aus der Konversation oder in derselben kurzen Runde, klären Sie:

• scope: welches Repository oder welcher Teil davon;
• audience: neuer Entwickler, Reviewer, Manager oder Vortrag;
• focus: der Teil, der am meisten zählt und die meiste Tiefe erhält;
• confidentiality: Seiten werden geteilt, daher lassen Sie Hosts, Geheimnisse, Kundennamen und unveröffentlichte Pläne weg, sofern nicht anders angegeben.

Wenn es keinen Code gibt, arbeiten Sie anhand der Beschreibung des Nutzers. Erfinden Sie niemals Teile, Abläufe oder Zahlen.

2. Den Codebestand in Phasen innerhalb eines Budgets lesen

Große Repositories passen nicht in den Kontext, und das Überfliegen ganzer Dateien verschwendet ihn. Lesen Sie in Phasen und hören Sie auf, sobald das Diagramm fundiert ist.

Phase	Befehl	Was Sie erhalten	Kosten
Karte	python scripts/scan_repo.py REPO [--section NAME]	Sprachen, Layout, Manifeste, Einstiegspunkte, I/O-Signale mit datei:zeile, Importe zwischen Teilen, eine zuerst lesen-Liste	gering, begrenzt durch --budget
Form	python scripts/scan_repo.py REPO --outline [PRÄFIX]	jede Klasse und Funktion mit Signatur und erster Docstring-Zeile, ohne Körper	mittel, begrenzt durch --budget
Beleg	python scripts/peek.py REPO datei:zeile datei:symbol ...	nur die Zeilen um jede Referenz herum, zusammengeführt, innerhalb eines festen Zeilen- und Tokenbudgets	gering pro Aufruf
Tiefe	ganze Dateien lesen	nur die 3 bis 8 Dateien, die die Kernlogik im Fokusbereich des Nutzers tragen	hoch

So arbeiten Sie sich durch die Phasen:

• Beginnen Sie mit README, Dokumentation und der Karte.
• Verwenden Sie das Outline für die Ordner, die wichtig sind. Führen Sie es bei einem großen Repository pro Top-Level-Teil aus, nicht für alles.
• Verwenden Sie peek für jedes I/O-Signal und jeden Einstiegspunkt, den Sie zeichnen wollen, und für die Funktion hinter jeder Prozessebene.
• Lesen Sie ganze Dateien nur dort, wo die Logik wirklich komplex ist.
• Führen Sie eine laufende Belegliste (Knoten → datei:symbol). Sie wird zu den source-Feldern.
• Der Scan basiert auf regulären Ausdrücken: Er übersieht dynamische Verkabelungen und meldet einige Fehlalarme, wie Muster innerhalb von Zeichenketten. Bestätigen Sie mit peek, bevor Sie zeichnen.

Token-Budget. Jeder Befehl endet mit seinen Kosten (≈N Tokens). Geben Sie nur das aus, was die Karte braucht:

• Lesen Sie niemals eine ganze Datei vor ihrem Outline. Peeken Sie datei:symbol, keine breiten Zeilenbereiche, und bündeln Sie Referenzen in einen peek-Aufruf.
• Eine abgeschnittene Liste endet mit … N mehr; erneut ausführen mit --section X. Rufen Sie sie nur ab, wenn das Diagramm sie braucht. Skizzieren Sie bei einem großen Repository einen Teil nach dem anderen mit --outline PRÄFIX.
• Hören Sie auf zu lesen, sobald jeder Knoten, den Sie zeichnen möchten, eine source hat.
• Überprüfen Sie mit unfold.py check und outline; lesen Sie das JSON oder die Seite nicht erneut. Patchen Sie diagram.json mit kleinen Änderungen; drucken Sie es nie vollständig neu aus.

Kosten, der Scan-Cache und was übersprungen wird: references/reading-code.md (Token-Budget).

3. Die Systemgrenze festlegen

Listen Sie die Eingaben (Anfragen, abonnierte Themen, CLI-Argumente, gelesene Dateien, Sensoren, Konfiguration) und die Ausgaben (Antworten, veröffentlichte Themen, geschriebene Dateien, Befehle, DB-Schreibvorgänge) auf. Markieren Sie sie auf jeder Architektur- und Prozessebene mit "role": "input" oder "role": "output".

4. Das Diagramm für jede Ebene auswählen

Die Übersicht ist immer architecture: 4 bis 10 Teile, Speicher und Externe, mit Eingaben links und Ausgaben rechts. Jeder Teil, den zu öffnen sich lohnt, erhält den Kindtyp, den sein Code erfordert:

Der Code darin ist…	type	Zeichnen
Mehrere Teile, die sich gegenseitig aufrufen oder Nachrichten senden	architecture	rounded Teile, cylinder Speicher, cloud Externe
Eine Abfolge von Schritten über einer Eingabe: ein Handler, eine Pipeline, ein Job oder ein Algorithmus	process	pill Start/Ende, rect Schritte, diamond Entscheidungen mit beschrifteten Zweigen, gestrichelte Rückführungen
Eine Interaktion zwischen Teilen über die Zeit: ein Anfragelebenszyklus, ein Handshake, ein Aktionsziel	sequence	Teilnehmer als Knoten, von links nach rechts; Nachrichten als Kanten in der Reihenfolge; gestrichelt für Rückgaben
Verhalten, das durch Zustände und Ereignisse gesteuert wird: eine Zustandsmaschine, ein Modus-Manager, eine Verbindung, ein Verhaltensbaum-Status	state	initial und final Markierungen, pill Zustände, Kanten beschriftet mit dem Ereignis oder der Wächterbedingung
Datenstrukturen, Schemas, ORM-Modelle, Nachrichtendefinitionen	data	table Knoten mit fields ("id: int PK"), Kanten beschriftet mit Kardinalität
Klassen und ihre Beziehungen: ein Objektmodell, eine Plugin-Hierarchie	class	class Knoten mit fields und methods; Kanten mit rel (inherits, implements, composition, …)
Das System in seiner Welt: Benutzer, benachbarte Systeme, die Technologie jedes Containers	c4	person für Menschen, Teile mit tech, cloud Externe, Gruppen als Grenzen
Was wo läuft: Hosts, Geräte, Cluster, Container	deployment	node3d Maschinen, Gruppen für Umgebungen, tech auf jedem
Modul- oder Paketimporte	dependency	rect Module, Kanten vom Importierenden zum Importierten
Ein Verhaltensbaum (py_trees, BehaviorTree.CPP, Nav2)	behaviour	Knoten mit bt (sequence, selector, parallel, decorator, action, condition); Kanten Eltern → Kind in Ausführungsreihenfolge
Eine Hierarchie: Konfigurationsbaum, Menü, Dokumentation, Themen	tree	Eltern → Kind Kanten, in der Reihenfolge
Veröffentlichungen, Migrationen, eine Boot- oder Startreihenfolge	timeline	Knoten in der Reihenfolge mit jeweils einem date

Gehen Sie tiefer, wo der Code es tut, und hören Sie auf, wo eine Notiz ausreichen würde. Öffnen Sie einen Teil nur, wenn sein Inneres 3 oder mehr bedeutungsvolle Elemente hat. Halten Sie jede Ebene bei etwa 12 Knoten; darüber hinaus verschachteln Sie. references/reading-code.md enthält Muster für Webservices, ROS 2, Pipelines, CLIs, Firmware, Frontends und Monorepos.

5. Visuelle Elemente dort hinzufügen, wo der Code sie hat

Wenn das Repository Screenshots, Architekturbilder, Demo-GIFs oder Videos enthält (suchen Sie in docs/, assets/ und der README), fügen Sie sie mit "media": {"src": "relativer/pfad.png", "caption": "…"} oder einer Liste von ihnen hinzu, um einem Teil mehrere zu geben. Jeder Knoten mit Medien zeigt ein Miniaturbild-Abzeichen und öffnet einen Viewer; ein Knoten mit "shape": "image" zeigt das Bild auf der Zeichenfläche. Fragen Sie für demonstrieren den Nutzer nach Screenshots der Teile, die Sie zeigen.

unfold.py build bindet lokale Dateien ein. Veröffentlichte claude.ai-Seiten blockieren entfernte Bilder, daher bevorzugen Sie lokale Dateien.

6. Die Texte schreiben

• meta.summary: ein Satz darüber, was das System für wen tut.
• meta.glossary: bis zu 8 Projektbegriffe, jeder mit einer Definition von höchstens 10 Wörtern.
• caption pro Ebene: eine Zeile über den Zweck, z.B. „Jedes Ziel wird auf Erreichbarkeit geprüft, bevor sich der Arm bewegt.“
• note auf einem Knoten: der erste Satz wird beim Hovern angezeigt, also sollte er für sich allein stehen; bis zu zwei weitere Sätze kommen in die Detailkarte.
• Kantenbeschriftungen: was fließt, in 1 bis 3 Wörtern.

7. Eine Tour schreiben

Für lernen und demonstrieren (und immer dann, wenn die Karte mehr als zwei Ebenen hat), fügen Sie einen meta.tours-Eintrag hinzu: 5 bis 9 Schritte in der Reihenfolge, in der ein Entwickler es erklären würde, von den Eingaben zu den Ausgaben. Jeder Schritt nennt einen path (die Knoten-IDs, die geöffnet werden sollen, von der Übersicht abwärts) und optional einen node, der hervorgehoben werden soll, mit einem title und ein oder zwei Sätzen text. Für demonstrieren fügen Sie Sprecher-notes hinzu. Für lernen enden Sie mit einem quiz-Schritt ({"q", "answer": Knoten-ID, "explain"}). Die Seite generiert auch eine Tour, wenn keine geschrieben wird, also überspringen Sie dies für eine kleine einstufige Karte.

8. Überprüfen, reviewen, bauen

python scripts/unfold.py check   diagram.json     # Fehler führen zum Abbruch; lesen Sie jede Warnung
python scripts/unfold.py outline diagram.json     # der gesamte Baum auf einem Bildschirm
python scripts/unfold.py drift   diagram.json --repo REPO   # jede Quelle löst noch auf
python scripts/unfold.py build   diagram.json seite.html --repo REPO   # fixiert meta.repo auf den Commit

Behalten Sie eine Kopie von dem, was Sie erzeugt haben, als diagram.generated.json neben diagram.json; ein erneutes Kartieren benötigt sie.

Lesen Sie die Gliederung, als wären Sie der Neuling:

• Können Sie das System daraus erklären?
• Beantwortet jede Ebene Eingabe → Verarbeitung → Ausgabe?
• Ist jedes Kind der richtige Typ?

Wenn Browserautomatisierung wie Playwright verfügbar ist, machen Sie einen Screenshot der Übersicht und einer inneren Ebene jedes Typs und beheben Sie Überlappungen oder Kreuzungen.

9. Ausliefern

Veröffentlichen Sie auf claude.ai mit dem Artifact-Tool seite.html aus /mnt/user-data/outputs/ mit capabilities: {"artifact": {}, "downloads": true}, was Speichern und Exportieren ermöglicht. Andernorts übergeben Sie die Datei; sie funktioniert offline.

Teilen Sie dem Nutzer dann in wenigen Zeilen mit:

• was die Übersicht zeigt;
• welche Teile abgeleitet sind;
• wie die Seite zu lesen ist: Klicken zum Öffnen, Hover zum Verfolgen, Esc oder Herauszoomen zum Zurückgehen, / zum Suchen, Tour oder T für die geführte Tour, P zum Präsentieren und Bearbeiten zum Ändern von Dingen;
• dass Export PNG, SVG, PDF, Mermaid, draw.io und Excalidraw für Folien, READMEs und andere Werkzeuge bereitstellt.

Wenn der Nutzer die Seite später bearbeitet hat, fahren Sie mit python scripts/unfold.py extract seite.html diagram.json fort, nicht mit Ihrer alten Kopie.

Um nach Codeänderungen neu zu kartieren, scannen Sie mit --changed-since <meta.repo.commit>, aktualisieren Sie eine Kopie von diagram.generated.json mit denselben IDs, führen Sie dann unfold.py merge in die bearbeitete Karte aus, sodass manuelle Änderungen erhalten bleiben. Schritte: references/reading-code.md (Neu-Kartierung).

Referenz

• references/intents.md: was jede Absicht ändert und ihre Folgefragen.
• references/schema.md: jedes Feld, Ebenentyp, Form und Farbe.
• references/reading-code.md: Code in Ebenen umwandeln, mit Mustern pro Ökosystem.
• Ändern Sie assets/template.html nicht für ein einzelnes Diagramm. Engine-Änderungen gehören in das Repository, mit Tests.