Die CLAUDE.md Datei: Was sie ist und warum jedes Projekt eine braucht

Du hast dein Projekt schon einmal Claude Code erklaert. Den Stack, die Befehle, den einen Ordner, den es niemals anfassen darf, den Grund fuer diese seltsame Retry-Schleife. Dann hast du die Session geschlossen, am naechsten Morgen eine neue geoeffnet und musstest alles noch einmal erklaeren. Eine CLAUDE.md Datei ist die Loesung. Es ist eine einfache Markdown-Datei, die Claude Code zu Beginn jeder Session liest und als feste Anweisungen behandelt, sodass der Kontext, den du sonst neu eintippen wuerdest, schon geladen ist, bevor du ein Wort sagst. Hier steht, was sie ist, wo sie liegt, wie sie tatsaechlich ladet und warum jedes ernsthafte Projekt eine haben sollte.

Das Wichtigste in Kuerze

• Eine CLAUDE.md Datei ist eine einfache Markdown-Datei, die Claude Code automatisch zu Beginn jeder Session liest und als feste Projektanweisungen in seinen Kontext aufnimmt.
• Sie existiert, weil Claude Code standardmaessig kein Gedaechtnis zwischen Sessions hat. Ohne sie beginnt jede Session bei null.
• Sie kann auf mehreren Ebenen liegen (Projekt-Root, Home-Verzeichnis, Unterverzeichnisse), und Claude kombiniert sie, wobei die naehere Datei Vorrang hat.
• Halte sie schlank und konkret. Alles darin konkurriert um die Aufmerksamkeit des Modells, und die Anthropic-Empfehlung liegt deutlich unter 200 Zeilen.
• Eine CLAUDE.md Datei sagt der KI, WIE sie in diesem Repo arbeiten soll. Sie ist nicht dafuer gebaut, deine sich veraendernden Fakten und Entscheidungen zu halten, und keins von beidem bleibt aktuell, wenn nicht etwas es aktuell haelt.

---

Was eine CLAUDE.md Datei ist

CLAUDE.md ist eine einfache Markdown-Datei, nach der Claude Code, Anthropics Kommandozeilen-Coding-Tool, sucht, wenn es eine Session in einem Verzeichnis startet. Findet es eine, liest es die ganze Datei und laedt den Inhalt in den Kontext, bevor deine erste Nachricht kommt. Praktisch wird die Datei zu einem Teil der festen Anweisungen, mit denen das Modell fuer diese Session arbeitet, so wie es ein System-Prompt tut. Du schreibst sie einmal im Klartext, und sie gilt fuer jede kommende Session, bis du sie aenderst.

Der Grund, warum das wichtig ist, ist einfach: standardmaessig erinnert sich Claude Code an nichts zwischen Sessions. Schliess das Fenster, oeffne ein neues, und du sprichst mit einer frischen Instanz, die dein Projekt nie gesehen hat. Sie erinnert sich nicht an die Entscheidungen von gestern, die vereinbarten Konventionen oder den Fehler, den du letzte Woche zweimal korrigiert hast. CLAUDE.md ist der Mechanismus, den Anthropic in das Tool eingebaut hat, um diese Luecke zu schliessen: das eine Stueck dauerhaften, session-uebergreifenden Kontexts, das du selbst schreibst und direkt steuerst.

Das hilfreiche mentale Modell: Es ist die Onboarding-Notiz, die du fuer einen erfahrenen Freelancer schreiben wuerdest, der ein starker Entwickler ist, aber deine Codebasis nie gesehen hat. Du bringst ihm nicht das Programmieren bei. Du erklaerst ihm die wenigen Dinge, die spezifisch fuer dein Projekt sind und die ihn sonst einen Tag Herumsuchen kosten wuerden.

Warum jedes Projekt eine braucht

"Jedes Projekt" klingt uebertrieben, bis du die Kosten zaehlst, keine zu haben. Das bringt dir eine CLAUDE.md Datei wirklich.

