CLAUDE.md für Claude Code: was rein gehört, was nicht

Claude Code baut Dein Projekt mit dem falschen Befehl, installiert eine Bibliothek, die Du gerade erst entfernt hast, oder vergisst nach einer langen Sitzung die Regel, die Du ihm vor einer Stunde erklärt hast. Fast immer liegt das an der CLAUDE.md: Sie fehlt, sie liegt am falschen Ort, oder sie ist so lang geworden, dass die wichtige Zeile darin untergeht.

Hier erfährst Du, wo Claude Code nach seinen Anweisungsdateien sucht, was in eine gute CLAUDE.md gehört und was Du besser herauslässt. Dazu kommt die echte CLAUDE.md von sonoya.com mit einer ehrlichen Bewertung jedes Abschnitts und eine Vorlage zum Anpassen. Grundlage ist die offizielle Doku zu CLAUDE.md und Memory und zu den Best Practices, Stand November 2026 mit Claude Code 2.1.

Was die CLAUDE.md ist und was nicht

Die CLAUDE.md ist eine gewöhnliche Markdown-Datei, die Claude Code zu Beginn jeder Sitzung liest. Wichtig für alles Weitere ist, wie sie ankommt: Ihr Inhalt landet als Nachricht direkt nach dem Systemprompt im Kontext. Claude behandelt sie also als Information und Bitte, nicht als Konfiguration, die das Programm erzwingt.

Daraus folgt die wichtigste Regel dieses Artikels. Alles, was Claude wissen sollte, um gute Entscheidungen zu treffen, gehört in die CLAUDE.md. Alles, was ausnahmslos passieren muss oder niemals passieren darf, gehört in einen Hook oder eine Berechtigungsregel, denn die führt Claude Code selbst aus, egal was das Modell gerade entscheidet.

Wo Claude Code die Dateien sucht

Claude Code kennt mehrere Orte. Alle gefundenen Dateien werden aneinandergehängt, keine ersetzt eine andere:

Beim Start lädt Claude Code die CLAUDE.md und CLAUDE.local.md aus dem Ordner, in dem Du es startest, und aus allen Ordnern darüber. Was näher am Startordner liegt, steht später im Kontext. Dateien in Unterordnern lädt Claude Code erst, wenn Claude dort eine Datei liest oder bearbeitet. So kann ein Unterordner wie backend/ eigene Regeln bekommen, die im restlichen Projekt keinen Platz wegnehmen.

Für größere Projekte gibt es den Ordner .claude/rules/. Jede Markdown-Datei darin ist ein Regelblock zu einem Thema. Ohne weitere Angabe wird sie wie die CLAUDE.md bei jedem Start geladen. Mit einem paths-Feld im Kopf lädt sie nur, wenn Claude eine passende Datei anfasst:

---
paths:
  - "src/api/**/*.ts"
---
- Eingaben in API-Handlern immer mit den Schemas aus src/api/schemas/ prüfen.

Außerdem kann eine CLAUDE.md andere Dateien mit @ einbinden, etwa @docs/git-workflow.md oder @AGENTS.md. Der Pfad gilt relativ zur Datei, in der der Verweis steht, und Importe dürfen höchstens vier Ebenen tief verschachtelt sein. Liegt eine eingebundene Datei außerhalb des Projekts, fragt Claude Code einmal nach Deiner Zustimmung. Ein Import macht die Datei übersichtlicher, spart aber keinen Kontext, denn die eingebundene Datei wird immer mitgeladen.

Zwei Dinge verwechseln viele mit der CLAUDE.md. Das automatische Gedächtnis (Auto Memory) schreibt Claude selbst nach ~/.claude/projects/<projekt>/memory/, wenn Du etwa sagst „merk Dir, dass wir pnpm nutzen”. Und eine vorhandene AGENTS.md, die Datei anderer Coding-Agenten, liest Claude Code standardmäßig nur dann, wenn es im Projekt keine CLAUDE.md gibt. Pflegst Du beide, setzt Du @AGENTS.md als erste Zeile in die CLAUDE.md und schreibst die Claude-spezifischen Regeln darunter.

Der Einstieg: /init und /memory

