CLAUDE.md-Dateien richtig nutzen und pflegen

1. Was eine CLAUDE.md eigentlich ist und wofür sie wirkt

Eine CLAUDE.md ist eine Markdown-Datei im Projekt-Root (oder in Unterverzeichnissen), die Claude Code automatisch in den Kontext lädt, sobald eine Session in diesem Verzeichnis startet. Technisch ist sie nichts Besonderes, nur Text, der dem Modell vor dem eigentlichen Prompt mitgegeben wird. Der Effekt ist trotzdem groß: Statt bei jeder neuen Session zu erklären, dass das Projekt Magento 2.4.8 mit Hyvä-Theme nutzt, PHP 8.4 mit Strict Types verlangt und Deployments ausschließlich über Docker-Wrapper-Skripte laufen, steht das einmal geschrieben und wird bei jeder Anfrage automatisch berücksichtigt.

Der zentrale Denkfehler bei vielen ersten CLAUDE.md-Versuchen ist, die Datei wie eine Projektdokumentation zu behandeln, die alles abdecken soll. Das Modell hat aber ein begrenztes Kontextfenster, und jede Zeile in der CLAUDE.md konkurriert mit dem eigentlichen Code, den Claude für eine Aufgabe lesen muss. Eine gute CLAUDE.md optimiert nicht auf Vollständigkeit, sondern auf Trefferquote: Sie enthält die Informationen, die Claude sich sonst falsch herleiten würde, und lässt alles weg, was sich in Sekunden aus dem Code selbst ablesen lässt.

2. Was in eine CLAUDE.md gehört

In eine CLAUDE.md gehören Informationen, die aus dem Code selbst nicht oder nur mit erheblichem Suchaufwand ablesbar sind, aber das Verhalten von Claude bei jeder Aufgabe beeinflussen sollen. Dazu zählen der Tech-Stack mit konkreten Versionen, verbindliche Coding-Standards wie Constructor Property Promotion oder das Verbot von assert(), projektspezifische Architekturentscheidungen wie ViewModels statt Block-Klassen, und die Befehle, mit denen täglich gearbeitet wird, etwa der Docker-Wrapper statt direktem php bin/magento-Aufruf.

Ebenso gehören Sicherheitsregeln hinein, die Claude sonst versehentlich verletzen könnte: geschützte Dateien, verbotene destruktive Kommandos, oder die Regel, niemals Secrets in Commits einzuchecken. Ein weiterer wichtiger Block sind wiederkehrende Muster, die im Projekt Konvention sind, aber von allgemeinen Best Practices abweichen, etwa ein Dual-Vendor-Workflow, bei dem jede Datei parallel in zwei Verzeichnissen gepflegt wird. Ohne diese Angabe würde Claude Code diese Konvention nicht erraten, selbst wenn es beide Verzeichnisse im Repository sieht.

# Good CLAUDE.md content: rules Claude cannot infer from code alone

## Tech Stack
- Magento 2.4.8-p4, PHP 8.4 (strict_types=1), Hyva Theme, Tailwind CSS v4, Alpine.js
- No jQuery, no Knockout.js, no Luma, no UI Components

## Coding Standards
- Prefer ViewModels (ArgumentInterface) over Block classes
- Use constructor property promotion for all dependency injection
- Plugins (interceptors) instead of class preferences
- Declarative schema (db_schema.xml) instead of install scripts

## Commands (never call php bin/magento directly)
- bin/magento [command]        # Magento CLI via Docker wrapper
- bin/cache-clean [tags]       # Clear cache, Hyva watcher stays active
- bin/analyse app/code/Vendor/Module --level=5   # PHPStan

## Forbidden patterns
- assert() for type narrowing -> use /** @var Type $var */ instead
- @ error silencing -> use try/catch or a PHPStan ignore comment

3. Was in eine CLAUDE.md nicht gehört

