Warum deine CLAUDE.md-Datei irgendwann außer Kontrolle gerät

Du kennst das wahrscheinlich: Du legst eine neue CLAUDE.md an. Nicht viel drin, nur ein paar nützliche Hinweise. Vielleicht eine Warnung vor dem merkwürdigen Authentifizierungs-Bug. Nichts Wildes.

Ein halbes Jahr später? Das Ding hat sich in ein 400-Zeilen-Monster verwandelt, das niemand mehr komplett durchblickt. Neue Regeln wurden oben drauf gepackt, alte nie hinterfragt, und irgendwo in der Mitte widersprechen sich zwei Anweisungen.

Dieses Phänomen hat jetzt auch die Forschungswelt erreicht – und die Ergebnisse sind alarmierend.

Die Zahlen hinter dem Chaos

Forscher haben über 247.000 Anweisungen in knapp 1.900 Repositories analysiert und dabei ein klares Muster entdeckt: Agentic Prompts wachsen und wachsen, ohne irgendwann geschrumpft zu werden. Im Schnitt kommen bei jedem Commit 4,9 neue Anweisungen hinzu. Minuspunkte? Fehlanzeige. Die Datei kennt nur eine Richtung.

Das Verblüffende: Je älter eine Anweisung wird, desto unwahrscheinlicher wird es, dass sie jemals gelöscht wird. Die Forscher nennen das "katastrophales Erinnern" – das genaue Gegenteil von dem, was man normalerweise als Problem betrachten würde.

Warum Aufräumen zur Mutprobe wird

Dahinter steckt eine einfache Kosten-Nutzen-Rechnung.

Neue Anweisungen reinzuschreiben ist billig. Du siehst ein Problem, du schreibst eine Lösung, fertig. Sofortiger Nutzen, minimaler Aufwand.

Aber eine alte Anweisung entfernen? Das ist ein ganz anderes Kaliber. Du musst verstehen, wo diese Anweisung überall relevant sein könnte. Du musst Wechselwirkungen mit allen anderen Regeln durchdenken. Du musst sichergehen, dass beim Entfernen nichts Subtiles kaputtgeht.

Die Forscher haben diesen kognitiven Aufwand als O(2^|D|) berechnet – bei |D| vorhandenen Anweisungen wächst er also exponentiell. Mit jeder neuen Regel verdoppelt sich quasi die Komplexität, wenn du auch nur eine einzige Anweisung hinterfragen willst.

Kein Wunder, dass Entwickler irgendwann aufgeben. Der Pfad des geringsten Widerstands führt immer nur nach oben: Neue Hinweise dran, alte drin lassen, Datei wächst.

Der unterschätzte Held: Kommentare

Hier wird es richtig spannend. Die Lösung kommt nicht von neuen prompting-Techniken oder besserer Models. Sie existiert seit den Anfängen der Programmierung: Kommentare.

Die Forscher haben einen interessanten Ansatz gewählt. Sie haben einen Standard-Benchmark kurzerhand umgedreht und geschaut, was passiert, wenn man Prompts mit Kommentaren anreichert, die die versteckte Logik erklären.

Das Ergebnis? Statt um 211 Prozent sind die Prompts nur noch um 1,4 Prozent gewachsen.

Und jetzt kommt der Clou: Diese Kommentare haben nicht nur das Wachstum gebremst. Die tatsächliche Leistung bei realen Aufgaben verbesserte sich um bis zu 23 Prozent.

Kommentare sind also nicht nur kosmetischer Schnickschnack. Sie sind tragende Strukturen, die AI-Assistenten helfen, Kontexte richtig zu interpretieren.

Warum wir gerade jetzt umdenken müssen

Wir erleben gerade einen fundamentalen Wandel darin, was "Code" bedeutet. Die Forscher stellen eine provokante Frage: "Wenn Englisch das neue Code ist – warum haben wir dann noch keine Kommentare?"

Guter Punkt. Seit Jahrzehnten wissen Entwickler: Code ohne Kommentare ist technische Schulden. Kommentare erklären das Warum, nicht nur das Was. Sie fangen Absichten ein, Edge Cases und Wissen, das man aus der Syntax allein nicht ableiten kann.

Aber in unserem Eifer, immer mehr an AI Coding Assistants zu delegieren, behandeln wir natürliche Sprache plötzlich wie etwas völlig anderes. Wir schreiben Imperative – tu dies, lass das, vergiss X nicht – ohne jemals zu erklären, warum.

Das Ergebnis sehen wir in diesen aufgeblähten CLAUDE.md-Dateien: Anweisungen, die keiner mehr ganz versteht, die sich gegenseitig widersprechen können, und die wachsen, ohne dass es eine Mechanismen zur Rationalisierung gibt.

Was du konkret tun kannst

Wenn du eine CLAUDE.md oder ähnliche Prompts pflegst, gibt dir die Forschung klare Empfehlungen:

Kommentiere deine Anweisungen, nicht nur deinen Code. Erkläre, warum eine Regel existiert. Dokumentiere Edge Cases. Fange die Begründung hinter Entscheidungen ein.

Mach periodische Aufräumsessions zur Routine. Nicht nur appenden – umschreiben. Die Forscher betonen ausdrücklich, dass vollständige Neuformatierungen eine der wenigen Möglichkeiten sind, das Wachstum tatsächlich zu stoppen.

Behandle deine AI-Anweisungen wie Onboarding-Dokumentation. Würdest du einem neuen Entwickler eine 400-Zeilen-Datei voller undifferenzierter Regeln in die Hand drücken? Dein AI-Assistent verdient dieselbe Klarheit.

Der Blick nach vorn

Der aktuelle Weg ist nicht nachhaltig. Jedes neue Projekt startet mit guten Vorsätzen und endet in einem Wartungsalbtraum. Aber die Lösung könnte simpler sein als gedacht: Schreibe für den Menschen (oder die AI), der deine Anweisungen in sechs Monaten liest – nicht nur für den, der heute gerade eine Frage beantwortet.

Kommentare sind kein Ballast. Sie sind das Fundament des Verständnisses.