Eine CLAUDE.md-Datei schreiben in 2026: Ein praktischer Leitfaden

Eine CLAUDE.md-Datei ist eine schlichte Markdown-Datei, die Claude Code zu Beginn jeder Session automatisch liest und dem Modell damit dauerhafte Anweisungen mitgibt, die es sich nicht aus deinem Code ableiten kann: Build-Befehle, Konventionen, Architektur und die "mach immer X"-Regeln, die du leid bist, ständig zu wiederholen. Leg sie ins Wurzelverzeichnis deines Projekts, halte sie unter ~200 Zeilen und fülle sie mit konkreten, überprüfbaren Anweisungen statt mit einem Wiki-Abladeplatz. Dieser Leitfaden zeigt, wo die Datei liegt, was hineingehört, wie du vorhandene Dokumente importierst und wiederverwendest und wie du sie mit den eigenen Befehlen von Claude Code generierst und trimmst.

Es lohnt sich, vorab präzise zu sein, denn die meisten Beiträge vermischen zwei Dinge, die Claude Code strikt getrennt hält: die CLAUDE.md, die du schreibst, und das automatische Memory, das Claude für sich selbst schreibt. Wir behandeln beides – und warum die von Hand geschriebene Datei nach wie vor das Wirksamste am gesamten Setup ist.

Was ist eine CLAUDE.md-Datei?

Eine CLAUDE.md-Datei ist die Anweisungsschicht für Claude Code. Beim Session-Start lädt Claude Code sie in das Kontextfenster und liefert sie als Nachricht aus, die Claude liest, bevor es deinen Code auch nur anfasst. Die Doku von Anthropic beschreibt sie als den Ort, an dem du "aufschreibst, was du sonst immer wieder erklären müsstest" – den Tech-Stack, wie man Tests ausführt, Namenskonventionen und Architekturentscheidungen, die ein neues Teammitglied bräuchte. Es ist Markdown, also sind Überschriften und Aufzählungslisten die ganze Struktur, die du brauchst.

Eine Feinheit, die die Doku ausdrücklich benennt: CLAUDE.md ist Kontext, keine erzwungene Konfiguration. Claude liest sie und versucht, sich daran zu halten, aber es gibt keine harte Garantie, gerade bei vagen oder widersprüchlichen Regeln. Alles, was zwingend an einem festen Punkt passieren muss – "führe den Linter vor jedem Commit aus" – gehört in einen Hook, nicht in eine Zeile Prosa. Diese Unterscheidung prägt alles Weitere.

Wohin mit deiner CLAUDE.md-Datei

CLAUDE.md kann an mehreren Stellen liegen, und Claude Code lädt sie der Reihe nach vom Allgemeinsten zum Spezifischsten und hängt sie aneinander, statt sie zu überschreiben. Eine Projekt-Anweisung landet im Kontext nach einer Nutzer-Anweisung, sodass die spezifischere Datei zuletzt gelesen wird.

Geltungsbereich	Ort	Zweck	Geteilt mit
Verwaltete Richtlinie	/etc/claude-code/CLAUDE.md (Linux/WSL); /Library/Application Support/ClaudeCode/CLAUDE.md (macOS); C:\Program Files\ClaudeCode\CLAUDE.md (Windows)	Organisationsweite Standards, die die IT ausrollt	Alle auf dem Rechner
Nutzer	~/.claude/CLAUDE.md	Deine persönlichen Vorlieben über alle Projekte hinweg	Nur du
Projekt	./CLAUDE.md oder ./.claude/CLAUDE.md	Team-weite Projektregeln	Dein Team, via git
Lokal	./CLAUDE.local.md	Private projektspezifische Notizen (per gitignore ausschließen)	Nur du, dieses Projekt

Claude Code liest CLAUDE.md aus deinem Arbeitsverzeichnis und jedem darüberliegenden Verzeichnis, sodass in einem Monorepo eine Wurzel-Datei und eine Paket-Datei beide greifen. Dateien in Unterverzeichnissen unterhalb deiner Position werden bei Bedarf geladen, nur wenn Claude dort Dateien liest. Führe /context in einer Session aus und prüfe die Liste Memory files, um zu bestätigen, was tatsächlich geladen wurde – das ist der schnellste Weg, um "Claude ignoriert meine CLAUDE.md" zu debuggen, was fast immer daran liegt, dass die Datei nicht an einem geladenen Ort liegt.

Was in eine CLAUDE.md-Datei gehört (und was nicht)

