CLAUDE.md richtig nutzen: Das Projekt-Gehirn für Claude Code

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. Und ganz nebenbei sparst du Tokens, weil du den Kontext nicht mehr manuell in jeden Prompt tippst.

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. In der offiziellen Claude-Code-Dokumentation zum Memory-System wird das ganz nüchtern beschrieben: Jede Session startet mit einem frischen Kontextfenster, und die CLAUDE.md ist der Mechanismus, der Wissen über diese Grenze hinweg trägt.

Ein wichtiger Punkt, den viele unterschätzen: Die Datei beeinflusst jeden Task und jeden Output. Sie ist kein Nachschlagewerk, das nur bei Bedarf gezogen wird, sondern permanenter Bestandteil des Kontexts. Das ist ihre größte Stärke – und gleichzeitig der Grund, warum jede überflüssige Zeile darin weh tut. Dazu später mehr.

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 ins Repo legen und mit deinem Team teilen, damit alle denselben Projekt-Kontext haben.

Was du wahrscheinlich noch nicht wusstest: Es gibt nicht nur zwei Ebenen, sondern mittlerweile sechs. Klingt ganz schön kompliziert? Ist es nicht – du brauchst im Alltag meistens nur zwei davon. Aber es hilft zu wissen, was es sonst noch gibt.

Die sechs Ebenen der Memory-Hierarchie

