CLAUDE.md Best Practices: was hineingehört, was nicht, und wie man die Größe misst

Die Dokumentation von Anthropic nennt für eine CLAUDE.md genau eine Zahl: „target under 200 lines per CLAUDE.md file.“ Dazu kommen ein guter Test für jede Zeile und eine Tabelle, was hinein soll und was nicht. Das stimmt alles, und nichts davon sagt dir, was die Datei kostet, denn eine Zeile ist keine Kosteneinheit. Das Modell zahlt in Tokens.

Ich pflege zwei Ebenen dieser Dateien. Eine globale in ~/.claude/CLAUDE.md, die jeder meiner Agenten lädt, und eine pro Projekt, ./CLAUDE.md oder ./.claude/CLAUDE.md, in jedem Repository. Claude Code lässt die eine die andere nicht überschreiben, sondern hängt sie aneinander: zuerst die User-Datei, dann die Projektdatei. Ich kürze sie seit Monaten, lasse sie wachsen und messe sie, und die Geschichte steht in git. Was sie zeigt und was in der Doku fehlt: Jede Zeile in einer CLAUDE.md ist eine Behauptung, dass der Agent ohne sie falsch abbiegen würde. Solche Behauptungen kosten fast nichts und werden selten überprüft.

Jede Doku-Aussage, die ich unten zitiere, habe ich gegen Claude Code 2.1.310 geprüft.

Was gehört in eine CLAUDE.md?

Zeilen, deren Fehlen der Agent nicht bemerken kann. Ein Build-Befehl, den Claude nicht erraten kann, ein Fallstrick, der lautlos scheitert, eine Konvention, die vom Standard abweicht: Fehlt so eine Zeile, gibt es in der Session nichts, was den Agenten dazu bringt, danach zu suchen.

Die Best-Practices-Seite von Anthropic formuliert den Test als Frage an jede Zeile:

"Would removing this cause Claude to make mistakes?" If not, cut it.

Die Include-Spalte ist die praktische Fassung: Bash-Befehle, die Claude nicht erraten kann, Code-Style-Regeln, die vom Standard abweichen, Testanweisungen, Repository-Etikette, projektspezifische Architekturentscheidungen, Eigenheiten der Umgebung wie Pflichtvariablen und „common gotchas or behaviors that aren’t self-evident.“ Die Memory-Doku ergänzt einen Auslöser dafür, wann man überhaupt eine Zeile schreibt: Claude macht denselben Fehler ein zweites Mal, oder du tippst dieselbe Korrektur wie in der letzten Session.

Als ich im Juli meinen globalen Guide gekürzt habe, von geschätzten 12.866 Tokens auf 5.694 und dann auf 3.737, stand im Commit ein schärferes Kriterium für dieselbe Prüfung. Eine Zeile blieb dauerhaft geladen, wenn sie „a rule whose failure gives the agent no signal to go look anything up“ war. Alles andere wanderte hinter einen Lesezugriff: das Tutorial zum Task-Tool in dessen --help, die Monitoring-Beispiele in ein eigenes Dokument, die Service-Tabellen ins Runbook. Der Agent findet sie trotzdem, denn sobald er an einer Aufgabe sitzt, weiß er, dass er diese Anleitungen braucht. Nach einer Regel, von deren Existenz man nichts weiß, sucht niemand, und nur diese Art Zeile muss jedes Mal geladen werden.

Was gehört nicht in eine CLAUDE.md?

Alles, was Claude aus dem Code ableiten kann, alles, was Claude Code ohnehin injiziert, Prozeduren, die nur manchmal zählen, und die Geschichte, wie eine Regel entstanden ist.

Der ableitbare Teil steht in der Exclude-Spalte der Doku: was Claude durch Lesen des Codes herausfindet, Standardkonventionen der Sprache, Beschreibungen Datei für Datei, „information that changes frequently.“ Der /doctor-Check schlägt genau diese Kürzungen inzwischen für eine eingecheckte CLAUDE.md vor. Er will Verzeichnisstrukturen, Abhängigkeitslisten und Architekturüberblicke entfernen und behält „pitfalls, rationale, and conventions that differ from tool defaults.“

Den injizierten Teil übersieht man leicht, weil man ihn nie geschrieben hat. Claude Code legt schon einiges ins Kontextfenster: die Skill-Liste mit Beschreibungen, die Namen der MCP-Tools, Auto Memory samt eigener Anleitung dafür. Plugins können über Hooks noch mehr hinzufügen. Im Juli habe ich gemerkt, dass mein globaler Guide die komplette Skill-Liste wiederholte, die der Harness ohnehin in jede Session lädt, und dass ein Plugin-Hook rund tausend Tokens beisteuerte, die ich nicht auf dem Schirm hatte. Wer den Harness dupliziert, zahlt für denselben Kontext zweimal. Bevor du eine Zeile ergänzt, schau nach, was schon in der Session steht.

