Ratgeber · 8. November 2026 · 12 Min. Lesezeit

CLAUDE.md erstellen: Was reingehört und was nicht

CLAUDE.md erstellen für Claude Code: wo die Datei liegt, was reingehört, was nicht, wie /init dir hilft und warum weniger als 200 Zeilen besser wirken.

Das Wichtigste in Kürze

  • Die CLAUDE.md ist eine normale Markdown-Datei, die Claude Code zu Beginn jeder Sitzung liest, quasi die Einarbeitung für deinen KI-Kollegen.
  • Es gibt sie auf mehreren Ebenen: global für dich (~/.claude/CLAUDE.md), pro Projekt (./CLAUDE.md) und lokal nur für dich im Projekt (./CLAUDE.local.md), und Claude liest sie alle zusammen.
  • /init erzeugt dir eine erste Fassung, die du danach kürzt, statt bei null anzufangen.
  • Rein gehören Befehle, Regeln und wiederholte Korrekturen, raus bleiben Architektur-Beschreibungen, die Claude selbst im Code liest; Ziel sind weniger als 200 Zeilen.
  • Regeln, die nie gebrochen werden dürfen, gehören in einen Hook, lange Abläufe in einen Skill und nicht in die CLAUDE.md.

Eine CLAUDE.md erstellst du am schnellsten, indem du in deinem Projektordner Claude Code startest und /init eingibst: Claude schaut sich dein Projekt an und legt dir eine erste Version an, die du danach von Hand kürzt und ergänzt. Rein gehört nur, was Claude nicht selbst aus dem Code ablesen kann, also deine Befehle zum Bauen und Testen, deine Regeln, deine Eigenheiten und die Fehler, die Claude sonst immer wieder macht. Raus bleibt alles, was Claude sowieso sieht, und die Datei sollte unter 200 Zeilen bleiben, weil sie in jeder Sitzung komplett mitgeladen wird. Hier zeige ich dir, wo die Datei liegt, wie ich sie aufbaue, was ich bewusst weglasse und was du machst, wenn Claude deine CLAUDE.md einfach ignoriert.

Was ist eine CLAUDE.md und wofür brauche ich sie?

Claude Code fängt jede Sitzung bei null an. Es weiß nicht, dass du in deinem Projekt immer mit npm run build prüfst, dass du nie direkt auf main committest oder dass deine Website auf Deutsch im Du-Ton geschrieben ist. Das musst du ihm entweder jedes Mal neu sagen, oder du schreibst es einmal in eine Datei, die Claude automatisch liest. Diese Datei ist die CLAUDE.md.

Laut der offiziellen Doku zum Gedächtnis von Claude Code wird die CLAUDE.md zu Beginn jeder Sitzung geladen und landet damit direkt im Kontext. Das heißt, alles, was drinsteht, liest Claude bei jeder einzelnen Aufgabe mit, egal ob du gerade einen Button verschiebst oder eine ganze Funktion baust.

Ich vergleiche das immer gern mit einem neuen Mitarbeiter: Du würdest ihm am ersten Tag auch nicht den kompletten Code vorlesen, sondern ihm sagen, wie man das Projekt startet, worauf er aufpassen muss und welche Fehler hier schon mal richtig wehgetan haben. Genau so eine kurze Einarbeitung ist eine gute CLAUDE.md. Falls Claude Code bei dir noch gar nicht läuft, fang mit meiner Anleitung an, wie du Claude Code installierst, und komm dann hierher zurück.

Wo lege ich die CLAUDE.md an: global, im Projekt oder lokal?

Es gibt nicht die eine CLAUDE.md, sondern mehrere Ebenen, und jede hat ihren eigenen Zweck. Die Memory-Doku nennt diese Orte:

EbeneOrtGilt für
Verwaltet (Firma)auf dem Mac unter /Library/Application Support/ClaudeCode/CLAUDE.mdalle Nutzer auf dem Rechner, wird von der IT gesetzt
Global (du)~/.claude/CLAUDE.mddich, in all deinen Projekten
Projekt (Team)./CLAUDE.md oder ./.claude/CLAUDE.mdalle, die am Projekt arbeiten, wird mit Git geteilt
Lokal (du im Projekt)./CLAUDE.local.mdnur dich in diesem Projekt, gehört in die .gitignore

Wichtig: Diese Dateien überschreiben sich nicht gegenseitig, sondern werden aneinandergehängt. Claude liest die Datei in deinem Arbeitsordner und zusätzlich jede CLAUDE.md in den Ordnern darüber. Liegt also eine CLAUDE.md in ~/code und eine in ~/code/mein-projekt, bekommt Claude beide. Dateien in Unterordnern lädt Claude dagegen erst, wenn es dort wirklich arbeitet.

Für dich heißt das ganz praktisch:

  • In die globale Datei kommt, was überall gilt, zum Beispiel deine Sprache, wie du angesprochen werden willst und deine allgemeinen Arbeitsregeln.
  • In die Projekt-Datei kommt alles, was das Projekt betrifft und was auch jeder andere im Team wissen muss.
  • In die lokale Datei kommt, was nur dich betrifft, zum Beispiel dein eigener Testserver oder deine persönlichen Vorlieben. Die Best Practices von Claude Code empfehlen genau das: persönliche Vorlieben in die CLAUDE.local.md.

Ich muss ehrlich sagen, dass ich am Anfang alles in eine einzige globale Datei gepackt habe, und die wurde dann schnell zu einem Monster, das in jedem Projekt Regeln mitgeschleppt hat, die dort gar nicht gepasst haben. Seit ich sauber trenne, arbeitet Claude in jedem Projekt deutlich ruhiger.

Wie erstelle ich meine erste CLAUDE.md mit /init?

Du musst nicht mit einer leeren Datei anfangen. Öffne dein Terminal im Projektordner, starte Claude Code und tipp:

claude
/init

Laut Doku erstellt /init eine erste CLAUDE.md für dein Projekt, und wenn schon eine existiert, schlägt es dir Verbesserungen vor, statt alles zu überschreiben. Claude schaut sich dafür deine Dateien an, also zum Beispiel deine package.json, deine Ordnerstruktur und deine Skripte, und schreibt daraus eine Zusammenfassung.

Jetzt kommt der Teil, den die meisten überspringen: Lies die Datei durch und streich. /init ist ein Startpunkt, kein fertiges Ergebnis. Oft steht danach viel drin, was Claude auch ohne die Datei herausfinden würde, zum Beispiel eine lange Beschreibung deiner Ordner. Das kostet nur Platz. Behalte die Befehle, korrigier, was nicht stimmt, und ergänz die Dinge, die Claude gar nicht wissen kann, weil sie nur in deinem Kopf sind.

Eine schlanke Projekt-CLAUDE.md sieht bei mir ungefähr so aus:

# Website Projekt

## Befehle
- Dev-Server: npm run dev (Port 4035)
- Vor jedem Commit: npx tsc --noEmit und npm run build, beide grün

## Regeln
- Nie direkt auf main committen, immer Branch und Pull Request
- Sichtbarer Text auf Deutsch im Du-Ton, Code-Kommentare auf Englisch
- Farben nur über die Tokens in app/globals.css, keine Hex-Werte in Seiten

## Nicht anfassen ohne Rückfrage
- package.json und package-lock.json
- .github/ (Deploy-Pipeline)

## Bekannte Stolperfallen
- Links zwischen Subdomains immer mit voller Adresse, sonst landen sie im falschen Pfad

Das sind keine 30 Zeilen, und trotzdem steckt darin alles, was Claude in diesem Projekt sonst falsch machen würde.

Was gehört in eine CLAUDE.md und was nicht?

Die wichtigste Regel steht in den Best Practices: Schreib nur das rein, was Claude nicht selbst aus dem Code herausfinden kann. Claude kann deinen Code lesen, deine Ordner durchsuchen und deine Konfiguration öffnen. Was es nicht kann, ist deine Gedanken lesen.

