DAA Code Review Fähigkeit
Analysiere Python-Code, Markdown-Dokumentation und Mermaid-Diagramme auf Qualitätsprobleme. Kombiniert externe Linter (ruff) mit Claudes Analyse, um ein umfassendes Code-Review mit Korrekturvorschlägen zu liefern. Sollte nicht nur darin bestehen, ruff und andere Linter auszuführen, sondern den Code stattdessen auf Konformität mit guter Softwareentwicklungspraxis (SOLID, DRY, YAGNI, Einfachheit statt Komplexität), Sicherheitslücken und aussagekräftige Variablenbenennung zu prüfen, z.B. Nicht so:
pkb = p_key.private_bytes(
encoding=serialization.Encoding.DER,
format=serialization.PrivateFormat.PKCS8,
encryption_algorithm=serialization.NoEncryption(),
)
Sondern so:
private_key_bytes = p_key.private_bytes(
encoding=serialization.Encoding.DER,
format=serialization.PrivateFormat.PKCS8,
encryption_algorithm=serialization.NoEncryption(),
)
Schnellstart
Python-Code analysieren
from python_analyzer import analyze_python, analyze_python_file
from report_generator import generate_console_report, generate_markdown_report
from models import ReviewReport
# Einen Code-Snippet analysieren
result = analyze_python(code_string)
# Eine Datei analysieren
result = analyze_python_file(Path("src/module.py"))
# Bericht erstellen
report = ReviewReport(results=[result], title="Code Review")
generate_console_report(report) # Konsolenausgabe
markdown = generate_markdown_report(report) # Markdown-Zeichenkette
Markdown analysieren
from markdown_analyzer import analyze_markdown, analyze_markdown_file
result = analyze_markdown(content)
# oder
result = analyze_markdown_file(Path("README.md"))
Mermaid-Diagramme analysieren
Für die Mermaid-Validierung verwende Claudes Verständnis in Kombination mit einer Websuche nach der neuesten Syntax. Siehe mermaid-checks.md.
Arbeitsablauf
- Code empfangen – Von einem Dateipfad oder eingefügtem Snippet
- Dateityp erkennen – Python (.py), Markdown (.md) oder Mermaid (.mmd, Codeblöcke)
- Analyse durchführen – Zuerst externe Linter, dann Claudes Analyse
- Bericht erstellen – Sowohl Konsolen- als auch Markdown-Formate
- Bericht speichern – Markdown-Bericht in
docs/code_reviews/{YYYY-MM-DD}_{dateiname}.mdschreiben (Verzeichnis ggf. erstellen) - Korrekturen prüfen – Korrekturvorschläge dem Benutzer präsentieren
- Korrekturen anwenden – Mit Benutzerfreigabe (flexible Genehmigungsmodi)
- README prüfen – Vor dem Pushen sicherstellen, dass README.md die aktuellen Änderungen widerspiegelt (neue Funktionen, geänderte APIs, aktualisierte Abhängigkeiten, geänderte Konfiguration)
Analysefähigkeiten
Python (über ruff + Claude)
| Kategorie | Beispiele | Schweregrad |
|---|---|---|
| PEP8 | Zeilenlänge, Einrückung, Leerzeichen | WARNING/INFO |
| Ungenutzter Code | Nicht verwendete Importe, Variablen, Argumente | WARNING |
| Typannotationen | Fehlende Annotationen bei Funktionen | INFO |
| Docstrings | Fehlende/fehlerhafte numpy-ähnliche Docstrings | INFO |
| Komplexität | Funktionen mit hoher zyklomatischer Komplexität | INFO |
| Laufzeitfehler | Nicht definierte Namen, Syntaxfehler | ERROR |
| Importe | Uns organisierte Importe, verbotene Importe | INFO |
Markdown
| Überprüfung | Beschreibung | Schweregrad |
|---|---|---|
| Überschriftenstruktur | Korrekte h1→h2→h3-Abfolge | WARNING |
| Defekte Links | Dateiverknüpfungen, die nicht existieren | ERROR |
| Fehlender Alternativtext | Bilder ohne Barrierefreiheitstext | WARNING |
| Formatierung | Nachgestellte Leerzeichen, Leerzeilen | INFO |
| Codeblöcke | Fehlende Sprachkennung | INFO |
| Kodierungsfehler | UTF-8-Zeichen, die als ×, âœ", usw. erscheinen | ERROR |
Mermaid
Vor der Validierung im Web nach der aktuellen Mermaid.js-Dokumentation suchen. Prüfen:
- Diagrammtypdeklaration
- Knoten-/Kantensyntax
- Strukturelle Korrektheit
- Beziehungsdefinitionen
Ausgabeformate
Konsole (Interaktiv)
Farbige Ausgabe mit Schweregrad-Indikatoren:
- ✗ FEHLER (rot) – Muss behoben werden
- ⚠ WARNUNG (gelb) – Sollte behoben werden
- ℹ INFO (blau) – Kann behoben werden
Markdown-Bericht
Gespeichert unter docs/code_reviews/{YYYY-MM-DD}_{dateiname}.md. Bei Dateiübergreifenden Überprüfungen einen beschreibenden Namen verwenden (z. B. 2026-03-02_vollstaendiges_repo_review.md).
Strukturierter Bericht mit:
- Zusammenfassungsstatistik
- Status-Badge (Bestanden/Nicht bestanden)
- Problem-Tabelle pro Datei
- Ausklappbare Problemdetails
- Kategorieaufschlüsselung
Fehlerkorrektur
Korrekturen können genehmigt werden:
- Auf einmal – Alle automatisch korrigierbaren Probleme anwenden
- Nach Kategorie – Alle PEP8-Korrekturen anwenden, Docstrings überspringen
- Nach Schweregrad – Erst Fehler beheben, dann Warnungen
- Nach Datei – Nur bestimmte Dateien korrigieren
- Einzeln – Jede Korrektur einzeln prüfen
Siehe fix-workflow.md für den detaillierten Arbeitsablauf.
Referenzdokumentation
- python-checks.md – Python-Regel-Details
- markdown-checks.md – Markdown-Regel-Details
- mermaid-checks.md – Mermaid-Validierungsanleitung
- fix-workflow.md – Arbeitsablauf zur Korrekturfreigabe
Beispielhafte Verwendungsmuster
Vollständige Repository-Überprüfung
Benutzer: "Überprüfe die Codequalität in meinem Projekt"
1. Liste Python- und Markdown-Dateien auf
2. Analysiere jede Datei
3. Fasse in einem ReviewReport zusammen
4. Zeige Konsolenzusammenfassung
5. Speichere Bericht in docs/code_reviews/{YYYY-MM-DD}_vollstaendiges_repo_review.md
6. Biete an, Korrekturen anzuwenden
Schnelle Code-Überprüfung
Benutzer: [fügt Code-Snippet ein]
"Gibt es damit Probleme?"
1. Snippet direkt analysieren
2. Probleme inline melden
3. Spezifische Korrekturen vorschlagen
Pre-Commit-Überprüfung
Benutzer: "Überprüfe diese Dateien, bevor ich committe"
1. Angegebene Dateien analysieren
2. Fokus auf Fehler und Warnungen
3. Bei Fehlern blockieren
4. Schnellkorrekturen anwenden, falls genehmigt
5. Prüfen, ob README basierend auf den Änderungen aktualisiert werden muss
6. README aktualisieren, wenn neue Funktionen, APIs oder Abhängigkeiten geändert wurden
Skripte
| Skript | Zweck |
|---|---|
models.py | Datenstrukturen (Issue, Severity, AnalysisResult) |
python_analyzer.py | Python-Analyse mit ruff |
markdown_analyzer.py | Markdown-Qualitätschecks |
report_generator.py | Konsolen- und Markdown-Berichtserstellung |
Anforderungen
- Python 3.10+
- ruff (über pip installiert)
- Webzugriff für die Mermaid-Dokumentationssuche