95 % der Leute nutzen Claude Code ohne diese Datei. Das verpassen sie.

Ich habe Dutzende von Claude-Code-Konfigurationen getestet.

Die einzige Sache, die meine Ausgabe wirklich verändert hat: eine 60-zeilige Datei namens CLAUDE.md.

Lesezeichen setzen 🔖

Hier ist genau, wie es funktioniert, warum die meisten Leute es völlig übersehen, und die vollständige Vorlage, die du heute kopieren kannst.

Was dir niemand über Claude Code sagt

Vor deinem ersten Prompt. Vor einer einzigen Codezeile. Bevor überhaupt etwas in deiner Sitzung passiert.

Claude liest eine Datei. Nur eine.

CLAUDE.md.

Und behandelt sie für die gesamte Sitzung als absolute Wahrheit. Nicht als Vorschlag. Nicht als Kontext unter vielen. Als das maßgebliche Briefing, das jede Entscheidung einrahmt, die es treffen wird.

Deshalb ist diese Datei die am meisten unterschätzte Variable im gesamten Claude-Code-Stack.

Die meisten Leute haben überhaupt keine. Und diejenigen, die eine haben, haben einen von zwei Fehlern gemacht: entweder ist die Datei substanzlos, oder sie ist 300 Zeilen lang mit „Sei ein erfahrener Senior-Engineer, der Schritt für Schritt denkt."

Beides ist nutzlos. Aus unterschiedlichen Gründen.

Warum die meisten CLAUDE.md-Dateien nicht funktionieren: Die 3 wahren Gründe

Grund 1: Zu lang

Claude kann zuverlässig etwa 150 bis 200 Anweisungen pro Sitzung befolgen. Das ist eine strukturelle Einschränkung, keine Frage des guten Willens.

Problem: Der interne System-Prompt von Claude Code enthält bereits etwa 50 Anweisungen. Das bedeutet, dass deine CLAUDE.md tatsächlich 100 bis 150 Anweisungsslots hat, bevor Claude beginnt, sie fallen zu lassen.

Wenn deine Datei 200 Zeilen lang ist, ignoriert Claude deine Regeln nicht absichtlich. Es vergisst sie mechanisch. Du hast kein Compliance-Problem. Du hast ein Aufmerksamkeitsbudget-Problem.

Grund 2: Schlechter Inhalt

Die Mehrheit der CLAUDE.md-Dateien ist mit Dingen gefüllt, die Claude selbst ableiten kann, oder die sein Verhalten nicht messbar verändern.

„Verhalte dich wie ein Senior-Engineer." → Claude weiß bereits, was das bedeutet, und es verankert kein spezifisches Verhalten. „Denke Schritt für Schritt." → Das ist in seinem Training. Du verschwendest eine Zeile. „Schreibe sauberen und wartbaren Code." → Keine konkreten Kriterien. Claude weiß nicht, was „sauber" in deinem spezifischen Kontext bedeutet.

Jede Zeile, die keinen spezifischen, konkreten Fehler verhindert, ist eine Zeile, die von Anweisungen gestohlen wird, die tatsächlich wichtig sind. Der Test ist einfach: Wenn du diese Zeile löschst, wird Claude dann etwas Konkretes falsch machen? Wenn die Antwort nein ist, gehört die Zeile nicht dorthin.

Grund 3: Keine Hierarchie

Die meisten Leute ignorieren, dass es drei Ebenen von Anweisungen in Claude Code gibt, und sie stopfen alles an die gleiche Stelle.

~/.claude/CLAUDE.md → Global (gilt für alle deine Projekte)

.claude/CLAUDE.md → Projekt (geteilt mit dem Team, in Git)

./CLAUDE.local.md → Lokal (persönliche Überschreibungen, gitignoriert)

Die globale Ebene ist für Regeln, die du in jedem Projekt wiederholen würdest. Die Projektebene ist für Kontext, der für deinen Stack und dein Team spezifisch ist. Die lokale Ebene ist für deine persönlichen Vorlieben, die nicht geteilt werden müssen.

Die drei Ebenen richtig zu nutzen, hält jede Datei kurz, fokussiert und wirklich effektiv. Alles in eine Datei zu packen, ist, als würde man einen Trichter bauen, um deine wichtigen Regeln unter Rauschen zu ertränken.

Die 5 Abschnitte, die eine effektive CLAUDE.md ausmachen

Nachdem ich Dutzende von CLAUDE.md-Dateien in der Produktion durchforstet habe – Open-Source-Projekte, offizielle Anthropic-Dokumente, Community-Best-Practice-Repositories – hier sind die 5 Abschnitte, die alle effektiven Dateien gemeinsam haben:

