Ich schaue mir gerne bestehende Setups und Frameworks an, um daraus Verbesserungen für mein eigenes AI-Coding-Setup abzuleiten. Eine CLAUDE.md, die gerade besonders viel Aufmerksamkeit bekommt, basiert auf den Learnings von Andrej Karpathy, Mitgründer von OpenAI. Das Repository dazu hat inzwischen über 100.000 Sterne auf GitHub.
In diesem Artikel zeige ich dir, welche Fehler Karpathy bei Coding Agents beobachtet hat, welche vier Prinzipien daraus entstanden sind und wie du sie in dein Projekt übernimmst.
Karpathys Beobachtung: Vom Programmieren zum Beschreiben
Anfang 2026 hat Karpathy auf X einen langen Post über seinen Entwicklungsworkflow geteilt, der über 7,7 Millionen Mal aufgerufen wurde. Sein Workflow, den er seit rund 20 Jahren pflegt, hat sich innerhalb kürzester Zeit massiv verändert: Er ist in wenigen Wochen von etwa 80 Prozent manuellem Coding und 20 Prozent Agent Coding auf 80 Prozent Agent Coding und 20 Prozent manuelle Korrekturen umgestiegen. Er programmiert also hauptsächlich in natürlicher Sprache.
Er schreibt auch offen, dass das seinem Ego ein bisschen wehtut. Das kann ich gut verstehen. Programmieren ist ein Handwerk, auf das Entwickler:innen zu Recht stolz sind. Wenn das plötzlich eine KI übernimmt, ist das erstmal ein Schlag.
Die neuen Fehler von Coding Agents
Diese neue Art zu entwickeln bringt laut Karpathy neue Arten von Fehlern mit sich. Früher waren es Syntaxfehler: ein vergessenes Semikolon, ein falscher Parameter. Die erkennst und behebst du schnell.
Heute beschreibt er die Fehler als „subtle conceptual errors that a slightly sloppy, hasty junior dev might do“. Also Fehler, die ein etwas schludriger, hastiger Junior-Entwickler machen würde. Sie sind schwer zu finden, weil der Code auf den ersten Blick plausibel aussieht. Konkret:
- Stille Annahmen: Die KI trifft Annahmen, ohne dich zu fragen. Sie wählt eine Interpretation und läuft los. Wenn sie unsicher ist, sagt sie nicht Bescheid.
- Übersehene Widersprüche: Gibst du widersprüchliche Anforderungen, fällt das dem Agenten nicht auf, oder er sagt es dir zumindest nicht.
- Keine Einordnung: Du fragst nach einer Lösung und bekommst eine. Aber keinen Hinweis, ob es einen einfacheren oder besseren Weg gibt und was du mit dem gewählten Ansatz aufgibst.
- Überkomplizierter Code: Der Agent schreibt 1.000 Zeilen, wo 100 gereicht hätten, und räumt nicht genutzten Code nicht auf.
- Ungefragte Änderungen: Er ändert Code oder Kommentare, die mit der eigentlichen Aufgabe nichts zu tun haben.
Dazu kommt, dass die Modelle laut Karpathy immer noch zu gefällig sind. Fragst du „Geht das nicht einfacher?“, lautet die Antwort „Ja, klar“, und aus tausend Zeilen werden ein paar hundert, ohne dass der Agent von sich aus innegehalten hätte. Genau das ist der frustrierende Teil: Die KI läuft im Zweifel los, statt sich zu fragen, ob das überhaupt die beste Variante ist.
Karpathys Empfehlung: Nutze für Features den Plan-Modus. Wenn Claude Code erst plant und dann umsetzt, macht er viele dieser Punkte deutlich besser. Wie das geht, beschreibe ich in meinem Artikel über die wichtigsten Claude Code Befehle.
Die CLAUDE.md als Gegenmittel
Außerdem kann man laut Karpathy mit Anweisungen in der CLAUDE.md nachhelfen. Diese Datei lädt Claude Code bei jeder neuen Session automatisch in seinen Kontext. Was dort steht, berücksichtigt Claude also jederzeit.
Welche Anweisungen genau, beschreibt Karpathy leider nicht. Der Entwickler Forrest Chang hat seine Beobachtungen deshalb in eine fertige CLAUDE.md übersetzt. Das Repository ist Open Source und übersichtlich aufgebaut. Wichtig: Es ist ein Community-Projekt, nicht Karpathys eigenes. Im Kern stehen vier Prinzipien.
Prinzip 1: Think Before Coding
Das erste Prinzip adressiert die stillen Annahmen. Es sagt im Kern:
- Bevor du etwas baust, nenne deine Annahmen.
- Wenn du unsicher bist, frag nach.
- Gibt es mehrere Interpretationen, zeig sie mir, statt still eine auszuwählen.
- Wenn es einen einfacheren Weg gibt, sag es.
Ein Beispiel: Du willst eine Funktion, die alle Benutzerdaten exportiert. Ohne diese Regel würde Claude wahrscheinlich einfach alle Nutzer mit allen vorhandenen Daten exportieren. Ohne zu fragen, welche Felder, welches Format und wie es mit dem Datenschutz aussieht. Mit der Regel stellt Claude zuerst Rückfragen, um die Anforderung zu verstehen.
Prinzip 2: Simplicity First
Hier geht es darum, Overengineering zu verhindern. Gefordert ist „minimum code that solves the problem, nothing speculative“, also der minimale Code, der das Problem löst:
- keine Abstraktionen auf Vorrat,
- keine Features, Flexibilität oder Konfigurationsmöglichkeiten, nach denen niemand gefragt hat,
- keine Fehlerbehandlung für Fälle, die gar nicht eintreten können,
- wenn 200 Zeilen geschrieben wurden, wo 50 reichen, neu schreiben.
Besonders gut gefällt mir die Prüffrage: Würde ein Senior Engineer sagen, dass das überkompliziert ist? Falls ja, vereinfachen.
Prinzip 3: Surgical Changes
Claude soll nur dort ändern, wo es nötig ist. Behebt er einen Bug, fasst er nur den Code an, der den Bug betrifft. Nicht alles drumherum und auch nicht die Kommentare. Außerdem passt er sich dem bestehenden Code-Stil an, auch wenn er es selbst anders machen würde.
Eingebaut ist ein einfacher Test: „Every changed line should trace directly to the user's request.“ Jede geänderte Zeile muss sich direkt auf deinen Auftrag zurückführen lassen.
Unabhängig davon solltest du dir die Diffs immer ansehen, also die Gegenüberstellung von altem und neuem Stand, die Claude Code bei jeder Änderung anzeigt. Am Ende bist du für den produzierten Code verantwortlich.
Prinzip 4: Goal-Driven Execution
Das vierte Prinzip geht auf einen Satz aus Karpathys Post zurück: „Don't tell it what to do, give it success criteria and watch it go.“ Sag dem Agenten nicht, was er tun soll, sondern gib ihm Erfolgskriterien.
Claude soll Aufgaben also selbst in überprüfbare Ziele umwandeln. Aus „Behebe den Fehler“ wird: Schreib einen Test, der den Fehler reproduziert, und bring ihn dann zum Laufen. Bei einem Refactoring heißt das: Die Tests müssen vorher und nachher grün sein.
Nach demselben Gedanken funktioniert übrigens auch der Befehl /goal in Claude Code, bei dem du Claude eine klare Zielbedingung gibst.
So übernimmst du die Regeln in dein Projekt
Du kannst die Prinzipien eins zu eins in deine eigene CLAUDE.md kopieren. Laut dem Repository gibt es zwei Wege.
Als Plugin für alle Projekte:
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills
Als CLAUDE.md in einem einzelnen Projekt. Für ein neues Projekt ohne CLAUDE.md:
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
Hast du schon eine CLAUDE.md, hängst du die Regeln an, statt sie zu überschreiben:
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
Die Originaldatei ist auf Englisch. Wenn du lieber eine kompakte deutsche Fassung in deine CLAUDE.md schreiben willst, kannst du dich an dieser Zusammenfassung orientieren:
## Arbeitsprinzipien
1. Erst denken, dann coden: Nenne deine Annahmen, bevor du etwas baust. Frag nach, wenn etwas unklar ist. Gibt es mehrere Interpretationen, zeig sie mir. Gibt es einen einfacheren Weg, sag es.
2. Einfachheit zuerst: Schreib nur den minimalen Code, der das Problem löst. Keine Abstraktionen, Features oder Konfiguration, nach denen ich nicht gefragt habe. Keine Fehlerbehandlung für unmögliche Fälle. Würde ein Senior Engineer den Code überkompliziert nennen, vereinfache ihn.
3. Chirurgische Änderungen: Ändere nur, was die Aufgabe erfordert. Lass angrenzenden Code und Kommentare in Ruhe. Halte dich an den bestehenden Stil. Jede geänderte Zeile muss sich direkt auf meinen Auftrag zurückführen lassen.
4. Zielgetrieben arbeiten: Übersetze Aufgaben in überprüfbare Ziele. Bei Bugs zuerst einen Test schreiben, der den Fehler reproduziert, dann den Test grün machen. Bei Refactorings müssen die Tests vorher und nachher grün sein.
Falls dein Projekt noch gar keine CLAUDE.md hat: In meiner Anleitung zur ersten Web-App mit Claude Code zeige ich, wie du sie mit /init anlegst.
Was die Regeln leisten und was nicht
Die vier Prinzipien sind kein Wundermittel. Claude Code wird auch danach Fehler machen. Sie grenzen die typischen Fehlerquellen aber deutlich ein und verändern, wie Claude an Aufgaben herangeht. Das erspart dir auf Dauer einige Kopfschmerzen.
Ein Thema aus Karpathys Post finde ich noch bemerkenswert: Er merkt selbst, dass seine Fähigkeit, Code manuell zu schreiben, langsam nachlässt. Code lesen und Code schreiben sind unterschiedliche Fähigkeiten. Wer hauptsächlich KI-generierten Code reviewt, kommt beim Schreiben aus der Übung. Das beschäftigt gerade viele Entwickler:innen, und ich halte diese ehrliche Beobachtung für wichtig.
Einordnung: Gute Regeln sind der Anfang eines Systems
Die Karpathy-Regeln setzen genau an den Schwächen an, die ich bei Coding Agents im Alltag auch sehe: stille Annahmen, zu viel Code und Änderungen, nach denen niemand gefragt hat. Für ein paar Minuten Aufwand bekommst du spürbar disziplinierteres Verhalten.
Eine CLAUDE.md allein reicht aber nicht, wenn du produktive Software entwickeln willst. Dann brauchst du einen strukturierten Entwicklungsprozess, in dem jedes Feature eine Spezifikation mit überprüfbaren Kriterien bekommt, bevor gebaut wird, und in dem die Umsetzung unabhängig geprüft wird. Die vier Prinzipien sind dafür ein guter Baustein.
