Codeablauf-Visualisierungsstandard
Dieses Skill stellt eine wiederverwendbare Vorlage und Methodik zur Verfügung, um Codeabläufe zu analysieren und visuelle Dokumente zu erstellen.
Kernprinzip: Mit Text und ASCII-Diagrammen klar erklären, „woher die Daten kommen, welche Schichten sie durchlaufen und wo sie schließlich landen“.
Wann verwenden
Verwende dieses Skill in den folgenden Szenarien:
- Der Benutzer fragt: „Wie funktioniert diese Funktion?“.
- Eine neue Funktion benötigt ein Datenflussdesign.
- Vor einem Refactoring muss die vorhandene Logik analysiert werden.
- Erstellung technischer Dokumentation oder Architekturbeschreibungen.
- Bei einem Code-Review muss die Aufrufkette visualisiert werden.
Kernvorlagen
1. Vollständiges Ablaufdiagramm (mit Szenarienvergleich)
Geeignet für: Die Analyse einer Funktion in mehreren Nutzungsszenarien (z. B. manuell vs. automatisch, Erfolg vs. Fehler).
┌─────────────────────────────────────────────────────────────────────┐
│ Funktionsname (z.B. Limit-Verwaltung Lebenszyklus)|
└─────────────────────────────────────────────────────────────────────┘
═══════════════════════════════════════════════════════════════════════
Szenario 1: Szenarioname (z. B. Automatische Abfrage des Limitstatus)
═══════════════════════════════════════════════════════════════════════
Benutzerbefehl
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ uv run python -m src.cli.xxx ... │
└────────────────┬────────────────────────────────────────────────┘
│
▼
┌────────────────┐
│ CLI-Ebene │ Ruft Flow-Funktion auf
│ _do_xxx() │ ────────────────────┐
└────────────────┘ │
▼
┌──────────────────────────┐
│ Flow-Ebene │
│ xxx_flow() │
└───────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ Data-Ebene │
│ XxxRepo / XxxClient │
└────────┬─────────────────────┘
│
▼
┌────────────────────────────┐
│ Externes System / DB │
│ (SQLite / API / etc) │
└──────────┬─────────────────┘
│ Rückgabedaten
▼
┌──────────────────────────────────┐
│ Datenverarbeitung (Parsing/Umwandlung)│
└─────────────┬────────────────────┘
│
▼
┌──────────────────────┐
│ Rückgabewert-Datentyp│ ← Erklärung, warum er beibehalten/vereinfacht wird
│ (Result / Item / ...)│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ CLI-Ebene formatierte Ausgabe │
└──────────────────────┘
│
▼
╔══════════════════════════════════════════════════╗
║ Terminal-Ausgabe Beispiel ║
║ (Mit Rahmen hervorgehoben, um die Sicht des Endbenutzers zu zeigen)║
╚══════════════════════════════════════════════════╝
═══════════════════════════════════════════════════════════════════════
Szenario 2: Weiteres Szenario
═══════════════════════════════════════════════════════════════════════
(Wiederhole obige Struktur, hebe Unterschiede hervor)
2. Datenbanktabellen-Struktur
Geeignet für: Die Erklärung von Datenbanktabellen, die an einer Funktion beteiligt sind.
CREATE TABLE table_name (
id INTEGER PRIMARY KEY AUTOINCREMENT, -- ← Erklärung der Primärschlüsselrolle
field1 TEXT NOT NULL, -- Erläuterung der Feldbedeutung
field2 TEXT, -- Geschäftsbedeutung 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 | Erläuterung |
|---|---|---|---|---|
| 42 | value1 | value2 | value3 | Erklärt die geschäftliche Bedeutung dieses Datensatzes |
| 43 | ... | ... | ... | ... |
Typische Abfragen:
-- Szenariobeschreibung: Wann wird diese Abfrage benötigt?
SELECT * FROM table_name
WHERE condition1 = ?
AND (condition2 IS NULL OR condition2 >= ?);
3. Schichten-Aufrufkettendiagramm (vereinfacht)
Geeignet für: Die schnelle Erklärung von Funktionsaufrufbeziehungen.
CLI-Ebene (_do_xxx)
│
└─> Flow-Ebene (xxx_flow)
│
├─> Data/Repo (xxx_repo.get)
│ │
│ └─> SQLite (SELECT ...)
│
└─> Data/Client (xxx_client.fetch)
│
└─> Externe API (HTTP GET ...)
4. Datenklassen-Design-Analysetabelle
Geeignet für: Die Bewertung, ob Zwischendatenklassen notwendig sind.
| Klassenname | Anzahl Felder | Verwendung | Bewertung | Grund |
|---|---|---|---|---|
XxxResult | 6 | Mehrfeld-Aggregation + CLI-Anzeige | ✅ Behalten | Erfüllt das „Minimal-notwendig-Prinzip“ |
XxxWrapper | 1 | Einzelfeld-Wrapper | ❌ Löschen | Überflüssiger Wrapper, stattdessen direkten Typ zurückgeben |
XxxItem | 3 | Listendetail-Element | ✅ Behalten | Hat geschäftliche Semantik |
Vergleichsbeispiel:
# ❌ Überflüssiger Wrapper
@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. Geschäftliche Schlüsselpunkte kennzeichnen
Geeignet für: Die Hervorhebung von Geschäftsregeln und Designentscheidungen.
┌─────────────────────────────────────────────────────────────┐
│ Geschäftliche Schlüsselpunkte │
├──────────────────────┬──────────────────────────────────────┤
│ Warum so entworfen? │ Konkrete Entscheidung │
├──────────────────────┼──────────────────────────────────────┤
│ • Datengenauigkeit │ Beträge mit Decimal, 2 Nachkommastellen│
│ • Idempotenz │ Eindeutige Einschränkung nach (fund_code, date) │
│ • Rückverfolgbarkeit │ record_id als global eindeutige ID │
└──────────────────────┴──────────────────────────────────────┘
Verwendung
Schritt 1: Analyseziel festlegen
Beantworte die folgenden Fragen:
- Welche Funktion möchte der Benutzer verstehen?
- Wie viele Szenarien hat diese Funktion? (Erfolg/Fehler, manuell/automatisch, usw.)
- Welche Schichten sind betroffen? (CLI → Flow → Data → DB/API)
- Welche Schlüsseldatenklassen gibt es? Warum sind sie so entworfen?
Schritt 2: Geeignete Vorlage auswählen
- Mehrere Szenarien vergleichen → Vorlage 1 (Vollständiges Ablaufdiagramm)
- Einzelner Ablauf → Vorlage 3 (Schichten-Aufrufkette)
- Datenbankdesign → Vorlage 2 (Tabellenstruktur + Beispieldaten)
- Datenklassenbewertung → Vorlage 4 (Analysetabelle)
Schritt 3: Inhalt einfügen
Grundsätze:
- Verwende ASCII-Diagramme anstelle von langem Text.
- Verwende Pfeile (
│ ▼ ┐ ┘ └ ├ ─), um den Datenfluss zu verbinden. - Verwende Rahmen (
┌ ┐ └ ┘ │ ─), um Schichten zu trennen. - Verwende doppelte Rahmen (
╔ ╗ ╚ ╝ ║ ═), um für den Benutzer sichtbare Teile hervorzuheben. - Füge an Schlüsselstellen Kommentare hinzu (
← Erklärung).
Zeichenverwendungsstandard:
| Zeichen | Verwendung | Beispiel |
|---|---|---|
│ ▼ | Vertikaler Fluss | Daten von oben nach unten |
→ ← | Horizontale Erklärung | record_id: int ← Datenbank-Primärschlüssel |
┌ ┐ └ ┘ | Einfacher Rahmen | Um Codeblöcke, Befehle |
╔ ╗ ╚ ╝ | Doppelter Rahmen | Hervorhebung von Terminalausgaben, wichtigen Ergebnissen |
═══ | Trennlinie | Trennung verschiedener Szenarien |
Schritt 4: Vergleichsanalyse hinzufügen
Before vs After (Refactoring-Szenario):
# Before (Problemversion)
...Code...
# Probleme:
# - Überflüssiger Wrapper
# - Redundante Felder
# - Erhöhte kognitive Belastung
# After (Verbesserte Version)
...Code...
# Verbesserungen:
# - Direkte Rückgabe eines aussagekräftigen Typs
# - Weniger Zwischenschichten
# - Geringere Wartungskosten
Praxisbeispiele
Beispiel 1: Limit-Verwaltungsablauf (Vollversion)
(Siehe obiges Vorlage-1-Beispiel, vollständiger Ablauf mit 4 Szenarien)
Beispiel 2: Datenklassenbewertung (Modul fund_restriction)
| Funktion | Vorherige Rückgabe | Jetzige Rückgabe | Bewertung | Grund |
|---|---|---|---|---|
add_restriction | AddRestrictionResult(6 Felder) | Behalten | ✅ | CLI muss alle Felder anzeigen |
end_restriction | EndRestrictionResult(4 Felder) | bool | ❌ | Nur Erfolg/Fehler erforderlich |
check_trading_status | CheckStatusResult(2 Felder) | ParsedRestriction | None | ❌ | Nur einfacher Wrapper |
Ausgabeprüfliste (Checklist)
Stelle bei der Erstellung eines Ablaufvisualisierungsdokuments sicher, dass Folgendes enthalten ist:
- Übersicht auf oberster Ebene (Funktionsziel, beteiligte Module)
- Aufzählung der Szenarien (Erfolg/Fehler, manuell/automatisch, usw.)
- Schichten-Ablaufdiagramm (CLI → Flow → Data → Extern)
- Datenbanktabellenstruktur (falls betroffen)
- Beispieldaten und Abfragen (zum besseren Verständnis)
- Erklärung der Schlüsseldatenklassen (warum beibehalten/vereinfacht)
- Designgründe (warum so gemacht?)
- Zukünftige Erweiterungspunkte (TODO oder reservierte Schnittstellen)
Antimuster (Nicht so machen)
❌ Reine Textbeschreibung des Ablaufs
Zuerst wird die CLI-Funktion _do_xxx aufgerufen, dann ruft _do_xxx die Flow-Funktion xxx_flow auf, xxx_flow ruft dann die Data-Funktion xxx_repo.get auf...
✅ Mit ASCII-Diagramm
CLI (_do_xxx) → Flow (xxx_flow) → Data (xxx_repo.get) → SQLite
❌ Tabelle ohne Fokus
| Feld | Typ |
|---|---|
| id | int |
| name | str |
✅ Geschäftliche Bedeutung hervorheben
| Feld | Typ | Erläuterung | Geschäftsregel |
|---|---|---|---|
| id | int | Primärschlüssel | Automatisch generiert, global eindeutig |
| name | str | Fondsname | Nicht leer, wird angezeigt |
❌ SQL ohne Szenariobeschreibung
SELECT * FROM table WHERE id = ?;
✅ Mit Geschäftsszenario
-- Szenario: Benutzer fragt Details einer Einschränkungsaufzeichnung ab
SELECT * FROM fund_restrictions WHERE id = ?;
-- Szenario: DCA-Analyse prüft, ob ein bestimmter Tag 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: Beim Ausgeben von Codebeispielen die Codierungsstandards einhalten.
- architecture: Das Ablaufdiagramm muss die Schichtenarchitektur-Vorgaben einhalten.
- dev-workflow: Vor dem Analysieren des Ablaufs den relevanten Code und die Dokumentation lesen.
Zusammenfassung
Der Kernwert dieses Skills:
- Wiederverwendbare Vorlagen: Reduziert die Zeit für den Aufbau von Grund auf.
- Einheitlicher visueller Stil: ASCII-Diagramme + Tabellen + Rahmen.
- Geschäftsperspektive: Nicht nur der Codeablauf, sondern auch das „Warum“.
- Vergleichsanalyse: Vorher/Nachher, Mehrfachszenarien-Vergleich.
- Prüflisten-Check: Stellt sicher, dass keine wichtigen Informationen fehlen.
Nutzungshäufigkeit: Kann jedes Mal verwendet werden, wenn erklärt werden muss, „wie eine bestimmte Funktion funktioniert“.