ellmos-ai Bugfix-Protokoll: Systematisches 6-Phasen Debugging
Strukturiertes Vorgehen bei Bugs — von der Symptom-Analyse bis zur Verifikation. Verhindert planloses Herumprobieren und stellt sicher, dass Fixes nachhaltig sind.
Uebersicht
| Phase | Name | Ziel | Max. Zeit |
|---|---|---|---|
| 1 | Schnell-Checks | Offensichtliche Ursachen ausschliessen | 2 min |
| 2 | Diagnose | Ursache lokalisieren | 10 min |
| 3 | Isolierter Test | Bug reproduzierbar machen | 5 min |
| 4 | Fix | Minimale Korrektur | 10 min |
| 5 | Verifikation | Fix pruefen + Seiteneffekte | 5 min |
| 6 | Dokumentation | Wissen sichern | 2 min |
20-Minuten-Regel: Wenn nach 20 Minuten kein Fortschritt → Ansatz wechseln oder Hilfe holen.
Phase 1: Schnell-Checks (2 min)
Bevor du tief einsteigst — pruefe die haeufigsten Ursachen:
Checkliste
- Syntax-Fehler? Fehlermeldung genau lesen, Zeile pruefen
- Import-Fehler? Modul installiert? Richtiger Name? Circular Import?
- Tippfehler? Variablen-/Funktionsnamen korrekt?
- Falscher Datentyp? String statt Int? None wo Objekt erwartet?
- Veralteter Cache?
__pycache__loeschen, Neustart - Falsche Umgebung? Richtiges venv aktiv? Richtige Python-Version?
- Encoding? UTF-8 vs. cp1252 (Windows-Klassiker)
Schnell-Aktionen
# Cache leeren
find . -name "__pycache__" -type d -exec rm -rf {} + 2>&1
find . -name "*.pyc" -delete 2>&1
# Imports pruefen
python -c "import modulname"
# Syntax pruefen
python -m py_compile datei.py
Phase 2: Diagnose (10 min)
Strategie: Von aussen nach innen
- Fehlermeldung analysieren — Traceback von unten nach oben lesen
- Letzte Aenderungen pruefen —
git diff,git log --oneline -10 - Diagnose-Tools einsetzen — Eigene Diagnose-Tools je nach Projekt verwenden
Diagnose-Tools (Beispiele)
Je nach Projekt koennen spezialisierte Diagnose-Skripte hilfreich sein:
| Tool | Zweck |
|---|---|
import_diagnose.py |
Import-Probleme analysieren |
method_analyzer.py |
Methoden-Signaturen pruefen |
env_checker.py |
Umgebungsvariablen/Pfade validieren |
Hinweis: Eigene Diagnose-Tools je nach Projekt erstellen oder vorhandene Projekt-Tools nutzen. Wichtig ist das systematische Vorgehen, nicht das spezifische Tool.
Debugging-Techniken
# 1. Print-Debugging (schnell aber effektiv)
print(f"DEBUG: variable={variable!r}, type={type(variable)}")
# 2. Breakpoint (interaktiv)
breakpoint() # Python 3.7+
# 3. Traceback erweitern
import traceback
traceback.print_exc()
# 4. Logging statt Print
import logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)
logger.debug(f"State: {state!r}")
Phase 3: Isolierter Test (5 min)
Minimal Reproducible Example (MRE)
Ziel: Bug mit minimal Code reproduzieren.
# test_bug.py — Minimaler Reproduktions-Test
"""
Bug: [Kurze Beschreibung]
Erwartet: [Was sollte passieren]
Tatsaechlich: [Was passiert stattdessen]
"""
# Minimaler Setup
# ... nur das Noetigste
# Bug-Ausloeser
# ... exakter Code der den Bug triggert
# Erwartetes Ergebnis
# assert result == expected, f"Got {result}"
Isolations-Strategien
- Neue Datei: Bug in eigener Datei reproduzieren
- Abhaengigkeiten entfernen: Eine nach der anderen, bis Bug verschwindet
- Halbieren: Code-Block halbieren, pruefen welche Haelfte den Bug enthaelt
- Git Bisect:
git bisect start,git bisect bad,git bisect good <commit>
Phase 4: Fix (10 min)
Prinzipien
- Minimal: Aendere so wenig wie moeglich
- Verstehen: Nie blind fixen — verstehe WARUM es kaputt ist
- Eine Sache: Ein Fix pro Commit, nicht mehrere Probleme gleichzeitig
- Rueckwaerts-kompatibel: Bestehende Funktionalitaet nicht brechen
Fix-Muster
# SCHLECHT: Symptom behandeln
try:
result = broken_function()
except: # Alles schlucken
result = default_value
# GUT: Ursache beheben
def broken_function():
if input_data is None: # Eigentliche Ursache: None-Check fehlte
return default_value
return process(input_data)
Haeufige Fix-Kategorien
| Kategorie | Typischer Fix |
|---|---|
| None/Null | Guard-Clause: if x is None: return default |
| Index-Fehler | Bounds-Check: if i < len(lst) |
| Type-Fehler | Explizite Konvertierung: str(x), int(x) |
| Import-Fehler | Pfad korrigieren, Paket installieren |
| Encoding | UTF-8 explizit angeben: encoding='utf-8' |
| Race Condition | Lock/Mutex, oder Reihenfolge aendern |
| State-Bug | Initialisierung pruefen, Reset einfuegen |
Phase 5: Verifikation (5 min)
Checkliste
- Bug ist gefixt: Originales Problem tritt nicht mehr auf
- MRE besteht: Isolierter Test laeuft durch
- Keine Regression: Bestehende Tests laufen noch
- Edge Cases: Leere Eingabe, None, grosse Daten getestet
- Projekt-Tools: Im Projekt-Tools-Verzeichnis nachschauen ob es relevante Test-/Validierungstools gibt
Test-Befehle
# Unit-Tests
python -m pytest tests/ -v
# Nur betroffene Tests
python -m pytest tests/test_modul.py -v -k "test_name"
# Type-Check
python -m mypy datei.py
# Lint
python -m flake8 datei.py
Phase 6: Dokumentation (2 min)
Bug-Report Template
## Bug-Report: [Kurztitel]
**Datum:** YYYY-MM-DD
**Schwere:** kritisch / hoch / mittel / niedrig
**Komponente:** [Modul/Datei]
### Symptom
[Was der User sieht / Fehlermeldung]
### Ursache
[Technische Root-Cause]
### Fix
[Was geaendert wurde + warum]
### Betroffene Dateien
- `datei1.py` — [Aenderung]
- `datei2.py` — [Aenderung]
### Praevention
[Wie kann dieser Bug-Typ in Zukunft vermieden werden?]
Commit-Message Format
fix: [Kurze Beschreibung des Fixes]
Ursache: [Root-Cause in einem Satz]
Fix: [Was geaendert wurde]
Test: [Wie verifiziert]
PyQt6 / GUI Debugging — Haeufige Fallen
Diese Sektion ist relevant fuer Desktop-GUI-Projekte mit PyQt6/PySide6.
Top 5 PyQt6 Traps
| Trap | Problem | Loesung |
|---|---|---|
| Signal-Slot Disconnect | Signal connected aber Handler laeuft nicht | print in Handler, Signature pruefen |
| Thread-Safety | GUI-Update aus Worker-Thread | QMetaObject.invokeMethod oder Signal nutzen |
| Layout-Cascade | Widget unsichtbar/falsch platziert | widget.show(), Layout-Hierarchie pruefen |
| Event-Loop Block | GUI friert ein | Langzeit-Ops in QThread auslagern |
| Garbage Collection | Widget verschwindet ploetzlich | Referenz als self.widget halten |
PyQt6 Debug-Helfer
# Widget-Hierarchie ausgeben
def dump_widget_tree(widget, indent=0):
print(" " * indent + f"{widget.__class__.__name__}: {widget.objectName()}")
for child in widget.findChildren(QWidget):
if child.parent() == widget:
dump_widget_tree(child, indent + 2)
# Signal-Debugging
from PyQt6.QtCore import QObject
original_connect = QObject.connect
def debug_connect(self, *args, **kwargs):
print(f"CONNECT: {self.__class__.__name__} -> {args}")
return original_connect(self, *args, **kwargs)
Quick Reference
BUG GEFUNDEN?
│
▼
[Phase 1: Schnell-Checks] ──── Offensichtlich? → FIX
│
▼
[Phase 2: Diagnose] ────────── Ursache klar? → Phase 4
│
▼
[Phase 3: Isolierter Test] ── Reproduzierbar? → Phase 4
│ │
│ Nicht reproduzierbar?
│ │
│ Logging einbauen,
│ auf erneutes Auftreten warten
▼
[Phase 4: Fix] ─────────────── Minimal + verstanden
│
▼
[Phase 5: Verifikation] ────── Tests gruen? → Phase 6
│ │
│ Tests rot? → Zurueck zu Phase 4
▼
[Phase 6: Dokumentation] ───── Bug-Report + Commit
20-Minuten-Regel
Wenn du nach 20 Minuten festhaengst:
- Ansatz wechseln — Andere Debugging-Technik probieren
- Rubber Duck — Problem laut erklaeren (oder aufschreiben)
- Pause — 5 Minuten weggehen, dann mit frischem Blick
- Hilfe holen — Kollege fragen, Stack Overflow, Dokumentation
- Zuruecksetzen —
git stash, komplett neu anfangen