Karpathy CLAUDE.md Regeln + 8 weitere: Das 12-Regel-Template im Test über 30 Codebases

Ende Januar 2026: Andrej Karpathy postet einen Thread auf X und beschwert sich darüber, wie Claude Code schreibt. Drei Fehlermuster — stille falsche Annahmen, Überkomplizierung, orthogonaler Schaden an Code, der nicht hätte angefasst werden sollen. Forrest Chang liest den Thread, verpackt die Beschwerden in 4 Verhaltensregeln in einer einzigen CLAUDE.md-Datei und veröffentlicht sie auf GitHub. 5.828 Stars am ersten Tag. 60.000 Bookmarks in zwei Wochen. 120.000 Stars bis Mitte 2026. Das am schnellsten wachsende Single-File-Repo des Jahres. Am 9. Mai 2026 postete ein verifizierter Entwickler mit dem Handle @mnilax (Mnimiy) einen ausführlichen X-Artikel mit einer der schärfsten Engineering-Thesen des Jahres: Sie testeten das Template 6 Wochen lang in 30 Codebases und fügten dann 8 weitere Regeln hinzu, um die Lücken zu schließen. 2,7 Millionen Views, 18.800 Bookmarks. Dies ist die vollständige Analyse — und was sie bedeutet, wenn Sie Claude innerhalb von Antigravity (oder einer anderen Agent-IDE) mit einer GEMINI.md oder AGENTS.md Datei nutzen.

Der ursprüngliche X-Post von @mnilax, den dieser Artikel aufschlüsselt — 2,7 Mio. Aufrufe, 18,8K Lesezeichen, 9. Mai 2026.

1. Der virale Moment

Karpathys ursprünglicher Thread war nicht präskriptiv. Es war eine Beschwerde — die Art, die Senior Engineers nach einem schlechten Nachmittag posten. Drei spezifische Fehlermuster:

1. Stille falsche Annahmen. Claude schlussfolgert, was man meinte, baut auf der falschen Schlussfolgerung auf und sagt es einem nie.
2. Überkomplizierung. Claude greift zu Abstraktionen, Layern, generischen Helpern. Der 4-Zeilen-Fix wird zu 40 Zeilen.
3. Orthogonaler Schaden. Claude "verbessert" Code, der nicht hätte angefasst werden sollen — Whitespace, Benennung, Formatierung, benachbarte Funktionen, nach denen nicht gefragt wurde.

Forrest Chang las den Thread und erledigte die Arbeit, die sonst niemand machte: Er schrieb auf, was Karpathy implizit forderte. Vier kurze, imperative Regeln. Eine Datei. 65 Zeilen. Öffentliches Repo. Das Tempo zählt — Forrest fügte keinen Kommentar hinzu, machte kein Framework daraus, monetarisierte es nicht. Nur die Regeln.

Es traf einen Nerv. Entwickler, die täglich mit Claude

2. The Original 4 Rules (Karpathy via Forrest Chang)

Hier ist die Basis — die Regeln in ihrer ursprünglichen Form. Wenn du heute noch keine CLAUDE.md hast, fange mit diesen an:

Mnimiys Daten: Diese vier schließen ~40 % der Fehlermodi in unbeaufsichtigten Claude Code-Sessions. Die restlichen ~60 % liegen in den Lücken, die das ursprüngliche Template nicht abdeckt.

3. Warum eine Erweiterung nötig war

Das Template wurde im Januar 2026 geschrieben. Das Claude Code-Ökosystem im Mai 2026 ist eine ganz andere Hausnummer. Der Artikel nennt vier Realitäten nach Januar, die die ursprünglichen 4 Regeln nicht abdecken:

• Agenten-Konflikte. Multi-Agenten-Setups, bei denen zwei Agenten dieselben Dateien bearbeiten und sich gegenseitig in die Quere kommen. Karpathys Regeln setzen einen einzelnen Autocomplete-Loop voraus. Echte Multi-Agenten-Orchestrierung benötigt Ownership-Regeln.
• Hook-Kaskaden. Claude Code-Hooks werden bei jedem Tool-Aufruf ausgelöst. Ohne Budgets macht ein gesprächiger Hook aus einem 200-Token-Request 8.000 Token.
• Konflikte beim Laden von Skills. Mehrere Skills mit überlappenden Beschreibungen verwirren den Description-Matching-Dispatcher. Das ursprüngliche Template enthält keine Informationen zur Disambiguierung.
• Mehrstufige Workflows. Ein 6-stufiges Refactoring, das bei Schritt 4 fehlschlägt, bedeutet, dass die Schritte 5 und 6 auf einem fehlerhaften Zustand aufbauen. Das ursprüngliche Template behandelt jeden Claude-Turn als One-Shot.