Implementierungsdetails, die Claude durch einfaches Lesen des Codes selbst herausfinden kann, gehören nicht in die CLAUDE.md. Eine Liste aller Klassen eines Moduls, die genaue Signatur einer Methode, oder eine Beschreibung, was eine bestimmte Datei tut, veralten garantiert bei der nächsten Änderung und sind für Claude ohnehin nur einen Tool-Aufruf entfernt. Wer solche Details in die CLAUDE.md schreibt, verdoppelt nicht nur Wartungsaufwand, sondern riskiert Widersprüche zwischen Dokumentation und tatsächlichem Code, die das Modell dann als Wahrheit behandelt.

Ebenso fehl am Platz sind allgemeine Programmierweisheiten, die für jedes PHP-Projekt gelten würden und keinen projektspezifischen Mehrwert liefern, etwa dass Variablennamen aussagekräftig sein sollen. Auch temporäre Informationen wie der aktuelle Stand eines laufenden Refactorings oder eine To-do-Liste für die nächste Woche gehören nicht hierher, dafür existieren separate Dateien wie ein Changelog oder ein Projektmanagement-Tool. Die Faustregel: Wenn eine Änderung im Code eine Änderung in der CLAUDE.md erzwingen würde, war die Information wahrscheinlich zu granular für diese Datei.

# Anti-pattern: implementation detail that will rot within days

## SeoSuiteHelper.php
- Line 42: getMetaTitle() reads the "meta_title" attribute
- Line 58: fallback logic uses product name if meta_title is empty
- Constructor takes StoreManagerInterface and ProductRepositoryInterface

# This belongs nowhere in CLAUDE.md - Claude reads the file directly
# and the description is already stale after the next refactor.

4. Struktur und Reihenfolge: was zuerst gelesen wird

Die Reihenfolge der Abschnitte in einer CLAUDE.md ist kein kosmetisches Detail. Claude liest die Datei linear als Teil des Systemkontexts, und Informationen, die früh stehen, werden zuverlässiger berücksichtigt als solche, die am Ende einer langen Datei vergraben sind. Ein bewährtes Muster: Zuerst der Tech-Stack in wenigen Zeilen, danach die verbindlichen Coding-Standards, danach die häufigsten Kommandos, und erst am Ende Detailregeln für Randfälle wie PHPStan-Ausnahmen für bekannte Magento-Interface-Lücken.

Kurze, scannable Listen schlagen lange Fließtextabsätze. Claude verarbeitet eine Liste mit klaren Bullet-Points zuverlässiger als einen Absatz, in dem dieselbe Regel in einem Nebensatz versteckt ist. Überschriften mit ## und ### helfen zusätzlich, weil sie thematische Blöcke klar abgrenzen und es Claude erlauben, bei einer konkreten Aufgabe gezielt den relevanten Abschnitt heranzuziehen, statt die gesamte Datei gleichmäßig zu gewichten. Code-Beispiele in der CLAUDE.md selbst sollten kurz und illustrativ bleiben, nicht als vollständige Referenzimplementierung dienen.

# Recommended order inside a CLAUDE.md

## 1. Tech Stack (always first, a few lines)
## 2. Coding Standards & Patterns (binding rules)
## 3. Common Commands (CLI, Docker, build)
## 4. Project Structure (paths, vendor conventions)
## 5. Known Exceptions & Edge Cases (last, rarely needed)

# Anti-pattern: everything in one long prose paragraph
# without headings and without bullet points

5. Hierarchie: globale, Projekt- und Verzeichnis-CLAUDE.md

Claude Code unterstützt mehrere CLAUDE.md-Dateien gleichzeitig, die sich ergänzen statt gegenseitig zu ersetzen. Eine globale CLAUDE.md unter ~/.claude/CLAUDE.md gilt für alle Projekte eines Nutzers und eignet sich für persönliche Präferenzen wie Antwortsprache oder generelle Git-Sicherheitsregeln. Eine projektspezifische CLAUDE.md im Repository-Root, eingecheckt in Git, gilt für alle, die an diesem Projekt arbeiten, und enthält die in diesem Artikel beschriebenen Projektkonventionen.