Prozeduren gehören in Skills. Die Beschreibung eines Skills steht in jeder Session im Kontext, der Inhalt wird aber nur geladen, „when you invoke them or when Claude determines they’re relevant.“ Anweisungen für einen Teil der Codebasis gehören in pfadgebundene Regeln, und die Bindung steckt im Frontmatter, nicht im Ordner: Eine Datei in .claude/rules/ ohne paths-Feld wird beim Start geladen, genau wie die CLAUDE.md selbst. Mit dem Feld wird sie erst geladen, wenn Claude eine passende Datei liest oder bearbeitet:

---
paths:
  - "src/api/**/*.ts"
---
 
- API handlers validate input with the shared schema module.

Historie gehört in ein Changelog oder in die Commit-Message. Dazu unten mehr, denn Begründung und Historie sind nicht dasselbe.

Wie groß sollte eine CLAUDE.md sein?

So klein, dass die Token-Zahl, die Claude Code selbst anzeigt, innerhalb eines Budgets bleibt, das du bewusst gesetzt hast. Das 200-Zeilen-Ziel ist ein vernünftiger Anfang, aber eine Zeilenzählung kann eine teure Datei durchwinken.

Die Begründung der Doku stimmt: Längere Dateien „consume more context and reduce adherence.“ Schwach ist die Metrik. Im Juli bestand die CLAUDE.md eines Projekts den Zeilencheck meines Audit-Skripts mit 83 Zeilen. Nach der Schätzung desselben Skripts waren es rund 12.000 Tokens; das meiste stand auf einer einzigen Zeile mit 25.782 Zeichen, und wie der nächste Abschnitt zeigt, liegt diese Schätzung zu niedrig. Ein Zeilenlimit sieht davon nichts, also habe ich das Skript auf ein Token-Budget pro Datei umgestellt: 2.500 für die meisten Projektdateien, ein eigenes, größeres Budget für den globalen Guide und eine Obergrenze für die Zeilenlänge, die eingefügte Riesenblöcke abfängt.

Imports und Kommentare ziehen in entgegengesetzte Richtungen. Imports machen eine Datei nicht billiger: Die Doku sagt klar, dass @path-Imports „help you organize a long file but don’t reduce its context cost“, weil die importierte Datei zusammen mit der importierenden geladen wird. HTML-Kommentare auf Blockebene schon: Sie werden entfernt, bevor der Inhalt in den Kontext kommt, eine Notiz für menschliche Maintainer kostet also nichts. Kommentare innerhalb von Codeblöcken bleiben erhalten.

Wie misst man die Größe einer CLAUDE.md in Tokens?

Frag Claude Code. Der Befehl /context listet jede beim Start geladene Memory-Datei mit Token-Zahl auf, und das funktioniert auch im Headless-Lauf.

Interaktiv startest du /context im Projektverzeichnis und schaust unter Memory files. Aus der Shell, im selben Verzeichnis:

claude -p "/context" | awk '/^### Memory Files/{f=1} /^### Skills/{f=0} f'

Bei mir kommt eine Tabelle mit einer Zeile pro Datei heraus: die User-CLAUDE.md, die User-Regeln, die Projekt-CLAUDE.md, jeweils mit Tokens. Lass den Filter weg und starte nur claude -p "/context", falls in deiner Ausgabe ein anderer Abschnitt folgt.

Der Aufwand lohnt sich wegen der Lücke zwischen dieser Zahl und einer selbstgebauten Schätzung. Mein Skript schätzt Tokens aus Zeichen: vier lateinische Zeichen pro Token, weniger bei Kyrillisch. Für meinen globalen Guide (424 Zeilen, 19.114 Zeichen) kommt es auf etwa 4.800 Tokens, /context zeigt 7,1k. Eine Projekt-CLAUDE.md, die das Skript auf 2.484 schätzte, knapp unter meinem Budget von 2.500, liegt laut /context bei 4,1k. Das sind zwei Dateien und gerundete Werte, und /context kann selbst auf eine lokale Schätzung zurückfallen, nimm es also als Zähler des Tools, nicht als absolute Wahrheit. Trotzdem lag meine Schätzung bei beiden Dateien um den Faktor 1,5 bis 1,7 zu niedrig. Markdown voller Backticks, Pfade und Flags ist keine Prosa, und ein fixes Verhältnis von Zeichen zu Tokens weiß das nicht.

Wenn du also ein Budget setzt, wähl Einheit und Messgerät zusammen, und nimm das Messgerät, das das Tool benutzt. Ein Budget, das mit wc -m geteilt durch vier geprüft wird, ist ein Budget für eine andere Datei.