Mnimiy's These: Die ursprünglichen 4 sind grundlegend, nicht falsch. Sie sind unvollständig.

4. Die 8 neuen Regeln (jeweils mit dem Moment, der sie begründet hat)

Jede dieser Regeln resultiert aus einem spezifischen Vorfall innerhalb der Studie über 30 Codebases. Der Artikel zeigt erst den Moment, dann die Regel. Unten: dieselbe Struktur, zusammengefasst.

Regel 5 — Lassen Sie das Modell keine Nicht-Sprachaufgaben erledigen

Deterministische Entscheidungen gehören in deterministischen Code. Retry-Policies, Routing, Eskalationsschwellen — keine LLM-Aufrufe. Das Modell entscheidet jede Woche anders.

Der Moment: Ein LLM-Aufruf zur Entscheidung "Soll bei 503 ein Retry erfolgen?" funktionierte zwei Wochen lang, wurde dann aber unzuverlässig, weil das Modell begann, den Request-Body als Kontext für die Entscheidung zu interpretieren. Die Retry-Policy wurde willkürlich, da der Prompt effektiv zufällig war.

Regel 6 — Harte Token-Budgets, keine Ausnahmen

Jede Schleife birgt das Risiko, in einen 50.000-Token-Context-Dump auszuarten. Das Modell stoppt nicht von selbst. Budgets bieten eine harte Grenze.

Der Moment: Eine 90-minütige Debugging-Session, die über derselben 8KB-Fehlermeldung iterierte. Am Ende schlug Claude Fixes vor, die der Benutzer 40 Nachrichten zuvor bereits abgelehnt hatte. Ein Token-Budget hätte die Schleife in Minute 12 abgebrochen.

Regel 7 — Konflikte aufzeigen, nicht mitteln

Wenn zwei Teile der Codebase widersprüchlich sind, versucht Claude, es beiden recht zu machen. Das Ergebnis ist inkohärenter Code, der beide Muster kombiniert und unter keinem von beiden korrekt funktioniert.

Der Moment: A codebase had two error-handling patterns — async/await with try/catch and a global error boundary. Claude wrote code that did both. Errors got swallowed twice. 30 minutes to figure out.

Rule 8 — Read before you write

Karpathy's "Surgical Changes" tells Claude not to touch adjacent code. It doesn't tell Claude to understand adjacent code. Without this addition, Claude writes new code that conflicts with existing code 30 lines away.

The moment: Claude added a function next to an existing identical function it hadn't read. The new one won by import order. The original had been the source of truth for 6 months.

Rule 9 — Tests are not optional, but they're not the goal

Goal-Driven Execution treats "tests pass" as success. In practice, Claude writes code that passes shallow tests while breaking production behavior.

The moment: 12 tests for an auth function, all passing, auth broken in production. The tests checked the function returned something, not whether it returned the right thing. Function passed because it was returning a constant.

Rule 10 — Long-running operations need checkpoints

The original template assumes one-shot interactions. Real Claude Code work is multi-step — refactors across 20 files, features over a session, debugging across commits. Without checkpoints, one wrong turn loses all progress.

The moment: A 6-step refactor went wrong on step 4. Claude proceeded to do steps 5 and 6 on top of the broken state. Untangling took longer than redoing the whole refactor.

Rule 11 — Convention beats novelty

In a codebase with established patterns, Claude likes to introduce its own. Even when its way is "better," introducing a second pattern is worse than either pattern alone.

The moment: Claude introduced React hooks into a class-component codebase. The hooks worked. They also broke the codebase's testing patterns, which assumed componentDidMount. Half a day to remove and rewrite.

Regel 12 — Sichtbar scheitern, nicht lautlos

Die teuersten Fehler von Claude sehen wie Erfolge aus. Eine Funktion "funktioniert", gibt aber falsche Daten zurück. Eine Migration "wird abgeschlossen", hat aber 30 Datensätze übersprungen. Ein Test "besteht", aber die Assertion war falsch.

Der Moment: Claude meldete, dass eine Datenbank-Migration "erfolgreich abgeschlossen" wurde. Dabei wurden lautlos 14 % der Datensätze übersprungen, die eine Constraint-Verletzung verursachten. Das Überspringen wurde protokolliert, aber nicht gemeldet. Entdeckt wurde dies erst 11 Tage später, als die Berichte fehlerhaft erschienen.

5. Die Zahlen