Die beste CLAUDE.md ist eine kurze Liste konkreter, überprüfbarer Fakten. Nimm Build- und Test-Befehle auf, das Projektlayout, Konventionen, die von den Tool-Standardeinstellungen abweichen, und die Fehler, die du mehr als einmal korrigieren musstest. Schreib "Führe npm test vor dem Commit aus" und "API-Handler liegen in src/api/handlers/", nicht "teste deine Änderungen" oder "halte Dateien ordentlich" – Konkretheit ist das, worauf Claude tatsächlich reagieren kann.

Was du weglässt, zählt genauso viel. Zwing das Modell nicht dazu, die Arbeit eines Linters zu übernehmen; wenn du ESLint oder Prettier hast, überlass ihnen die Durchsetzung des Stils und lass ihn aus der Datei heraus. Überspring alles, was Claude direkt aus der Codebasis lesen kann – Verzeichnisbäume, Abhängigkeitslisten und Architektur-Überblicke sind genau das, was der /doctor-Check von Claude Code zum Kürzen vorschlagen wird. Aufgabenspezifische, mehrstufige Abläufe gehören in eine Claude Code Skill, die bei Bedarf geladen wird, und alles Pfadspezifische ("alle API-Endpunkte brauchen Eingabevalidierung") gehört in eine .claude/rules/-Datei, die per paths:-Glob eingegrenzt ist, sodass sie nur dann in den Kontext gelangt, wenn Claude passende Dateien anfasst. Eine gute Faustregel: Wenn ein Eintrag nicht in jeder Session nützlich ist, hat er in der CLAUDE.md nichts zu suchen.

Halte sie kurz: CLAUDE.md ist ein Token-Budget, kein Wiki

Da CLAUDE.md bei jedem Zug geladen wird, kostet jede Zeile Kontext. Das von Anthropic genannte Ziel liegt bei unter 200 Zeilen pro Datei; längere Dateien verbrauchen mehr Kontext und verringern messbar, wie genau sich Claude daran hält (eine Datei über 4 MiB wird komplett übersprungen). Das Context-Engineering-Team von HumanLayer geht noch weiter, hält die eigene Datei unter 60 Zeilen und verweist auf die praktische Obergrenze, dass Frontier-Modelle nur ~150–200 Anweisungen zuverlässig befolgen – und der eigene System-Prompt von Claude Code verbraucht davon bereits rund 50, bevor du überhaupt ein Wort geschrieben hast.

Das mentale Modell, das hilft: Behandle CLAUDE.md als RAM und Skills, Regeln und Referenzdokumente als Festplatte. Du lädst beim Booten nicht die ganze Festplatte. Steck die immer geltenden Regeln in die CLAUDE.md und verweise auf alles Situative mit einem Link oder einem Import. Wenn die Datei über die 200 Zeilen hinauskriecht, ist das das Signal zum Aufteilen, nicht zum Weiterscrollen.

Andere Dateien importieren und deine AGENTS.md wiederverwenden

CLAUDE.md kann andere Dateien mit der Syntax @path/to/file einbinden. Imports werden beim Start in den Kontext expandiert, die Pfade können relativ oder absolut sein, und sie lassen sich bis zu vier Ebenen tief verschachteln. Setze einen Pfad in Backticks, wenn du ihn erwähnen willst, ohne ihn zu importieren.

Der nützlichste Fall ist Interoperabilität. Claude Code liest CLAUDE.md, nicht AGENTS.md – wenn dein Repo also bereits den werkzeugübergreifenden AGENTS.md-Standard nutzt, dupliziere ihn nicht. Erstelle eine CLAUDE.md, die ihn importiert, und ergänze darunter etwaige Claude-spezifische Hinweise:

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

Ein Symlink (ln -s AGENTS.md CLAUDE.md) funktioniert ebenfalls, wenn du keine Claude-spezifischen Ergänzungen brauchst. Ein Vorbehalt: Ein Import, der außerhalb deines Arbeitsverzeichnisses aufgelöst wird, löst einen einmaligen Bestätigungsdialog aus – ein bewusster Schutz vor Dateien, die andere Leute in ein geteiltes Repo committen.

Sie mit /init, /memory und /doctor generieren und pflegen

Du musst nicht mit einer leeren Datei anfangen. Führe /init aus, und Claude analysiert die Codebasis und schreibt eine Start-CLAUDE.md mit den Build-Befehlen, Test-Schritten und Konventionen, die es entdeckt; existiert bereits eine, schlägt es Verbesserungen vor, statt sie zu überschreiben. Es liest sogar vorhandene Cursor- und Copilot-Regeldateien und übernimmt die relevanten Teile. Behandle das Ergebnis als Entwurf – der eigentliche Wert liegt in der Handvoll Anweisungen, die Claude nicht ableiten konnte und die du hinterher ergänzt.