Das gehört rein:

  • Befehle, mit denen das Projekt gebaut, getestet und gestartet wird, vor allem wenn sie nicht offensichtlich sind.
  • Regeln für die Arbeit, zum Beispiel wie du committest, welche Branches es gibt und was vor einem Commit grün sein muss.
  • Stil und Sprache, also wie Texte klingen sollen, welche Wörter tabu sind und in welcher Sprache Code-Kommentare stehen.
  • Tabuzonen, also Dateien oder Bereiche, die Claude nicht ohne Rückfrage ändern soll.
  • Wiederholte Korrekturen. Die Memory-Doku sagt es ziemlich direkt: Wenn Claude denselben Fehler zweimal macht oder du dieselbe Korrektur immer wieder tippst, gehört sie in die CLAUDE.md.

Das bleibt draußen:

  • Architektur-Beschreibungen, die Claude selbst im Code lesen kann. Die Best Practices raten ausdrücklich davon ab, die Architektur nachzuerzählen, wenn Claude sie sich selbst anschauen kann.
  • Lange Schritt-für-Schritt-Abläufe, die du nur ab und zu brauchst. Die gehören in einen Skill, dazu gleich mehr.
  • Projektstand und Aufgabenlisten. Die veralten in ein paar Tagen, und dann arbeitet Claude auf einem alten Stand, ohne dass du es merkst.
  • Passwörter, API-Schlüssel und andere Geheimnisse. Die gehören in eine .env, nie in eine Datei, die mit Git geteilt wird.
  • Allgemeine Weisheiten wie „schreib sauberen Code“. Das macht Claude ohnehin, und jede solche Zeile kostet nur Aufmerksamkeit.

Der Test, den ich bei jeder Zeile mache: Würde Claude ohne diese Zeile etwas falsch machen? Wenn die Antwort nein ist, fliegt sie raus.

Wie lang darf eine CLAUDE.md sein und wie halte ich sie aktuell?

Die Memory-Doku nennt eine klare Zahl: unter 200 Zeilen pro Datei. Längere Dateien verbrauchen mehr Kontext und führen dazu, dass Claude sich schlechter an sie hält. Die Best Practices begründen das so, dass die Datei in jede Sitzung geladen wird und jede Zeile bei jeder Aufgabe Aufmerksamkeit kostet. Je mehr drinsteht, desto mehr geht die einzelne wichtige Regel unter.

Für längere Inhalte gibt es zwei Werkzeuge:

  • Imports mit @pfad. Du kannst in der CLAUDE.md auf eine andere Datei verweisen, zum Beispiel @docs/git-regeln.md. Der Pfad ist relativ zur Datei, in der der Import steht, und Imports können bis zu vier Ebenen tief verschachtelt sein. Aber Achtung: Laut Doku sparen Imports keinen Kontext, die importierte Datei wird trotzdem mitgeladen. Sie helfen dir nur beim Ordnen.
  • Regeln in .claude/rules/. Dort legst du Regeln ab, die nur für bestimmte Pfade gelten. Eine Regel für deine Tests muss dann nicht geladen sein, wenn Claude gerade an deinem CSS arbeitet.

Aktuell halten ist dann eigentlich einfach, wenn du dir zwei Gewohnheiten angewöhnst. Erstens: Jedes Mal, wenn du Claude zum zweiten Mal dasselbe korrigierst, schreibst du die Korrektur als eine Zeile in die Datei. Zweitens: Ab und zu liest du die ganze Datei durch und streichst, was nicht mehr stimmt. Eine veraltete Regel ist schlimmer als gar keine, weil Claude sich brav daran hält. In meinem Artikel über die häufigsten Claude Code Fehler siehst du, wie viel Zeit und Token ein überladenes oder veraltetes Setup kosten kann.

Warum ignoriert Claude Code meine CLAUDE.md und was hilft dann?