Mnimiy verfolgte dieselben 50 repräsentativen Aufgaben in 30 Codebases über 6 Wochen hinweg in drei Konfigurationen: kein CLAUDE.md, die ursprünglichen 4 Regeln, die vollständigen 12 Regeln. Die Fehlerquote ist der Anteil der Aufgaben, die eine Korrektur oder einen Rewrite erforderten, um der Absicht zu entsprechen — gezählt über sieben verschiedene Fehlertypen (stille Fehlannahme, Over-Engineering, orthogonaler Schaden, lautloses Scheitern, Konventionsverletzung, Konflikt-Mittelung, verpasster Checkpoint).

Der drastische Rückgang (41 % → 3 %) ist das offensichtliche Ergebnis. Das interessante Ergebnis ist, dass der Wechsel von 4 auf 12 Regeln fast keinen Compliance-Overhead verursachte (78 % → 76 %), während die Fehlerquote um weitere 8 Punkte gesenkt wurde. Die neuen Regeln decken Fehlermuster ab, die die ursprünglichen 4 nicht berührten — sie konkurrieren nicht um dasselbe Aufmerksamkeitsbudget.

Dies ist das empirische Argument dafür, über 4 Regeln hinauszugehen. Wenn das Hinzufügen von Regeln die Compliance proportional verschlechtern würde, bliebe man bei 4. Das tut es aber nicht.

6. Wo das ursprüngliche Template lautlos scheitert

Vier Szenarien, in denen Karpathys 4 nicht ausreichen — noch bevor Regeln hinzugefügt werden. Der Artikel stellt explizit klar, dass das Original nicht falsch ist, sondern den Problemraum von Januar 2026 adressiert:

1. Langlaufende Agent-Tasks. Die Regeln zielen auf den Moment ab, in dem Claude Code schreibt. Sie sagen nichts über mehrstufige Pipelines aus. Keine Budget-Regel. Keine Checkpoint-Regel. Keine Fail-Loud-Regel. Pipelines driften.
2. Konsistenz über mehrere Codebases hinweg. "Match existing style" setzt einen einzigen Stil voraus. In einem Monorepo mit 12 Services muss Claude entscheiden, welchen Stil es wählt. Die ursprünglichen Regeln sagen ihm nicht, wie. Es wählt zufällig oder bildet den Durchschnitt.
3. Testqualität. Goal-Driven Execution betrachtet "tests pass" als Erfolg. Es wird nicht verlangt, dass Tests aussagekräftig sein müssen. Das Ergebnis sind Tests, die nichts Nützliches prüfen, aber Claude zuversichtlich machen.
4. Produktion vs. Prototyp. Dieselben 4 Regeln, die Produktionscode vor Over-Engineering schützen, bremsen auch Prototypen aus, die berechtigterweise 100 Zeilen spekulatives Scaffolding benötigen, um eine Richtung zu finden. "Simplicity First" greift bei Code in frühen Phasen zu weit.

7. Was nicht funktioniert hat (Die gescheiterten Experimente)

Möglicherweise der nützlichste Abschnitt des Artikels — nicht die Regeln, die es in die Auswahl geschafft haben, sondern die Muster, die explizit aussortiert wurden:

• Aus sozialen Medien gesammelte Regeln. Die meisten waren entweder Neufassungen von Karpathys 4 mit anderen Worten oder domänenspezifische Regeln ("always use Tailwind classes"), die sich nicht generalisieren lassen. Aussortiert.
• Mehr als 14 Regeln. Mnimiy testete bis zu 18. Jenseits von 14 sank die Compliance von 76 % auf 52 %. Das von Anthropic dokumentierte 200-Zeilen-Limit ist real — darüber hinaus wendet Claude Pattern-Matching auf "Regeln existieren" an, ohne sie tatsächlich zu lesen.
• Tooling-abhängige Regeln. "Always use eslint" schlägt stillschweigend fehl, wenn eslint nicht installiert ist. Ersetzt durch fähigkeitsunabhängige Formulierungen: "match the codebase's enforced style."
• Beispiele statt Regeln. Drei Beispiele verbrauchen so viel Kontext wie ~10 Regeln, und Claude neigt zum Overfitting. Regeln sind abstrakt, Beispiele sind spezifisch. Nutze Regeln.
• Vage Verstärkungswörter. "Sei vorsichtig," "denk scharf nach," "konzentriere dich wirklich." Compliance ~30 %, da nichts davon testbar ist. Ersetzt durch konkrete Imperative wie "Annahmen explizit benennen."
• Identitäts-Prompts. Claude zu sagen, es solle "Senior" sein, funktioniert nicht. Claude glaubt bereits, es sei Senior. Die Compliance-Lücke liegt zwischen Denken und Handeln. Imperative schließen sie; Identitäts-Prompts nicht.