Zusätzlich lassen sich CLAUDE.md-Dateien in Unterverzeichnissen platzieren, deren Inhalt nur relevant wird, wenn Claude tatsächlich in diesem Verzeichnis arbeitet, etwa eine CLAUDE.md in app/code/Mironsoft/SeoSuite/ mit modulspezifischen Regeln, die für den Rest des Projekts irrelevant wären. Diese Aufteilung verhindert, dass die Root-CLAUDE.md mit Spezialwissen überladen wird, das nur für einen kleinen Teil der Codebasis gilt. Wichtig ist, doppelte oder widersprüchliche Regeln zwischen den Ebenen zu vermeiden, weil unklar ist, welche Ebene bei einem Konflikt priorisiert wird.

# Typical CLAUDE.md hierarchy in a multi-module Magento project
~/.claude/CLAUDE.md                              # personal, global preferences
src/CLAUDE.md                                    # project-wide conventions
src/app/code/Mironsoft/SeoSuite/CLAUDE.md         # module-specific rules only

# Check which CLAUDE.md files are currently loaded in a session
find . -name "CLAUDE.md" -not -path "*/vendor/*" -not -path "*/node_modules/*"

6. Pflege über die Projektlaufzeit: wann und wie aktualisieren

Eine CLAUDE.md ist kein einmalig geschriebenes Artefakt, sondern ein lebendes Dokument, das mit dem Projekt altert. Der zuverlässigste Auslöser für ein Update ist eine Code-Review-Situation, in der Claude wiederholt denselben Fehler macht oder eine Konvention verletzt, die dem Team bekannt ist. Wenn ein Entwickler zum dritten Mal in einer Session korrigieren muss, dass Plugins statt Preferences verwendet werden sollen, gehört diese Regel in die CLAUDE.md, nicht in den nächsten Prompt.

Ebenso sollte jede große Architekturentscheidung, etwa der Wechsel von einem alten Frontend-Stack zu Hyvä-Theme, unmittelbar in der CLAUDE.md nachgezogen werden, damit Claude nicht mit veralteten Annahmen weiterarbeitet. Ein einfacher Test für Aktualität: Bei jedem größeren Merge in den Hauptzweig kurz prüfen, ob sich Tech-Stack-Angaben oder Kommandos geändert haben. Wer die CLAUDE.md nie wieder anfasst, nachdem sie einmal geschrieben wurde, riskiert nach einigen Monaten eine Datei, die aktiv falsche Annahmen transportiert, was schlimmer ist als gar keine CLAUDE.md zu haben.

7. CLAUDE.md im Team: Versionierung und Konsistenz

Weil eine projektweite CLAUDE.md Teil des Repositories ist, durchläuft sie denselben Review-Prozess wie jede andere Codeänderung. Das ist gewollt: Eine neue Regel in der CLAUDE.md betrifft alle Teammitglieder, die mit Claude Code arbeiten, und sollte deshalb nicht im Alleingang eingeführt werden. In der Praxis bewährt sich, Änderungen an der CLAUDE.md in denselben Pull Request wie die zugehörige Codeänderung zu packen, damit der Kontext für die Regel direkt neben der Regel selbst sichtbar ist.

Ein häufiges Problem in Teams ist Drift zwischen dem, was in der CLAUDE.md steht, und dem, was tatsächlich im Code praktiziert wird. Wenn die Datei etwa vorschreibt, ausschließlich ViewModels statt Block-Klassen zu verwenden, aber die Hälfte des bestehenden Codes noch Block-Klassen nutzt, entsteht Verwirrung darüber, ob die Regel für neuen Code oder auch für bestehenden Code gilt. Eine explizite Formulierung wie neue Klassen verwenden ViewModels, bestehende Block-Klassen werden bei Berührung migriert löst diese Ambiguität auf und verhindert, dass Claude bei jeder Aufgabe neu rät.