Die Frage kommt in der Community gefühlt jede Woche: „Ich hab es doch in die CLAUDE.md geschrieben, warum macht Claude es trotzdem?“ Die ehrliche Antwort ist, dass die CLAUDE.md eine Anweisung ist und kein Schloss. Claude liest sie und versucht sich daran zu halten, aber eine Garantie ist das nicht, vor allem wenn die Datei lang ist und die Regel irgendwo in Zeile 340 steht.

Was viele dann machen: Sie schreiben WICHTIG in Großbuchstaben davor. Die Best Practices sagen dazu ganz nüchtern, dass das selten hilft. Was hilft, ist das passende Werkzeug für die Art von Regel:

Art der RegelWo sie hingehörtWarum
Darf nie gebrochen werdenHook, Deny-Regel oder verwaltete Einstellungwird von Claude Code selbst durchgesetzt, nicht vom Modell
Langer Ablauf mit vielen SchrittenSkillwird nur geladen, wenn er gebraucht wird
Gilt nur für bestimmte Dateien.claude/rules/ mit Pfadangabebelastet nicht jede Sitzung
Kurze Regel für fast jede AufgabeCLAUDE.mdwird immer gelesen

Hooks sind dabei der stärkste Hebel. Ein Hook ist ein kleines Skript, das Claude Code selbst ausführt, zum Beispiel bevor eine Datei bearbeitet wird. Laut Hooks-Doku blockiert ein Hook die Aktion, wenn er mit dem Code 2 endet, und gibt den Grund über stderr zurück. Eine Regel wie „fass nie die Migrationen an“ wird so fest durchgesetzt, statt darauf zu hoffen, dass Claude sich erinnert.

Skills lösen das andere Problem, nämlich lange Abläufe. Laut Skills-Doku ist von einem Skill immer nur die Beschreibung im Kontext, der ganze Inhalt wird erst geladen, wenn der Skill gebraucht wird. Ein Ablauf mit zwanzig Schritten für dein Deployment kostet in der CLAUDE.md also bei jeder Aufgabe Platz, als Skill fast gar nichts. Welche Skills ich selbst täglich nutze, zeige ich dir in meinem Artikel über meine wichtigsten Claude Code Skills. Und wenn Claude für eine Aufgabe Zugriff auf ein anderes System braucht, zum Beispiel auf Notion oder einen Browser, dann ist das weder ein Fall für die CLAUDE.md noch für einen Skill, sondern für einen MCP Server.

Meine Faustregel: Die CLAUDE.md sagt Claude, wie ihr zusammenarbeitet. Ein Skill sagt Claude, wie eine bestimmte Aufgabe geht. Und ein Hook sorgt dafür, dass bestimmte Dinge einfach nicht passieren können.

Was ist der Unterschied zwischen CLAUDE.md, AGENTS.md und Auto Memory?

Neben der CLAUDE.md begegnen dir noch zwei Begriffe, die ähnlich klingen.

AGENTS.md ist ein offenes Format für Anleitungen an Coding-Agenten, beschrieben als README für Agenten, und wird laut der Seite in über 60.000 Open-Source-Projekten verwendet. Der Unterschied zur CLAUDE.md ist vor allem, dass AGENTS.md nicht nur für Claude gedacht ist, sondern auch für andere Agenten. Laut Memory-Doku kann Claude Code eine AGENTS.md lesen, wenn es keine CLAUDE.md gibt. Wenn du also neben Claude noch ein zweites Modell nutzt, wie ich es in meinem Artikel über Codex neben Claude Code beschreibe, lohnt es sich, die gemeinsamen Regeln an einer Stelle zu halten, statt zwei Dateien parallel zu pflegen, die irgendwann auseinanderlaufen.

Auto Memory ist das Gegenstück zur CLAUDE.md: Die CLAUDE.md schreibst du selbst, bei Auto Memory macht sich Claude Code selbst Notizen über das, was es in deinem Projekt gelernt hat. Das klingt praktisch, hat aber einen Haken, den ich selbst erlebt habe: Wenn zwei Orte Regeln enthalten, weißt du irgendwann nicht mehr, welcher gerade gilt. Ich halte es deshalb so, dass alles, was wirklich zählt, bewusst und von mir in der CLAUDE.md steht, weil ich die lesen, prüfen und mit Git zurückdrehen kann.