• Du wiederholst dich nicht mehr. Den Build-Befehl, den Test-Befehl, das Detail "wir nutzen pnpm, nicht npm": du schreibst jedes einmal, statt am Anfang jedes Prompts.
• Claude fuehrt die richtigen Befehle aus. Wenn die Datei die genauen Test- und Lint-Befehle nennt, nutzt Claude sie, statt einen plausiblen, aber falschen zu raten. Seine Faehigkeit, die eigene Arbeit zu pruefen, haengt davon ab zu wissen, wie du pruefst.
• Es wiederholt deine Fehler nicht. Die wertvollsten Zeilen in den meisten Dateien sind Korrekturen. Jedes Mal, wenn die KI denselben falschen Schritt zweimal macht, schreibst du die Korrektur einmal, und es hoert auf.
• Dein Team teilt ein Gehirn. Eine committete CLAUDE.md bedeutet, dass Claude Code bei jedem Entwickler denselben Konventionen folgt, sodass neue Mitarbeiter das Stammeswissen des Projekts am ersten Tag erben.
• Das Ergebnis wird spezifisch fuer dich. Generischer Output ist die Voreinstellung, wenn das Modell nichts ueber deine Situation weiss. Projektkontext ist der guenstigste Hebel, um das Ergebnis auf deine tatsaechliche Codebasis abzustimmen.

Ein Projekt ohne CLAUDE.md ist nicht neutral. Es ist eins, in dem du in jeder Session die Erklaerungssteuer zahlst und in dem Claude Dinge raet, die du ihm einfach haettest sagen koennen.

Wo eine CLAUDE.md Datei liegt

Claude Code prueft mehrere Orte, und sie stapeln sich, statt zu konkurrieren. Die naehere Datei ergaenzt die breitere, und wenn zwei Dateien im Konflikt stehen, gewinnt der spezifischere Ort.

Zwei Details, die oft stolpern lassen. Erstens ist der Dateiname case-sensitiv: er muss genau CLAUDE.md lauten, Name in Grossbuchstaben und Endung in Kleinbuchstaben. Zweitens liest Claude in einem Monorepo die Datei, die dem bearbeiteten Code am naechsten ist, sodass eine /frontend/CLAUDE.md und eine /backend/CLAUDE.md unterschiedliche Konventionen tragen koennen, ohne sich in die Quere zu kommen. Unter Windows loest ~/.claude zu %USERPROFILE%\.claude auf.

Wie sie tatsaechlich ladet

Das Ladeverhalten lohnt sich zu verstehen, weil ein paar seiner Eigenheiten echte Verwirrung stiften.

Claude liest CLAUDE.md zu Beginn einer Session. Das bedeutet, dass Aenderungen, die du waehrend einer aktiven Session an der Datei vornimmst, nicht automatisch uebernommen werden. Wenn du eine Regel mitten in der Session aenderst, starte eine frische Session, damit sie wirkt. Ein schneller Weg, um zu pruefen, ob die Datei ueberhaupt geladen wurde: oeffne eine neue Session und frag Claude, was deine CLAUDE.md sagt.

Die Anweisungen sind Leitlinie, keine Erzwingung. Claude behandelt die Datei als starken Kontext, nicht als hartes Tor. Wenn du eine Aktion wirklich blockieren musst, egal was das Modell entscheidet, ist dafuer ein Tool-Use-Hook da, nicht eine Zeile in CLAUDE.md. Die Datei praegt das Verhalten; sie kontrolliert es nicht.

Die Datei konkurriert auch um Kontext. Alles darin wird in dasselbe Fenster geladen, das Claude fuer deine eigentliche Arbeit nutzt. Eine knappe Datei laesst mehr Raum fuer die Aufgabe; eine ueberladene verwaessert sowohl deine wichtigen Regeln als auch das Budget, das das Modell zum Denken braucht. Anthropics Empfehlung zielt darauf, jede Datei deutlich unter 200 Zeilen zu halten, und in der Praxis funktioniert eine Root-Datei mit 50 bis 100 Zeilen, deren Details in pfad-basierte Regeln ausgelagert sind, besser als eine lange Datei.

