CLAUDE.md

Was ist CLAUDE.md?

CLAUDE.md ist die Markdown-Instruktionsdatei, die Claude Code, Anthropics Coding-Agent, automatisch zu Beginn jeder Sitzung liest. Sie trägt dauerhaften Projektkontext: Build- und Testbefehle, Code-Konventionen, Architekturnotizen und Regeln, die der Agent befolgen muss, sodass dieselbe Anleitung für jede Aufgabe gilt, ohne in Prompts wiederholt zu werden.

Die wichtigsten Punkte

• Es ist stehender Speicher, automatisch geladen. Alles in CLAUDE.md formt jede Sitzung in diesem Projekt, was es zur einflussreichsten Datei in einem Claude-Code-Workflow macht.
• Es ist geschichtet. Claude Code merged Dateien von der Nutzerebene (~/.claude/CLAUDE.md), der Projektwurzel und Unterverzeichnissen, wobei spezifischere Dateien breitere ergänzen und verfeinern.
• Jede Zeile kostet Kontext. Die Datei wird jeder Sitzung vorangestellt, sodass sie mit Code und Konversation um das Context Window konkurriert, und aufgeblähte Dateien verschlechtern die Ergebnisse.
• Es ist das Gegenstück von Claude Code zur anbieterneutralen AGENTS.md-Konvention, und Teams, die mehrere Agenten nutzen, pflegen oft eine Datei und verweisen von der anderen darauf.
• Anweisungen funktionieren am besten als kurze, imperative, projektspezifische Regeln. Generischer Rat wie "schreibe sauberen Code" verschwendet Tokens; "führe make lint aus, bevor du eine Aufgabe abschließt" ändert Verhalten.

So funktioniert es

Wenn Claude Code in einem Verzeichnis startet, sammelt es CLAUDE.md-Dateien aus mehreren Orten: eine globale Datei im Home-Verzeichnis der Nutzenden für persönliche Präferenzen, die überall gelten, die Projektwurzel-Datei, die meist ins Git eingecheckt und vom Team geteilt wird, und optionale Dateien in Unterverzeichnissen, die Regeln für ihren Teil des Baums ergänzen. Der kombinierte Inhalt landet vor der ersten Nutzernachricht an oberster Stelle im Kontext des Agenten und fungiert als Projekt-Ebenen-Systemanleitung. Eine verwandte Konvention, CLAUDE.local.md oder eine nicht getrackte persönliche Datei, hält individuelle Overrides, die außerhalb der Versionskontrolle bleiben.

Teams lassen die Datei auf zwei Arten wachsen. Der bewusste Weg ist, sie wie ein Onboarding-Dokument für eine sehr wörtlich nehmende mitwirkende Person zu schreiben: exakte Befehle, Namenskonventionen, Verzeichnisgrenzen, Links zu tieferer Dokumentation. Der inkrementelle Weg ist, Korrekturen einzufangen, während sie passieren; Claude Code unterstützt, mitten in der Sitzung schnell eine Anweisung an den Speicher anzuhängen, sodass "wir nutzen hier pnpm, nicht npm" zur permanenten Regel wird, sobald es zum ersten Mal gesagt wird. Ausgereifte Setups nutzen auch Imports, bei denen CLAUDE.md auf andere Dateien verweist, um gemeinsame Standards einzubinden, ohne sie zu duplizieren. Was in diesen Dateien landet, ist ziemlich vorhersagbar: Eine empirische Studie von 2025 mit 253 CLAUDE.md-Dateien aus 242 Repositories fand, dass sie typischerweise flachen Hierarchien folgen, dominiert von operativen Befehlen, technischen Implementierungsnotizen und High-Level-Architektur [1].

Was die Datei mächtig macht, ist der kumulative Effekt. Eine einmal im Chat gemachte Korrektur hilft einmal. Dieselbe Korrektur in CLAUDE.md hilft jeder Sitzung, jeder Ingenieurin im Team, unbegrenzt. Deshalb reviewen erfahrene Teams die Datei in Pull Requests wie jedes andere Stück Infrastruktur, und deshalb behandeln Context-Engineering-Diskussionen sie als den ersten Hebel, den man zieht, bevor aufwendigere Maschinerie kommt. Reale Nutzung bestätigt das: Eine Studie mit 2.303 Agenten-Kontextdateien über 1.925 Repositories hinweg fand, dass sie sich wie Konfigurationscode entwickeln, durch häufige, kleine Ergänzungen [2].

