Warum KI-generierter Code besser kommentiert werden muss — und wie

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

WARUM, nicht WAS — Schlecht: // Farbe auf blau setzen. Gut: // Brand-Accent aus CI — muss #1A56DB sein laut Style Guide. Der Code zeigt was passiert. Der Kommentar erklärt die Entscheidung.
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.
Abschnitte benennen — Bei Dateien über 100 Zeilen: Abschnittskommentare als Navigation. // ━━━ Scroll-Animationen ━━━, // ━━━ Mobile Navigation ━━━. Wie Kapitelüberschriften in einem Buch.
Nicht-offensichtliche Werte erklären — setPixelRatio(Math.min(devicePixelRatio, 2)) braucht: // Begrenzt Pixel Ratio auf 2 — verhindert GPU-Ueberlastung auf Retina-4x-Displays. Magic Numbers ohne Kontext sind Zeitbomben.
Löschen was offensichtlich ist — // Variable deklarieren vor const x = 5 ist Rauschen. Je weniger Kommentare du hast, desto mehr Aufmerksamkeit bekommt jeder einzelne.

III

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:

## 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.

Häufige Fragen

Soll Claude den Code kommentieren oder soll ich es manuell tun?

Beides. Claude kommentiert per CLAUDE.md-Regel automatisch. Du ergänzt nach Review die Stellen die Claude nicht kennen kann: Business-Kontext, verworfene Alternativen, Team-Entscheidungen.

Wie viele Kommentare sind zu viele?

Wenn mehr als 30 Prozent deiner Datei Kommentare sind, ist es zu viel. Gute Kommentare sind selten und wertvoll. Schlechte Kommentare sind häufig und ignoriert.

Hilft das wirklich gegen den Vibe Coding Hangover?

Ja — Kommentare sind Prävention. Der Hangover entsteht wenn du Code nicht mehr verstehst. Kommentare sind billiger als Debugging. Die Vanilla JS Checkliste hilft beim Verstehen, Kommentare beim Erinnern.

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

Quellen

CodeRabbit — AI Code Quality Analysis (Dezember 2025)

Anthropic — Claude Code Best Practices