8. Das mentale Modell

Reduziert man den Artikel auf seinen tragenden Satz, erhält man dies:

Das ordnet alles neu ein. Die meisten Entwickler behandeln CLAUDE.md als eine Datei für persönliche Präferenzen — eine Liste von stilistischen Vorlieben und Abneigungen, die mit der Zeit wächst. Das Argument des Artikels ist, dass eine Präferenzdatei die falsche Form ist. Die richtige Form ist eine Liste von Fehlermodi, auf die du tatsächlich gestoßen bist, mit einer Regel pro Modus.

Es erklärt auch, warum der Artikel mit einer kontraintuitiven Empfehlung endet:

Eine CLAUDE.md mit 6 Regeln, die auf deine echten Fehlermodi abgestimmt ist, schlägt eine mit 12 Regeln, von denen du 6 nie brauchen wirst.

Kopiere nicht alle 12 hinein, nur weil es jemand auf X gesagt hat. Lies sie, behalte die, die zu Fehlern passen, die du gemacht hast, und lass den Rest weg.

9. Übertragung auf Antigravity (GEMINI.md / AGENTS.md)

Der Artikel ist auf Claude fokussiert, aber die Abstraktion ist portabel. Antigravity liest prozedurale Regeln aus zwei Dateien im gleichen Format:

• GEMINI.md — die Gemini-spezifische System-Prompt-Datei. Siehe unseren GEMINI.md Guide.
• AGENTS.md — das toolübergreifende Format (funktioniert mit Claude Code, Cursor, Antigravity). Siehe unseren AGENTS.md Leitfaden.

Beide sind empfehlend, nicht erzwingend, beide stoßen bei etwa 200 Zeilen an ihre Grenzen, bevor die Einhaltung nachlässt, und beide folgen derselben Disziplin: "Regel nennen, keine Beispiele, keine vagen Verstärker". Die 12 Regeln lassen sich im Wesentlichen unverändert übertragen. Spezifische Antigravity-Überlegungen:

1. Regel 6 (Token-Budgets) wird kritisch, nicht optional. Das Antigravity-Kontingent verbraucht sich schneller als bei Claude Code. Kombiniere die Regel mit unserem Token-Reduktions-Playbook.
2. Regel 10 (Checkpoints) lässt sich auf den Agent Manager von Antigravity übertragen. Wenn ein Multi-Agent-Durchlauf bei Schritt 4 schiefläuft, möchtest du den Agent beenden und von einem vorherigen Artefakt aus fortfahren können, anstatt ganz von vorne zu beginnen.
3. Regel 7 (Konflikte offenlegen) hilft bei Modell-Wechseln. Wenn du mitten in der Sitzung zwischen Gemini und Claude Opus wechselst (wie in unserer Modell-Wechsel-Analyse), übernimmt das neue Modell oft veralteten Kontext vom alten und versucht, inkompatible Muster in Einklang zu bringen.
4. Regel 12 (sichtbares Scheitern) wird bei Autopilot am meisten unterschätzt. Wenn du auto-acceptausführst, summieren sich stille Fehler über mehrere Cmd-Enter-Zyklen hinweg, bevor du sie bemerkst. Zwinge den Agent dazu, jeden übersprungenen Schritt offenzulegen.

Gleiches Template, andere Runtime, gleiche Logik.

10. Das vollständige 12-Regeln-Template (bereit zum Kopieren und Einfügen)

Speichere dies als CLAUDE.md (oder GEMINI.md oder AGENTS.md) im Repo-Root. Der Originalartikel merkt an: Halte die Gesamtdateigröße kombiniert unter 200 Zeilen, einschließlich aller projektspezifischen Ergänzungen unten; darüber hinaus lässt die Compliance nach.

Das ist die Datei. Zwei Dinge sind damit zu tun:

1. Lies die 12 Punkte ehrlich durch. Welche davon entsprechen Fehlern, die du diesen Monat tatsächlich gemacht hast? Behalte diese. Verwirf den Rest. Eine Datei mit 6 Regeln, die auf deine Fehlermuster abgestimmt ist, schlägt eine Datei mit 12 Regeln, die du nie auslösen wirst.
2. Füge unten projektspezifische Regeln hinzu. Stack-specific ("always use the Repository pattern"), test-runner ("run pnpm test:unit before reporting done"), error patterns. Keep the total under 200 lines.

11. FAQ