Häufige Fragen

Wie erstelle ich eine CLAUDE.md?

Am einfachsten mit dem Befehl /init in Claude Code, der dir eine erste Fassung für dein Projekt anlegt. Danach kürzt du die Datei von Hand und ergänzt die Regeln, die Claude nicht aus dem Code ablesen kann. Du kannst die Datei aber auch einfach selbst als CLAUDE.md im Projektordner anlegen.

Wo liegt die CLAUDE.md?

Die Projektdatei liegt im Hauptordner deines Projekts als CLAUDE.md oder unter .claude/CLAUDE.md. Deine globale Datei liegt unter ~/.claude/CLAUDE.md, und eine persönliche Datei nur für dich im Projekt heißt CLAUDE.local.md und gehört in die .gitignore.

Wie lang sollte eine CLAUDE.md sein?

Unter 200 Zeilen pro Datei, so steht es in der offiziellen Doku. Längere Dateien verbrauchen mehr Kontext, und Claude hält sich schlechter an die einzelnen Regeln, weil jede Zeile in jeder Sitzung mitgelesen wird.

Liest Claude Code mehrere CLAUDE.md-Dateien gleichzeitig?

Ja, die Dateien werden zusammengefügt und nicht überschrieben. Claude liest die Datei im Arbeitsordner und jede CLAUDE.md in den Ordnern darüber, Dateien in Unterordnern lädt es erst, wenn es dort arbeitet.

Warum hält sich Claude nicht an meine CLAUDE.md?

Meistens, weil die Datei zu lang ist und die Regel darin untergeht, oder weil die Regel eigentlich eine harte Grenze ist. Kürze die Datei auf das Wesentliche, und setz Regeln, die nie gebrochen werden dürfen, über einen Hook oder eine Deny-Regel durch statt mit „WICHTIG“ in Großbuchstaben.

Was ist der Unterschied zwischen CLAUDE.md und AGENTS.md?

Die CLAUDE.md ist für Claude Code gedacht, AGENTS.md ist ein offenes Format, das auch andere Coding-Agenten lesen. Claude Code kann eine AGENTS.md lesen, wenn keine CLAUDE.md da ist.

Kann ich andere Dateien in meine CLAUDE.md einbinden?

Ja, mit einem Import über @pfad, zum Beispiel @docs/regeln.md. Der Pfad ist relativ zur importierenden Datei, und Imports sparen keinen Kontext, weil die eingebundene Datei trotzdem geladen wird.

Fazit

Eine gute CLAUDE.md ist kurz, ehrlich und von dir gepflegt. Starte mit /init, streich alles, was Claude sowieso im Code sieht, und behalte die Befehle, Regeln und Stolperfallen, die nur du kennst. Trenn sauber zwischen global, Projekt und lokal, bleib unter 200 Zeilen, und schieb harte Regeln in Hooks und lange Abläufe in Skills. Mach dir heute einmal die Mühe, deine eigene CLAUDE.md Zeile für Zeile mit der Frage durchzugehen, ob Claude ohne diese Zeile etwas falsch machen würde, du wirst überrascht sein, wie viel rausfliegen kann. Und wenn du sehen willst, wie andere ihre CLAUDE.md, ihre Skills und ihre KI Agenten aufbauen, findest du im kostenlosen KI Agenten Club meine Skills, den Kurs Claude Grundlagen und Leute, die genau daran arbeiten und ihre Learnings teilen.

KI Agenten Club

Du willst nicht nur lesen, sondern bauen?

Im KI Agenten Club baust du mit Vishal KI-Agenten für dein Business. Kurse, fertige Skills und Leute, die dasselbe bauen.

Zum KI Agenten Club

Das könnte dich auch interessieren