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

[GN⁺]

Hacker-News-Kommentare

• Claude neigt dazu, Anweisungen in CLAUDE.md gelegentlich zu ignorieren
  Je mehr Informationen in der Datei stehen, die mit der konkreten Aufgabe nichts zu tun haben, desto eher befolgt Claude diese Anweisungen nicht
  Ein Freund hatte Claude angewiesen, ihn „Mr Tinkleberry“ zu nennen, und immer wenn Claude das vergaß, war klar, dass es die Datei ignorierte

• Ich nutze schon länger den Table-of-Contents-Ansatz
  Ich trenne aufgabenspezifische Anweisungen in einzelne Markdown-Dateien auf, und in CLAUDE.md stehen nur die Liste und kurze Beschreibungen
  So bleibt das Context Window sauber
  Meine Beispieldatei gibt es hier

  • Ich habe dieselbe Methode auch ausprobiert, aber die Ergebnisse waren sehr wechselhaft
    Claude hat die anderen Dokumentdateien in der Praxis kaum tatsächlich gelesen

• Ich habe das Gefühl, dass zu viel Context für Claude die Qualität eher verschlechtert
  Deshalb halte ich immer zwei Versionen des Codes vor

  1. den ursprünglichen Code ohne Kommentare und Leerraum
  2. den Code mit Kommentaren
     Dem LLM gebe ich nur die erste Version
     Ich denke, das Verhältnis von Compute zu Information ist entscheidend. Rechenkapazität ist schließlich begrenzt
  • Ich hatte eine ähnliche Erfahrung, aber es wurde effizienter, als ich wiederkehrende Inhalte in eine Claude-Notes-Datei gepackt habe
    Man muss nicht alles hineinwerfen, aber Kerninformationen hineinzuschreiben hatte einen hohen ROI
    Bei allgemeinen Projekten funktioniert Claude gut, aber bei neuen Frameworks oder Tools ist es oft verwirrt
  • Du hast gesagt, dass du zwei Code-Versionen pflegst; mich würde interessieren, wie du diese Konsistenz verwaltest
    Ich würde gern wissen, ob du nach Änderungen ein Skript verwendest, das Kommentare und Leerraum entfernt
  • Ich denke, man sollte in Dokumentdateien eine hohe Informationsdichte beibehalten
  • Du hast gesagt, dass du dem LLM nicht die Version mit Kommentaren gibst; mich würde interessieren, wie du das konkret umsetzt
  • Letztlich ist Attention endlich. Wenn man zu viel Context hineingibt, verteilt sich die Konzentration

• Eigentlich gibt es auch ohne dieses komplizierte Setup eine Lösung
  Nämlich den Code klar zu dokumentieren
  Wenn man knapp aufschreibt, was jede Datei macht, dient das bereits als Prompt
  Man kann README.md aktiv nutzen
  LLMs wurden bereits mit öffentlichen Informationen trainiert, daher muss man nichts Neues erfinden

  • Aber wenn man Dokumentation für KI schreibt, braucht es eine andere Herangehensweise als bei Dokumentation für menschliche Leser
    Der bloße Rat „Dokumentiere den Code gut“ passt in diesem Kontext nicht
  • Ich denke auch, dass die AI-Community oft unnötigerweise das Rad neu erfindet
    README ist gut, aber CLAUDE.md hat einen anderen Zweck
    Zum Beispiel hat Claude/agents.md die Funktion, beim Zugriff auf ein bestimmtes Verzeichnis automatisch in den Context eingefügt zu werden
    In komplexen Codebases ist Context-Management viel wichtiger
  • CLAUDE.md ist nicht einfach nur ein Dokument, sondern dient dazu, den Initial Prompt des Modells anzupassen
    Deshalb verfehlt der Rat „Schreib einfach einen guten Prompt“ den Kern
  • Wo würde man zum Beispiel die Regel hinschreiben, dass Datenbankabfragen immer Indizes verwenden müssen?
    Wenn man sie ins README schreibt, erfüllt es am Ende dieselbe Rolle wie CLAUDE.md
    Der Zweck von CLAUDE.md ist es, Claude zentrale Informationen im Voraus zu geben, damit es nicht jedes Mal alle Dokumente erneut lesen muss
    Menschen erinnern sich, aber Claude vergisst bei jeder Aufgabe wieder alles, deshalb braucht man eine Struktur, die erneutes Onboarding reduziert

• Ehrlich gesagt habe ich das Gefühl, wenn man KI-Infrastruktur so aufwendig aufsetzen muss, dann ist es besser, einfach selbst zu programmieren

  • Aber stylebezogene Einstellungen muss man nur einmal vornehmen und kann sie dann wiederverwenden
    Ich verwalte gemeinsame Regeln und projektspezifische Regeln getrennt
  • Das im Artikel beschriebene Setup ist in ein paar Stunden erledigt
    KI nicht zu nutzen ist schlicht ein Produktivitätsverlust
  • Den Großteil des anfänglichen Setups kann man auch dem LLM überlassen
  • Tatsächlich ist der Aufwand gar nicht so groß. Das Problem ist eher, dass man die Tools überoptimieren will
  • Entscheidend ist, ob die Kosten wiederkehrend oder einmalig sind
    Wenn das Setup nur einmal nötig ist, lohnt sich die Investition absolut
    „Das Setup ist lästig“ klingt wie die Ausrede von Leuten, die auch die Einrichtung eines Debuggers vermeiden

• Ich kopiere den benötigten Code einfach in das Chatfenster und füge ihn dort ein und nutze es wie ein Gespräch
  Die Modelle sind inzwischen so viel besser geworden, dass sie auch ohne .md-Dateien ziemlich gute Ergebnisse liefern
  Solche Dateien können vielleicht kleine Verbesserungen bringen, aber ich glaube nicht, dass sie eine magische 100-fache Produktivität liefern

  • Aber das ist ein anderer Anwendungsfall
    Hier geht es darum, dass Claude selbstständig vollständige Features implementiert oder Bugs behebt
  • Ich habe Ähnliches erlebt. Ich habe CLAUDE.md einmal erstellt, nutze es jetzt aber nicht mehr
    Es funktioniert schon gut genug, wenn man einfach den nötigen Context gibt. Es wirkt ein bisschen wie Bikeshedding
  • Trotzdem kann es Wiederholungen reduzieren, wenn man zumindest Datenbanktabellen oder eine Liste von Spalten vorab zusammenstellt

• Ich lasse Claude CLAUDE.md selbst schreiben
  Wenn man ihm sagt: „README.md ist für Nutzer, CLAUDE.md ist für dich“,
  aktualisiert es Anweisungen wie „Prüfe immer die API-Dokumentation“ automatisch mit
  Man muss keinen magischen Prompt kennen, solange das Ergebnis gut ist

  • Aber ich frage mich, ob es Belege dafür gibt, dass von KI selbst geschriebene Anweisungen besser sind als von Menschen geschriebene
    Es scheint keinen besonderen Grund zu geben, warum KI sich selbst am besten prompten können sollte