Fuer groessere Setups unterstuetzt CLAUDE.md Imports mit einer @path/to/file Syntax, sodass du die Hauptdatei schlank halten und ein detailliertes Dokument nur einbeziehen kannst, wenn es relevant ist.

Was in eine CLAUDE.md Datei gehoert

Es gibt kein vorgeschriebenes Format. Die besten Dateien halten die dauerhaften, projektspezifischen Fakten, die beim Lesen des Codes nicht offensichtlich sind:

• Was das Projekt ist, in zwei oder drei Zeilen: Zweck und Stack.
• Befehle, die zaehlen: die genauen Test-, Dev-Server-, Lint- und Build-Befehle.
• Konventionen, denen du immer folgst: "jeder DB-Zugriff laeuft ueber queries.ts, nie rohes SQL in Handlern."
• Dinge, die zu vermeiden sind: veraltete Ordner, verbotene Abhaengigkeiten, Muster, von denen du abgeruckt bist.
• Fehler, die Claude immer wieder macht: die Korrekturen, die aus einem wiederkehrenden Aergernis eine einmalige Loesung machen.

Halte Secrets heraus, ganze eingefuegte Dokumente, generische Ratschlaege, die jeder kompetente Entwickler kennt, und Changelog-Historie, die ins git gehoert. Der Test fuer jede Zeile: Muesste ein starker Entwickler, der neu in diesem Repo ist, das gesagt bekommen, und wuerde es echte Zeit sparen? Wenn ja, gehoert es hinein.

Ein minimaler Starter zum Kopieren

Der schnellste Weg, eine zu erstellen, ist der eingebaute /init Befehl. Fuehr ihn in deinem Projekt aus, und Claude scannt deine Codebasis (Package-Dateien, Konfiguration, Struktur) und erzeugt eine Starter-CLAUDE.md mit erkannten Befehlen und Konventionen. Behandle das als Entwurf, nicht als fertige Datei, und kuerze sie.

Wenn du lieber von Hand anfaengst, hier ist ein bewusst minimales, kopierbares Geruest. Es ist absichtlich kurz. Jede Zeile sagt Claude entweder, wie das Projekt laeuft, eine Konvention, die es nicht kennen wuerde, oder einen Fehler, den es vermeiden soll.

# CLAUDE.md

## Project

Internal billing service. Node + TypeScript, Postgres, deployed on Fly.
Handles subscriptions, invoices, and Stripe webhooks.

## Commands

- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test` (run before every commit)
- Types: `pnpm typecheck`
- Lint: `pnpm lint`

## Conventions

- Money is integer cents, never floats. Use the `Money` type.
- All DB access goes through `src/db/queries.ts`. No raw SQL in handlers.
- New endpoints get a test in `test/api/` in the same PR.

## Avoid

- Do not add retry loops around `stripe.ts`. It is idempotent by design.
- The `legacy/` folder is deprecated. Do not extend it; flag if touched.

Du kannst das mit der Zeit erweitern, aber eine kurze Datei, der Claude tatsaechlich folgt, schlaegt eine lange, die es nur ueberfliegt. Wenn du die ausfuehrliche Behandlung von Struktur, Abschnitten und Hygiene willst, ist das ein eigenes Thema; hier geht es darum, was die Datei ist und warum du sie brauchst.

Der Teil, den jeder Guide auslaesst: WIE ist nicht dasselbe wie WAS

Hier ist die Unterscheidung, an der die meisten CLAUDE.md Erklaerungen vorbeigehen, und sie ist der Grund, warum selbst eine perfekte Datei eine Luecke laesst.

Eine CLAUDE.md Datei sagt der KI, wie sie in einem Projekt arbeiten soll. Befehle, Konventionen, Grenzen. Sie ist prozedural, und sie handelt von der Codebasis, nicht von dir.

Deine Fakten sind eine andere Art von Kontext. Wer deine Nutzer sind, was du letzte Woche zum Pricing entschieden hast, warum ein Feature existiert, die Begruendung aus einem Meeting, die es nie in ein Dokument geschafft hat, deine Meinung zu einer Bibliothek, die Richtung, in die du letzten Monat gepivotet bist. Dieses Wissen macht den Output einer KI spezifisch fuer deine tatsaechliche Situation, statt nur generisch richtig. Es gehoert nicht in eine projektbezogene Setup-Datei, weil es keine Prozedur ist und nicht auf ein Repo begrenzt ist. Es folgt dir ueber jedes Projekt und jedes Tool, das du nutzt.

Beide Arten von Kontext teilen dasselbe Versagensmuster: sie veralten von Hand. Eine CLAUDE.md driftet in dem Moment, in dem sich der Code aendert und du vergisst, die Datei zu bearbeiten, und dann folgt Claude selbstbewusst einer Regel, die nicht mehr stimmt. Deine Fakten driften schneller, weil sich deine Welt schneller bewegt als dein Repo, und niemand plant eine Aufgabe "geh alle meine Notizen aktualisieren". Der Unterschied ist, dass eine CLAUDE.md klein genug ist, um sie mit Disziplin zu pflegen. Deine Fakten sind zu viele und zu schnelllebig, um sie durch das Bearbeiten von Dateien aktuell zu halten.

Eine CLAUDE.md sagt der KI, wie. Deine aktuellen Fakten sind eine eigene Aufgabe.

Das WAS aktuell halten, ohne es zu betreuen

Hier verdient sich ein selbstpflegendes Gedaechtnis seinen Platz neben einer gut gefuehrten CLAUDE.md. Statt dass du Aenderungen gegen deine eigenen Notizen einreichst, baut ein Tool wie Locul ein zweites Gehirn aus dem, was du ohnehin produzierst (Markdown-Dateien, PDFs, Diktate, Notion, dein LinkedIn-Profil), und haelt es auf deiner Maschine aktuell. Wenn sich ein Fakt aendert, markiert es den alten als abgeloest und den neuen als aktiv, sodass die KI aus der aktuellen Wahrheit arbeitet. Es liefert diesen Kontext dann ueber MCP an Claude Code und deine anderen Tools, sodass das "Was" ueber jedes Tool reist, das du nutzt, nicht nur Claude Code.

Die zwei Teile ergaenzen sich. Deine CLAUDE.md uebernimmt das prozedurale WIE fuer ein bestimmtes Repo. Ein lebendiges Gedaechtnis uebernimmt das WAS: deine aktuellen Fakten und Entscheidungen, frisch gehalten ohne Pflegeritual. Und weil das meiste, aus dem wir arbeiten, geliehen ist, kannst du ein kuratiertes Memory Pack (ein Buendel der besten Fakten, Meinungen und Playbooks fuer einen Bereich) in dieses Gehirn injizieren, sodass das Denken eines erfahrenen Operators in deinem Output auftaucht, so wie deine Projektkonventionen in Claude Code auftauchen. Wie CLAUDE.md neben Claudes anderen Gedaechtnisformen steht, deckt der Claude Memory Guide im vollen Bild ab.

Eine CLAUDE.md ist nur so aktuell wie ihre letzte Bearbeitung. Die Fakten, die deine KI nach dir klingen lassen, bewegen sich schneller, als du von Hand bearbeiten kannst.

Haeufig gestellte Fragen

Wofuer wird eine claude.md Datei verwendet?

Sie gibt Claude Code feste, projektspezifische Anweisungen, die es zu Beginn jeder Session liest: was das Projekt ist, die Befehle zum Ausfuehren, die Konventionen und die zu vermeidenden Fehler. Sie beseitigt die Notwendigkeit, dein Projekt jedes Mal neu zu erklaeren, wenn du eine neue Session oeffnest, und sie wird Teil des Kontexts, aus dem Claude arbeitet.

Wo liegt die claude.md Datei?

Auf mehreren Ebenen, die sich stapeln. Im Projekt-Root (./CLAUDE.md) fuer team-weite Regeln, die du ins git committest, in deinem Home-Verzeichnis (~/.claude/CLAUDE.md) fuer persoenliche Vorlieben ueber jedes Projekt und optional in einem Unterverzeichnis (./packages/x/CLAUDE.md) fuer Regeln, die auf einen Teil eines Monorepos begrenzt sind. Bei Konflikten gewinnt die naehere, spezifischere. Der Dateiname ist case-sensitiv und muss genau CLAUDE.md lauten.

Wie erstelle ich eine claude.md Datei?

Der schnellste Weg ist, /init in deinem Projekt auszufuehren. Claude Code scannt deine Codebasis und erzeugt eine Starter-Datei mit den erkannten Befehlen und Konventionen. Behandle diesen Output als Entwurf: pruefe ihn, streiche Generisches und ergaenze die projektspezifischen Details und Korrekturen, die er verpasst hat. Du kannst die Datei auch einfach von Hand aus einem kurzen Geruest erstellen.

Wie lang sollte eine claude.md Datei sein?

Kuerzer, als du denkst. Alles in der Datei laedt in dasselbe Kontextfenster, das Claude fuer die Arbeit nutzt, sodass eine lange Datei sowohl deine wichtigen Regeln verwaessert als auch das Budget frisst, das das Modell braucht. Anthropics Empfehlung zielt darauf, jede Datei deutlich unter 200 Zeilen zu halten. Eine knappe Root-Datei mit 50 bis 100 Zeilen, der Claude tatsaechlich folgt, schlaegt eine mit 300 Zeilen, die es nur ueberfliegt.

Ist eine claude.md Datei dasselbe wie Claudes Gedaechtnis?

Nein. CLAUDE.md ist eine Datei, die du schreibst und pflegst und die Claude sagt, wie es in einem Projekt arbeiten soll. Sie ist prozedural und repo-bezogen. Claude Code hat separat ein Memory-Tool, das es selbst verwaltet, und die Consumer-Apps haben ihr eigenes chat-uebergreifendes Gedaechtnis. Deine persoenlichen Fakten, Entscheidungen und sich veraendernder Kontext sind wiederum eine andere Art von Wissen, und keins davon haelt sich selbst aktuell, wenn nicht etwas dafuer gebaut ist.

Funktioniert eine claude.md Datei mit anderen Tools als Claude Code?

Die CLAUDE.md Datei selbst ist eine Claude-Code-Konvention. Andere Tools lesen sie nicht. Das ist eine echte Einschraenkung, wenn du mehrere KI-Tools nutzt, weil der Kontext, den du in CLAUDE.md legst, in einem Tool gefangen ist. Fakten ueber dich und deine Arbeit sind nuetzlicher, wenn sie ueber jedes Tool reisen, weshalb eine ueber MCP gelieferte Memory-Schicht (mit der sich viele KI-Tools verbinden koennen) ein besserer Ort fuer das "Was" ist als eine tool-spezifische Datei.

---

Eine gute CLAUDE.md Datei ist es wert, knapp gehalten zu werden, weil sie das eine Stueck deines KI-Setups ist, das du voll steuerst, und jedes Projekt profitiert echt davon, eine zu haben. Aber dein Setup ist mehr als eine einzige Datei, und die Fakten, die den Output deiner KI spezifisch fuer dich machen, driften schneller, als du von Hand bearbeiten kannst. Locul ist ein zweites Gehirn, das sich aus dem baut, was du ohnehin produzierst, und sich auf deiner Maschine aktuell haelt, und diesen Kontext dann an Claude Code und deine anderen Tools liefert. Der Einstieg ist kostenlos mit 500 Memories und lokaler KI. So funktioniert es.