Abschnitt 1: Kritische Befehle

Claude beginnt jede Sitzung, ohne zu wissen, wie man dein Projekt baut, deine Tests ausführt oder Lint-Fehler behebt. Es wird raten. Und seine Schätzungen werden dich Züge kosten.

Sag ihm genau, was es eingeben soll:

Befehle

• Build: npm run build
• Dev: npm run dev
• Einzelnen Test ausführen: npm test -- path/to/file
• Vollständigen Test: npm test
• Lint + Fix: npm run lint:fix
• Typen prüfen: npx tsc --noEmit

Kurz. Präzise. Direkt verwendbar.

Ohne diesen Abschnitt wird Claude versuchen, npm test auszuführen, wenn dein Projekt auf pnpm vitest läuft. Es wird drei Züge damit verbringen, ein Befehlsproblem zu debuggen, das nie funktioniert hätte. Drei Züge, die du für echte Arbeit hättest nutzen können.

Abschnitt 2: Architektur-Landkarte

Claude beginnt jede Sitzung mit null Kenntnissen über deine Codebasis. Null. Es weiß nicht, wo deine Geschäftslogik lebt. Es weiß nicht, ob deine Komponenten zustandslos sein sollen. Es weiß nicht, dass deine API-Routen keine Geschäftslogik enthalten sollten.

Gib ihm eine Landkarte:

Architektur

• src/lib/services/ → gesamte Geschäftslogik
• src/components/ → nur zustandslose UI-Komponenten
• src/lib/store/ → globaler Zustand (Zustand)
• src/app/api/ → API-Routen, hier keine Geschäftslogik
• DB-Zugriff nur über Server-Actions oder API-Routen

Keine erschöpfende Auflistung deiner Baumstruktur. Nur genug, damit Claude weiß, wo die Dinge leben, und, was noch wichtiger ist, wo sie NICHT hingehören.

Diese Unterscheidung ... wohin es geht vs. wohin nicht ... ist das, was die häufigsten Architekturfehler verhindert.

Abschnitt 3: Harte Regeln

Dies ist der wichtigste Abschnitt der gesamten Datei. Ohne Ausnahme.

Jede Regel hier muss eine einzige Frage beantworten: „Wenn ich diese Zeile lösche, wird Claude dann einen konkreten Fehler machen?"

Wenn ja → die Regel bleibt. Wenn nein → hat sie dort nichts zu suchen.

Beispiel für wertvolle Regeln:

Regeln

• NEVER .env-Dateien oder Geheimnisse committen
• Alle asynchronen Aufrufe müssen in einem try/catch eingewickelt sein
• Nur funktionale Komponenten, null Klassenkomponenten
• Verbindliche Commit-Präfixe: feat:, fix:, docs:, refactor:
• Jeder PR muss vor dem Mergen npm run verify bestehen
• Nur statischer Export, kein SSR (bereitgestellt auf S3)
• WICHTIG: Typenprüfung nach jeder Code-Änderung ausführen

Zwei Dinge zu dieser Liste.

Erstens sind negative Regeln genauso wichtig wie positive. „NEVER .env-Dateien committen" ist eine Regel, die nur so lange offensichtlich erscheint, bis Claude es eines Tages tut. Füge sie hinzu.

Zweitens: Hervorhebungsmarker wie WICHTIG or YOU MUST funktionieren tatsächlich.

Das ist nicht anekdotisch. Anthropic bestätigt es in ihrer eigenen Dokumentation: Das Hinzufügen von WICHTIG or YOU MUST vor einer Regel verbessert nachweislich Claudes Einhaltung dieser Regel.

Verwende sie sparsam: Hebe sie für Regeln auf, die die schwerwiegendsten Konsequenzen haben, wenn sie ignoriert werden.

Bleib unter 15 Regeln in diesem Abschnitt. Darüber hinaus verwässerst du die Aufmerksamkeit für die, die wirklich zählen.

Abschnitt 4: Workflow-Präferenzen

Du hast es erlebt. Du bittest Claude, eine Zeile zu reparieren. Es schreibt drei Dateien neu, benennt deine Funktionen um und refaktoriert eine Klasse, die nichts mit deiner Anfrage zu tun hatte.

Dieser Abschnitt verhindert das:

Workflow

• Vor komplexen Aufgaben klärende Fragen stellen
• Minimale Änderungen vornehmen, keinen nicht zusammenhängenden Code umgestalten
• Nach jeder Änderung Tests ausführen, Fehler beheben, bevor fortgefahren wird
• Separate Commits pro logischer Änderung erstellen, keinen riesigen Commit
• Bei Unsicherheit zwischen zwei Ansätzen beide erklären und mich wählen lassen

