Spezifikation zur Visualisierung von Code-Abläufen
Dieser Skill bietet eine Reihe wiederverwendbarer Vorlagen und Methoden zur Analyse von Code-Abläufen und zur Erstellung visueller Dokumentation.
Kernprinzip: Mit Text und ASCII-Diagrammen klar erklären, "woher die Daten kommen, durch welche Schichten sie gehen und wohin sie schließlich gelangen".
Wann verwenden
Verwenden Sie diesen Skill in folgenden Szenarien:
- Der Benutzer fragt, "wie eine bestimmte Funktion funktioniert"
- Eine neue Funktion erfordert das Design eines Datenflusses
- Vor einer Refaktorierung muss die vorhandene Logik analysiert werden
- Beim Schreiben technischer Dokumentation oder Architekturbeschreibungen
- Bei Code-Reviews muss die Aufrufkette visualisiert werden
Kernvorlagen
1. Vollständiges Flussdiagramm (Szenarienvergleich)
Geeignet für: Analyse einer Funktion mit mehreren Anwendungsszenarien (z. B. manuell vs. automatisch, Erfolg vs. Fehler)
┌─────────────────────────────────────────────────────────────────────┐
│ Funktionsname (z. B. Gesamtlebenszyklus des Limits) │
└─────────────────────────────────────────────────────────────────────┘
═══════════════════════════════════════════════════════════════════════
Szenario 1: Szenarioname (z. B. Automatische Abfrage des Limitstatus)
═══════════════════════════════════════════════════════════════════════
Benutzerbefehl
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ uv run python -m src.cli.xxx ... │
└────────────────┬────────────────────────────────────────────────┘
│
▼
┌────────────────┐
│ CLI-Schicht │ Ruft Flow-Funktion auf
│ _do_xxx() │ ────────────────────┐
└────────────────┘ │
▼
┌──────────────────────────┐
│ Flow-Schicht │
│ xxx_flow() │
└───────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ Daten-Schicht │
│ XxxRepo / XxxClient │
└────────┬─────────────────────┘
│
▼
┌────────────────────────────┐
│ Externes System / DB │
│ (SQLite / API / etc) │
└──────────┬─────────────────┘
│ Datenrückgabe
▼
┌──────────────────────────────────┐
│ Datenverarbeitung (Parsen/Konvertieren)│
└─────────────┬────────────────────┘
│
▼
┌──────────────────────┐
│ Rückgabedatenklasse │ ← Erklärung, warum beibehalten/vereinfacht
│ (Result / Item / ...)│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ CLI-Schicht formatiert Ausgabe │
└──────────────────────┘
│
▼
╔══════════════════════════════════════════════════╗
║ Beispiel für Terminalausgabe ║
║ (Mit Rahmen umgeben, um die für den Endbenutzer ║
║ sichtbare Wirkung hervorzuheben) ║
╚══════════════════════════════════════════════════╝
═══════════════════════════════════════════════════════════════════════
Szenario 2: Ein weiteres Szenario
═══════════════════════════════════════════════════════════════════════
(Obige Struktur wiederholen, Unterschiede hervorheben)
2. Erklärung der Datenbanktabellenstruktur
Geeignet für: Erklärung der an einer Funktion beteiligten Datenbanktabellen
CREATE TABLE table_name (
id INTEGER PRIMARY KEY AUTOINCREMENT, -- ← Erklärung der Primärschlüsselfunktion
field1 TEXT NOT NULL, -- Bedeutung des Feldes erklären
field2 TEXT, -- Geschäftliche Bedeutung von NULL
...
);
-- Index (Erklärung, warum dieser Index benötigt wird)
CREATE INDEX idx_xxx ON table_name(field1, field2);
Beispieldatentabelle:
| id | field1 | field2 | field3 | Erklärung |
|---|---|---|---|---|
| 42 | wert1 | wert2 | wert3 | Geschäftliche Bedeutung dieses Datensatzes erklären |
| 43 | ... | ... | ... | ... |
Typische Abfrage:
-- Szenariobeschreibung: Wann wird diese Abfrage benötigt?
SELECT * FROM table_name
WHERE condition1 = ?
AND (condition2 IS NULL OR condition2 >= ?);
3. Geschichtete Aufrufkette (vereinfachte Version)
Geeignet für: Schnelle Erklärung der Funktionsaufrufbeziehungen
CLI-Schicht (_do_xxx)
│
└─> Flow-Schicht (xxx_flow)
│
├─> Daten/Repo (xxx_repo.get)
│ │
│ └─> SQLite (SELECT ...)
│
└─> Daten/Client (xxx_client.fetch)
│
└─> Externe API (HTTP GET ...)
4. Analysetabelle für Datenklassen-Design
Geeignet für: Bewertung, ob Zwischendatenklassen notwendig sind
| Klassenname | Felder | Verwendung | Bewertung | Grund |
|---|---|---|---|---|
XxxResult | 6 | Mehrfeldaggregation + CLI-Anzeige | ✅ Beibehalten | Erfüllt "Prinzip der minimalen Notwendigkeit" |
XxxWrapper | 1 | Einzelfeld-Wrapper | ❌ Löschen | Übermäßige Kapselung, direkte Rückgabe des Rohdatentyps |
XxxItem | 3 | Listendetail-Element | ✅ Beibehalten | Hat geschäftliche Semantik |
Vergleichsbeispiel:
# ❌ Übermäßige Kapselung
@dataclass
class XxxResult:
field: SomeType # Nur ein Feld
def xxx_flow() -> XxxResult:
return XxxResult(field=value)
# ✅ Vereinfacht
def xxx_flow() -> SomeType: # Direkte Rückgabe
return value
5. Markierung geschäftlicher Kernpunkte
Geeignet für: Hervorhebung von Geschäftsregeln und Entwurfsentscheidungen
┌─────────────────────────────────────────────────────────────┐
│ Geschäftliche Kernpunkte │
├──────────────────────┬──────────────────────────────────────┤
│ Warum so entworfen? │ Konkrete Entscheidung │
├──────────────────────┼──────────────────────────────────────┤
│ • Datengenauigkeit │ Beträge mit Decimal, 2 Dezimalstellen│
│ • Idempotenz │ Eindeutige Einschränkung nach │
│ │ (fund_code, date) │
│ • Rückverfolgbarkeit │ record_id als global eindeutige ID │
└──────────────────────┴──────────────────────────────────────┘
Verwendung
Schritt 1: Analyseziel festlegen
Beantworten Sie folgende Fragen:
- Welche Funktion möchte der Benutzer verstehen?
- Welche Szenarien hat diese Funktion? (Erfolg/Fehler, manuell/automatisch usw.)
- Welche Schichten sind beteiligt? (CLI → Flow → Data → DB/API)
- Welche Schlüsseldatenklassen gibt es? Warum wurden sie so entworfen?
Schritt 2: Passende Vorlage auswählen
- Szenarienvergleich → Vorlage 1 (Vollständiges Flussdiagramm)
- Einzelner Ablauf → Vorlage 3 (Geschichtete Aufrufkette)
- Datenbankdesign → Vorlage 2 (Tabellenstruktur + Beispieldaten)
- Datenklassenbewertung → Vorlage 4 (Analysetabelle)
Schritt 3: Inhalt füllen
Prinzipien:
- ASCII-Diagramme anstelle von langen Textblöcken verwenden
- Pfeile (
│ ▼ ┐ ┘ └ ├ ─) zum Verknüpfen des Datenflusses verwenden - Rahmen (
┌ ┐ └ ┘ │ ─) zur Trennung von Schichten verwenden - Doppelrahmen (
╔ ╗ ╚ ╝ ║ ═) zur Hervorhebung benutzersichtbarer Teile verwenden - Kommentare an Schlüsselpunkten hinzufügen (
← Erklärung)
Symbolverwendungskonventionen:
| Symbol | Verwendung | Beispiel |
|---|---|---|
│ ▼ | Vertikaler Fluss | Daten von oben nach unten |
→ ← | Horizontale Erklärung | record_id: int ← Datenbank-Primärschlüssel |
┌ ┐ └ ┘ | Einfacher Rahmen | Codeblöcke, Befehle umgeben |
╔ ╗ ╚ ╝ | Doppelrahmen | Terminalausgabe, wichtige Ergebnisse hervorheben |
═══ | Trennlinie | Verschiedene Szenarien trennen |
Schritt 4: Vergleichsanalyse hinzufügen
Before vs. After (Refaktorierungsszenario):
# Before (Problemversion)
...code...
# Probleme:
# - Übermäßige Kapselung
# - Redundante Felder
# - Erhöhte kognitive Belastung
# After (Verbesserte Version)
...code...
# Verbesserungen:
# - Direkte Rückgabe sinnvoller Typen
# - Reduzierung der Zwischenschichten
# - Geringere Wartungskosten
Praxisbeispiele
Beispiel 1: Limitverwaltungsablauf (Vollversion)
(Siehe obiges Vorlagenbeispiel 1, erweitert auf 4 Szenarien des vollständigen Ablaufs)
Beispiel 2: Datenklassenbewertung (Modul fund_restriction)
| Funktion | Vorherige Rückgabe | Jetzige Rückgabe | Bewertung | Grund |
|---|---|---|---|---|
add_restriction | AddRestrictionResult(6 Felder) | Beibehalten | ✅ | CLI muss alle Felder anzeigen |
end_restriction | EndRestrictionResult(4 Felder) | bool | ❌ | Nur Erfolg/Fehler erforderlich |
check_trading_status | CheckStatusResult(2 Felder) | `ParsedRestriction | None` | ❌ |
Ausgabeprüfliste (Checklist)
Stellen Sie bei der Erstellung eines Ablaufvisualisierungsdokuments sicher, dass Sie Folgendes enthalten:
- Übersicht auf oberster Ebene (Funktionsziel, beteiligte Module)
- Aufzählung der Szenarien (Erfolg/Fehler, manuell/automatisch usw.)
- Geschichtetes Flussdiagramm (CLI → Flow → Data → Extern)
- Datenbanktabellenstruktur (falls betroffen)
- Beispieldaten und -abfragen (zur Verständnisförderung)
- Erklärung der Schlüsseldatenklassen (warum beibehalten/vereinfacht)
- Entwurfsentscheidungen (warum wurde es so gemacht?)
- Zukünftige Erweiterungspunkte (TODO oder reservierte Schnittstellen)
Anti-Patterns (Nicht so machen)
❌ Reine Textbeschreibung des Ablaufs
Zuerst wird die CLI-Schicht-Funktion _do_xxx aufgerufen, dann ruft _do_xxx die Flow-Schicht-Funktion xxx_flow auf,
xxx_flow ruft wiederum die Daten-Schicht-Methode xxx_repo.get auf...
✅ Mit ASCII-Diagramm
CLI (_do_xxx) → Flow (xxx_flow) → Data (xxx_repo.get) → SQLite
❌ Tabelle ohne Schwerpunkt
| Feld | Typ |
|---|---|
| id | int |
| name | str |
✅ Geschäftliche Bedeutung hervorheben
| Feld | Typ | Erklärung | Geschäftliche Einschränkung |
|---|---|---|---|
| id | int | Primärschlüssel | Automatisch generiert, global eindeutig |
| name | str | Fondsname | Nicht leer, zur Anzeige |
❌ SQL ohne Szenariobeschreibung
SELECT * FROM table WHERE id = ?;
✅ Mit geschäftlichem Szenario
-- Szenario: Benutzer fragt Details einer bestimmten Limit-Aufzeichnung ab
SELECT * FROM fund_restrictions WHERE id = ?;
-- Szenario: Bei DCA-Analyse prüfen, ob ein bestimmtes Datum limitiert ist
SELECT * FROM fund_restrictions
WHERE fund_code = ? AND start_date <= ? AND (end_date IS NULL OR end_date >= ?);
Zusammenarbeit mit anderen Skills
- code-style: Bei Codebeispielen die Codierkonventionen einhalten
- architecture: Flussdiagramme müssen den Architektureinschränkungen entsprechen
- dev-workflow: Vor der Ablaufanalyse relevanten Code und Dokumentation lesen
Zusammenfassung
Der Kernwert dieses Skills:
- Wiederverwendbare Vorlagen: Reduziert die Zeit für den Start von Null
- Einheitlicher visueller Stil: ASCII-Diagramme + Tabellen + Rahmen
- Geschäftliche Perspektive: Nicht nur Code-Abläufe, sondern auch "Warum"
- Vergleichsanalyse: Vorher/Nachher, Szenarienvergleich
- Prüflisten: Stellt sicher, dass keine wichtigen Informationen fehlen
Verwendungshäufigkeit: Immer dann, wenn erklärt werden muss, "wie eine bestimmte Funktion funktioniert".