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:

EbeneOrtWofür
Organisationsrichtlinie/etc/claude-code/CLAUDE.md unter Linux, eigene Pfade unter macOS und WindowsVorgaben, die die IT setzt
Persönlich~/.claude/CLAUDE.mdDeine Vorlieben über alle Projekte hinweg
Projekt./CLAUDE.md oder ./.claude/CLAUDE.mdDas Team, über Git geteilt
Lokal./CLAUDE.local.md, in die .gitignoreDeine 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

  1. Du schreibst auf, wie gearbeitet werden soll
  2. Die Regel bleibt allgemein
  3. Niemand kann nachsehen, ob sie befolgt wurde
  4. Sie bleibt stehen, auch wenn sie überholt ist

0 von 4 Schritten brauchen einen Menschen

Aus einem Vorfall

  1. Etwas geht kaputt und kostet Zeit oder Geld
  2. Du findest die Ursache
  3. Die Regel nennt die Ursache und den Preis
  4. 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

Architektur260 ZeilenDesignsystem65 ZeilenVorspann ohne Überschrift35 ZeilenHarte Regeln33 ZeilenWas es nicht ist14 ZeilenOffene Punkte10 ZeilenStolperfallen8 Zeilen

Eigene Messung am 21.10.2026 an CLAUDE.md im Repo enlixai/enlix-academy. 431 Zeilen gesamt.

Zeilen je Abschnitt in unserer CLAUDE.md
Architektur260 Zeilen
Designsystem65 Zeilen
Vorspann ohne Überschrift35 Zeilen
Harte Regeln33 Zeilen
Was es nicht ist14 Zeilen
Offene Punkte10 Zeilen
Stolperfallen8 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 verbietetWas es vorher gekostet hat
searchParams, cookies() oder headers() in einer Seitenkomponente lesenEin 97-faches Hochschnellen der Vercel-CPU-Zeit auf einem anderen Projekt
Den Supabase-Client im Header-Baustein importieren74 kB Auth-Bibliothek im gemeinsamen Chunk jeder einzelnen Seite
Einen GET-Endpunkt für den Checkout anbieten75 echte Stripe-Sitzungen, erzeugt von Linkscannern in Firmenpostfächern, und null Menschen
Quizantworten in benannte Spalten schreibenSpalten, die auseinanderdrifteten, bis q10_flow_state Zieltexte enthielt
Einen Parameter zu einem bestehenden RPC hinzufügenPostgREST beantwortet danach jeden Aufruf mit PGRST203
Rabatte als percent_off statt amount_off anlegen50 % von 3999 sind 1999,5, und das lässt sich nicht abbuchen
next build starten, während next dev läuftEine weiße Seite und __webpack_modules__[moduleId] is not a function
Eine RLS-Policy ergänzen, um einen Lesezugriff zu reparierenDirekter Zugriff wird mit 42501 abgewiesen, der Weg führt über einen RPC
Die Digistore24-Signatur selbst berechnen statt aus der Doku zu pinnenZehn Tage Wiederholungsversuche und kein Käufer bekommt Zugang
Das helle Theme wiederherstellenDie Annahme dahinter wurde nie geprüft: 1 Sitzung, 1 Lead, 0 Käufe
Deutsche Seiten unter einem englischen Wurzel-Layout ausliefernBis zum 02.10.2026 trug jede deutsche Seite lang="en"
Auf next 15.1.x zurückgehenEine als kritisch eingestufte Sicherheitslücke
Zwölf Regeln aus unserer CLAUDE.md, jeweils mit dem Vorfall, der sie ausgelöst hatQuelle: Eigene Datei, gezählt am 21.10.2026

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

Unsere CLAUDE.md431 ZeilenDavon allein der Abschnitt Architektur260 ZeilenAnthropics Zielgröße je Datei200 Zeilen

Zielgröße laut code.claude.com/docs/en/memory, abgerufen am 21.10.2026. Eigene Datei am selben Tag gemessen.

Dateigröße gegen die dokumentierte Zielgröße
Unsere CLAUDE.md431 Zeilen
Davon allein der Abschnitt Architektur260 Zeilen
Anthropics Zielgröße je Datei200 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.

Geschrieben von

Marco Kohns

Co-Founder von ENLIX, Dozent für KI und Wachstum

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