Eine Größengrenze ist hart statt nur empfohlen. Eine CLAUDE.md oder Regeldatei, die bei Bedarf geladen wird, in einem Unterverzeichnis oder über einen paths:-Treffer, wird an einem Limit pro Datei abgeschnitten: 40.000 Zeichen bei einem Kontextfenster von 200K; bei 1M sind es 200.000 auf Opus 4.6 und Sonnet 4.6 und 150.000 auf neueren Modellen. Claude bekommt den Anfang der Datei und einen Hinweis, den Rest zu lesen, und bis das passiert, fehlen die späteren Anweisungen. Das Limit gilt ab 2.1.309; prüf die Länge mit wc -m.

Sollte man eine CLAUDE.md mit /init anfangen?

Als ersten Entwurf ja. Die Doku empfiehlt es, und ein Entwurf ist besser als eine leere Datei. Lies das Ergebnis aber als den Teil, den du als Erstes kürzt.

/init analysiert die Codebasis und schreibt Build-Befehle, Testanweisungen und die Konventionen, die es findet. Gibt es schon eine CLAUDE.md, schlägt es Verbesserungen vor, statt sie zu überschreiben. Mit gesetztem CLAUDE_CODE_NEW_INIT=1 läuft ein interaktiver Ablauf, der auch Skills und Hooks anbietet und einen Vorschlag zeigt, bevor irgendetwas geschrieben wird. Außerdem übernimmt es Regeln aus anderen Tools, die es findet, etwa .cursorrules oder Copilot-Anweisungen.

Eine Datei, die durch Lesen des Codes entsteht, besteht vor allem aus dem, was sich aus dem Code ableiten lässt, und genau das schlägt /doctor als Erstes zum Streichen vor. Behalte die Befehle, die Claude nicht hätte erraten können, lösch die Beschreibung der Verzeichnisstruktur, und lass die Datei dann so wachsen, wie es die Doku beschreibt: eine Zeile jedes Mal, wenn Claude denselben Fehler zweimal macht. Committe sie, damit die Geschichte jeder Zeile woanders lebt als in der Datei.

Sollte eine CLAUDE.md-Regel sagen, warum es sie gibt?

Ja, im Präsens, direkt neben der Regel. Der Vorfall, aus dem sie entstanden ist, gehört in den Commit, der die Zeile hinzugefügt hat. Und behandle auch die Begründung als Hypothese, denn sie kann falsch sein.

Das liegt daran, wie das Modell die Datei liest. Eine nackte Regel wird gegen alles andere im Kontext abgewogen, ohne Maßstab dafür. Eine Regel mit Begründung lässt sich auf eine Situation anwenden, an die der Autor nicht gedacht hat. Wie das zum /doctor-Prompt-Audit passt, das Historie in Anweisungsdateien als Ballast markiert, habe ich schon aufgeschrieben: Die Begründung bleibt in der Datei, die Kriegsgeschichte geht nach git, wo git blame sie findet und keine Session sie aus Versehen liest.

Mein eigener Guide zeigt, warum auch die Begründung eine Prüfung braucht. Beim Kürzen im Juli verschwand eine zählbare Regel: Hat eine Antwort mehr als fünf Bullets, zwei Emojis, eine Tabelle oder drei Überschriften, schreib sie als Prosa neu. Fünf Tage später habe ich sie zurückgeholt, mit einer datierten Notiz: Sie sei am selben Morgen weggefallen, an dem die Ausgabemenge sprang („the same morning output volume jumped“), und wegen der längeren Standardantworten von Opus 5 reiche die qualitative Fassung der Regel allein nicht mehr aus. Das war ein vernünftiger Schluss, aber keine Messung. In derselben Woche war Opus 5 zum Standardmodell geworden, und am Tag, an dem ich die Regel zurückholte, habe ich meine Sessions auch wieder auf Opus 4.8 festgelegt.

Eine Woche später kam die Messung, die ich vorbereitet hatte, mit vorab festgelegter Signatur: Wenn die Formatierungsregel wirkt, sinkt die Zahl der Bullets und Überschriften; war das Modell die Ursache, sinkt die Länge, während die Struktur bleibt. Testobjekt war das Morgen-Briefing, das meine Agenten schreiben. Die mittlere Länge stieg von 1.932 Zeichen vor dem Kürzen auf 2.935 danach und fiel in den sieben Briefings nach dem Festlegen des Modells auf 1.775. Bullets pro Briefing: 12,4 / 14,8 / 19,0. Die Zählwerte, auf die die Regel zielt, sind nie gesunken, während die Länge zurückging, sobald die Sessions wieder auf Opus 4.8 liefen. Beide Änderungen kamen gleichzeitig, also lässt sich der Effekt der Regel so nicht isolieren, und die Länge des Briefings hängt auch davon ab, wie viel über Nacht passiert ist. Das Modell ist die am besten gestützte Ursache, keine bewiesene.