Von dort aus listet /memory jede Memory-Datei über alle Geltungsbereiche hinweg auf und öffnet sie, und /doctor schlägt Kürzungen für eine eingecheckte CLAUDE.md vor, indem es ableitbare Inhalte streicht, aber die Fallstricke und Begründungen behält. Wenn du Claude sagst "füg das zur CLAUDE.md hinzu", bearbeitet es die Datei direkt. Und weil die Datei einfach Markdown unter Versionskontrolle ist, durchlaufen Änderungen den Code-Review wie jeder andere Teil des Repos – so bleibt die CLAUDE.md, die unsere eigene Publishing-Pipeline hier bei TechRiseUps antreibt, über die Zeit ehrlich.

CLAUDE.md vs. automatisches Memory

Neuere Versionen von Claude Code haben ein zweites, automatisches Memory-System hinzugefügt, und es lässt sich leicht mit CLAUDE.md verwechseln. Die Aufteilung ist sauber: Du schreibst CLAUDE.md (Anweisungen und Regeln); Claude schreibt das automatische Memory (Dinge, die es über deine Vorlieben und Korrekturen beobachtet). Das automatische Memory liegt unter ~/.claude/projects/<project>/memory/, mit einem MEMORY.md-Index, dessen erste 200 Zeilen (oder 25 KB) bei jeder Session geladen werden, sowie Themen-Dateien, die bei Bedarf laden.

Halte sie in ihren Bahnen. CLAUDE.md sind deine Anforderungen; das automatische Memory ist das, was Claude darüber gelernt hat, wie du arbeitest. Claude verzichtet bewusst darauf, etwas zu speichern, das deine CLAUDE.md bereits festhält, sodass eine straffe CLAUDE.md das automatische Memory sogar sauberer macht. Du kannst all das über /memory durchsehen, bearbeiten oder löschen – es ist alles schlichtes Markdown.

Häufig gestellte Fragen

Was sollte ich in meine CLAUDE.md-Datei schreiben? Build- und Test-Befehle, die Projektstruktur, Konventionen, die von den Standardeinstellungen abweichen, und die Korrekturen, die du dich ständig wiederholen siehst. Halte jeden Eintrag konkret und überprüfbar. Lass Code-Stil weg (nutze einen Linter), aufgabenspezifische Abläufe (nutze Skills) und alles, was Claude aus dem Code lesen kann.

Wie schreibe ich die perfekte CLAUDE.md-Datei? Eine perfekte gibt es nicht, aber das verlässliche Muster ist kurz und konkret: unter 200 Zeilen, konkrete Anweisungen, unter Markdown-Überschriften gruppiert, mit situativen Details, die in Imports, Regeln oder Skills ausgelagert sind. Starte mit /init, trimm dann mit /doctor und verfeinere, während Claude Fehler macht.

Kann Claude die CLAUDE.md-Datei für mich erstellen? Ja. Ein Aufruf von /init generiert eine Start-CLAUDE.md aus deiner Codebasis, und du kannst Claude jederzeit bitten, Einträge hinzuzufügen oder zu bearbeiten. Die endgültige Datei gehört weiterhin dir – arbeite die Regeln von Hand aus, die es nicht selbst entdecken konnte.

Wie unterscheidet sich CLAUDE.md von AGENTS.md? AGENTS.md ist ein werkzeugübergreifender offener Standard; CLAUDE.md ist die Datei, die Claude Code tatsächlich lädt. Claude Code liest AGENTS.md nicht direkt – wenn du also eine pflegst, importiere sie mit @AGENTS.md in die CLAUDE.md oder verlinke die beiden per Symlink, statt doppelte Dateien zu führen.

Warum ignoriert Claude meine CLAUDE.md? Meist liegt die Datei nicht an einem geladenen Ort – führe /context aus und prüfe Memory files. Wenn sie geladen wurde, Claude aber trotzdem abweicht, mach die Anweisung konkreter, beseitige Widersprüche und verschieb alles, was immer laufen muss, in einen Hook, statt dich auf Prosa zu verlassen.

Sources

• Claude Code Doku – Wie Claude sich dein Projekt merkt: offizielle Referenz für CLAUDE.md-Speicherorte, Ladereihenfolge, Imports, Größenlimits, /init, /memory und automatisches Memory.
• HumanLayer – Writing a good CLAUDE.md: Context-Engineering-Hinweise zu Länge, progressiver Offenlegung und der Obergrenze von ~150–200 Anweisungen.