Beispiel

Das Monorepo eines Startups hat eine Regel, die jeden neuen Ingenieur und jeden Agenten stolpern lässt: Das API-Paket generiert seinen TypeScript-Client, und das manuelle Bearbeiten des generierten Codes bricht still den nächsten Build. Nachdem der Agent genau das zweimal getan hat, fügt das Team eine Root-CLAUDE.md hinzu: nie packages/api-client/src/generated/ bearbeiten, nach Schema-Änderungen mit pnpm codegen regenerieren, pnpm turbo test --filter=...[HEAD] ausführen, bevor eine Aufgabe für abgeschlossen erklärt wird, und konventionelle Commit-Nachrichten verwenden. Sie fügen auch eine packages/infra/CLAUDE.md hinzu, die warnt, dass Terraform-Dateien von der CI angewendet werden und nie lokal angewendet werden dürfen. Agenten-Sitzungen hören von diesem Tag an auf, die zwei teuersten Fehler im Repo zu machen.

Häufige Missverständnisse

Der klassische Fehler ist, CLAUDE.md als Auffangbecken zu behandeln und sie zu Tausenden Wörtern Stilphilosophie, veralteter Befehle und eingefügter Dokumentation anschwellen zu lassen. Weil die Datei in jede Sitzung geladen wird, besteuert Aufblähung jede Aufgabe, und Modelle folgen langen Anweisungslisten weniger zuverlässig als kurzen. Die Disziplin, die funktioniert, ist dieselbe wie bei Code: minimal halten, aktuell halten, Regeln löschen, die ihre Tokens nicht mehr verdienen, und Referenzmaterial in verlinkte Dokumente verschieben, die der Agent bei Bedarf lesen kann. Es lohnt sich auch, ehrliche Erwartungen darüber zu haben, was die Datei leisten kann. Eine Ablationsstudie von 2026 mit 288 ausgewerteten Läufen über 17 reale Repository-Aufgaben fand, dass Kontextdateien wie CLAUDE.md weder bei Claude Code noch bei Codex die Korrektheit messbar verschoben [3]. Der Wert der Datei liegt darin, Konventionen, Befehle und Grenzen zu steuern, nicht darin, das Modell schwerere Probleme lösen zu lassen.

FAQ

Was unterscheidet CLAUDE.md von AGENTS.md? Umfang der Zielgruppe. AGENTS.md ist eine anbieterübergreifende Konvention, die von vielen Coding-Agenten gelesen wird; CLAUDE.md ist Claude Codes native Datei, mit zusätzlichem Verhalten wie hierarchischem Merging, Imports und In-Session-Speicher-Updates. Teams, die mehrere Agenten betreiben, pflegen typischerweise eine kanonische Instruktionsdatei und lassen die andere darauf verweisen.

Sollte CLAUDE.md in die Versionskontrolle eingecheckt werden? Die Datei auf Projektebene, ja. Sie kodiert Teamwissen und sollte sich durch Review entwickeln wie jede geteilte Konfiguration. Persönliche Präferenzen gehören in die Home-Verzeichnis-Datei oder eine lokale Variante, die ungetrackt bleibt.

Wie lang sollte eine CLAUDE.md sein? So kurz wie möglich, während sie die Befehle und Regeln abdeckt, die der Agent tatsächlich braucht. Viele effektive Dateien sind unter hundert Zeilen. Wenn Ihre sich wie Dokumentation statt wie Anweisungen liest, verschieben Sie die Dokumentation woandershin und verlinken Sie sie.

Quellen

1. arXiv. "On the Use of Agentic Coding Manifests: An Empirical Study of Claude Code, Analyse von 253 CLAUDE.md-Dateien aus 242 Repositories." https://arxiv.org/abs/2509.14744. Abgerufen im August 2026.
2. arXiv. "Agent READMEs: An Empirical Study of Context Files for Agentic Coding, Entwicklungsmuster über 2.303 Kontextdateien." https://arxiv.org/abs/2511.12884. Abgerufen im August 2026.
3. arXiv. "Do Context Files Help Coding Agents? A Two-Agent Ablation Study on Real Repositories, 288 ausgewertete Läufe über 17 Aufgaben." https://arxiv.org/abs/2607.27250. Abgerufen im August 2026.