Sumit Pandey hat ein Phänomen seziert, an dem man schwer vorbeikommt: eine einzige CLAUDE.md-Datei aus dem Repository andrej-karpathy-skills hat ohne eine Zeile Code rund 91.000 Sterne auf GitHub gesammelt — vier Verhaltensregeln, destilliert aus Karpathys Beobachtungen. „Erst denken, dann coden“, „Einfachheit zuerst“, „chirurgische Änderungen“, „zielgetriebene Ausführung“. Pandey stellt eine präzise Diagnose und schließt mit dem Satz, der den Artikel laut gemacht hat: «it is winning because it is not a layer. It is a contract». Ich pflege eine große, geschichtete CLAUDE.md über einem maschinellen Kontext-Routing — und genau deshalb möchte ich dieser These widersprechen. Nicht sie widerlegen. Die Grenze festnageln, hinter der sie nicht mehr trägt.
Meine These: Er hat recht für den Median, aber „Vertrag“ und „Schicht“ sind keine Gegensätze — sie sind zwei Punkte auf einer Skala
Pandey hat in der Hauptsache recht: Für den Median-Nutzer ist eine flache Datei aus vier Regeln keine Einfachheit aus Armut, sondern verdiente Einfachheit. Die meisten Projekte sollten genau so beginnen. Aber ich würde seine Metapher drehen. „Vertrag“ und „Schicht“ sind keine Gegensätze, zwischen denen man wählen muss. Die flache Datei ist genau so lange ein Vertrag, wie ein einzelnes Regelblatt ausreicht, um jede Verpflichtung auszudrücken. Schichten (mein dreiachsiges Routing ist eine bereits veröffentlichte Geschichte, und ich erzähle sie hier nicht nach) sind keine Aufgabe des Vertrags, sondern verdiente Komplexität, für die man genau einmal bezahlt: wenn man ein Problem bekommt, das die flache Datei physisch nicht widerspruchsfrei aufschreiben kann. Vor diesem Moment sind Schichten Rauschen. Danach wird die flache Datei selbst zum Rauschen, und ihre Regeln verrotten.
Wo er recht hat: Die vier Regeln schließen eine echte Lücke, und die Viralität ist eine Stimme für das Problem
Das Stärkste am Artikel sind nicht die Regeln selbst, sondern die Ehrlichkeit darüber, warum sie nötig sind. Pandey beschreibt seine eigenen Fehlschläge wörtlich: ein Agent setzte einem dreizeiligen Cache Dependency Injection und eine Klasse mit acht Methoden an; ein anderer Agent hat beim Beheben eines Datums-Parsings «reformatted the entire file» und nicht benachbarte Funktionen umgeschrieben. Ich erkenne jede Zeile wieder — das ist nicht exotisch, das ist der Default. Die Regeln sind für einen Senior-Engineer offensichtlich und für das Modell nicht; genau diese Lücke schließt die Datei. Und Pandey deutet die Viralität korrekt: 91.000 Sterne sind «not a vote on the file. It is a vote on the problem». Stille Annahmen, Überkomplexität, Scope Creep — die drei Wände, gegen die jeder läuft, der ernsthaft mit Agenten arbeitet. Die Datei benennt sie in klarer Sprache und ist in dreißig Sekunden installiert. Ich stimme voll zu: Die Einstiegshürde entscheidet, und für die meisten ist dies der richtige erste und einzige Schritt.
Wo er unvollständig ist: „verbessert die Verteilung des Verhaltens“ ist selbst die Bruchlinie
Der wichtigste Satz im Artikel ist nicht der laute, sondern der leise in den Vorbehalten: Die Datei «improves the distribution of behavior. It does not guarantee specific behavior». Pandey legt ihn ehrlich auf den Tisch und geht weiter. Ich halte hier inne, denn hier verläuft die Naht, die entscheidet, was man überhaupt in eine CLAUDE.md schreiben kann.
Eine Markdown-Anweisung ist eine probabilistische Verschiebung, keine Garantie. Für weiche Präferenzen reicht das: Namensstil, Framework-Wahl, Test-Policy, „refaktoriere benachbarten Code nicht“. Wenn das Modell in einem von zwanzig Fällen den Stil verletzt, überlebe ich das — das Review fängt es ab. Aber es gibt eine Klasse von Regeln, für die „verbesserte Verteilung“ ein Fehlschlag ist, kein Erfolg. Compliance und Produktionssicherheit lassen sich nicht als Präferenz ausdrücken. Ein Präzedenzfall, den ein Prompt nicht ehrlich aufschreiben kann: „für Remotes der Form github.com/OEM-WEB/* dürfen Commits und PRs den Trailer Co-Authored-By: Claude nicht enthalten.“ Eine flache Verhaltensdatei kann darum bitten. Sie kann es nicht garantieren — denn eine Prosa-Anweisung ist per Definition unverbindlich, und die rechtliche Anforderung eines Kunden teilt sich nicht in „verbesserte Verteilung“.
Daher meine harte Linie beim Authoring. Weiche Präferenzen leben in Markdown — dort gehören sie hin, und die flache Datei reicht dort fast allen. Compliance und Prod-Sicherheit mechanisiere ich: Remote-Erkennung vor einem Commit, ein Gate mit namentlicher Freigabe vor Aktionen gegen die Produktion, Injektion des nötigen Kontexts durch einen Hook beim Sitzungsstart. Nicht weil ich Schichten liebe — tue ich nicht, sie kosten Wartung. Sondern weil ein Prompt von Natur aus nicht erzwingbar ist, und der einzige Weg, „gebeten“ in „garantiert“ zu verwandeln, ist, die Regel aus der Prosa in einen ausführbaren Mechanismus zu heben. Genau das ist der Fall, in dem Pandeys „Vertrag-als-Text“ bricht und dem „Vertrag-als-Harness“ weichen muss.
Was zu tun ist: flach beginnen, nur schichten, wenn der Maßstab dazu zwingt
Daraus folgt die Regel, nach der ich heute eine CLAUDE.md bauen würde — und sie liefert fast immer die Antwort „bleib flach“.
Beginne mit einer flachen Datei. Pandeys vier Regeln plus deine Projektkonventionen — Benennung, Framework, Tests. Das ist ein Vertrag, und für ein Projekt in einer Organisation ist er selbstgenügsam. Baue kein Routing, für das es keinen Anlass gibt.
Schichte nicht nach Geschmack — schichte auf einen Alarmauslöser. Damit das keine Ausrede wird, brauchst du eine falsifizierbare Schwelle. Mein Auslöser für Schichten greift, wenn mindestens eines zutrifft: (a) du hast zwei oder mehr Organisationen mit widersprüchlichen Compliance-Regeln, die die flache Datei nicht ohne Selbstwiderspruch festhalten kann; oder (b) es ist eine Regel entstanden, die garantiert und nicht erbeten werden muss — das heißt, eine Verletzung kostet kein Review, sondern einen Vorfall. Solange keine Schwelle greift, ist die flache Datei strikt besser. Früher hinzugefügte Schichten sind Komplexität, für die du ohne das von ihr gelöste Problem bezahlst.
Trenne, worum du bittest, von dem, was du garantierst. Bevor du eine Zeile zur CLAUDE.md hinzufügst, frage: Ist das eine Präferenz oder eine Verpflichtung? Eine Präferenz geht in Markdown, und Dank an Pandey, der gezeigt hat, wie wenig dafür nötig ist. Eine Verpflichtung geht aus der Prosa in einen Mechanismus: ein Hook, ein Gate, eine Pre-Commit-Prüfung. Wenn eine Regel genau so sehr zählt, dass „verbesserte Verteilung“ nicht reicht — dann gehört sie nicht in eine Datei, die nur die Verteilung verbessert.
Das Fazit ist kurz. Pandey hat recht, und sein Rechthaben zählt mehr, als die Lautstärke der These vermuten lässt: Fast jeder braucht einen flachen Vertrag, und fast jeder überkompliziert ihn. Aber die flache Datei und das geschichtete Routing sind keine Lager — sie sind zwei Enden einer Skala verdienter Komplexität. Beginne links. Bewege dich nach rechts nur, wenn du ein Compliance-Problem in der Hand hast, das ein Regelblatt nicht ausdrücken kann, oder eine Anforderung, die du nicht als Bitte in Prosa belassen darfst. Und dann lautet die ehrliche Lehre aus Pandeys Artikel nicht „der Vertrag hat die Schichten geschlagen“, sondern „schreibe in Prosa alles, worum du bitten kannst, und mechanisiere alles, was du garantieren musst“.