Falls Claude Code noch nicht läuft, hilft die Anleitung: Claude Code auf dem Mac installieren & nutzen. Starte Claude Code danach im Projektordner und tippe:

/init

Claude untersucht das Projekt und schreibt einen ersten Entwurf mit Build- und Testbefehlen und den Konventionen, die es im Code findet. Gibt es schon eine CLAUDE.md, schlägt /init Verbesserungen vor, statt sie zu überschreiben. Die Doku sagt dazu sinngemäß, dass die eigentliche Arbeit danach vor allem im Streichen besteht.

Mit /memory öffnest Du jede der Dateien aus der Tabelle oben in Deinem Editor. Existiert eine noch nicht, legt der Befehl sie an. Dort schaltest Du auch das automatische Gedächtnis ein oder aus.

Was hinein gehört

Die Messlatte ist einfach: Rein kommt nur, was Claude nicht selbst aus dem Code herauslesen kann. Konkret sind das vier Sorten von Zeilen.

1. Wie Arbeit geprüft wird. Der exakte Befehl für Tests, Typprüfung und Linter, und wie ein einzelner Test läuft. Das ist laut Doku die nützlichste Zeile überhaupt, weil Claude damit sein eigenes Ergebnis kontrollieren kann.
2. Stellen, an denen der Code in die Irre führt. Ein altes Muster, das überall steht, aber nicht mehr kopiert werden soll, oder ein Ordner, der ungenutzt aussieht und trotzdem gebraucht wird.
3. Entscheidungen, die nicht im Repository stehen. Welcher Fehler-Helfer gilt, wie deployt wird, warum eine Version festgenagelt ist.
4. Alles, was Du Claude schon zweimal erklären musstest.

Formuliere jede Zeile so konkret, dass sie sich überprüfen lässt. „Einrückung mit zwei Leerzeichen” funktioniert, „Code ordentlich formatieren” nicht. Schreib zu Verboten den Grund dazu, denn mit Begründung erkennt Claude auch die Fälle, an die Du beim Schreiben nicht gedacht hast.

Was nicht hinein gehört

Genauso wichtig ist, was draußen bleibt, denn jede Zeile kostet bei jeder Aufgabe ein wenig Aufmerksamkeit, ob sie passt oder nicht.

• Was im Code steht. Ordnerstruktur, Abhängigkeitslisten und Architekturübersichten liest Claude selbst. Die Doku zählt das ausdrücklich zu den Ratschlägen, die heute überholt sind.
• Lange Abläufe und Nachschlagewissen. Eine Release-Checkliste mit zwölf Schritten oder die komplette API-Dokumentation gehören in einen Skill, der nur bei Bedarf geladen wird.
• Regeln ohne jede Ausnahme. „Lies niemals .env” ist hier nur eine Bitte. Erzwingen lässt sich das mit Hooks und Berechtigungen, wie weiter unten gezeigt.
• Geschichte und Prosa. Sätze wie „früher galt X, das wurde geändert” verwirren mehr, als sie helfen. Schreib nur, was heute gilt.
• Persönliches. Deine Testdaten oder Lieblingsbefehle gehören in die CLAUDE.local.md oder nach ~/.claude/CLAUDE.md, nicht in die Datei des Teams.
• Nachdruck in Großbuchstaben. IMPORTANT oder YOU MUST brauchten ältere Modelle. Aktuelle folgen einer ruhig formulierten Zeile, und zu viel Nachdruck führt laut Doku eher dazu, dass Claude die Regel auch dort anwendet, wo sie nicht passt.

Länge und Struktur

Die Doku empfiehlt weniger als 200 Zeilen pro Datei. Längere Dateien verbrauchen mehr Kontext und werden schlechter befolgt. Claude Code warnt beim Start und unter /status, wenn eine Datei über der empfohlenen Länge liegt.

Gliedere mit ##-Überschriften und kurzen Aufzählungen statt mit Fließtext, und lies die Datei regelmäßig auf Widersprüche durch. Stehen zwei Regeln gegeneinander, entscheidet Claude sich mehr oder weniger zufällig für eine. Ein nützliches Detail: HTML-Kommentare wie <!-- Notiz für Menschen --> entfernt Claude Code, bevor die Datei in den Kontext geht. Dort kannst Du Hinweise für Kollegen ablegen, ohne Kontext zu verbrauchen.

