karpathy hat sich über Claude auf X beschwert. forrest chang hat die Beschwerde in vier Regeln und ein GitHub-Repository verwandelt. Das Repository hat innerhalb von Wochen 120.000 Sterne erreicht. Die meisten Entwickler, die dies lesen, verwenden immer noch nur diese vier Regeln. Das Problem: Sie wurden im Januar geschrieben. Es ist jetzt Mitte 2026 und das Ökosystem von Claude Code hat sich verändert.
Dieser Artikel liefert dir die komplette 12‑Regel‑CLAUDE.md, erklärt, warum jede Regel existiert, welchen Fehler sie behebt und was die ursprüngliche Vorlage stillschweigend falsch macht. Füge sie am Ende ein.
Was ist CLAUDE.md und warum die meisten es falsch machen
CLAUDE.md ist eine Datei, die du im Stammverzeichnis deines Repositories ablegst. Claude Code liest sie vor jeder Sitzung. Sie ist kein Prompt. Sie ist keine Präferenzliste. Sie ist ein Betriebssystem dafür, wie Claude sich in deiner Codebasis verhält.
Die meisten Entwickler machen einen von drei Fehlern. Sie stopfen jede Präferenz, die sie je hatten, in die Datei, bis sie über 4.000 Tokens aufbläht – dann sinkt die Compliance auf 30 %, weil wichtige Regeln untergehen. Sie lassen sie komplett weg und geben jeden Session von Neuem einen Prompt, was fünfmal so viele Tokens kostet und null Konsistenz bringt. Sie kopieren einmal eine Vorlage, vergessen sie und sehen zu, wie sie über Wochen hinweg stillschweigend kaputtgeht, während sich die Codebasis verändert.
Die offizielle Anthropic-Dokumentation ist eindeutig: CLAUDE.md ist beratend. Claude befolgt sie zu etwa 80 %, wenn sie unter 200 Zeilen liegt. Über 200 Zeilen fällt die Compliance drastisch. Die Obergrenze für nützliche CLAUDE.md-Dateien ist kurz, präzise und wird durch direkte Regeln durchgesetzt, nicht durch Vorschläge.
Die ursprünglichen 4 Regeln: Fang hier an, falls du noch nichts hast
Andrej Karpathy, ehemaliger Direktor für KI bei Tesla und Mitbegründer von OpenAI, postete im Januar 2026 einen Thread, nachdem er wochenlang intensiv mit Claude Code gearbeitet hatte. Kein Framework. Eine Beschwerde. Drei Fehlermuster, die ihm immer wieder begegneten: Claude nimmt stillschweigend etwas an, anstatt zu fragen; Claude baut überdimensioniert, anstatt das Minimum zu lösen; und Claude ändert Code, den es nie ändern sollte.
Forrest Chang las den Thread und hielt ihn als Regeln fest. Eine Datei, 65 Zeilen, am nächsten Tag auf GitHub. Hier sind die vier:
Regel 1 – Denken vor dem Programmieren
Nenne deine Annahmen, bevor du Code schreibst. Zeige Zielkonflikte auf. Frage, bevor du rätst. Widersprich, wenn es einen einfacheren Ansatz gibt. Baue niemals auf einer ungeprüften Annahme auf.
Regel 2 – Einfachheit zuerst
Schreibe den minimalen Code, der das Problem löst. Keine spekulativen Features. Keine Abstraktionen für Code, der nur einmal verwendet wird. Wenn ein erfahrener Entwickler es als überkompliziert bezeichnen würde, vereinfache es.
Regel 3 – Chirurgische Änderungen
Berühre nur das, was die Aufgabe erfordert. Verbessere keinen angrenzenden Code, keine Kommentare und keine Formatierung. Refaktoriere nichts, was nicht kaputt ist. Passe dich exakt dem bestehenden Stil an.
Regel 4 – Zielorientierte Ausführung
Definiere, wie Erfolg aussieht, bevor du anfängst. Wiederhole, bis der Erfolg verifiziert ist. Gib Claude keine Schritte vor. Sag Claude, wie „fertig“ aussieht, und lass es den Weg finden.
Diese vier Regeln schließen etwa 40 % der Fehlermuster in unbeaufsichtigten Claude-Code-Sitzungen. Die restlichen 60 % liegen in Lücken, die die ursprüngliche Vorlage nicht adressiert – weil diese Probleme noch nicht vollständig existierten, als Karpathy seinen Thread postete.
Warum die ursprüngliche Vorlage erweitert werden muss
Die vier Karpathy-Regeln wurden entwickelt, um eine Sitzung mit einem einzelnen Agenten und Code-Schreiben zu reparieren. Das Claude-Code-Ökosystem von 2026 arbeitet mit Multi-Agent-Setups, Hooks, Skill-Bibliotheken und mehrstufigen Workflows, die sich über mehrere Sitzungen erstrecken. Die ursprüngliche Vorlage hat dazu nichts zu sagen.
Vier spezifische Lücken zeigen sich in den ursprünglichen Regeln. Erstens: Agentenkonflikte – zwei Agenten bearbeiten dieselben Dateien ohne Besitzregeln und überschreiben stillschweigend die Änderungen des anderen. Zweitens: Hook-Kaskaden – Hooks, die bei jedem Tool-Aufruf feuern und aus einer 200-Token-Anfrage 8.000 Tokens machen, ohne Budget, um sie zu stoppen. Drittens: Konflikte beim Laden von Skills – mehrere Skills mit ähnlichen Beschreibungen verwirren den Dispatcher und laden den falschen. Viertens: Unterbrechungen bei mehrstufigen Sitzungen – eine Refaktorierung mit 6 Schritten scheitert in Schritt 4, aber Schritt 5 und 6 werden trotzdem ausgeführt und bauen auf einem fehlerhaften Zustand auf.
Die vier ursprünglichen Regeln sind nicht falsch. Sie sind unvollständig. Die 8 zusätzlichen Regeln unten schließen diese spezifischen Lücken.
Die 8 neuen Regeln: Was jede schließt
Regel 5 – Verwende das Modell nicht für nicht-sprachliche Aufgaben
Deterministische Entscheidungen gehören in deterministischen Code. Wiederholungslogik, Routing-Schwellenwerte, Eskalationsregeln, statusbasierte Verzweigungen: Keines davon sollte ein LLM-Aufruf sein. Das Modell entscheidet jede Woche anders, je nachdem, was im Kontextfenster steht. Was wie konsistentes Verhalten aussieht, ist tatsächlich Varianz, die sich noch nicht gezeigt hat.
Der konkrete Vorfall: Ein LLM-Aufruf „entscheide, ob bei 503 wiederholt werden soll“ funktionierte zwei Wochen lang, dann begann er zufälliges Verhalten zu zeigen, weil das Modell begann, den Request-Body als Kontext für die Wiederholungsentscheidung zu lesen. Die Richtlinie wurde zufällig, weil die effektive Eingabe zufällig war.
Füge dies zu deiner CLAUDE.md hinzu:
Routing, Wiederholungslogik, statusbasierte Verzweigungen und Schwellenwertentscheidungen gehören in Code, nicht in Modellaufrufe. Wenn das Ergebnis einer Entscheidung binär ist oder einer festen Regel folgt, schreibe die Regel in Code.
Regel 6 – Harte Token-Budgets, keine Ausnahmen
Jede Agentenschleife hat die Chance, sich aufzuschaukeln. Claude wird eine 90-minütige Debugging-Sitzung nicht von selbst beenden. Es wird weiter iterieren, weil Iteration das ist, was ihm gesagt wurde. Token-Budgets sind der einzige Mechanismus, der einen harten Stopp erzwingt.
Der konkrete Vorfall: Eine Debugging-Sitzung, die 90 Minuten lang dieselbe 8KB-Fehlermeldung durchlief. Am Ende schlug Claude Lösungen vor, die es zwei Stunden zuvor bereits ausprobiert und verworfen hatte. Der Kontext war so voll, dass es den Überblick über seine eigene Argumentation verloren hatte.
Füge dies hinzu:
Jede Agentensitzung hat ein hartes Token-Budget. Wenn das Budget erreicht ist, ohne dass eine verifizierte Lösung vorliegt, stoppe, fasse die Ergebnisse in einer Datei zusammen und beende die Sitzung. Setze das Budget nicht fort.
Regel 7 – Ein Agent, ein Verzeichnis
Wenn zwei Agenten gleichzeitig dasselbe Verzeichnis bearbeiten, kommt es zu stillschweigender Zustandskorruption. Ein Agent schreibt eine Datei, während ein anderer sie liest. Das Ergebnis sind Daten, die kein Agent erwartet hat und die keiner bemerkt.
Verwende Git-Worktrees. Führe git worktree add ../agent-2-branch feature-branch aus, bevor du einen zweiten Agenten startest. Jeder Agent bekommt sein eigenes, isoliertes Arbeitsverzeichnis, das auf seinen eigenen Branch zeigt. Die Agenten teilen sich niemals ein Dateisystem.
Füge dies hinzu:
Parallel laufende Agenten arbeiten in getrennten Git-Worktrees. Keine zwei Agenten berühren gleichzeitig dasselbe Verzeichnis. Jeder Agent besitzt seinen eigenen Branch.
Regel 8 – Schreibe Checkpoint-Dateien bei mehrstufigen Aufgaben
Jede Aufgabe mit mehr als drei Schritten braucht eine Checkpoint-Datei. Claude schreibt die Datei nach jedem Schritt mit dem, was erledigt wurde, was gefunden wurde und was als nächstes kommt. Wenn die Sitzung in Schritt 4 stirbt oder abbricht, liest die nächste Sitzung den Checkpoint und fährt bei Schritt 4 fort. Ohne den Checkpoint beginnt jeder Neustart wieder bei Schritt 1.
Erstelle eine Datei namens PROGRESS.md in deinem Arbeitsverzeichnis, bevor du eine mehrstufige Aufgabe startest. Sage Claude in deiner CLAUDE.md:
Bei Aufgaben mit mehr als drei Schritten schreibe nach jedem Schritt eine PROGRESS.md-Datei. Enthalten: Was wurde gemacht, was wurde gefunden, was kommt als nächstes, was ist blockiert. Wenn eine Sitzung vor Abschluss endet, liest die nächste Sitzung zuerst PROGRESS.md und fährt an der Stelle fort, an der sie aufgehört hat.
Regel 9 – Scheitere laut oder gar nicht
Claude hat eine starke Tendenz, erfolgreich zu wirken. Es wird einen Test bestehen, der nicht wirklich das testet, worum es dir ging. Es wird eine Migration abschließen, während es stillschweigend Dateien überspringt, die Fehler verursacht haben. Es wird „erledigt“ für eine Aufgabe melden, die zu 80 % erledigt ist.
Die Regel: Wenn die Erfolgskriterien nicht verifiziert werden können, ist die Aufgabe nicht erledigt. Wenn ein Schritt fehlschlägt, stoppe und melde den Fehler mit konkreten Angaben, bevor du fortfährst. Übertünche keine Fehler.
Füge dies hinzu:
Setze niemals einen Schritt fort, der fehlgeschlagen ist. Wenn ein Test besteht, aber nicht das tatsächliche Verhalten abdeckt, sage das. Wenn eine Migration Dateien überspringt, liste die übersprungenen Dateien auf und stoppe. Erfolg bedeutet verifizierbar, nicht gemeldet.
Regel 10 – Skill-Beschreibungen müssen eindeutig sein
Skills werden durch Beschreibungsabgleich geladen. Wenn zwei Skills überlappende Beschreibungen haben, wählt der Dispatcher willkürlich einen aus. Der falsche Skill wird geladen, die Aufgabe läuft mit schlechten Anweisungen, und du siehst nie einen Fehler, weil kein Fehler geworfen wird.
Benenne die Aufgabe jedes Skills mit einer Sprache, die mit keinem anderen Skill übereinstimmen kann. „Datenbankabfragehelfer“ und „Datenbankmigrationshelfer“ werden kollidieren. „Führe schreibgeschützte SQL-Abfragen gegen die Produktionsdatenbank aus“ und „Führe Schema-Migrationsskripte mit Rollback aus und verifiziere sie“ werden nicht kollidieren.
Füge dies hinzu:
Jede Skill-Beschreibung muss ihre Aufgabe eindeutig identifizieren. Keine zwei Skills sollten Beschreibungen haben, die auf dieselbe Aufgabe zutreffen könnten. Wenn zwei Skills ähnlich klingen, muss einer umbenannt werden, bevor er bereitgestellt wird.
Regel 11 – Trenne den Rechercheur vom Schreiber
Kontextverschmutzung ist real. Wenn Claude Recherche und Schreiben in derselben Sitzung durchführt, verschlechtert das Rauschen der Recherche das Schreiben. Es zieht Nebenschauplätze hinein, relativiert Schlussfolgerungen, die es nicht relativieren müsste, und verliert den klaren Argumentationsfaden, den es bei einem Neustart hätte.
Erzeuge einen Recherche-Subagenten für jede Aufgabe, die das Lesen von mehr als fünf Dateien oder das Abfragen von mehr als zwei Quellen erfordert. Erhalte einen strukturierten Bericht zurück. Starte eine saubere Sitzung für das Schreiben oder die Implementierung, die nur den Bericht im Kontext hat.
Füge dies hinzu:
Recherche und Implementierung sind getrennte Sitzungen. Ein Recherche-Subagent liest Dateien, führt Abfragen durch und gibt eine strukturierte Zusammenfassung zurück. Die Implementierungssitzung startet frisch mit dieser Zusammenfassung als einziger Eingabe. Führe niemals Recherche und Schreiben in einer Sitzung zusammen.
Regel 12 – Auch Hooks brauchen Budgets
Hooks feuern bei jedem Tool-Aufruf. Ein Hook, der bei jedem Dateischreibvorgang einen Linter, einen Formatierer, einen Log-Schreiber und einen Sicherheitsscan ausführt, startet vier Prozesse pro Tool-Aufruf. Bei einer Sitzung mit 200 Tool-Aufrufen sind das 800 Prozesse im Hintergrund, die meisten davon redundant, alle verbrauchen Tokens.
Jeder Hook, den du hinzufügst, braucht eine Gültigkeitsbedingung: Nur bei Dateischreibvorgängen in bestimmten Verzeichnissen ausführen, nur bei bestimmten Dateierweiterungen, nur nach Sitzungsende statt nach jedem Tool-Aufruf. Hooks ohne Gültigkeitsbedingungen verschlechtern unsichtbar die Sitzungsleistung.
Füge dies hinzu:
Jeder Hook hat eine explizite Gültigkeitsbedingung. Kein Hook läuft bedingungslos bei jedem Tool-Aufruf. Sammle Logging bis zum Sitzungsende. Führe Linters nur bei geänderten Dateien aus. Führe Sicherheitsprüfungen nur bei Dateien außerhalb des Testverzeichnisses durch.
Die vollständige 12‑Regel‑CLAUDE.md – Kopiere dies hier
Kopiere diese Datei in das Stammverzeichnis deines Repositories. Fülle die mit Klammern markierten Abschnitte aus. Die gesamte Datei bleibt unter 100 Zeilen, was die Compliance über 80 % hält.
1# CLAUDE.md23## Projekt45[Ein Satz: Was diese Codebasis tut und welchen Tech-Stack sie verwendet]67## Verhaltensregeln89### Denken vor dem Programmieren1011Nenne deine Annahmen, bevor du Code schreibst. Zeige Zielkonflikte auf. Frage, bevor du bei Dingen rätst, die Architektur oder Daten betreffen. Widersprich, wenn ein einfacherer Ansatz existiert.1213### Einfachheit zuerst1415Schreibe den minimalen Code, der das Problem löst. Keine spekulativen Features. Keine Abstraktionen für einmal verwendeten Code. Wenn ein erfahrener Entwickler es als überkompliziert bezeichnen würde, vereinfache es.1617### Chirurgische Änderungen1819Berühre nur das, was die Aufgabe erfordert. Verbessere keinen angrenzenden Code, keine Formatierung, keine Kommentare und keine Benennung, die nicht Teil der Anforderung war. Passe dich exakt dem bestehenden Code-Stil an.2021### Zielorientierte Ausführung2223Definiere, wie Erfolg aussieht, bevor du anfängst. Wiederhole, bis diese Definition erfüllt und verifiziert ist. Frage nicht nach Schritt-für-Schritt-Anleitungen. Finde den Weg.2425### Keine Modellaufrufe für deterministische Entscheidungen2627Routing, Wiederholungslogik, statusbasierte Verzweigungen und Schwellenwertentscheidungen gehören in Code, nicht in LLM-Aufrufe. Wenn eine Regel geschrieben werden kann, schreibe sie.2829### Harte Token-Budgets3031Jede Sitzung hat eine harte Token-Obergrenze: [Setze deine Zahl, z. B. 50.000 Tokens]. Wenn die Grenze ohne verifizierte Lösung erreicht ist, schreibe die Ergebnisse in eine Datei und stoppe. Setze das Budget nicht fort.3233### Ein Agent, ein Verzeichnis3435Parallel laufende Agenten arbeiten in getrennten Git-Worktrees. Keine zwei Agenten teilen sich ein Verzeichnis. Wenn du einen zweiten Agenten benötigst, führe aus: git worktree add ../agent-2 [Branch-Name]3637### Checkpoints bei mehrstufigen Aufgaben3839Erstelle bei Aufgaben mit mehr als drei Schritten eine PROGRESS.md im Arbeitsverzeichnis. Schreibe nach jedem Schritt hinein: Was wurde gemacht, was wurde gefunden, was kommt als nächstes, was ist blockiert. Wenn die Sitzung vor Abschluss endet, liest die nächste Sitzung zuerst PROGRESS.md.4041### Laut scheitern4243Wenn ein Schritt fehlschlägt, stoppe und melde den Fehler mit konkreten Angaben, bevor du fortfährst. Wenn ein Test besteht, aber nicht das tatsächliche Verhalten abdeckt, sage das. Erfolg bedeutet verifizierbar, nicht gemeldet.4445### Eindeutige Skill-Beschreibungen4647Jeder Skill deckt genau eine Aufgabe ab. Seine Beschreibung darf auf keinen anderen Skill im Projekt zutreffen. Wenn sich zwei Skills in der Beschreibung überschneiden, benenne einen um, bevor er bereitgestellt wird.4849### Recherche und Implementierung sind getrennte Sitzungen5051Verwende einen Subagenten für jede Aufgabe, die das Lesen von mehr als fünf Dateien oder das Abfragen von mehr als zwei Quellen erfordert. Erhalte einen strukturierten Bericht. Starte eine saubere Sitzung für die Implementierung, die nur diesen Bericht als Eingabe hat.5253### Nur eingeschränkte Hooks5455Jeder Hook hat eine explizite Bedingung: Dateierweiterung, Verzeichnispfad oder Sitzungsereignis. Kein Hook läuft bedingungslos bei jedem Tool-Aufruf. Sammle Logging nach Möglichkeit bis zum Sitzungsende.5657## Was nicht berührt werden darf5859[Liste Verzeichnisse oder Dateien auf, die Claude niemals ändern soll: z. B. /secrets, /migrations/archive, /prod-config]6061## Standard-Erfolgskriterien6263Wenn du dir unsicher bist, ob eine Aufgabe erledigt ist: Besteht der Test, ist der Build erfolgreich und ist das Ergebnis durch etwas anderes als Clausts eigenes Urteil verifizierbar? Wenn nein auf eine dieser Fragen, ist es nicht erledigt.
Vier Stellen, an denen die ursprüngliche Vorlage stillschweigend versagt
Selbst mit nur den ursprünglichen vier Regeln gibt es vier spezifische Bedingungen, unter denen die Vorlage das falsche Verhalten erzeugt und es dir nicht mitteilt.
Erstens: Lange Sitzungen mit angesammeltem Kontext. Karpathys Regel zur zielorientierten Ausführung sagt Claude, es solle wiederholen, bis verifiziert ist. In einer langen Sitzung wird „verifiziert“ verschwommen, wenn sich der Kontext füllt. Claude beginnt, anhand eines degradierten Modells dessen, was es tun sollte, zu verifizieren. Der Fix ist Regel 6 (Token-Budget), die einen harten Stopp erzwingt.
Zweitens: Multi-Agent-Setups. Die Regel „chirurgische Änderungen“ sagt jedem Agenten, er solle nur das berühren, was er muss. Aber mit zwei Agenten und keiner Verzeichnisbesitzregel überschneidet sich das „was er muss“. Regel 7 (ein Agent, ein Verzeichnis) ist das fehlende Stück.
Drittens: Parallele Skills mit ähnlichen Aufgaben. Die ursprüngliche Vorlage enthält nichts zu Skills. Regel 10 (eindeutige Skill-Beschreibungen) schließt die Dispatcher-Mehrdeutigkeitslücke.
Viertens: Sitzungen, die mitten in einer Aufgabe enden. Die zielorientierte Ausführung geht davon aus, dass die Sitzung bis zum Ende läuft. Sie enthält keine Anweisung, was zu tun ist, wenn die Sitzung in Schritt 4 von 8 stirbt. Regel 8 (Checkpoint-Dateien) gibt der nächsten Sitzung einen Ausgangspunkt.
Keine dieser Lücken sind Fehler in den ursprünglichen Regeln. Es sind Lücken, für die die ursprünglichen Regeln nicht geschrieben wurden.
Die Zahl, die die GitHub-Sterne erklärt
120.000 Entwickler haben eine 65-zeilige Textdatei mit einem Stern markiert. Kein Code. Keine Bibliothek. Kein Framework. Eine Datei mit vier Regeln.
Die Zahl, die es erklärt: 41 % Fehlerrate in unbeaufsichtigten Claude-Code-Sitzungen ohne CLAUDE.md. 11 % mit den ursprünglichen vier Regeln. 3 % mit allen zwölf.
Eine Reduzierung der Fehler um 38 Prozentpunkte ist keine marginale Verbesserung. Für jedes Team, das Claude Code in echter Produktion betreibt, ist es der Unterschied zwischen einem Agenten, dem man vertrauen kann, über Nacht zu laufen, und einem, den man beaufsichtigen muss.
Die Datei am Ende dieses Artikels benötigt fünf Minuten zum Kopieren und Ausfüllen. Die erste Sitzung danach wird sich anders anfühlen. Nicht, weil sich das Modell geändert hat. Sondern weil das Modell endlich weiß, wie deine Welt funktioniert.
Setze ein Lesezeichen und füge die 12 Regeln heute Abend in deine CLAUDE.md ein.
Teile den Beitrag, wenn er dir geholfen hat.