Die Regel steht noch im Guide, und ihre Notiz behauptet weiterhin, dass die Regel die Länge des Modells im Zaum hält, was die Messung nicht bestätigt hat. Genau auf diesen Fehler solltest du in deiner eigenen Datei achten: Eine Begründung, die im Moment des Fixes geschrieben wurde, liest sich danach für immer wie eine ausgemachte Sache. Wenn eine Zeile wichtig ist, schreib auf, woran man sieht, dass sie wirkt, und schau einmal nach.

Wirkt IMPORTANT in einer CLAUDE.md?

Auf einer einzelnen Zeile kann Betonung helfen; über viele Zeilen verteilt bedeutet sie nichts mehr. Und auch noch so viel Betonung macht aus einer CLAUDE.md-Zeile keine Garantie.

Die Best-Practices-Seite sagt es direkt:

If Claude keeps skipping one instruction, add emphasis such as
"IMPORTANT" to that line alone. If you emphasize many lines, none of
them stands out.

Das passt zum Argument des Prompt-Audits gegen Drucksprache (Großbuchstaben, MUST, NEVER): Eine Datei voller Großbuchstaben liest sich wie eine Datei voller Alarme, und aktuelle Modelle wenden sie übereifrig an. Eine einzige betonte Zeile mit der Begründung daneben ist die Fassung, die beide Einwände übersteht.

Betonung hat auch eine Obergrenze. Laut Doku kommt der Inhalt der CLAUDE.md als User-Nachricht an, nach den eigenen Anweisungen von Claude Code statt mitten in ihnen, und Claude „tries to follow it, but there’s no guarantee of strict compliance.“ Für alles, was jedes Mal passieren muss, rät die Doku selbst zu einem Hook, der als Shell-Befehl an einem festen Punkt läuft, egal was das Modell entscheidet. Eine Regel, die halten muss, gehört in ein Gate, nicht in Prosa, und sobald sie dort ist, kann die Zeile in der CLAUDE.md zu einem Verweis schrumpfen oder ganz verschwinden.

Wie verhindert man, dass eine CLAUDE.md wieder wächst?

Notier ihre Größe jedes Mal, wenn du sie anfasst, mit dem Zähler des Tools, und rechne trotzdem damit, dass sie wächst. Wachstum kommt Zeile für Zeile, jede einzelne vernünftig, und ein Budget-Check allein meldet es erst, wenn die Datei schon groß ist.

Mein globaler Guide ist das Beispiel. Nach dem Kürzen im Juli hatte er laut meinem Skript 3.737 Tokens, unter einem Budget von 5.000, das ich am selben Tag dafür gesetzt hatte. Drei Monate später sagt dasselbe Skript 4.789: 28 Prozent mehr, und jede Ergänzung war gerechtfertigt, als sie dazukam. Der automatische Check schlägt weiterhin nicht an, weil die Datei unter Budget liegt und das Skript 5 Prozent obendrauf erlaubt, bevor es warnt. Das Wachstum zeigt sich erst, wenn man die zwei notierten Zahlen nebeneinanderlegt. Und laut /context steht die Datei schon bei 7,1k, weit über dem Budget, das sie laut Skript einhält.

Die Checks, die Drift sichtbar halten, fangen jeweils etwas anderes ab. /context nach dem Bearbeiten einer Datei, die jede Session lädt, liefert die Zahl, die du mit dem letzten Mal vergleichst. /doctor auf einer eingecheckten CLAUDE.md findet Zeilen, die inzwischen aus dem Code ableitbar sind. /doctor prompt-audit nach einem Modellwechsel findet Regeln, die für das Modell geschrieben wurden, das du verlassen hast, Widersprüche zwischen Dateien und Pfade, die es nicht mehr gibt. Claude Code warnt außerdem beim Start und in /status, wenn eine Anweisungsdatei die empfohlene Länge überschreitet oder mehrere kleine zusammen über ein gemeinsames Limit kommen. Liegt in deinem Repository zusätzlich eine AGENTS.md, prüf, welche Datei tatsächlich geladen wird: Standardmäßig liest Claude Code AGENTS.md nur als Fallback, wenn es im Arbeitsverzeichnis oder darüber keine CLAUDE.md, .claude/CLAUDE.md oder CLAUDE.local.md gibt. Deine ~/.claude/CLAUDE.md zählt für diese Prüfung nicht, und /context zeigt, welche du bekommen hast.

Keiner dieser Checks sagt dir, ob eine Zeile ihren Platz noch verdient. Sie sagen dir, dass sich die Datei verändert hat. Ob die Begründungen darin noch stimmen, ist der eine Check, den du von Hand machen musst.