8. Praxisbeispiel: CLAUDE.md für ein Magento-Projekt

Ein konkretes Beispiel macht die vorherigen Abschnitte greifbar. Die folgende Struktur orientiert sich an einem realen Magento-2-Projekt mit Hyvä Theme und zeigt, wie kompakt eine wirkungsvolle CLAUDE.md sein kann, ohne wichtige Informationen auszulassen. Auffällig ist die Kürze jedes Abschnitts: Kein Punkt braucht mehr als zwei Zeilen, um wirksam zu sein.

Bemerkenswert ist auch, was in diesem Beispiel bewusst fehlt: keine Liste aller Module, keine Erklärung, wie db_schema.xml grundsätzlich funktioniert, keine Kopie der Magento-Dokumentation. All das kann Claude bei Bedarf selbst nachschlagen oder aus dem Code lesen. Die CLAUDE.md konzentriert sich ausschließlich auf projektspezifische Entscheidungen und Abweichungen von der Magento-Standardpraxis.

{
  "example_structure": "CLAUDE.md sections for a Magento 2 / Hyva project",
  "sections": [
    "Tech Stack: Magento version, PHP version, Hyva Theme, no jQuery/Knockout",
    "Coding Standards: ViewModels over Blocks, constructor DI, plugins over preferences",
    "CLI Commands: Docker wrapper scripts, never call php bin/magento directly",
    "Deploy Sequence: exact order of build, static-content:deploy, cache:flush",
    "PHPStan: target level, known Magento interface gaps with ignore comments",
    "Forbidden Patterns: assert(), @ error silencing, addFieldToFilter with int",
    "Module Conventions: every module ships config.xml, system.xml, acl.xml"
  ]
}

9. Typische Fallstricke im Vergleich

Die meisten Probleme mit CLAUDE.md-Dateien lassen sich auf wenige wiederkehrende Muster zurückführen. Die folgende Tabelle stellt häufige Fehler den empfohlenen Alternativen gegenüber, jeweils mit der konkreten Konsequenz für die Zusammenarbeit mit Claude Code.

Auffällig ist, dass fast alle Fallstricke auf denselben Grundfehler zurückgehen: die CLAUDE.md wie ein Wiki statt wie ein kuratiertes Regelwerk zu behandeln. Ein Wiki darf wachsen, weil Leser gezielt suchen. Eine CLAUDE.md wird bei jeder Anfrage vollständig in den Kontext geladen, weshalb jede überflüssige Zeile echte Kosten verursacht, sowohl an Tokens als auch an der Wahrscheinlichkeit, dass eine wichtige Regel im Rauschen untergeht.

10. Zusammenfassung

Eine gute CLAUDE.md löst ein konkretes Problem: Sie gibt Claude Code Projektwissen mit, das sich nicht zuverlässig aus dem Code selbst ableiten lässt, ohne die Datei mit Informationen zu überladen, die Claude ohnehin in Sekunden nachschlagen kann. Tech-Stack, Coding-Standards, Befehle und projektspezifische Abweichungen gehören hinein. Implementierungsdetails, allgemeine Programmierweisheiten und temporäre To-dos gehören nicht hinein. Kurze, mit Überschriften strukturierte Listen werden zuverlässiger beachtet als lange Fließtextabsätze.

Der größte Hebel liegt in der kontinuierlichen Pflege: Eine CLAUDE.md, die nach der ersten Version nie wieder angefasst wird, driftet unweigerlich vom tatsächlichen Projektstand ab und wird nach einigen Monaten zur Quelle falscher Annahmen. Wer Änderungen an der CLAUDE.md wie normale Codeänderungen behandelt, im selben Pull Request wie die zugehörige Regel, mit Review durch das Team, hält die Datei über die gesamte Projektlaufzeit hinweg als verlässliche Grundlage für die Zusammenarbeit mit Claude Code.

11. FAQ: CLAUDE.md-Dateien richtig nutzen und pflegen