CLAUDE.md-Datei: 431 Zeilen aus dem Betrieb erklärt
Von Marco Kohns, Co-Founder von ENLIX, Dozent für KI und Wachstum
· 10 Min. Lesezeit
Die CLAUDE.md ist eine Markdown-Datei im Projektstamm, die Claude Code zu Beginn jeder Sitzung mitliest. Hinein gehört das, was du sonst jedes Mal neu erklären würdest. Die meisten Anleitungen beantworten damit die Frage, was man hineinschreiben könnte. Die schwierigere Frage ist, was eine Zeile darin verdient, und die lässt sich nur an einer Datei zeigen, die seit Monaten im Betrieb steht.
Unsere ist 431 Zeilen lang und steuert die Website, auf der du gerade liest. Sie ist damit mehr als doppelt so lang wie die Zielgröße, die Anthropic in der eigenen Dokumentation nennt. Unten steht, woraus diese 431 Zeilen bestehen, welche Regeln darin einen bezifferbaren Schaden benennen und warum wir die empfohlene Grenze bewusst reißen.
Was ist die CLAUDE.md-Datei?
Eine Markdown-Datei mit Anweisungen, die Claude Code zu Beginn jeder Sitzung liest, weil jede Sitzung mit einem leeren Kontextfenster anfängt. Sie trägt das, was im Code nicht steht: warum eine Entscheidung so getroffen wurde, welcher Befehl das Projekt baut, welche Stelle schon einmal kaputtgegangen ist.
Anthropic nennt in der Dokumentation zum Projektgedächtnis vier Anlässe, eine Zeile aufzunehmen: Claude macht denselben Fehler ein zweites Mal, ein Code-Review findet etwas, das Claude über diese Codebasis hätte wissen müssen, du tippst dieselbe Korrektur wie in der letzten Sitzung, oder ein neuer Kollege bräuchte denselben Kontext. Alle vier haben dieselbe Form: etwas ist schon einmal passiert. Keiner davon lautet "schreib auf, wie du gerne arbeitest".
Daneben steht das Auto-Memory, das Claude selbst führt. Die Unterscheidung ist sauber: die CLAUDE.md schreibst du, das Auto-Memory schreibt Claude. Beide werden zu Sitzungsbeginn geladen, und beide sind Kontext und keine Garantie.
Wohin gehört die Datei, und welche gelten gleichzeitig?
In den Projektstamm, als ./CLAUDE.md oder ./.claude/CLAUDE.md, und von dort in die
Versionskontrolle. Daneben gibt es drei weitere Ebenen, die gleichzeitig gelten und in dieser
Reihenfolge geladen werden, von der breitesten zur spezifischsten:
| Ebene | Ort | Wofür |
|---|---|---|
| Organisationsrichtlinie | /etc/claude-code/CLAUDE.md unter Linux, eigene Pfade unter macOS und Windows | Vorgaben, die die IT setzt |
| Persönlich | ~/.claude/CLAUDE.md | Deine Vorlieben über alle Projekte hinweg |
| Projekt | ./CLAUDE.md oder ./.claude/CLAUDE.md | Das Team, über Git geteilt |
| Lokal | ./CLAUDE.local.md, in die .gitignore | Deine Notizen zu diesem einen Projekt |
Der wichtigste Satz dazu steht in der Dokumentation und wird oft überlesen: alle gefundenen Dateien werden aneinandergehängt, nicht gegeneinander ausgespielt. Es gibt also kein Überschreiben einer Ebene durch die nächste. Was näher an deinem Arbeitsverzeichnis liegt, wird zuletzt gelesen, und bei zwei Anweisungen, die sich widersprechen, wählt Claude laut Dokumentation unter Umständen willkürlich eine aus. Zwei Regeln, die sich widersprechen, sind deshalb schlimmer als eine fehlende.
Dateien in Unterverzeichnissen verhalten sich anders als die oberhalb: sie werden nicht beim Start
geladen, sondern erst, wenn Claude in diesem Unterverzeichnis eine Datei liest oder ändert. Ob
eine Datei tatsächlich geladen wurde, zeigt dir /context unter "Memory files". Das ist die
Prüfung, die den Unterschied macht zwischen "die Regel steht da" und "die Regel ist angekommen".
Was gehört hinein und was nicht?
Hinein gehört, was in jeder Sitzung gilt und sich aus dem Code nicht ableiten lässt: Build- und
Testbefehle, Projektaufbau, Konventionen, Architekturentscheidungen mit ihrer Begründung. Nicht
hinein gehört, was nur für einen Teil des Projekts gilt oder eine mehrstufige Prozedur ist. Dafür
gibt es Skills und pfadgebundene Regeln unter .claude/rules/, die
per paths-Frontmatter erst laden, wenn Claude eine passende Datei anfasst.
Die Dokumentation gibt dazu einen Formulierungstest mit, der kürzer ist als jede Checkliste:
schreib Anweisungen, die konkret genug sind, um sie zu prüfen. "Use 2-space indentation" statt
"Format code properly". "Run npm test before committing" statt "Test your changes". Eine
Anweisung, deren Befolgung du nicht nachsehen kannst, kannst du auch nicht durchsetzen.
Wir haben dem einen zweiten Test danebengestellt, der aus dem Betrieb kommt und härter ist: eine Regel darf bleiben, wenn sie einen Vorfall benennt, der schon einmal etwas gekostet hat. Alles andere ist ein Wunschzettel. Der Unterschied sieht in der Datei harmlos aus und im Alltag nicht:
Zwei Wege, wie eine Zeile in die Datei kommt
Schritt, den nur ein Mensch liefert
Aus dem Wunschzettel
- Du schreibst auf, wie gearbeitet werden soll
- Die Regel bleibt allgemein
- Niemand kann nachsehen, ob sie befolgt wurde
- Sie bleibt stehen, auch wenn sie überholt ist
0 von 4 Schritten brauchen einen Menschen
Aus einem Vorfall
- Etwas geht kaputt und kostet Zeit oder Geld
- Du findest die Ursache
- Die Regel nennt die Ursache und den Preis
- Sie fällt raus, sobald die Ursache verschwunden ist
3 von 4 Schritten brauchen einen Menschen
Beide Wege erzeugen eine Zeile. Nur der zweite erzeugt eine, die du später wieder löschen kannst.
Der zweite Weg hat eine Eigenschaft, die der erste nicht hat: die Regel trägt ihr eigenes Verfallsdatum. Steht in der Zeile, warum sie existiert, kannst du in sechs Monaten prüfen, ob der Grund noch gilt. Steht es nicht da, bleibt sie für immer stehen und verbraucht Kontext.
Wie sieht eine CLAUDE.md aus, die seit Monaten im Betrieb ist?
Zum größten Teil nicht nach Stilvorgaben, sondern nach Architektur. Wir haben die Datei dieses Repos am 21.10.2026 vermessen: 431 Zeilen, 3.836 Wörter, 6 Abschnitte der ersten und 7 der zweiten Ebene. So verteilt sich das Gewicht:
Zeilen je Abschnitt in unserer CLAUDE.md
Eigene Messung am 21.10.2026 an CLAUDE.md im Repo enlixai/enlix-academy. 431 Zeilen gesamt.
| Architektur | 260 Zeilen |
|---|---|
| Designsystem | 65 Zeilen |
| Vorspann ohne Überschrift | 35 Zeilen |
| Harte Regeln | 33 Zeilen |
| Was es nicht ist | 14 Zeilen |
| Offene Punkte | 10 Zeilen |
| Stolperfallen | 8 Zeilen |
Sechzig Prozent der Datei beschreiben, wie die Anwendung aufgebaut ist und wo sie empfindlich ist. Der Abschnitt mit den Stilregeln ist der zweitkleinste. Das ist das Gegenteil dessen, was die meisten Vorlagen nahelegen, und es ergibt sich von selbst, sobald Regeln nur noch aus Vorfällen entstehen: Vorfälle passieren an Schnittstellen, nicht an Einrückungen.
Dieselbe Datei zählt 27 Zeilen, die ein Verbot aussprechen, also ein "never", "do not" oder "must not" tragen. Zwölf dieser Regeln benennen einen konkreten Vorfall mit einer Zahl oder einer Fehlermeldung. Diese zwölf sind der Kern der Datei, und sie sind der Grund, warum sie nicht kürzer ist:
| Was die Regel verbietet | Was es vorher gekostet hat |
|---|---|
searchParams, cookies() oder headers() in einer Seitenkomponente lesen | Ein 97-faches Hochschnellen der Vercel-CPU-Zeit auf einem anderen Projekt |
| Den Supabase-Client im Header-Baustein importieren | 74 kB Auth-Bibliothek im gemeinsamen Chunk jeder einzelnen Seite |
| Einen GET-Endpunkt für den Checkout anbieten | 75 echte Stripe-Sitzungen, erzeugt von Linkscannern in Firmenpostfächern, und null Menschen |
| Quizantworten in benannte Spalten schreiben | Spalten, die auseinanderdrifteten, bis q10_flow_state Zieltexte enthielt |
| Einen Parameter zu einem bestehenden RPC hinzufügen | PostgREST beantwortet danach jeden Aufruf mit PGRST203 |
Rabatte als percent_off statt amount_off anlegen | 50 % von 3999 sind 1999,5, und das lässt sich nicht abbuchen |
next build starten, während next dev läuft | Eine weiße Seite und __webpack_modules__[moduleId] is not a function |
| Eine RLS-Policy ergänzen, um einen Lesezugriff zu reparieren | Direkter Zugriff wird mit 42501 abgewiesen, der Weg führt über einen RPC |
| Die Digistore24-Signatur selbst berechnen statt aus der Doku zu pinnen | Zehn Tage Wiederholungsversuche und kein Käufer bekommt Zugang |
| Das helle Theme wiederherstellen | Die Annahme dahinter wurde nie geprüft: 1 Sitzung, 1 Lead, 0 Käufe |
| Deutsche Seiten unter einem englischen Wurzel-Layout ausliefern | Bis zum 02.10.2026 trug jede deutsche Seite lang="en" |
| Auf next 15.1.x zurückgehen | Eine als kritisch eingestufte Sicherheitslücke |
Jede dieser Zeilen ist in der Datei zwei bis vier Zeilen lang, weil der Preis mit dransteht. Ohne den Preis wären es zwölf Einzeiler, und jeder davon klänge nach Geschmacksfrage.
Warum ist diese Datei doppelt so lang wie empfohlen?
Weil wir die Kosten kennen und sie bezahlen, und das ist ein Unterschied zu "wir haben die Grenze nicht gelesen". Die Dokumentation nennt als Zielgröße unter 200 Zeilen je Datei und begründet das klar: längere Dateien verbrauchen mehr Kontext und senken die Befolgung. Beides stimmt.
Dateigröße gegen die dokumentierte Zielgröße
Zielgröße laut code.claude.com/docs/en/memory, abgerufen am 21.10.2026. Eigene Datei am selben Tag gemessen.
| Unsere CLAUDE.md | 431 Zeilen |
|---|---|
| Davon allein der Abschnitt Architektur | 260 Zeilen |
| Anthropics Zielgröße je Datei | 200 Zeilen |
Die Grafik zeigt zugleich den Ausweg. Was die Datei über die Grenze trägt, sind nicht die zwölf
teuren Regeln, sondern die 260 Zeilen Architekturbeschreibung. Genau dafür ist .claude/rules/
gedacht: ein pfadgebundenes Regelwerk lädt erst, wenn Claude eine passende Datei anfasst, und die
Beschreibung der Datenbank muss nicht in jeder Sitzung mitlaufen, in der jemand eine Überschrift
ändert.
Zwei Wege, die nicht funktionieren, damit du sie nicht ausprobieren musst. Der erste ist das
Auslagern per @pfad-Import: die importierten Dateien werden beim Start mitgeladen, die Datei
sieht kürzer aus und der Kontextverbrauch bleibt gleich. Die Dokumentation sagt das ausdrücklich.
Der zweite ist Kürzen durch Streichen der Begründungen. Eine Regel ohne Grund kann niemand
später wieder löschen, und eine Datei, aus der nichts mehr herausfällt, wächst linear weiter.
Was kann die CLAUDE.md nicht?
Sie kann nichts erzwingen. Das ist keine Schwäche der Formulierung, sondern die Bauart: Claude behandelt diese Dateien laut Dokumentation als Kontext und nicht als erzwungene Konfiguration. Wer eine Aktion unabhängig von der Entscheidung des Modells blockieren will, braucht einen PreToolUse-Hook. Je konkreter und kürzer eine Anweisung ist, desto zuverlässiger wird sie befolgt, aber "zuverlässiger" ist nicht "immer".
Daraus folgt eine Arbeitsteilung, die sich im Alltag auszahlt. Was weh tut, wenn es einmal
durchrutscht, gehört in einen Test oder einen Hook. Was lästig ist, wenn es durchrutscht, gehört
in die CLAUDE.md. Bei uns ist der Build selbst die Prüfung für die wichtigste Regel: jede
Marketing-Route muss statisch bleiben, und npm run build bricht ab, wenn eine Seite dynamisch
wird. Der Satz in der CLAUDE.md erklärt das Warum, die Prüfung macht den Fehler unmöglich.
Zweitens kann die Datei nicht ersetzen, dass jemand sie aufräumt. Dafür gibt es seit Kurzem
/doctor prompt-audit: Claude durchsucht deine Anweisungsdateien nach Widersprüchen, nach Verweisen
auf Dateien, die es nicht mehr gibt, und nach Regeln für ältere Modelle. Du bekommst einen Bericht
mit Änderungsvorschlägen, und es ändert sich nichts, bis du es verlangst.
Wie fängst du an?
Mit /init in einer laufenden Sitzung. Claude liest das Projekt und schreibt eine erste Fassung
mit den Build-Befehlen, den Testanweisungen und den Konventionen, die es findet. Existiert die
Datei schon, schlägt /init Verbesserungen vor, statt sie zu überschreiben.
Danach hört die Automatik auf, und zwar an einer sinnvollen Stelle: /init kann aufschreiben, was
im Projekt steht, aber nicht, was dich letzten Dienstag Stunden gekostet hat. Diese Zeilen kommen
aus dem Betrieb, eine nach der anderen, immer an dem Tag, an dem etwas schiefgeht. Unsere Datei
ist in vier Tagen Anfang Oktober von 414 auf 431 Zeilen gewachsen, nicht in einer
Aufräumsitzung, sondern in fünf einzelnen Commits neben der eigentlichen Arbeit.
Eine brauchbare Reihenfolge für die ersten Wochen: /init laufen lassen, mit /context prüfen,
dass die Datei geladen wird, und ab dann jedes Mal eine Zeile ergänzen, wenn du dieselbe Korrektur
zum zweiten Mal tippst. Wo du damit im größeren Lernpfad stehst, steht in
Claude Code lernen; welche Oberfläche welche Dateien überhaupt
sieht, in Claude Code CLI. Wie die Sitzung aussieht, in der du zum
ersten Mal dieselbe Korrektur tippst, beschreibt
die erste Sitzung mit Claude Code.
Wenn du das lieber an einem echten Projekt mit jemandem durchgehst, der die zwölf Regeln oben selbst bezahlt hat: genau das ist der dritte Block im Claude Code System.
Häufige Fragen
Was ist die CLAUDE.md-Datei?
Eine Markdown-Datei im Projektverzeichnis, die Claude Code zu Beginn jeder Sitzung mitliest. Darin stehen die Dinge, die sich aus dem Code nicht ableiten lassen: Befehle, Architekturentscheidungen, Konventionen und die Regeln, die ein neuer Mitarbeiter am ersten Tag erklärt bekäme. Die Dokumentation von Anthropic nennt sie ausdrücklich Kontext und keine erzwungene Konfiguration.
Wohin gehört die CLAUDE.md-Datei?
In den Projektstamm, als `./CLAUDE.md` oder `./.claude/CLAUDE.md`, und von dort ins Versionskontrollsystem, damit das Team dieselbe Datei hat. Daneben gibt es drei weitere Ebenen: eine organisationsweite Richtliniendatei, deine persönliche `~/.claude/CLAUDE.md` für alle Projekte und eine `CLAUDE.local.md`, die du in die `.gitignore` einträgst. Alle gefundenen Dateien werden aneinandergehängt, nicht gegeneinander ausgespielt.
Wie lang darf eine CLAUDE.md sein?
Anthropic nennt als Zielgröße unter 200 Zeilen je Datei, mit der Begründung, dass längere Dateien mehr Kontext verbrauchen und die Befolgung sinken lassen. Unsere Projektdatei hat 431 Zeilen, also mehr als das Doppelte. Das ist eine bewusste Abweichung und kein Freibrief: der Weg zurück führt über `.claude/rules/`, nicht über das Löschen von Regeln.
Wie erstelle ich eine CLAUDE.md?
Mit `/init` in einer laufenden Sitzung. Claude analysiert das Projekt und schreibt eine erste Fassung mit Build-Befehlen, Testanweisungen und den Konventionen, die es findet. Existiert die Datei bereits, schlägt `/init` Verbesserungen vor, statt sie zu überschreiben. Alles Weitere kommt aus dem Betrieb, nicht aus einer Vorlage.
Was gehört nicht in die CLAUDE.md?
Alles, was nur für einen Teil des Projekts gilt oder eine mehrstufige Prozedur ist. Dafür gibt es Skills und pfadgebundene Regeln unter `.claude/rules/`, die erst laden, wenn Claude eine passende Datei anfasst. Und alles, was wirklich blockieren muss: das gehört in einen PreToolUse-Hook oder in einen Test, nicht in einen Satz.
Marco hat als Growth Product Manager in einem Silicon-Valley-Scale-up gearbeitet und gibt diese Arbeitsweise seitdem auf Deutsch weiter. Heute führt er ENLIX mit Tobias und baut mit denselben Systemen zwei eigene Produkte, über die er in den Kursen offenlegt, was funktioniert und was nicht.
- Growth Product Manager in einem Silicon-Valley-Scale-up, Series A bis B, finanziert von a16z, General Catalyst und Sapphire, mit Nutzern in über 100 Ländern und über 20.000 Städten
- Begutachtete Veröffentlichung im Journal of Business Research zu generativer KI im Marketing, gemeinsam mit Prof. René Bohnsack. Die Forschung dazu begann im Sommer 2022, Monate bevor ChatGPT öffentlich wurde
- Dozent für die Weiterbildung von Führungskräften an der Católica-Lisbon, über 10 Seminare, über 1.500 unterrichtete Teilnehmende
Weiterlesen
Claude Code lernen: vier Schritte in dieser Reihenfolge
Nicht die Feature-Liste, sondern die Lernreihenfolge. Vier Schritte mit Abbruchkriterium, gemessen an der Regeldatei, die diese Website steuert.
19. Oktober 2026
Claude Code Skills: Wann ein Skill, wann die CLAUDE.md
Ein Skill ist ein Ordner mit einer SKILL.md. Was hineingehört, wo er liegen muss und was das Nachmessen unserer eigenen Bibliothek gezeigt hat.
25. September 2026
Claude Code CLI: Terminal, IDE, Desktop oder Web?
Vier Oberflächen, ein Programm. Welche du wofür nimmst, entschieden an 224 Commits aus unserem eigenen Repository.
5. Oktober 2026
