KI-Code besser kommentieren: 5 Regeln

KI-generierter Code funktioniert meistens. Aber er erklärt sich nie. Claude schreibt keine Kommentare die sagen warum etwas so gelöst wurde, nur was passiert. Nach zwei Wochen verstehst du deinen eigenen vibe-gecodeten Code nicht mehr. Das ist kein Versagen, das ist das strukturelle Problem von AI-Code: Er hat kein Gedächtnis für deine Absichten.

Frequently Asked Prompts

Kommentieren

Kommentiere diesen Code. Für jeden Abschnitt: ein Kommentar der erklärt WARUM dieser Ansatz gewählt wurde, nicht WAS passiert. Zielgruppe: jemand der den Code in 3 Monaten zum ersten Mal liest.

Review

Prüfe diesen Code auf Wartbarkeit. Markiere Stellen die in 3 Monaten unverständlich sein werden und schlage Kommentare oder Refactoring vor.

In CLAUDE.md

Regel für deine CLAUDE.md: "Kommentiere jeden Codeblock mit einem Satz der erklärt warum dieser Ansatz gewählt wurde. Keine Kommentare die nur die Syntax beschreiben."

Das Problem: Code ohne Kontext

AI-Code hat kein Gedächtnis. Claude weiß nicht dass du letzte Woche eine andere Lösung verworfen hast. Cursor weiß nicht dass dieser Workaround wegen eines Safari-Bugs existiert. Copilot weiß nicht dass diese Funktion absichtlich langsamer ist weil die schnelle Version einen Edge Case nicht abfing.

Das Ergebnis: Code der funktioniert aber nicht erklärt warum er so funktioniert. CodeRabbit (Dezember 2025) dokumentiert dass AI-Code 1,7-mal mehr Issues hat als menschlicher Code, und Logic/Correctness-Probleme 75 Prozent häufiger auftreten. Ein Großteil davon sind keine Syntax-Fehler sondern: der Code tut nicht was du dachtest weil die Absicht nirgends dokumentiert ist.

5 Regeln für nützliche Kommentare

1. WARUM, nicht WAS, Schlecht: // Farbe auf blau setzen. Gut: // Brand-Accent aus CI, muss #2d5fc2 sein laut Style Guide. Der Code zeigt was passiert. Der Kommentar erklärt die Entscheidung.
2. Workarounds markieren, Jeder Workaround braucht einen Kommentar: // Safari 17.2 rendert backdrop-filter nicht korrekt bei position:fixed, daher opacity-Fallback. Ohne diesen Kommentar löscht jemand den Workaround und der Bug kehrt zurück.
3. Abschnitte benennen, Bei Dateien über 100 Zeilen: Abschnittskommentare als Navigation. // ━━━ Scroll-Animationen ━━━, // ━━━ Mobile Navigation ━━━. Wie Kapitelüberschriften in einem Buch.
4. Nicht-offensichtliche Werte erklären, setPixelRatio(Math.min(devicePixelRatio, 2)) braucht: // Begrenzt Pixel Ratio auf 2, verhindert GPU-Überlastung auf Retina-4x-Displays. Magic Numbers ohne Kontext sind Zeitbomben.
5. Löschen was offensichtlich ist, // Variable deklarieren vor const x = 5 ist Rauschen. Je weniger Kommentare du hast, desto mehr Aufmerksamkeit bekommt jeder.

Der CLAUDE.md-Trick

Statt nach jeder Generierung manuell zu kommentieren: Baue die Kommentar-Regel direkt in deine CLAUDE.md ein. So generiert Claude ab sofort kommentierten Code:

CLAUDE.mdregeln## Code-Regeln
- Jeder Codeblock: 1 Kommentar der WARUM erklärt
- Workarounds: Browser + Version + Bug beschreiben
- Magic Numbers: immer mit Erklärung
- Abschnitte ab 100 Zeilen: Navigationskommentare
- Keine Kommentare die nur Syntax beschreiben

Das ist Context Engineering für Wartbarkeit: Einmal definieren, in jedem Output automatisch anwenden. Die Investition sind 5 Zeilen in einer Datei, der Return ist lesbarer Code für die nächsten 12 Monate.

Zum Thema: Web Dev for Vibe Coders, Der komplette Guide 2026

Quellen

• CodeRabbit, AI Code Quality Analysis (Dezember 2025)
• Anthropic, Claude Code Best Practices

Verwandt: Debugging-Strategien für KI-Code