Jede Zeile hier beantwortet einen konkreten Schmerzpunkt. Der 47-Dateien-Riesencommit. Die nicht angeforderte vollständige Neuschreibung. Die Architekturentscheidung, die Claude allein trifft, wenn es dich hätte fragen sollen.

Abschnitt 5: Was NICHT in deine CLAUDE.md gehört

Dieser Abschnitt ist genauso wichtig wie die anderen. Vielleicht mehr.

Nicht aufnehmen:

• Persönlichkeitsanweisungen („Sei ein Senior-Engineer")
• Formatierungsregeln, die dein Linter bereits handhabt
• @-Imports, die ganze Dokumente in jede Sitzung ziehen
• Doppelte Regeln (wenn global sagt „Tests ausführen", wiederholt das Projekt es nicht)
• Alles, was Claude durch Auto-Memory selbst lernt

Dieser letzte Punkt wird weit unterschätzt.

Claude führt eigene Notizen in ~/.claude/projects/<projekt>/memory/. Führe /memory in deiner Sitzung aus, um zu sehen, was es bereits über dein Projekt gelernt hat. Nach ein paar Sitzungen wirst du oft feststellen, dass Claude bereits Informationen erfasst hat, die du von Hand in deine CLAUDE.md schreiben wolltest.

Verschwende deine begrenzten Anweisungen nicht mit Dingen, an die Claude sich selbst erinnert hat.

Die komplette Vorlage unter 60 Zeilen, bereit zur Verwendung

Lösche Abschnitte, die nicht auf dein Projekt zutreffen. Das Ziel ist nicht, alles zu füllen. Das Ziel ist, nur das zu behalten, was Claudes Verhalten messbar verändert.

Die Zeilen, die den größten Einfluss auf meine Ausgabe hatten: konkrete Ergebnisse

Nach dem Testen von Dutzenden von Konfigurationen sind hier die fünf Zeilen, die den sichtbarsten Unterschied gemacht haben:

WICHTIG: Typenprüfung nach jeder Code-Änderung ausführen → Verhindert, dass Claude Code mit kaputten Typen liefert, die es ohne explizite Aufforderung zur Prüfung nicht erkennt.

Minimale Änderungen vornehmen, keinen nicht zusammenhängenden Code umgestalten → Verhindert die vollständige und nicht angeforderte Neuschreibung ganzer Dateien.

Separate Commits pro logischer Änderung erstellen, keinen riesigen Commit → Verhindert den unlesbaren Monster-Commit von 47 gemischten Dateien.

Bei Unsicherheit zwischen zwei Ansätzen beide erklären und mich wählen lassen → Verhindert, dass Claude Architekturentscheidungen allein trifft, die dir gehört hätten.

Nur statischer Export, kein SSR → Verhindert, dass Claude Servercode in einem Projekt hinzufügt, das statisch auf S3 bereitgestellt wird.

Was diese fünf Zeilen gemeinsam haben: Jede verhindert einen spezifischen, häufigen und kostspieligen Fehler in der Debug-Zeit.

Dies ist der ultimative Test für jede Zeile deiner CLAUDE.md.

Der grundlegende Fehler und warum er so weit verbreitet ist

Die Leute behandeln ihre CLAUDE.md wie eine Wunschliste oder einen Persönlichkeits-Prompt.

„Sei senior." „Sei gründlich." „Denke wie ein Experte."

Das ist kein Briefing. Es ist magisches Denken.

Deine CLAUDE.md sollte ein technisches Dokument sein, keine Motivationsrede. Stack, Befehle, Architektur, konkrete Regeln, Workflow. Alles andere ist Rauschen, das mit den Anweisungen konkurriert, die wirklich wichtig sind.

Halte die Datei unter 80 Zeilen. Überarbeite sie jedes Mal, wenn Claude einen Fehler macht, den du hättest verhindern können.

Und vor allem: Verstehe, was diese Datei im Laufe der Zeit wird.

Eine gute CLAUDE.md spart dir im ersten Monat Zeit bei jeder Sitzung. Im dritten Monat hat sie deine Konventionen und deinen Stack so präzise erfasst, dass Claude fast wie ein Teammitglied arbeitet.

Im sechsten Monat enthält sie jeden Fehler, den Claude jemals in diesem Projekt gemacht hat, und verhindert sie alle automatisch.

Die Datei kapitalisiert sich selbst. Sie verbessert sich mit jeder Korrektur. Sie wird nach und nach zum besten Onboarding-Briefing, das du je geschrieben hast.

Nicht für Claude. Für dich.