WissenClaude Code & Vibe Coding
CLAUDE.md richtig schreiben, die Datei die dein Projekt Claude erklärt
Eine CLAUDE.md ist kein Regelwerk, das Claude blind gehorcht, sondern Kontext, den er zu befolgen versucht. Was rein gehört, wo sie liegt und wo ihre Grenzen sind.
Ein neuer freier Mitarbeiter, der zum ersten Mal an deinem Projekt arbeitet, würde erst mal fragen: welcher Befehl startet die Tests, wie heißen die Ordner, worauf muss ich achten. Genau diese Fragen beantwortet die CLAUDE.md, bevor sie überhaupt gestellt werden, weil Claude die Datei am Anfang jeder Session automatisch liest.
Kurz gesagt
Die CLAUDE.md ist eine einfache Markdown-Datei im Projektordner, die Claude Code am Anfang jeder Session automatisch lädt. Sie enthält Build-Befehle, Code-Konventionen, Architekturentscheidungen und Regeln, die du sonst jede Session erneut erklären müsstest. Anders als ein hart durchgesetzter Filter ist sie Kontext, den Claude befolgen soll, nicht muss. Kurz, konkret und ohne Widersprüche geschrieben, hält sich Claude deutlich zuverlässiger daran.
Was tatsächlich rein gehört
Die offizielle Faustregel: schreib rein, was du sonst jede Session erneut erklären würdest. Build- und Testbefehle, Namenskonventionen, Architektur-Entscheidungen, die aus dem Code selbst nicht ersichtlich sind, und feste Regeln wie "immer pnpm statt npm". Was dagegen nicht reingehört: alles, was Claude aus dem Code selbst ableiten kann, etwa eine komplette Ordnerübersicht oder eine Liste aller Abhängigkeiten. Für eine mehrstufige Anleitung, die nur für einen Teilbereich gilt, eignet sich eher ein eigener Skill, der nur bei Bedarf lädt, statt jede Session Platz zu belegen.
Wo die Datei liegen kann
Es gibt mehrere Ebenen, die sich ergänzen statt sich zu überschreiben. Eine ~/.claude/CLAUDE.md in deinem Benutzerordner gilt für all deine Projekte gleichzeitig, für persönliche Vorlieben. Eine ./CLAUDE.md oder ./.claude/CLAUDE.md im Projektordner gilt für alle, die daran arbeiten, und wandert übers Git-Repository mit. Eine ./CLAUDE.local.md, die du in die .gitignore aufnimmst, bleibt nur bei dir, für Dinge wie lokale Test-URLs. Claude Code hängt alle gefundenen Dateien aneinander, von der allgemeinsten bis zur projektnächsten, sodass die zuletzt gelesene am stärksten wiegt. Nested CLAUDE.md-Dateien in Unterordnern laden erst, sobald Claude tatsächlich eine Datei aus diesem Unterordner liest.
Der schnelle Einstieg über /init
Statt bei null anzufangen, lässt sich mit dem Befehl /init eine erste CLAUDE.md automatisch erzeugen. Claude analysiert dabei dein Projekt und schreibt Build-Befehle, Testanweisungen und erkannte Konventionen hinein. Existiert schon eine Datei, überschreibt /init sie nicht, sondern schlägt nur Ergänzungen vor. Von dort aus ergänzt du das, was Claude von sich aus nicht hätte wissen können, etwa warum eine bestimmte Bibliothek bewusst vermieden wird.
Wo die Grenzen liegen
Die CLAUDE.md wird als Kontext in die Session geladen, nicht als erzwungene Konfiguration. Laut offizieller Dokumentation gibt es dafür keine Garantie auf strikte Befolgung, besonders bei vagen oder sich widersprechenden Anweisungen. Als Faustregel gilt: unter 200 Zeilen bleiben, klar und konkret formulieren, regelmäßig aufräumen. Muss eine Regel wirklich immer greifen, etwa vor jedem Commit, gehört sie eher in einen Hook als in die CLAUDE.md.
Ich denke, der größte Fehler beim Schreiben ist, die Datei wie eine Dokumentation für Menschen zu behandeln, lang und vollständig. Für Claude zählt eher das Gegenteil: je kürzer und eindeutiger, desto zuverlässiger wird sie befolgt. Eine CLAUDE.md, die niemand mehr liest, weil sie zu lang geworden ist, bringt am Ende weniger als drei klare Zeilen.
Quellen: How Claude remembers your project (Claude Code Docs) · CLAUDE.md Best Practices: The Complete 2026 Guide (DEV Community)
Häufige Fragen
Wo muss die CLAUDE.md liegen, damit sie geladen wird?
Im Projektordner unter ./CLAUDE.md oder ./.claude/CLAUDE.md, damit dein ganzes Team sie über Git mitbekommt. Für nur dich selbst, projektübergreifend, kommt eine zweite unter ~/.claude/CLAUDE.md dazu.
Überschreiben sich mehrere CLAUDE.md-Dateien gegenseitig?
Nein, sie werden aneinandergehängt, von der allgemeinsten bis zur spezifischsten. Persönliche Vorgaben aus ~/.claude/CLAUDE.md stehen vor den Projektvorgaben, die zuletzt gelesene Datei wiegt am meisten.
Kann ich mit /init eine CLAUDE.md automatisch erzeugen lassen?
Ja. Claude Code analysiert dabei dein Projekt und schreibt Build-Befehle, Testanweisungen und erkannte Konventionen hinein. Existiert schon eine Datei, schlägt /init nur Verbesserungen vor, statt sie zu überschreiben.
Warum hält sich Claude manchmal nicht an meine CLAUDE.md?
Weil die Datei als Kontext geladen wird, den Claude befolgen soll, aber nicht als hart durchgesetzte Regel. Bei widersprüchlichen oder zu vagen Anweisungen entscheidet Claude im Zweifel selbst. Für eine Regel, die wirklich immer greifen muss, ist ein Hook die zuverlässigere Wahl.
Willst du das bei dir umsetzen?
In der Community zeige ich, was bei mir hält. Im Erstgespräch schauen wir uns dein Vorhaben konkret an.