Das echte Beispiel: die CLAUDE.md von sonoya.com

Die neuen Artikel auf dieser Website entstehen mit Claude Code in einem Astro-Repository, in dessen Wurzel eine CLAUDE.md liegt. Sie hat 134 Zeilen, gezählt mit wc -l, liegt also unter der Empfehlung. Hier ein gekürzter Auszug, an wenigen Stellen vereinfacht, im englischen Original:

## Stack

- Astro 7+ only. No React, Vue, Svelte, Solid, Preact, Next.js
  or any other client-side UI framework.
- Astro 7 requires Vite 8. The `overrides` block in `package.json`
  pins transitive deps (`vite`, `esbuild`, `yaml`) for security
  reasons. When Astro gets a major upgrade, those pins must be raised
  in the same step or the build fails with a confusing Vite error.

## Required structure

src/
  pages/        route files
  layouts/      shared page shells
  components/   reusable Astro components
  ...

## Visual direction

The earlier monochrome rule has been overridden. The site follows
the SmartMag "NewsMag" magazine layout: black top bar, vivid red
accent, brand-colored share buttons ...

## Content

All posts live in `src/content/posts/`. Do not modify these files
by hand unless fixing a specific bug in a specific post.

## Validation

Before reporting any task complete, run the full CI chain, the same
six steps as `.github/workflows/ci.yml`, in the same order:
npm ci
npm audit --audit-level=moderate
npm run security:audit
npm run check
npm run build
npm run seo:audit

## Docker / Coolify

- Use `expose: ["8080"]`, not `ports:`. Coolify's proxy routes traffic.

## What not to do

- Do not install React, Vue, Svelte, Solid, Preact, Next.js.
- Do not introduce new categories outside the 6 buckets.

Stark: die Zeile zu den overrides. Sie erklärt etwas, das im Code merkwürdig aussieht, und nennt Grund und Folge. Ohne sie könnte Claude die Pins beim nächsten Update für eine Altlast halten und entfernen.

Stark: „Validation”. Der Abschnitt definiert, was „fertig” heißt, mit genau den Befehlen, die auch die CI auf GitHub ausführt. Wie jeder Schritt repariert wird, steht nicht hier, sondern in einem eigenen Skill, auf den die Datei verweist.

Stark: expose statt ports. Ein Fallstrick mit Begründung in einer Zeile, denn ohne ihn läge die übliche Docker-Schreibweise nahe.

Richtig platziert: „unless fixing a specific bug”. Die Regel hat eine Ausnahme und bleibt deshalb in der CLAUDE.md. Ein Hook, der jede Änderung an Artikeln blockiert, wäre zu hart.

Gut abgesichert: das React-Verbot. Zusätzlich zur Regel prüft das Skript npm run guard:no-react das Ergebnis maschinell, unabhängig davon, was das Modell entscheidet.

Schwach: „Required structure”. Die Ordnerliste sieht Claude beim ersten Blick ins Projekt selbst. Ein Satz wie „neue Build-Skripte gehören nach helpers/” würde reichen.

Schwach: „The earlier monochrome rule has been overridden”. Der Verweis auf eine alte Regel ist Geschichte. Für Claude zählt nur, was jetzt gilt.

Ausbaufähig: die Designregeln. Farben, Share-Buttons und Typografie braucht Claude nur bei der Arbeit an Komponenten und am Stylesheet. Als .claude/rules/design.md mit paths: ["src/components/**", "src/styles/**"] würden sie beim Schreiben eines Artikels keinen Platz mehr belegen.

Vorlage zum Anpassen

Diese Vorlage folgt denselben Regeln. Ersetze die Befehle und Pfade durch die Deines Projekts und lösche jeden Abschnitt, zu dem Dir nichts Konkretes einfällt:

# <Projektname>

<Ein Satz: was das Projekt ist und worauf es ankommt.>

<!-- Wartung: Neue Regel erst eintragen, wenn Claude denselben Fehler zweimal gemacht hat. -->