• Managed Policy – unter macOS in /Library/Application Support/ClaudeCode/CLAUDE.md, unter Linux in /etc/claude-code/CLAUDE.md. Für Organisations-Richtlinien, die niemand einzeln aushebeln soll.
• User Memory – ~/.claude/CLAUDE.md. Deine persönlichen Präferenzen, gültig für alle Projekte.
• Project Memory – ./CLAUDE.md oder ./.claude/CLAUDE.md. Team-Regeln, die über Git geteilt werden.
• Local Project – ./CLAUDE.local.md. Dein persönlicher Kram für genau dieses Projekt, gehört in die .gitignore.
• Project Rules – ./.claude/rules/*.md. Modulare Regeln, die du sauber nach Thema trennen kannst.
• Auto Memory – ~/.claude/projects/<project>/memory/. Notizen, die Claude sich selbst schreibt.

Wer gewinnt bei Konflikten?

Die Regel ist angenehm simpel: Spezifischer schlägt allgemeiner. Was im Projekt steht, überschreibt deine globalen Vorlieben. Geladen wird rekursiv – Claude Code läuft vom aktuellen Arbeitsverzeichnis nach oben bis zum Root und sammelt unterwegs alles ein, was es findet. CLAUDE.md-Dateien in Unterverzeichnissen werden dagegen erst bei Bedarf gezogen, also genau dann, wenn du in dem jeweiligen Bereich arbeitest. Für Monorepos ist das Gold wert: Der Root bleibt schlank, und jedes Package bringt seinen eigenen Feinkontext mit.

User oder Projekt – was gehört wohin?

Diese Frage bekomme ich oft. Meine Faustregel: Alles, was mit dir zu tun hat, geht in die User-Ebene. Alles, was mit dem Repo zu tun hat, in die Projekt-Ebene.

• User Memory: Kommunikationsstil („antworte knapp“), persönlicher Coding-Stil, Editor-Setup, Paketmanager-Vorliebe
• Project Memory: Tech-Stack, Team-Konventionen, Architektur, Build- und Test-Befehle, Git-Konventionen

Wenn du das sauber trennst, bleibt jede Datei kurz. Und kurz ist – du ahnst es – der ganze Trick.

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. Bewährt hat sich ein einfacher Denkrahmen, den ich WHAT-WHY-HOW nenne: Was ist das Projekt, warum ist es so gebaut, wie es gebaut ist, und wie arbeitest du darin. Wenn eine Zeile keine dieser drei Fragen beantwortet, fliegt sie raus.

Die zehn Abschnitte mit dem besten Verhältnis von Aufwand zu Wirkung

1. Projekt-Übersicht – zwei, drei Sätze, was das Ding überhaupt ist
2. Tech-Stack – inklusive einer „NOT TO USE“-Zeile, die ist erstaunlich wirksam
3. Architektur – nur die grobe Landkarte, keine Detailkarte
4. Befehle – der höchste ROI der ganzen Datei
5. Code-Konventionen – prüfbar formuliert, nicht schwammig
6. UI- und Design-System – falls vorhanden
7. Wichtige Dateien – als Referenz, nicht als Kopie
8. „Do Not Touch“-Regeln – auto-generierte Ordner, Legacy-Code, .env.local
9. Test- und Qualitätsstandards
10. Domain-Vokabular – wenn ihr im Team eigene Begriffe nutzt

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
Package Manager: pnpm (NICHT npm oder yarn)
Code-Konventionen
Keine Default-Exports, immer Named Exports
Funktionale Komponenten, keine Klassen
Dateinamen in kebab-case
Frühe Returns, keine Verschachtelung über 3 Ebenen
Kommentare nur, wenn das Warum nicht offensichtlich ist
Befehle
Dev-Server: pnpm dev
Tests: pnpm test
Lint + Typecheck: pnpm check
Migration: pnpm db:migrate
Nicht anfassen
src/generated/ – wird automatisch erzeugt
.env.local – enthält Secrets
Regeln
Vor jedem Commit pnpm 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.

Vorlagen für unterschiedliche Projekttypen

Nicht jedes Projekt braucht dieselbe Datei. Ein Ein-Personen-Skript kommt mit 25 Zeilen aus, ein Monorepo braucht eine andere Aufteilung als eine WordPress-Agentur. Hier sind die vier Muster, mit denen ich in der Praxis arbeite:

• Minimal (~25 Zeilen): nur Befehle, die zwei, drei wichtigsten Konventionen und die bekannten Fallstricke. Für kleine Repos ist alles darüber wie mit Kanonen auf Spatzen zu schießen.
• Next.js SaaS (~80 Zeilen): Befehle, Architektur, Component-Regeln, Auth-Setup, Zahlungs-Flow und eine klare Ansage wie „vor dem Push immer Typecheck und Lint“.
• Monorepo-Root: Struktur der Packages, Root-Befehle, Cross-Package-Regeln. Die Details wandern in die Unterverzeichnisse.
• WordPress-Agentur: hier lohnen sich sehr spezifische Regeln – etwa wie REST-API-Aufrufe zu quoten sind (Datei schreiben und curl -d @file statt HEREDOC), dass das Featured Image nicht in den Body gehört, dass nach dem Deploy der Cache geleert wird und welcher Builder gilt (Divi, Gutenberg oder Elementor).

Was alle vier gemeinsam haben: Sie beschreiben nicht, was Claude ohnehin aus dem Code lesen kann. Verzeichnisbäume, Dependency-Listen, offensichtliche Architektur – das kostet nur Platz. Rein gehört das, was Claude nicht erraten kann: eure Eigenheiten, eure Stolperfallen, eure bewussten Abweichungen vom Standard.

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.

Seit März 2026 gibt es zusätzlich eine konversationelle Variante. Du startest sie mit CLAUDE_CODE_NEW_INIT=1 claude, und statt einfach loszuscannen stellt Claude dir Fragen zu deinem Workflow. Am Ende schlägt es dir nicht nur eine CLAUDE.md vor, sondern auch passende Skills und Hooks. Für Projekte, bei denen der Code allein nicht die halbe Wahrheit erzählt, ist das deutlich angenehmer.

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 kennst 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. Manche Entwickler schreiben die Datei bewusst komplett von Hand – auch das ist eine legitime Haltung, weil man dabei automatisch über jede Zeile nachdenkt.

Weniger ist mehr: das Aufmerksamkeits-Budget

Jetzt kommt der Teil, den fast alle falsch machen. Die Versuchung ist riesig, immer mehr in die CLAUDE.md zu packen. Jede Korrektur, jede Ausnahme, jede Kleinigkeit. Nach ein paar Monaten hast du 500 Zeilen – und das Modell befolgt weniger als vorher. Das ist kein Bug, sondern Physik.

Belegt ist der Effekt inzwischen ziemlich gut. Die viel zitierte Context-Rot-Studie von Chroma hat 18 Modelle getestet – und jedes einzelne davon wurde mit wachsendem Kontext schlechter, teils von rund 95 auf 60 Prozent Trefferquote. Nicht die meisten. Alle. Auch die mit den riesigen Kontextfenstern. Größer heißt eben nicht besser.

Meine Empfehlung deshalb ganz konkret:

• Unter 200 Zeilen als harte Obergrenze – die offizielle Doku nennt genau diese Marke als Punkt, ab dem die Adhärenz leidet
• Die richtig guten Dateien, die ich gesehen habe, liegen unter 60 Zeilen
• Formuliere spezifisch und imperativ: ❌ „Schreibe sauberen Code“ → ✅ „Verwende frühe Returns, keine Verschachtelung über 3 Ebenen“
• Bei nuancierten Regeln: Beispiele einbauen, gerne als ✅/❌-Codeblock. Ein Beispiel schlägt drei Absätze Erklärung.
• Deterministische Aktionen gehören in Hooks, nicht in die CLAUDE.md. Die Datei ist beratend, ein Hook ist garantiert.

Der letzte Punkt ist der wichtigste – und der am seltensten befolgte. Wenn etwas immer passieren muss, schreib keinen Wunsch in eine Markdown-Datei, sondern bau einen Hook. Faustregel: Was in der CI einen Merge blocken würde, gehört in die CI. Was einen Reviewer die Augenbraue heben lässt, gehört in die CLAUDE.md.

Modular arbeiten: Rules, Imports und Auto Memory

„Aber ich habe halt viel Kontext!“ – kenne ich. Das muss aber gar nicht alles in eine Datei. Es gibt drei Wege, die Last zu verteilen.

.claude/rules – modulare Regeln

Dateien unter .claude/rules/*.md werden automatisch mitgeladen. Der Clou: Über YAML-Frontmatter mit einem paths:-Eintrag kannst du Regeln an Pfade koppeln. Die Regel für deine API-Handler wird dann nur geladen, wenn Claude tatsächlich an einem API-Handler arbeitet. Genau so bleibt der Root schlank und der Kontext trotzdem präzise.

@import – Referenzen statt Copy-Paste

Mit der @import-Syntax ziehst du andere Dateien rein: @README.md, @docs/architecture.md oder auch @~/.claude/meine-regeln.md. Rekursiv sind bis zu vier Hops erlaubt. Ein Wort der Warnung: Das ist kein Lazy Loading. Importierte Dateien landen beim Start im Kontext und kosten dich dein Budget genauso wie direkt geschriebene Zeilen. Imports sind gut für Ordnung – nicht fürs Sparen.

Auto Memory – Claudes eigene Notizen

Claude Code legt unter ~/.claude/projects/<project>/memory/ selbst Notizen an: Build-Befehle, Debugging-Erkenntnisse, deine Korrekturen. Die MEMORY.md darin funktioniert als Index – die ersten 200 Zeilen werden pro Session geladen, themenspezifische Dateien holt sich Claude bei Bedarf. Das Ganze ist maschinenlokal und landet nicht in Git. Mit /memory schaust du rein und räumst auf, mit CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 schaltest du es ab.

Ich finde folgendes Bild dafür sehr treffend: Die CLAUDE.md ist die Verfassung – explizite Regeln, die du bewusst geschrieben hast. Auto Memory ist das Fallrecht – es wächst aus der Praxis. Und wie im echten Leben gilt: Bei Konflikt schlägt die Verfassung das Fallrecht.

Überlebt die CLAUDE.md ein /compact?

Kurze Antwort: Ja. Und das ist wichtiger, als es klingt. Nach einem /compact liest Claude Code die CLAUDE.md frisch von der Platte und injiziert sie neu in den Kontext. Deine Regeln sind also noch da.

Was nicht überlebt, sind Anweisungen, die du nur im Chat gegeben hast. „Ach übrigens, nutz bitte immer Named Exports“ – nach der Komprimierung ist das weg. Und genau das ist der häufigste Grund für das Gefühl „Claude hat plötzlich alles vergessen“. Wenn dir eine Anweisung wichtig ist, gehört sie in die Datei, nicht in den Verlauf.

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.
• Linter-Regeln eintragen. Was dein ESLint schon erzwingt, muss nicht nochmal ins Aufmerksamkeits-Budget. Reine Budget-Verschwendung.
• Code-Blöcke pasten. Kopierter Code veraltet garantiert. Referenziere die Datei stattdessen.
• Task-spezifisches global machen. Anweisungen für genau eine Aufgabe gehören in einen Subagent oder Slash-Command.
• Widersprüche zur Tooling-Config. Wenn die CLAUDE.md „2 Spaces“ sagt und Prettier 4 erzwingt, verliert am Ende dein Nervenkostüm.
• Zu viele Imports. Jeder Import kostet Kontext, auch wenn er nie gebraucht wird.
• CLAUDE.local.md nicht in .gitignore. Klassiker. Dein Kollege wird sich freuen.
• Sensitive Daten. Nur ENV-Namen reinschreiben, niemals Werte.
• Auto Memory nie aufräumen. Auch das wächst und wächst.
• 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. Der Standard hat ordentlich Fahrt aufgenommen: Laut agents.md nutzen ihn inzwischen über 60.000 Open-Source-Projekte, und mehr als 30 Coding-Agents lesen das Format.

Der Haken: Claude Code liest nativ nur die CLAUDE.md, nicht die AGENTS.md. Das ist kein Drama, du hast zwei saubere Lösungen:

• Import: Schreib einfach @AGENTS.md in deine CLAUDE.md. Damit zieht Claude Code den gemeinsamen Kontext mit rein, und du kannst darunter claude-spezifische Feinheiten ergänzen.
• Symlink: ln -s AGENTS.md CLAUDE.md. Eine Datei, alle Tools. Am elegantesten, wenn wirklich alles identisch sein soll.

In der Praxis musst du dich also nicht entscheiden. Wenn du in einem Projekt mit mehreren AI-Tools arbeitest, leg den gemeinsamen Kontext in die AGENTS.md und die Claude-Feinheiten in die CLAUDE.md. Bei einem reinen Claude-Code-Setup reicht die CLAUDE.md völlig.

Was zuletzt dazugekommen ist

Claude Code entwickelt sich schnell, und ein paar Neuerungen betreffen die CLAUDE.md direkt. Diese drei solltest du kennen:

• Safe Mode. Seit Juni 2026 startest du mit claude --safe-mode (oder CLAUDE_CODE_SAFE_MODE=1) eine Session komplett ohne Customizations – keine CLAUDE.md, keine Plugins, keine Skills, keine Hooks, kein MCP. Klingt unspektakulär, ist aber ein Diagnose-Werkzeug erster Güte: Wenn sich Claude seltsam verhält, weißt du danach sofort, ob deine Konfiguration schuld ist oder nicht.
• /cd. Ebenfalls seit Juni 2026 kannst du mitten in der Session das Verzeichnis wechseln, ohne dass der Cache neu aufgebaut wird. Im Monorepo spart das spürbar Zeit.
• Größere Kontextfenster. Seit Juli 2026 ist Sonnet 5 mit einer Million Token Kontext das Standardmodell. Das entschärft das Längen-Limit theoretisch – praktisch bleibt das Budget-Problem exakt bestehen. Mehr Platz heißt nicht mehr Aufmerksamkeit.

Ganz allgemein hilft es, die CLAUDE.md nicht isoliert zu sehen. Claude Code hat sieben Erweiterungspunkte: CLAUDE.md, Skills, Subagents, Agent Teams, Plugins, Hooks und MCP-Server. Die CLAUDE.md ist davon der Einstieg – aber eben nicht der Ort, an dem alles landen muss. Sobald etwas eine mehrstufige Prozedur ist, wird ein Skill draus. Sobald etwas erzwungen werden muss, wird ein Hook draus. Diese Arbeitsteilung ist der eigentliche Reifegrad-Sprung.

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, deinen Privatkram in CLAUDE.local.md.
• Nutze klare Überschriften. Struktur hilft dem Modell, die richtigen Infos schnell zu finden.
• Lagere Tiefe aus. Progressive Disclosure heißt das Prinzip: ausführliche Doku in eigene Dateien, in der CLAUDE.md nur die Referenz.
• Räum regelmäßig auf. Eine Datei, die jedes Quartal ein bisschen schrumpft, wird meistens besser.
• Modell-Wahl bedenken. Egal ob du mit Opus für komplexe Tasks, Sonnet für den Alltag oder Haiku für schnelle Edits arbeitest – die CLAUDE.md gilt für alle gleichermaßen.

Wenn du tiefer einsteigen willst: Anthropic hat die eigenen Best Practices für Claude Code öffentlich dokumentiert. Vieles davon deckt sich mit dem, was ich hier beschreibe – und das ist ein gutes Zeichen.

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 rigoros auf das Wesentliche, und ergänze jede Korrektur, die du sonst zehnmal tippen würdest, als Regel. Halte dich unter 200 Zeilen, schieb deterministische Dinge in Hooks und alles Tiefe in eigene Dateien. Deine claude md wächst so organisch mit deinem Projekt – aber sie wächst kontrolliert. Und genau darin liegt der Unterschied zwischen einer Datei, die hilft, und einer, die im Weg steht.

Leg direkt los: Sichere dir mein kostenloses Freebie mit 5 erprobten CLAUDE.md-Templates – für Frontend, Backend, Monorepo und mehr. Und wenn du Claude Code wirklich von Grund auf meistern willst, schau dir den Claude-Code-Kurs an, der dich Schritt für Schritt vom Setup zum produktiven Workflow bringt.

Häufig gestellte Fragen