CLAUDE.md ist eine Markdown-Datei, die Claude Code automatisch zu Beginn jeder Sitzung lädt; sie wird nicht als Konfiguration ausgeführt, sondern einfach als Text in den Prompt eingefügt.
Der Hauptfehler, den fast alle machen: Sie zerlegen die Datei in @imports und denken, das spart Kontext. Tatsächlich werden Imports vollständig und sofort geladen – Kontext wird nur durch path-scoped rules in .claude/rules/ wirklich gespart.
Größenrichtlinie: bis zu 200 Zeilen für ein Projekt CLAUDE.md, bis zu 30 Zeilen für ein persönliches ~/.claude/CLAUDE.md – Modelle behalten zuverlässig etwa 150-200 Anweisungen gleichzeitig im Kopf, und der System-Prompt von Claude Code selbst nimmt bereits etwa 50 davon ein.
CLAUDE.md, AGENTS.md und Cursor Rules sind nicht austauschbar: Claude Code liest nur CLAUDE.md, Cursor liest .cursor/rules/ und AGENTS.md, und AGENTS.md selbst steht als offener Standard derzeit in über 60.000 Repositories.
Der Artikel enthält ein funktionierendes Beispiel für CLAUDE.md für ein Spring Boot-Projekt, eine Analyse typischer Fehler und zwei dokumentierte Bugs, über die die meisten Anleitungen schweigen.
CLAUDE.md ist eine normale Markdown-Datei, die Claude Code automatisch zu Beginn jeder Sitzung lädt und dem Modell eine Art permanentes Gedächtnis für das Projekt gibt: Befehle, Architektur, Konventionen – alles, was das Modell nicht aus dem Code selbst ableiten kann (offizielle Dokumentation von Claude Code). Ich würde die Essenz der Datei so einfach wie möglich formulieren: CLAUDE.md macht Claude nicht intelligenter – es sorgt dafür, dass Claude aufhört zu vergessen.
Das ist keine Übertreibung. Ich persönlich hatte die Situation, dass ich eine Woche lang jede Sitzung dieselbe architektonische Bemerkung zum Projekt wiederholen musste – und sobald diese Zeile in CLAUDE.md verschoben wurde, hörte die Notwendigkeit der Wiederholung auf (eine ähnliche Erfahrung wird in der Analyse von maketocreate.com am Beispiel eines Laravel-Projekts mit dem Muster "Repository statt Eloquent in Controllern" beschrieben).
Unterschied zu README.md: README ist für Leute geschrieben, die ein Repository zum ersten Mal öffnen – es ist die Visitenkarte des Projekts. CLAUDE.md ist für ein Modell geschrieben, das bereits weiß, wie typischer Code aussieht, und nur das braucht, was Ihr spezifisches Projekt von Standardannahmen unterscheidet.
Unterschied zu AGENTS.md: AGENTS.md ist ein offener, instrumentenübergreifender Standard, der von Codex, Cursor, Copilot, Gemini CLI und anderen gelesen wird. Claude Code liest ihn nicht nativ – nur CLAUDE.md (TECHSY, im Live-Repository getestet). Mehr dazu im Vergleichsabschnitt unten.
Unterschied zu Cursor Rules: Cursor Rules ist ein Format, das spezifisch für Cursor ist (.cursor/rules/*.mdc), mit eigenem YAML-Frontmatter und Aktivierungsmodi. Dies ist ein paralleles, nicht mit CLAUDE.md kompatibles System: Wenn Sie CLAUDE.md in ein Cursor-Projekt legen, wird Cursor es einfach ignorieren.
Wie Claude CLAUDE.md verwendet
Claude Code sucht nach CLAUDE.md-Dateien in der Verzeichnishierarchie und lädt sie mit unterschiedlichem Verhalten je nach Ebene:
Global (~/.claude/CLAUDE.md) – persönliche Einstellungen, die in jedem Projekt auf Ihrem Computer gelten.
Projekt-Root (./CLAUDE.md) – die Hauptdatei, die in Git committet wird und für das gesamte Team gilt.
Verschachtelte CLAUDE.md in Unterverzeichnissen – werden nicht sofort geladen, sondern nur, wenn Claude tatsächlich auf Dateien im entsprechenden Unterverzeichnis zugreift. Dies ist ein beabsichtigtes Design: Ein Monorepo mit 50 Unterverzeichnissen wird nicht mit Anweisungen aufgebläht, die gerade nicht benötigt werden (Serenities AI).
Wenn Anweisungen von verschiedenen Ebenen kollidieren, gilt eine einfache Regel: Eine spezifischere Anweisung überschreibt eine allgemeinere. Wenn die Organisationsrichtlinie "4 Leerzeichen für Einrückungen" lautet und die projektbezogene CLAUDE.md "2 Leerzeichen" sagt – für dieses Projekt gewinnt die projektbezogene Anweisung (Serenities AI). Diese Regel sollten Sie im Hinterkopf behalten, wenn Sie entscheiden, auf welcher Ebene Sie etwas schreiben – etwas wirklich Gemeinsames für alle Ihre Projekte ist besser, sofort in die globale Datei zu legen, anstatt es in jedem Projekt zu duplizieren.
Wie Claude Code CLAUDE.md technisch lädt: Imports vs. Rules vs. Compaction
Dies ist der Abschnitt, für den ich diese ganze Artikel überhaupt geschrieben habe – denn fast alle Anleitungen, die ich vor dem Schreiben durchgesehen habe, geben den Rat "halte die Datei kurz", aber keine erklärt richtig, warum einige Techniken zur Kontextreduzierung funktionieren und andere nur so aussehen, als ob sie funktionieren.
@imports werden sofort geladen. Wenn Sie eine 500-zeilige CLAUDE.md in fünf Imports von je 100 Zeilen aufteilen, erhalten Sie eine leichter zu wartende Dateisammlung – aber der Kontext, der tatsächlich in das Modell geladen wird, bleibt derselbe 500-zeilige Umfang. Der Import wird beim Start der Sitzung vollständig entfaltet, als ob Sie den Inhalt der Datei direkt eingefügt hätten (Claude Certification Guide). Das ist die Falle, in die ich selbst fast getappt wäre: Es schien logisch, dass die Aufteilung in Dateien die Last reduziert, aber tatsächlich reduziert sie nur das Chaos in Ihrem Editor.
`.claude/rules/*.md` mit `paths:` frontmatter werden bei Bedarf geladen. Im Gegensatz zu Imports werden Regeldateien in .claude/rules/ nur dann geladen, wenn Claude tatsächlich mit einer Datei arbeitet, die dem angegebenen Glob-Muster entspricht. Dies ist der einzige Mechanismus in diesem System, der den Kontext wirklich, und nicht nur scheinbar, reduziert (offizielle Dokumentation). Wenn Ihr Ziel ist, den Kontextumfang zu reduzieren, und nicht nur Ordnung in den Dateien zu schaffen, benötigen Sie genau diese Regeln, nicht Imports.
Sitzungskomprimierung. Die Stamm-CLAUDE.md übersteht /compact – nach der Komprimierung des Gesprächsverlaufs liest Claude sie erneut von der Festplatte und injiziert sie erneut in die Sitzung. Verschachtelte CLAUDE.md und Pfad-bezogene Regeln werden jedoch nach der Komprimierung nicht automatisch wiederhergestellt – sie werden erst wieder geladen, wenn Claude das nächste Mal auf das entsprechende Unterverzeichnis oder die Datei zugreift (offizielle Dokumentation).
Integrierter Trimming. Seit Claude Code v2.1.206 gibt es den Befehl /doctor, der Ihre committete CLAUDE.md selbst analysiert und Vorschläge zur Entfernung macht: Alles, was das Modell direkt aus dem Code ableiten kann (Ordnerstruktur, Abhängigkeitsliste, Architekturübersicht) – zum Löschen; Stolpersteine, Begründungen für Entscheidungen und nicht standardmäßige Konventionen, die der Code allein nicht zeigt – zum Behalten (offizielle Dokumentation). Ich halte dieses Kriterium – "kann das aus dem Code abgeleitet werden?" – für den besten Praxistest für jede Zeile in Ihrer Datei, und ich werde darauf im Abschnitt Best Practices weiter unten zurückkommen.
Was muss unbedingt in CLAUDE.md enthalten sein?
Ich nähere mich dieser Liste nicht als willkürliche Sammlung von Kategorien, sondern durch ein Kriterium, das ich bereits oben erwähnt habe: Hier kommt nur das hinein, was das Modell nicht zuverlässig selbst aus dem Code ableiten kann. Wenn die Architektur zu 90 % durch einfaches Öffnen von drei Dateien verstanden werden kann – ist es nicht wert, sie zu beschreiben. Aber es gibt Kategorien, in denen das Modell ohne explizite Anweisung fast immer falsch rät oder Schritte zur Klärung aufwendet – und genau diese machen diese Liste aus meiner praktischen Erfahrung aus.
Technologie-Stack – Sprache, Framework, Versionen, die nicht immer eindeutig aus package.json oder pom.xml ersichtlich sind. Dies gilt insbesondere für Übergangsperioden: Wenn ein Projekt teilweise auf Java 17 und teilweise bereits auf 21 läuft oder Spring Boot 3.x mit einzelnen Modulen auf einer älteren Version verwendet – das Modell wird dies nicht erraten, und die fälschlicherweise angewendete API einer neueren Version führt zu einem Kompilierungsfehler, der manuell behoben werden muss.
Architektur – wie die Schichten der Anwendung organisiert sind, wohin neuer Code fließen soll. Ohne diesen Punkt habe ich regelmäßig gesehen, wie das Modell Geschäftslogik direkt in den Controller legt, weil dies der einfachste funktionierende Weg ist – technisch funktioniert der Code, aber er bricht die im Projekt akzeptierte Schichtstruktur.
Namenskonventionen – Konventionen, die von den Standardwerten für die Sprache oder das Framework abweichen. Das Modell folgt standardmäßig den allgemein akzeptierten Standards von Java oder Spring; wenn Ihr Team eigene Abweichungen hat (z. B. das Suffix Dto statt Request/Response), muss dies direkt gesagt werden – es wird diese Vereinbarung nicht selbst erraten.
Build-Befehle – die tatsächlichen Befehle Ihres Projekts (make build, ./gradlew build), nicht allgemeine Annahmen. Ohne dies schlägt das Modell oft einen generischen Befehl wie mvn install vor, auch wenn Ihr Projekt längst auf Gradle umgestellt hat – und Sie verlieren Zeit mit einer banalen Korrektur.
Tests – welches Framework, wie auszuführen, ob Tests vor oder nach der Funktion geschrieben werden müssen. Dies ist der Punkt, der am stärksten beeinflusst, ob das Modell seine Arbeit selbst überprüft, bevor es "fertig" sagt, oder ob es einfach Code auf Vertrauensbasis abliefert.
Beschränkungen – Verzeichnisse oder Dateien, die Claude ohne ausdrückliche Erlaubnis nicht berühren darf. Ich würde dies als einzigen Punkt aus der Liste hervorheben, der nicht auf die Codequalität, sondern auf die Sicherheit abzielt: Ohne ein ausdrückliches Verbot kann das Modell eine Migrationsdatei ändern, die bereits in der Produktion angewendet wurde, nur weil dies technisch die "einfachste" Lösung für das Problem ist.
Definition of Done – wann eine Aufgabe als abgeschlossen gilt: Tests bestanden, Linter sauber, Dokumentation aktualisiert. Ohne diesen Punkt wird die Grenze zwischen "Code geschrieben" und "Aufgabe erledigt" verschwommen, und genau hier entstehen am häufigsten Erwartungsbrüche zwischen dem, was das Modell geliefert hat, und dem, was tatsächlich abgeliefert werden musste.
Was sollte niemals in CLAUDE.md geschrieben werden?
Dies ist meiner Meinung nach der wichtigste Abschnitt des gesamten Artikels – und genau der, bei dem die meisten Konkurrenten sich auf allgemeine Worte beschränken. Ich werde bewusst nicht nur erklären, "was nicht geschrieben werden sollte", sondern was konkret kaputt geht, wenn Sie es doch schreiben – denn "unnötig" klingt wie eine Geschmacksberatung, aber tatsächlich steckt hinter jedem Punkt ein konkreter Schadensmechanismus.
Riesige Codeblöcke. CLAUDE.md ist kein Ort für Implementierungsbeispiele; verweisen Sie auf eine bestimmte Datei, anstatt den Inhalt einzufügen. Das Problem ist nicht nur der Umfang: Eingefügter Code veraltet schneller als eine Textbeschreibung. Eine Beschreibung der Architektur "der Dienst greift nicht direkt auf das Repository eines anderen Moduls zu" bleibt auch nach einem Jahr gültig. Ein eingefügtes Codebeispiel, das längst refaktorisiert wurde, wird das Modell aktiv in die Irre führen – es wird sich am Beispiel orientieren und nicht daran, wie der Code heute tatsächlich aussieht.
API-Dokumentation. Sie ändert sich häufiger als CLAUDE.md und veraltet schnell; ein Link zur tatsächlichen Dokumentation lebt länger als eine Kopie. Hier ist das Problem schlimmer als nur "veraltet" – eine veraltete Kopie der API-Dokumentation in CLAUDE.md ist aktiv schädlich, da das Modell ihr genauso vertraut wie dem Rest der Datei. Es wird mit Sicherheit einen Endpunkt vorschlagen, der nicht mehr existiert, oder ein Feld, das vor zwei Sprints umbenannt wurde, und Sie erhalten keinen Kompilierungsfehler, sondern einen stillen logischen Fehler, der bei der Überprüfung leicht übersehen wird.
README. Das Duplizieren von README in CLAUDE.md bedeutet doppelte Wartung desselben Inhalts – früher oder später werden sie auseinanderlaufen. Ich habe aus eigener Erfahrung gesehen, wie ein Team README bei jedem Release aktualisiert, weil neue Entwickler darauf schauen, aber die Kopie in CLAUDE.md vergessen – einfach weil es eine Datei ist, die seltener mit den Augen geöffnet, aber öfter vom Modell gelesen wird.
Changelog. Die Änderungsverlauf beeinflusst nicht, wie heute neuer Code geschrieben wird – es ist Ballast, der jede Sitzung Kontext frisst. Hier ist das Argument rein ökonomisch: Jede Zeile darüber, was im Februar passiert ist, konkurriert um die Aufmerksamkeit des Modells mit einer Zeile darüber, wie jetzt Code geschrieben wird – und das Modell kann nicht automatisch "das ist Geschichte" gegen "das ist eine aktuelle Regel" abwägen, es liest einfach die gesamte Datei als gleichwertigen Kontext.
Einmalige Anweisungen. "Aktualisiere heute die Abhängigkeit X" – das ist eine Aufgabe für den Chat, nicht für eine Datei, die ständig geladen wird. Wenn diese Anweisung nach der Ausführung nicht entfernt wird, wird sie weiterhin in jeder folgenden Sitzung geladen und kann das Modell sogar verwirren, wenn die Aufgabe längst erledigt ist und die Datei immer noch "aktualisiere X" sagt – das Modell wird versuchen, dies erneut zu tun, oder einen Schritt aufwenden, um zu klären, ob dies bereits geschehen ist.
Offensichtliche Dinge. "Schreibe sauberen Code", "füge Kommentare hinzu, wo nötig" – geben dem Modell nichts, was es nicht sowieso standardmäßig tut, und nehmen einfach Zeilen aus dem Limit von 150-200 Anweisungen ein, über das ich oben geschrieben habe. Dies ist die teuerste Art von Ballast von allen aufgeführten: Sie ist nicht nur nutzlos, sondern verdrängt Platz, den eine Zeile mit echtem Effekt einnehmen könnte – zum Beispiel dieselbe Namenskonvention für DTOs, die das Modell wirklich nicht selbst erraten konnte.
Optimale Struktur von CLAUDE.md
Basierend auf dem, was ich in funktionierenden Produktionsdateien und Community-Empfehlungen gesehen habe, sieht die optimale Struktur wie folgt aus:
Projektübersicht
Architektur
Codierkonventionen
Verzeichnisstruktur
Befehle
Testen
Sicherheit
Definition of Done
Agentenverhalten
Nützliche Referenzen
Die Reihenfolge ist hier nicht zufällig: Zuerst – der Kontext, in dem das Modell verstehen muss, um was für ein Projekt es sich überhaupt handelt (Übersicht, Architektur), dann – die Regeln, nach denen Code geschrieben werden soll (Konventionen, Struktur), dann – wie die eigene Arbeit überprüft werden soll (Befehle, Testen, Sicherheit, DoD), und schließlich – Verhaltensanweisungen und Links zu zusätzlichen Materialien.
Best Practices für das Schreiben von CLAUDE.md
Halten Sie die Datei kurz – konkret. Richtlinie: bis zu 200 Zeilen für ein Projekt CLAUDE.md, bis zu 30 Zeilen für ein persönliches ~/.claude/CLAUDE.md. Dies ist keine willkürliche Zahl – Frontier-Modelle folgen zuverlässig etwa 150-200 Anweisungen gleichzeitig, und der System-Prompt von Claude Code selbst nimmt bereits etwa 50 davon ein (HumanLayer, über maketocreate.com). Das heißt, jede zusätzliche Zeile in Ihrer Datei ist ein echter Wettbewerb um die Aufmerksamkeit des Modells mit anderen Anweisungen, kein kostenloser Bonus.
Verwenden Sie absolute Regeln. "Versuche, benannte Exporte zu verwenden" ist schlechter als "Verwende benannte Exporte, keine Standardexporte" – das Modell folgt einer klaren, eindeutigen Anweisung besser als einem weichen Wunsch.
Vermeiden Sie Widersprüche – und verstehen Sie, wie das System Konflikte löst, falls sie auftreten. Ich habe dies bereits oben geschrieben, aber ich wiederhole es hier bewusst: Eine spezifischere Anweisung überschreibt eine allgemeinere. Dieses Wissen bedeutet, dass Sie bewusst eine Ausnahme auf einer niedrigeren Ebene platzieren können (z. B. in der CLAUDE.md eines bestimmten Unterverzeichnisses), anstatt zu versuchen, eine einzige riesige, widerspruchsfreie Regel für das gesamte Projekt aufrechtzuerhalten.
Trennen Sie allgemeine und lokale Anweisungen. Allgemeine persönliche Präferenzen (bevorzugtes Diff-Format, Zeitzone) – in die globale Datei. Teamkonventionen – in die projektbezogene, unter Git.
Aktualisieren Sie die Datei regelmäßig. Eine CLAUDE.md, die drei Monate lang auf einem sich aktiv entwickelnden Projekt nicht bearbeitet wurde, ist fast garantiert eine Datei mit veralteten Befehlen.
Speichern Sie nicht den Projektverlauf. "Früher haben wir Redux verwendet, jetzt sind wir zu Zustand gewechselt" – interessant für einen Menschen, nutzlos für ein Modell, das nur den aktuellen Zustand benötigt.
Verweisen Sie auf Dokumentation statt zu kopieren. Eine Zeile mit einem Link lebt länger als ein kopierter Absatz, den niemand manuell synchronisieren wird.
Fügen Sie tatsächliche Projektbefehle hinzu. Nicht "teste ausführen", sondern buchstäblich ./gradlew test oder npm run test:unit – das Modell muss nicht raten.
Der Haupttest für jede Zeile: Kann das aus dem Code abgeleitet werden? Wenn ja – ist es ein Kandidat zum Löschen. Genau diese Logik verwendet der integrierte /doctor, und ich empfehle, sie bewusst anzuwenden, noch bevor das Schreiben zu einer 300-zeiligen Datei wird, die nachträglich gekürzt werden muss.
Beispiel für ein gutes CLAUDE.md
# Projektübersicht
Backend-API für ein Raumbuchungssystem. Spring Boot 3.5, Java 21, PostgreSQL.
# Architektur
Schichtenarchitektur: Controller → Service → Repository.
DTOs für Ein- und Ausgabedaten, Entities verlassen die Service-Schicht nicht.
Geschäftslogik nur im Service, Controller sind schlank.
# Coding Conventions
- Benannte Parameter in Konstruktoren über Lombok @RequiredArgsConstructor
- Exceptions – benutzerdefinierte unchecked, erben von ApiException
- DTOs über Record, nicht Class
- Daten – nur java.time, niemals java.util.Date
# Verzeichnisstruktur
src/main/java/com/company/booking/
controller/ — REST-Controller, nur Delegation an Service
service/ — Geschäftslogik
repository/ — Spring Data JPA
dto/ — Record-Klassen für API
entity/ — JPA Entities
config/ — Spring-Konfiguration
# Befehle
Build: ./gradlew build
Tests ausführen: ./gradlew test
Integrationstests ausführen: ./gradlew integrationTest (benötigt Docker für Testcontainers)
Lokal ausführen: ./gradlew bootRun --args='--spring.profiles.active=local'
# Tests
JUnit 5 + Mockito für Unit-Tests, Testcontainers + PostgreSQL für Integrationstests.
Jede neue Service-Methode mit Geschäftslogik – mindestens ein Unit-Test.
Mocken Sie nicht, was über Testcontainers getestet werden kann.
# Sicherheit
Passwörter, Token, persönliche Kundendaten niemals protokollieren.
Alle Endpunkte unter /admin/** – nur Rolle ADMIN, Prüfung auf @PreAuthorize-Ebene.
# Definition of Done
- Tests bestanden (./gradlew test)
- Keine neuen Warnungen von Checkstyle
- DTOs mit Javadoc dokumentiert, falls öffentliche API
# Agentenverhalten
Vor großen Refactorings – zuerst ein Plan, keine Dateibearbeitung.
Löschen Sie keine bestehenden Tests ohne ausdrückliche Erlaubnis, auch wenn sie "überflüssig erscheinen".
# Nützliche Referenzen
Architekturentscheidungen: docs/adr/
Beschreibung des Domänenmodells: docs/domain-model.md
Beachten Sie: Hier gibt es keine echten Code-Schnipsel, keine Kopie von README, kein Changelog. Jeder Abschnitt gibt dem Modell etwas, das es aus dem Code nicht zuverlässig ableiten könnte – deshalb funktioniert die Datei.
Beispiel für ein schlechtes CLAUDE.md
# Über das Projekt
Dies ist unser großartiges Projekt, mit dessen Entwicklung wir 2023 begonnen haben.
Zuerst haben wir Spring Boot 2 verwendet, dann sind wir auf 3 umgestiegen.
Im Februar 2025 haben wir das Zahlungsmodul neu geschrieben (siehe PR #482).
Im April haben wir Kafka hinzugefügt und im Juni wieder entfernt, weil es nicht funktionierte.
# Code-Stil
Schreiben Sie sauberen, lesbaren Code. Halten Sie sich an Best Practices.
Kommentare sollten aussagekräftig sein.
# Beispiel für einen Controller
```java
@RestController
@RequestMapping("/api/v1/bookings")
public class BookingController {
// ... 150 Zeilen Controller-Implementierung ...
}
```
# API-Dokumentation
GET /api/v1/bookings — gibt eine Liste von Buchungen zurück
Parameter: page, size, sort
Antwort: { "content": [...], "totalElements": 42, ... }
[... weitere 40 Endpunkte mit vollständiger Felddefinition ...]
# Changelog
- v1.2.0: Filterung nach Datum hinzugefügt
- v1.1.0: Bug mit Zeitzonen behoben
- v1.0.0: Erster Release
Dies ist fast eine lehrbuchmäßige Sammlung von Anti-Mustern: Projektgeschichte statt aktuellem Zustand, offensichtliche Ratschläge wie "schreiben Sie sauberen Code", eingefügter Implementierungscode statt Verweis auf eine Datei, vollständige Kopie der API-Dokumentation, die garantiert im ersten Sprint vom tatsächlichen Code abweicht, und ein Changelog, das keine Entscheidung über neuen Code beeinflusst. Eine Datei dieser Größe und dieses Inhalts würde den Kontext jede Sitzung verbrauchen und dem Modell nur minimale nützliche Signale liefern.
CLAUDE.md für Spring Boot
Für Java/Spring-Projekte würde ich den spezifischen Stack des Ökosystems in einem separaten Block hervorheben:
Maven oder Gradle – und spezifische Befehle zum Erstellen/Testen Ihrer Variante, nicht beide "für den Fall der Fälle".
Spring Boot-Version und die wichtigsten tatsächlich verwendeten Starter (web, data-jpa, security, actuator).
Spring AI, wenn das Projekt damit arbeitet – es ist erwähnenswert, welcher Provider (Ollama, OpenAI, Anthropic) im Dev-Profil standardmäßig verwendet wird.
Docker – Befehle zum lokalen Starten der Infrastruktur (docker-compose up -d), nicht nur die Erwähnung, dass Docker verwendet wird.
PostgreSQL – Version, ob Postgres-spezifische Typen (jsonb, arrays) verwendet werden, die in anderen DBMS möglicherweise keine direkte Entsprechung haben.
Flyway – Regel für die Nummerierung von Migrationen, ob eine bereits angewendete Migration bearbeitet werden kann (fast immer – nein).
Testcontainers – welche Container genau für Integrationstests verwendet werden, damit Claude nicht vorschlägt, etwas zu mocken, das bereits über eine echte Datenbank getestet wird.
CLAUDE.md für Monorepos
Für ein Monorepo mit mehreren Paketen in einem einzigen Repository ("root", "frontend/", "backend/", "shared/") funktioniert genau der Mechanismus verschachtelter CLAUDE.mds, der im Abschnitt über technisches Laden beschrieben ist: Die Root-Datei enthält das für das gesamte Repository Gemeinsame (allgemeine Konventionen, CI-Befehle), und jedes Unterverzeichnis enthält sein eigenes CLAUDE.md mit dem, was spezifisch dafür ist.
Praktischer Tipp: Duplizieren Sie in Unterverzeichnissen nicht, was bereits in der Root-Datei vorhanden ist – eine verschachtelte CLAUDE.md ergänzt die Root-Datei, ersetzt sie aber nicht vollständig. Und denken Sie an die Prioritätsregel: Wenn die Root-Datei etwas anderes sagt als frontend/CLAUDE.md, aber spezifisch für Frontend-Code, gewinnt die spezifischere Anweisung für die Arbeit innerhalb von frontend/.
CLAUDE.md für Microservices
Hier ist die Aufgabe prinzipiell anders als bei einem Monorepo. Bei einem Monorepo lautet die Frage: "Wo speichert man verschachtelte Dateien innerhalb eines einzigen Repositorys?". In einer Microservice-Architektur lebt jeder Service in seinem eigenen Repository mit seinem eigenen CLAUDE.md – und die eigentliche Frage ist nicht die Verschachtelung, sondern die Synchronisierung gemeinsamer Konventionen zwischen Repositorys, die physisch nicht durch einen einzigen Verzeichnisbaum verbunden sind.
Zwei praktische Ansätze, die ich gesehen habe: Erstens – gemeinsame Konventionen (Commit-Stil, Logging-Ansatz, gemeinsame Sicherheitsregeln) in einem separaten internen Repository aufbewahren und sie über @import in jedem Service einbinden (denken Sie daran – der Import wird vollständig entfaltet, halten Sie diese gemeinsame Datei kompakt). Zweitens – akzeptieren, dass eine geringe Duplizierung einiger Schlüsselzeilen in jedem Service-CLAUDE.md billiger ist als die Infrastruktur für die Synchronisierung, insbesondere wenn es nicht viele Dienste gibt und sie nicht jede Woche geändert werden.
CLAUDE.md vs AGENTS.md
Parameter
CLAUDE.md
AGENTS.md
Wer liest
Nur Claude Code
Codex, Cursor, Copilot, Gemini CLI, Windsurf und andere
Wer verwaltet den Standard
Anthropic
Agentic AI Foundation (Linux Foundation)
Speichermodell
Mehrstufig: global / Projekt / verschachtelt + Regeln mit Pfad-Scoping
Einfacher: Datei im Stammverzeichnis, Überschreibung nach Verzeichnistiefe
Verbreitung
Spezifisch für Claude Code
Über 60.000 öffentliche Repositories Mitte 2026
Der wichtigste Fakt, der am häufigsten verwechselt wird: Claude Code liest AGENTS.md nicht nativ, und andere Tools (Cursor, Copilot, Gemini CLI) lesen CLAUDE.md nicht – dies wurde durch einen direkten Test an einem Live-Repository bestätigt: Legen Sie CLAUDE.md in ein Cursor-Projekt, und Cursor ignoriert es einfach (TECHSY). Wenn Ihr Team mehr als ein KI-Tool verwendet, ist der praktischste Ansatz, AGENTS.md als Basisdatei für alle Tools zu verwenden und CLAUDE.md separat für das zu halten, was spezifisch für Claude Code ist (verschachtelte Struktur, pfadbezogene Regeln).
CLAUDE.md vs Cursor Rules
Parameter
CLAUDE.md
Cursor Rules
Format
Eine oder mehrere .md-Dateien
.mdc-Dateien in .cursor/rules/ mit YAML-Frontmatter
Aktivierungsmodi
Immer beim Betreten des Geltungsbereichs (global/Projekt/verschachtelt)
Vier Modi: Immer anwenden, Intelligent anwenden, Auf bestimmte Dateien anwenden und Legacy .cursorrules
Pfad-Scoping
Über separate .claude/rules/ mit paths: Frontmatter
In das Format selbst integriert über das Feld globs
Priorität bei Konflikten
Nach Verzeichnistiefe (spezifischer überschreibt allgemeineres)
Team → Projekt → Benutzer, frühere Quelle gewinnt
Objektiv betrachtet ist das Aktivierungssystem von Regeln in Cursor "out of the box" strukturierter – vier explizite Modi gegenüber dem einfacheren Modell von Claude Code. Die tiefere Hierarchie von Claude Code (global/Projekt/verschachtelt + Regeln) bietet jedoch mehr Flexibilität für große Monorepos. Wenn Ihr Team ausschließlich in Cursor arbeitet, würde ich nicht versuchen, das Claude Code-System künstlich nachzubilden – nutzen Sie einfach die nativen Funktionen der .mdc-Dateien.
CLAUDE.md vs Codex Instructions
Hier sollte die Ungenauigkeit im Namen des Vergleichs sofort behoben werden: OpenAI Codex hat kein separates eigenes Format "Codex Instructions" – der Codex CLI liest denselben offenen AGENTS.md, den auch andere Tools verwenden (The Prompt Shelf). Das bedeutet, der Vergleich "CLAUDE.md vs Codex" ist in der Praxis derselbe Fall wie "CLAUDE.md vs AGENTS.md" oben, mit einem Unterschied: Der Codex CLI hat einen praktischen Diagnosebefehl --print-instructions, der anzeigt, welcher zusammengeführte AGENTS.md-Inhalt tatsächlich in die aktuelle Sitzung geladen wurde – nützlich, wenn Sie vermuten, dass eine Datei abgeschnitten oder übersprungen wird.
Praktische Schlussfolgerung: Wenn Ihr Team sowohl Claude Code als auch Codex verwendet, bereiten Sie sich darauf vor, zwei Dateien zu pflegen – CLAUDE.md für das eine Tool, AGENTS.md für das andere – und bringen Sie wirklich gemeinsame Dinge in ein Format, das in beide importiert oder kopiert werden kann, ohne Abweichungen.
Typische Entwicklerfehler
Die meisten Punkte in diesem Abschnitt sind nicht nur "schlechte Praxis", sondern eine konkrete Ursache-Wirkungs-Kette, die ich entweder in eigenen Projekten oder in Beschreibungen der Community beobachtet habe. Ich beschreibe jeden einzelnen so, dass nicht nur "was falsch ist", sondern auch, was genau dies weiter verursacht.
Datei mit 1000 Zeilen. Ein klassischer Fehler – der Versuch, ein Projekt erschöpfend zu beschreiben, anstatt dem Modell nur das zu geben, was es nicht selbst ableiten kann. Die Folge ist direkt und ich habe den Mechanismus bereits oben erklärt: Das Modell behält etwa 150-200 Anweisungen gleichzeitig zuverlässig im Gedächtnis, und der System-Prompt von Claude Code beansprucht bereits etwa 50 davon. Eine Datei mit 1000 Zeilen ist kein "mehr Kontext über das Projekt", sondern ein überfülltes Aufmerksamkeitsbudget, bei dem die wichtige Regel der "Definition of Done" inmitten von hundert offensichtlichen Aussagen verloren geht, und das Modell beginnt tatsächlich, einen Teil der Anweisungen zu ignorieren, nicht aus böser Absicht, sondern weil es sie physisch nicht alle mit gleichem Gewicht aufrechterhalten kann.
Widersprüchliche Anweisungen. Tritt besonders häufig zwischen globalen und projektbezogenen Dateien auf, wenn persönliche Gewohnheiten mit Teamkonventionen kollidieren. Die Folge ist hier nicht abstrakt "das Modell ist verwirrt" – da die Regel der Spezifität gilt (Projekt überschreibt Global), wird das Modell tatsächlich immer die projektbezogene Regel ausführen, und Ihre persönliche Gewohnheit aus der globalen Datei wird jedes Mal stillschweigend ignoriert. Wenn Sie diese Regel nicht kennen, sieht es so aus, als würde Claude Ihre Einstellungen "vergessen" – tatsächlich wendet es den Prioritätsrang korrekt an, nur dass Sie nicht realisiert haben, dass die globale Zeile in diesem Projekt nie eine Chance hatte, zu wirken.
Veraltete Befehle. Eine Datei, die nach dem Wechsel von npm zu pnpm oder der Änderung der CI-Pipeline niemand mehr aktualisiert hat. Die Folge ist konkret: Das Modell führt genau den Befehl aus, der in der Datei steht, erhält eine Fehlermeldung "command not found" oder einen Lockfile-Konflikt und verbringt einen Schritt damit, selbst herauszufinden, was schiefgelaufen ist, anstatt sofort den richtigen Befehl auszuführen. Dies ist eine Kleinigkeit, die unbemerkt Zeit bei jeder Sitzung frisst, bis jemand eine Zeile aktualisiert.
Fehlende Architektur. Ein Modell ohne Beschreibung der Anwendungsschichten neigt dazu, neue Dateien nicht dort zu erstellen, wo es im Projekt üblich ist. Der Grund ist einfach: Ohne eine explizite Regel orientiert sich das Modell am einfachsten funktionierenden Weg für die jeweilige Aufgabe und nicht an der architektonischen Vereinbarung des Teams – technisch funktioniert der Code, auch wenn die Geschäftslogik direkt im Controller statt in der Service-Schicht landet, und Sie erhalten technisch korrekten, aber architektonisch falschen Code, der bei der Überprüfung verschoben werden muss.
Vermischung von Dokumentation und Anweisungen. Wenn CLAUDE.md versucht, gleichzeitig ein README, ein API-Verzeichnis und eine Anweisungsdatei zu sein, erfüllt es alle drei Rollen schlecht. Der Grund ist derselbe, den ich bereits im Abschnitt "Was man niemals schreiben sollte" erklärt habe: Dokumentation und Verzeichnisse ändern sich mit einer anderen Häufigkeit als Anweisungen für das Modell, und früher oder später weichen sie von der Realität ab – nur dass hier die Folge breiter ist, da die Datei sofort für drei verschiedene Zielgruppen (neue Entwickler, API-Suchende und das Modell selbst) den Fokus verliert und keine davon vollständig zufriedenstellt.
Dokumentierter Bug: User-Level-Regeln mit paths: Frontmatter in ~/.claude/rules/ werden Anfang 2026 nicht geladen, selbst wenn die Datei dem Muster entspricht – dies ist ein bestätigter Bug (GitHub Issue #21858). Praktische Folge: Wenn Sie eine persönliche, pfadbezogene Regel auf Ihrer Profil-Ebene geschrieben haben und diese leise nicht funktioniert, sieht es genau wie ein Fehler in Ihrem Glob-Muster aus – und Sie können stundenlang nach einem Fehler suchen, wo tatsächlich ein Bug im Werkzeug selbst liegt. Ein Workaround ist, pfadbezogene Regeln auf Projektebene statt auf persönlicher Profil-Ebene zu verschieben.
Überschriften aus importierten Dateien werden nicht automatisch heruntergestuft. Wenn die Hauptdatei \# Code conventions enthält und die importierte Datei mit einer eigenen \# Heading beginnt, ist das Ergebnis keine Unterüberschrift, sondern ein Geschwister auf derselben Ebene. Die Folge ist unauffällig, aber real: Die Dateistruktur, die in Ihrem Editor logisch aussieht (der Import ist scheinbar in den Abschnitt "verschachtelt"), wird im Modell tatsächlich als zwei unabhängige Überschriften derselben Ebene entfaltet – dies verwirrt die Hierarchie der Wichtigkeit von Anweisungen, wenn Sie erwartet haben, dass die Verschachtelung selbst dem Modell etwas signalisiert. Ein GitHub-Issue dazu wurde als "nicht geplant" geschlossen, daher ist keine Korrektur zu erwarten – achten Sie manuell auf die Überschriftenebenen (HackerNoon).
Glob-Muster, die mit { oder * beginnen, müssen in YAML-Frontmatter in Anführungszeichen gesetzt werden – ohne Anführungszeichen ist dies keine Einschränkung von Claude Code, sondern eine Standardanforderung der YAML-Syntax, die Entwickler regelmäßig überrascht (Medium, Frontend Master). Die Folge ist hier die gröbste von allen: Dies ist kein stiller Verhaltensfehler, sondern ein syntaktischer Parsing-Fehler – die gesamte Regeldatei kann überhaupt nicht geladen werden, und Sie verlieren nicht eine Regel, sondern den gesamten Satz von pfadbezogenen Regeln aus dieser Datei, bis Sie die Anführungszeichen finden und korrigieren.
FAQ
Kann man mehrere CLAUDE.md haben?
Ja, und ich würde sogar sagen, dass dies für jedes Projekt, das größer als ein einzelner Dienst ist, keine Option, sondern die Norm ist. Ich habe normalerweise drei Ebenen gleichzeitig in Arbeit: eine globale mit persönlichen Einstellungen, eine projektbezogene unter Git für das gesamte Team und mehrere verschachtelte in Unterverzeichnissen mit der Spezifität eines bestimmten Moduls. Sie konkurrieren nicht – jede Ebene ergänzt die allgemeinere nach der Spezifitätsregel, die ich bereits oben erklärt habe: Eine lokalere Anweisung überschreibt eine allgemeinere dort, wo sie sich überschneiden.
Wo speichert man die Datei am besten?
Hier halte ich mich an eine einfache Aufteilung nach Zweck. Die projektbezogene CLAUDE.md lege ich immer in das Stammverzeichnis des Repositories und committe sie in Git – sonst arbeitet das gesamte Team mit unterschiedlichen Anweisungen für dasselbe Modell, was den Sinn der Datei zunichte macht. Die persönliche Datei (~/.claude/CLAUDE.md) ist dagegen außerhalb des Repositories, da es sich um meine persönlichen Arbeitsgewohnheiten handelt, die anderen Teammitgliedern nicht aufgedrängt werden sollten.
Was ist die optimale Größe?
Als Richtlinie, an die ich mich selbst halte, sind es bis zu 200 Zeilen für eine Projektdatei und bis zu 30 Zeilen für eine persönliche globale Datei. Dies ist keine willkürliche Zahl zum Abhaken: Ich habe bereits im Abschnitt über Best Practices erklärt, dass Modelle etwa 150-200 Anweisungen gleichzeitig zuverlässig im Fokus behalten, und der System-Prompt von Claude Code selbst beansprucht bereits etwa 50 davon. Das Überschreiten dieser Grenze ist also kein ästhetisches Problem, sondern ein direkter Effizienzverlust: Ein Teil Ihrer Anweisungen funktioniert einfach nicht mehr zuverlässig.
Kann man Markdown verwenden?
Ja, das ist das native Format der Datei, und ich würde empfehlen, die Struktur nicht zu vernachlässigen – Überschriften und Listen sehen nicht nur "schön aus", sie helfen, zusammengehörige Anweisungen in logische Blöcke zu gruppieren, was sowohl für mich bei der Überprüfung der Datei als auch für das Modell bei der Verarbeitung des Kontexts die Lesbarkeit erleichtert.
Funktioniert CLAUDE.md in Unterverzeichnissen?
Ja, und gerade hier halte ich das Gedächtnismodell von Claude Code für stärker als einfachere Alternativen. Eine verschachtelte CLAUDE.md wird nicht sofort beim Start der Sitzung geladen, sondern on-demand – nur wenn Claude tatsächlich auf Dateien im entsprechenden Unterverzeichnis zugreift. Für Monorepos, mit denen ich regelmäßig arbeite, bedeutet dies, dass Anweisungen, die für ein Frontend-Modul spezifisch sind, keinen Kontext beanspruchen, wenn Claude ausschließlich mit Backend-Code arbeitet.
Muss man es in Git speichern?
Die Projektdatei – unbedingt ja, darauf bestehe ich in jedem Team, mit dem ich arbeite: Wenn CLAUDE.md nicht in Git ist, sammelt jeder Entwickler seine eigene, sich allmählich auseinanderentwickelnde Version von Anweisungen, und Sie verlieren den Hauptwert der Datei – die Konsistenz. Persönliche Override-Dateien füge ich dagegen immer zu .gitignore hinzu – sie sind spezifisch für meine Arbeitsumgebung, nicht für das Projekt.
Was ist der Unterschied zu README?
Ich formuliere diesen Unterschied über die Zielgruppe, nicht über das Format. README wird für eine Person geschrieben, die ein Repository zum ersten Mal öffnet und nichts über das Projekt weiß – es ist eine Visitenkarte. CLAUDE.md wird für ein Modell geschrieben, das bereits allgemeine Entwicklungsmuster kennt und nur das benötigt, was Ihr Projekt von den Standardannahmen unterscheidet. Als ich versuchte, beide Rollen in einer Datei zu vereinen, litten beide Zielgruppen gleichzeitig – ich habe darüber im Abschnitt über typische Fehler weiter oben detaillierter geschrieben.
Kann man es zusammen mit AGENTS.md verwenden?
Ja, und in meiner Praxis ist dies eher die Regel als die Ausnahme – selten hält sich ein Team heute ausschließlich an ein KI-Tool. Claude Code liest nur CLAUDE.md, während Cursor, Copilot oder Gemini CLI sich hauptsächlich an AGENTS.md orientieren. Wenn Ihr Team gemischt ist, würde ich sofort die Unterstützung beider Dateien einplanen und nicht versuchen, ein Werkzeug dazu zu bringen, das Format eines anderen zu lesen – das funktioniert einfach nicht.
Reduziert @import wirklich den Kontext?
Nein, und das ist genau die falsche Intuition, die ich selbst hatte, bevor ich den Mechanismus genauer verstand. Imports werden beim Start der Sitzung vollständig geladen – das Aufteilen der Datei in mehrere importierte Teile erleichtert Ihnen die Wartung des Codes, reduziert aber nicht das Volumen, das tatsächlich in das Modell gelangt. Wenn das Ziel die Einsparung von Kontext und nicht die Bearbeitungsfreundlichkeit ist, funktionieren nur pfadbezogene Regeln in .claude/rules/, die ich im Abschnitt über das technische Laden der Datei oben detailliert erklärt habe.
Was passiert mit CLAUDE.md nach /compact?
Die Wurzelfdatei wird neu von der Festplatte injiziert – das habe ich persönlich überprüft, und das Verhalten ist stabil. Verschachtelte CLAUDE.md und Regeln kehren nach der Kompaktierung jedoch nicht automatisch zurück: Sie werden erst wieder geladen, wenn Claude das nächste Mal auf das entsprechende Unterverzeichnis oder die Datei zugreift. Wenn Sie davon ausgehen, dass eine verschachtelte Anweisung nach der Kompaktierung für die gesamte Sitzung "gespeichert" wurde, ist dies eine gefährliche Annahme – es ist besser davon auszugehen, dass sie nur bei Bedarf nachgeladen wird.
Welche Mindestversion von Claude Code wird für /doctor-Trimming benötigt?
v2.1.206 oder neuer. Ich empfehle, Ihre aktuelle Version zu überprüfen, bevor Sie sich auf diesen Befehl in der Beschreibung der Best Practices oben verlassen – auf älteren Versionen fehlt der Befehl einfach, und Sie erhalten eine Fehlermeldung anstelle eines Hinweises zum Kürzen der Datei.
Schlussfolgerungen
Wenn ich einen Gedanken aus diesem Artikel mitnehmen würde, wäre es dieser: CLAUDE.md ist keine Dokumentation und keine Konfiguration, sondern Text, der jedes Mal um die begrenzte Aufmerksamkeit des Modells mit allem anderen konkurriert, was in den Kontext geladen wird. Jede zusätzliche Zeile ist keine kostenlose "für den Fall"-Versicherung, sondern ein realer Preis, den das Modell in jeder Sitzung zahlt.
Mein praktischer Rat, mit dem ich an jede neue CLAUDE.md herangehe: Versuchen Sie nicht, die perfekte Datei sofort zu schreiben. Beginnen Sie mit dem grundlegenden Minimum – Stack, Befehle, Schlüsselkonventionen – und fügen Sie jedes Mal eine Zeile hinzu, wenn Claude einen Fehler macht, den eine klare Regel hätte verhindern können. Und bevor Sie eine neue Zeile hinzufügen, wenden Sie denselben Test an, der /doctor zugrunde liegt: Kann dies aus dem Code abgeleitet werden? Wenn ja – schreiben Sie es nicht, das Modell wird es selbst herausfinden.
