Wie man ein gutes Claude.md schreibt

• Da ein LLM eine zustandslose Funktion ist, fungiert CLAUDE.md als zentrales Dokument, das Claude in jeder Sitzung erneut in die Codebasis einführt
• Die Datei sollte das WHAT (Struktur), WHY (Zweck) und HOW (Funktionsweise) des Projekts prägnant enthalten; ein Übermaß an unnötigen Anweisungen führt zu Leistungseinbußen
• Claude kann den Inhalt von CLAUDE.md gemäß den Anweisungen in der Systemnachricht ignorieren, wenn er als wenig relevant eingestuft wird
• Eine effektive Datei enthält nur kurze, allgemein anwendbare Informationen; detaillierte Anweisungen sollten in separate Dokumente ausgelagert und per Progressive Disclosure verwaltet werden
• CLAUDE.md ist der wirkungsmächtigste Hebelpunkt der Agent-Harness und sollte deshalb nicht automatisch generiert, sondern sorgfältig von Hand geschrieben werden

---

Die Zustandslosigkeit von LLMs und die Rolle von CLAUDE.md

• LLMs verwenden zum Zeitpunkt der Inferenz feste Gewichte und behalten weder sitzungsübergreifendes Lernen noch Erinnerungen bei
  • Damit das Modell die Codebasis verstehen kann, müssen alle Informationen als Eingabe-Token bereitgestellt werden
• Coding-Agenten wie Claude Code müssen Speicher explizit verwalten, und CLAUDE.md ist die einzige Datei, die automatisch in jede Unterhaltung aufgenommen wird
• Daraus ergeben sich drei zwingende Punkte
  1. Zu Beginn einer Sitzung weiß Claude nichts über die Codebasis
  2. In jeder Sitzung müssen die nötigen Informationen erneut vermittelt werden
  3. Das Standardmittel dafür ist CLAUDE.md

Onboarding der Codebasis: WHAT, WHY, HOW

• CLAUDE.md dient als Onboarding-Dokument, das Claude hilft, das Projekt zu verstehen
  • WHAT: Liefert eine Karte der Codebasis, etwa Tech-Stack, Projektstruktur oder Monorepo-Aufbau
  • WHY: Erklärt Zweck und Funktion der einzelnen Komponenten
  • HOW: Beschreibt, wie konkrete Aufgaben wie Build, Tests oder Type-Checking ausgeführt werden
• Allerdings ist es ineffizient, alle Befehle aufzulisten; es sollte nur die minimal notwendige Information enthalten sein

Warum Claude CLAUDE.md ignoriert

• Claude Code fügt in Nutzernachrichten den folgenden System-Reminder ein

  IMPORTANT: this context may or may not be relevant...
  

  • Dadurch ignoriert Claude diesen Kontext, wenn er für die aktuelle Aufgabe als nicht relevant eingeschätzt wird
• Je mehr nicht allgemein gültige Anweisungen die Datei enthält, desto wahrscheinlicher ist es, dass sie ignoriert wird
• Vermutlich hat Anthropic dies hinzugefügt, weil sich die Qualität der Ergebnisse verbessert, wenn unnötige Anweisungen ignoriert werden

Prinzipien für ein gutes CLAUDE.md

Less (instructions) is more

• LLMs können etwa 150 bis 200 Anweisungen zuverlässig befolgen
  • Bei kleineren Modellen fällt die Leistung deutlich schneller ab, und sie eignen sich weniger für mehrstufige Aufgaben
• Der System-Prompt von Claude Code enthält bereits rund 50 Anweisungen
  • Daher sollte CLAUDE.md nur minimale, allgemein gültige und unverzichtbare Anweisungen enthalten
• Je mehr Anweisungen hinzukommen, desto stärker verschlechtert sich die Ausführungsqualität aller Anweisungen gleichmäßig

Dateilänge und Geltungsbereich

• LLMs arbeiten besser mit fokussiertem und hochrelevantem Kontext
• Da CLAUDE.md in jede Sitzung aufgenommen wird, sollte es nur allgemein anwendbare Informationen enthalten
• Im Allgemeinen wird empfohlen, unter 300 Zeilen zu bleiben, möglichst noch kürzer
  • Die Beispieldatei von HumanLayer hat weniger als 60 Zeilen

Progressive Disclosure

• In großen Projekten ist es schwierig, alle Informationen in einer Datei unterzubringen; deshalb wird Progressive Disclosure empfohlen
  • Detaillierte Anweisungen werden in separate Markdown-Dateien im Ordner agent_docs/ ausgelagert
  • Zum Beispiel: building_the_project.md, running_tests.md, code_conventions.md
• CLAUDE.md sollte nur eine Liste dieser Dateien mit kurzen Beschreibungen enthalten sowie die Anweisung, dass Claude sie bei Bedarf lesen soll
• Statt Code-Snippets sollten file:line-Verweise verwendet werden, um Aktualität zu bewahren
• Das ähnelt dem Konzept von Claude Skills, konzentriert sich aber eher auf die Verwaltung von Anweisungen als auf den Einsatz von Tools

Claude ist kein Linter

• Es ist ineffizient, Richtlinien zum Code-Stil in CLAUDE.md aufzunehmen
  • LLMs sind teuer und langsam und im Vergleich zu Lintern weniger deterministisch
• Stilregeln werden über bestehende Code-Muster natürlich mitgelernt, daher sind separate Anweisungen unnötig
• Für Formatierung sollten Linter mit automatischer Korrektur (z. B. Biome) eingesetzt werden, und Claude sollte nur das Ergebnis der Korrektur erhalten
• Bei Bedarf lassen sich Formatierung und Validierung mit Stop Hook oder Slash Command automatisieren

Keine automatische Generierung

• Ein per /init-Befehl oder Auto-Generierung erstelltes CLAUDE.md wird nicht empfohlen
  • Denn diese Datei ist ein High-Leverage-Punkt, der alle Sitzungen und Ergebnisse beeinflusst
• Schon eine einzige falsche Anweisung kann kaskadierende negative Auswirkungen auf die gesamte Codequalität haben
• Deshalb sollte jeder Satz sorgfältig geprüft und von Hand geschrieben werden

Fazit

• CLAUDE.md ist ein Dokument, das Claude in die Codebasis onboardet, und sollte WHY, WHAT und HOW klar definieren
• Anweisungen sollten minimiert werden; enthalten sein sollte nur allgemein gültiger und knapper Inhalt
• Mit Progressive Disclosure werden nur die jeweils nötigen Informationen schrittweise bereitgestellt
• Claude sollte nicht als Linter verwendet werden; stattdessen sollten spezialisierte Tools sowie Hook- und Command-Funktionen parallel genutzt werden
• Statt automatischer Generierung sollte die Datei sorgfältig von Hand erstellt werden, um die Qualität der gesamten Harness zu maximieren