## Befehle
- Installieren: npm ci
- Entwicklungsserver: npm run dev
- Einzelnen Test ausführen: npx vitest run pfad/zur/datei.test.ts
- Typprüfung: npm run check

## Fertig heißt
- npm run check und npm run build laufen ohne Fehler durch.

## Konventionen
- Fehler über die Helfer in src/lib/errors.ts werfen, nie als nackten String.
- Datumswerte in UTC speichern, Anzeige auf Deutsch (de-DE).

## Fallstricke
- src/legacy/ ist noch in Betrieb: nicht löschen, aber seine Muster nicht kopieren.
- Die Pins im overrides-Block von package.json sind Absicht (Sicherheit)
  und werden bei jedem Major-Update von Astro mit angehoben.

## Nicht tun
- Keine neuen Abhängigkeiten ohne Rückfrage, weil jede ins Sicherheitsaudit geht.
- Keine Commits direkt auf main.

Die Platzhalter in spitzen Klammern ersetzt Du durch Namen und Beschreibung Deines Projekts. Der HTML-Kommentar bleibt für Menschen sichtbar und kostet keinen Kontext.

Prüfen, ob die Datei wirkt

Tippe in einer neuen Sitzung:

/context all

Unter Memory files müssen alle Dateien stehen, die beim Start geladen werden sollen. Fehlt eine dort, sieht Claude sie nicht. Eine CLAUDE.md in einem Unterordner erscheint hier nicht, weil sie erst bei Bedarf lädt. Sobald das passiert, zeigt das Terminal eine Zeile mit Loaded und dem Pfad.

Nach /compact liest Claude Code die CLAUDE.md im Projektordner neu von der Festplatte. Ist eine Anweisung nach dem Komprimieren verschwunden, stand sie nur im Chat. Dann gehört sie in die Datei.

Wenn Claude die Regel trotzdem ignoriert

Die drei häufigsten Ursachen lassen sich schnell prüfen.

• Die Datei wird nicht geladen. Sie liegt im falschen Ordner, oder Claude Code wurde in einem anderen Verzeichnis gestartet. /context all zeigt es sofort.
• Die Regel geht unter. Die Datei ist zu lang oder enthält eine zweite Regel, die der ersten widerspricht. /doctor schlägt Streichungen für eine eingecheckte CLAUDE.md vor, und /doctor prompt-audit sucht ab Version 2.1.283 nach veralteten und widersprüchlichen Anweisungen, ohne selbst etwas zu ändern.
• Die Regel darf keine Ausnahme haben. Dann ist die CLAUDE.md der falsche Ort. Ein PreToolUse-Hook, der mit Exit-Code 2 abbricht, verhindert zum Beispiel Änderungen an einem geschützten Ordner zuverlässig, und ein Eintrag wie "deny": ["Read(./.env)"] unter permissions in .claude/settings.json sperrt die Datei.

Pflege im Alltag

Behandle die CLAUDE.md wie Code: Sie liegt in Git, Änderungen laufen durch denselben Review wie der Rest, und veraltete Zeilen fliegen raus, sobald Du sie bemerkst. Der beste Zeitpunkt für eine neue Zeile ist der Moment, in dem Du Claude dieselbe Korrektur zum zweiten Mal gibst. Sag dann ausdrücklich „schreib das in die CLAUDE.md”. Mit „merk Dir das” landet die Notiz im automatischen Gedächtnis, das nur auf Deinem Rechner liegt und nicht im Repository.

CLAUDE.md, Rules, Skills, Hooks und Settings abgrenzen

Arbeitest Du zusätzlich mit Codex, zeigt Claude Code Skills in Codex nutzen, wie der zweite Agent Deine Skills und die CLAUDE.md mitliest. Die Unterschiede der beiden Werkzeuge bei Projektdateien, Preisen und Sicherheitsmodi stehen im Vergleich Claude Code oder Codex CLI: welcher Coding-Agent?.

Eine gute CLAUDE.md ist am Ende kurz und ein wenig langweilig: ein paar Befehle, ein paar Fallstricke mit Begründung, ein paar Verbote. Dann bleibt jede Zeile wichtig genug, dass Claude sie auch nach Stunden noch beachtet.