Du sitzt vor Claude Code, tippst eine Aufgabe ein – und das Modell schlägt dir einen Tech-Stack vor, den du gar nicht nutzt, ignoriert deine Naming-Conventions und startet den Dev-Server mit dem falschen Befehl. Klingt vertraut? Genau hier kommt die CLAUDE.md ins Spiel. Diese eine Datei ist das Projekt-Gehirn für Claude Code: Sie speichert den Projekt-Kontext, den das Modell sonst bei jeder Session neu erraten müsste. In diesem Artikel zeige ich dir, was in eine gute claude md gehört, wo sie liegt, wie du sie mit /init automatisch erstellst – und welche Fehler du dir sparen kannst.
Der Unterschied ist drastisch. Vorher: Du wiederholst in jedem Prompt, dass dein Projekt auf TypeScript und Vite läuft, dass Tests mit Vitest gefahren werden und dass du keine Default-Exports willst. Nachher: Du schreibst „Bau mir die Login-Komponente“ – und Claude weiß bereits, wie dein Code aussehen soll, weil alles in der CLAUDE.md steht. Weniger Reibung, weniger Korrektur-Schleifen, mehr Output.
Was ist die CLAUDE.md?
Die CLAUDE.md ist eine einfache Markdown-Datei, die Claude Code automatisch als Kontext lädt, bevor es deine erste Aufgabe bearbeitet. Du musst sie nicht manuell anhängen, nicht per Prompt referenzieren, nicht erwähnen – sie ist einfach da. Inhaltlich ist sie eine Mischung aus Onboarding-Doku und Hausordnung: Sie erklärt dem Modell, worum es im Projekt geht, mit welchem Tech-Stack du arbeitest und welche Regeln gelten.
Stell dir die Datei wie das Briefing für einen neuen Kollegen vor. Ein guter Entwickler, der frisch ins Team kommt, braucht ein paar Sätze Kontext, bevor er produktiv ist. Claude Code ist genau dieser Kollege – nur dass er bei jeder neuen Session sein Gedächtnis verliert. Die CLAUDE.md ist sein persistentes Notizbuch.
Wo liegt die CLAUDE.md und wie wird sie geladen?
Standardmäßig gehört die Datei in den Projekt-Root – also dort, wo auch deine package.json oder dein .git-Ordner liegt. Sobald du Claude Code in diesem Verzeichnis startest, wird die CLAUDE.md automatisch eingelesen. Kein Setup, kein Flag, nichts. Du kannst die Datei auch direkt in dein Projekt legen und mit deinem Team teilen, damit alle denselben Projekt-Kontext haben.
Es gibt aber noch eine zweite Ebene: die globale CLAUDE.md unter ~/.claude/CLAUDE.md. Was hier drinsteht, gilt für alle deine Projekte. Ideal für persönliche Präferenzen, die nichts mit einem konkreten Repo zu tun haben – etwa „Antworte mir knapp“ oder „Erkläre keine Basics, ich bin kein Anfänger“. Claude Code kombiniert beide Ebenen: erst die globalen Regeln, dann die projektspezifischen. So musst du allgemeine Vorlieben nur einmal festhalten.
Für Monorepos gilt: Du kannst auch in Unterverzeichnissen weitere CLAUDE.md-Dateien ablegen. Claude Code zieht den passenden Kontext heran, je nachdem, in welchem Teil des Projekts du gerade arbeitest.
Was gehört in eine gute CLAUDE.md?
Halte dich kurz und konkret. Die CLAUDE.md ist kein Wiki – jeder Satz kostet Tokens und konkurriert um die Aufmerksamkeit des Modells. Diese fünf Blöcke haben sich bewährt: Projekt-Kontext, Tech-Stack, Code-Konventionen, Befehle und Regeln. So sieht ein solides Beispiel aus:
# Projekt: TaskFlow
## Kontext
SaaS-Tool für Projektmanagement. Solo-Projekt, Fokus auf
schnelle Iteration. Zielgruppe: kleine Teams.
## Tech-Stack
- Frontend: React 19 + TypeScript + Vite
- Styling: Tailwind CSS (keine CSS-Module)
- State: Zustand
- Backend: Node.js + Hono, PostgreSQL via Drizzle ORM
- Tests: Vitest
## Code-Konventionen
- Keine Default-Exports, immer Named Exports
- Funktionale Komponenten, keine Klassen
- Dateinamen in kebab-case
- Kommentare nur, wenn das Warum nicht offensichtlich ist
## Befehle
- Dev-Server: `npm run dev`
- Tests: `npm run test`
- Lint + Typecheck: `npm run check`
- Migration: `npm run db:migrate`
## Regeln
- Vor jedem Commit `npm run check` ausführen
- Keine neuen Dependencies ohne Rückfrage
- Secrets gehören in .env, niemals in den Code
Diese Struktur ist bewusst schlank. Sie sagt Claude Code genau, womit es arbeitet, ohne es mit Roman-langen Erklärungen zuzuschütten. Wenn du mehrere Varianten für unterschiedliche Projekttypen suchst, findest du im Freebie weiter unten fünf fertige Vorlagen.
CLAUDE.md mit /init automatisch erstellen
Du musst die Datei nicht von Hand schreiben. Starte Claude Code in deinem Projekt und tippe den Befehl /init. Das Modell scannt dann deinen Code, erkennt den Tech-Stack, die Verzeichnisstruktur und die wichtigsten Befehle – und generiert daraus eine erste CLAUDE.md. Das ist der schnellste Weg zu einem brauchbaren Startpunkt, besonders bei bestehenden Codebasen.
Wichtig: Behandle das Ergebnis von /init als Entwurf, nicht als fertiges Produkt. Die automatische Erkennung trifft den groben Rahmen gut, aber deine speziellen Regeln und Konventionen kennt nur du. Geh die generierte Datei einmal durch, streiche Überflüssiges und ergänze die Dinge, die dir beim Arbeiten am häufigsten auf die Nerven gehen.
Häufige Fehler mit der CLAUDE.md
- Zu lang. Eine 500-Zeilen-CLAUDE.md verwässert die wichtigen Regeln. Halte sie unter ein, zwei Bildschirmseiten.
- Veraltet. Wenn sich dein Tech-Stack ändert, die Datei aber nicht, lügt sie das Modell an. Pflege sie wie Code.
- Zu vage. „Schreib sauberen Code“ hilft nicht. „Keine Default-Exports“ schon. Sei konkret und prüfbar.
- Alles reinpacken. Die CLAUDE.md ist kein Ersatz für deine README oder die API-Doku. Verlinke umfangreiche Inhalte, statt sie zu duplizieren.
- Nie testen. Schreib eine Regel rein und schau, ob Claude sie befolgt. Wenn nicht, formuliere sie schärfer oder rück sie an den Anfang.
CLAUDE.md vs AGENTS.md
Vielleicht ist dir AGENTS.md schon begegnet. Das ist ein tool-übergreifender Standard, der dasselbe Ziel verfolgt wie die CLAUDE.md – nämlich AI-Coding-Agents mit Projekt-Kontext zu versorgen – aber nicht an ein einzelnes Tool gebunden ist. Während die CLAUDE.md spezifisch für Claude Code ist, soll AGENTS.md von verschiedenen Agents gelesen werden können.
In der Praxis musst du dich nicht entscheiden: Claude Code kann beide Welten bedienen. Wenn du in einem Projekt mit mehreren AI-Tools arbeitest, kann es sinnvoll sein, den gemeinsamen Kontext in eine AGENTS.md zu legen und claude-spezifische Feinheiten in der CLAUDE.md zu ergänzen. Bei einem reinen Claude-Code-Setup reicht die CLAUDE.md völlig.
Best Practices für die CLAUDE.md
- Committe sie ins Repo. So profitiert dein ganzes Team – und Future-You – vom gleichen Kontext.
- Iteriere. Jedes Mal, wenn du Claude dasselbe korrigierst, gehört diese Korrektur als Regel in die Datei.
- Trenne global und lokal. Persönliche Vorlieben in
~/.claude/CLAUDE.md, Projekt-Spezifisches in den Projekt-Root. - Nutze klare Überschriften. Struktur hilft dem Modell, die richtigen Infos schnell zu finden.
- Modell-Wahl bedenken. Egal ob du mit Opus 4.8 für komplexe Tasks, Sonnet 4.6 für den Alltag oder Haiku 4.5 für schnelle Edits arbeitest – die CLAUDE.md gilt für alle gleichermaßen.
FAQ
Muss ich die CLAUDE.md in jedem Prompt erwähnen?
Nein. Claude Code lädt die Datei automatisch aus dem Projekt-Root, sobald du das Tool im Verzeichnis startest. Du musst sie weder anhängen noch referenzieren – sie ist immer Teil des Kontexts.
Was ist der Unterschied zwischen der globalen und der projektspezifischen CLAUDE.md?
Die globale Datei unter ~/.claude/CLAUDE.md gilt für alle deine Projekte und eignet sich für persönliche Präferenzen. Die projektspezifische CLAUDE.md im Projekt-Root beschreibt das konkrete Repo. Claude Code kombiniert beide, wobei die Projekt-Ebene den engeren Kontext liefert.
Wie groß sollte eine CLAUDE.md sein?
So klein wie möglich, so groß wie nötig. Als Faustregel: Wenn du beim Scrollen den Überblick verlierst, ist sie zu lang. Konzentriere dich auf die Infos, die Claude wirklich braucht, um in deinem Projekt produktiv zu sein.
Fazit
Die CLAUDE.md ist der größte Hebel für besseren Output aus Claude Code – und gleichzeitig einer der am meisten unterschätzten. Statt in jedem Prompt deinen Projekt-Kontext zu wiederholen, schreibst du ihn einmal sauber auf und lässt das Modell ihn automatisch laden. Starte mit /init, kürze das Ergebnis auf das Wesentliche, und ergänze jede Korrektur, die du sonst zehnmal tippen würdest, als Regel. Deine claude md wächst so organisch mit deinem Projekt.
