CLAUDE.md auf Diät — wo der größte unsichtbare Token-Posten sitzt

Bei einem Audit über knapp zwanzig meiner eigenen Projekte bin ich auf eine CLAUDE.md mit 329 Zeilen gestoßen. Keine ungewöhnliche Größe, wie ich später feststellen musste — sie war eher Durchschnitt. Das Unangenehme ist nicht die Länge selbst. Das Unangenehme ist, dass diese Datei bei jedem Sitzungsstart vollständig in den Kontext geladen wird, dass jeder Token bei jeder Folgeantwort ins Budget zählt und dass sie unauffällig im Hintergrund läuft, während man über ganz andere Optimierungen nachdenkt. Nach dem Audit war mir klar: in den meisten Projekten ist die CLAUDE.md der größte einzelne Token-Posten überhaupt. Größer als jedes Memory, größer als jede einzelne Read-Operation, größer als das, wofür man sich normalerweise schämt. Und fast niemand sieht sie an, weil sie so unscheinbar wirkt, wie eine Textdatei nur sein kann.

Was die CLAUDE.md technisch ist

Fachlich ist sie schnell erklärt. Eine Markdown-Datei im Projekt-Root, die Claude Code bei jedem Sitzungsstart automatisch in den Prompt lädt — typischerweise als Teil des System-Präfix, also ganz am Anfang, noch vor dem eigentlichen Gesprächsverlauf. Das heißt: Jede Zeile, die in dieser Datei steht, ist in jedem Request der Sitzung Bestandteil des Prompts. Wenn die Sitzung fünfzig Requests lang ist, zahlst du jede Zeile fünfzigfach. Ein ungünstiges Multiplikator-Verhältnis, das erst sichtbar wird, wenn man es ausrechnet.

Der zweite, härtere Punkt: Es gibt nicht nur eine CLAUDE.md. Es gibt die projektspezifische Datei im Repo und daneben die globale ~/.claude/CLAUDE.md im User-Profil, die in jedem Projekt geladen wird. Beide sind technisch dieselbe Art Datei — der Unterschied liegt in der Reichweite. Die Projekt-Datei zahlt über alle Requests innerhalb dieses einen Projekts. Die globale zahlt über alle Projekte, in denen du arbeitest. Je globaler der Ort, desto teurer jede einzelne Zeile. Wer eine Tabelle mit Shopware-Core-Pfaden in die globale Datei schreibt, zahlt sie auch dann, wenn er gerade an einem WordPress-Thema oder einem .NET-Projekt arbeitet. Das ist keine Theorie, das ist die Rechnung.

Warum sie so zuverlässig wächst

Der Grund, aus dem CLAUDE.md-Dateien regelmäßig explodieren, ist kein Versäumnis. Es ist ein gut gemeinter Reflex. Sie ist der natürliche Ablageort für alles, was „wichtig genug ist, dass die KI es immer wissen soll“. Wenn dir bei einem Problem auffällt, dass der Assistent eine bestimmte Konvention nicht kennt, schreibst du sie in die CLAUDE.md. Wenn ein neues Architekturthema dazukommt, schreibst du es dort hinein. Wenn du dich einmal über einen bestimmten Fehler geärgert hast, hinterlässt du dort eine Warnung, damit das nicht noch einmal passiert. Jeder einzelne Eintrag ist nachvollziehbar. Die Summe wird teuer, ohne dass je jemand entschieden hätte, dass sie es sein soll.

Nach einigen Monaten hast du eine Datei, die gleichzeitig Code-Stil-Leitfaden, Architektur-Dokument, Workflow-Pflichtenheft, Definition-of-Done-Liste und Senior-Review-Checklist ist. Inhaltlich alles wertvoll. Organisatorisch ein Problem. Jede dieser Teile hat nämlich ihren eigenen, richtigen Platz — nur ist dieser Platz fast nie die CLAUDE.md.

Was wirklich in die CLAUDE.md gehört

Nach dem Audit habe ich drei Kategorien definiert, die den Schnitt überleben. Alles, was nicht in eine dieser drei fällt, wandert raus. Die Rolle und Erwartungshaltung. Zwei oder drei Sätze, die klarmachen, wer der Assistent ist und welches Qualitätsniveau erwartet wird. „Du bist ein erfahrener Senior-Entwickler. Ziel: ausschließlich produktionsreifer Code — kein Entwicklungsstand, keine Quick-Fixes, keine TODOs ohne BRIEF.“ Das sind drei Zeilen, die den Rahmen für alles Weitere setzen. Sie gehören in die CLAUDE.md, weil sie bei jeder Antwort wirken müssen.

Die Workflow-Pflicht-Disziplin. Das sind die wenigen Regeln, die jede Interaktion betreffen und bei deren Verletzung ein reales Problem entsteht. Brief-Workflow, Push-Freigabe, die Goldregel zur KI-Datei-Hygiene, „PHP- und WP-CLI-Befehle immer über ddev„. Das sind Punkte, bei denen die Kosten eines Fehlers so hoch sind, dass sich der Token-Preis ihrer dauerhaften Präsenz rechtfertigt. Entscheidend ist hier: knapp, nicht diskursiv. Eine Zeile pro Regel, nicht drei Absätze Begründung. Die Begründung gehört an eine andere Stelle.

Verweise auf detaillierte Regeln. Das ist die dritte und für die Token-Bilanz wichtigste Kategorie. Statt den Inhalt einer Regel selbst in die CLAUDE.md zu schreiben, steht dort nur ein Zweizeiler: „Vollständige Code-Konventionen: .ai/rules/dotnet.md.“ Der Verweis kostet in der Größenordnung dreißig Tokens. Die referenzierte Datei wird nur dann geladen, wenn sie wirklich gebraucht wird — nicht bei jedem Sitzungsstart, sondern genau dann, wenn der Assistent für die aktuelle Aufgabe eine Konvention nachschlagen muss. Das ist der Unterschied zwischen „immer bezahlt“ und „bei Bedarf bezahlt“. Er ist der eigentliche Hebel dieses Patterns.

Was raus muss — und wohin

Jetzt die Gegenbewegung. Alles, was in den nächsten Absätzen beschrieben ist, habe ich in meinen eigenen CLAUDE.md-Dateien gefunden — und rausgeworfen. Es ist nicht wertlos, es ist nur am falschen Ort.

Ausführliche Code-Stil-Beispiele. „So darf ein Kommentar aussehen, so nicht.“ Mit Vorher-Nachher-Blöcken, mit ausformulierter Begründung, vielleicht sogar mit zwei, drei Varianten. Inhaltlich nützlich. Aber bei jedem Sitzungsstart geladen? Definitiv nicht. Solche Beispiele gehören in eine Sprach-Regeldatei wie .ai/rules/dotnet.md oder .ai/rules/php.md, wo der Assistent sie nur dann liest, wenn er sie für die konkrete Aufgabe braucht. Die CLAUDE.md verweist darauf, und der Assistent macht den Rest.

Definition-of-Done-Checklisten. Eine Liste von fünfzehn Punkten, die vor jedem BRIEF-Abschluss geprüft werden müssen. Wichtig, notwendig, unstrittig. Aber wenn sie in der CLAUDE.md steht, wird sie bei jedem „Was ist der aktuelle Stand?“ genauso mitgeladen wie bei einem „Schreib einen Commit-Message-Text“. Die Checkliste gehört in eine allgemeine Regeldatei — bei mir .ai/rules/general.md — und die CLAUDE.md erwähnt in einer Zeile, dass sie existiert und wo sie liegt.

Architektur-Diagramme und Projektbeschreibungen. Sie gehören in .ai/context/architecture.md oder eine Projektbeschreibung, die der Assistent bei Bedarf liest. Nicht in den System-Präfix, wo sie bei jedem Request mitfließen. Ein ASCII-Diagramm der Schichtenarchitektur ist schnell vierzig Zeilen lang — und in neun von zehn Requests braucht der Assistent es nicht, weil er an einer Stelle arbeitet, die mit der Gesamtarchitektur nichts zu tun hat.

Beispiel-Codeblöcke, Prompt-Vorlagen und Snippets. Diese gehören in .ai/prompts/ oder in die jeweilige Regeldatei. Sie sind Nachschlagewerk, kein System-Präfix. Und Token-Optimierungs-Hinweise — das ist der leicht paradoxe Fall — gehören natürlich auch nicht in die CLAUDE.md. Eine vierzigzeilige Anleitung, wie der Assistent Tokens sparen soll, die in jedem einzelnen Sitzungsstart gelesen wird, kostet mehr Tokens, als sie je spart. Das klingt witzig, ist aber ein Fehler, den ich bei mir selbst gefunden habe. Paradox und lehrreich zugleich.

Das Verweis-Pattern in der Praxis

Das Prinzip ist einfach. Statt Inhalt ein Verweis. Nicht „unsere Coding-Konventionen lauten wie folgt: erstens immer explizite Typen, zweitens keine abgekürzten Namen, drittens…“, sondern „Coding-Konventionen: siehe .ai/rules/coding.md„. Zwei Zeilen statt vierzig. Der Assistent liest coding.md nur dann, wenn er tatsächlich Code schreibt oder prüft, für den die Konventionen relevant sind.

Das funktioniert, weil Claude Code intelligent mit Verweisen umgeht. Wenn in der CLAUDE.md steht, dass es eine Datei .ai/rules/coding.md mit ausführlichen Konventionen gibt, dann wird sie gelesen, sobald die aktuelle Aufgabe sie nahelegt. Der Assistent muss nicht alles wissen, was irgendwann einmal relevant sein könnte. Er muss wissen, wo es steht, wenn er es braucht. Genau diese Verschiebung — von „alles präsent“ zu „alles erreichbar“ — ist der Kern des Verweis-Patterns.

Der Effekt ist doppelt. Erstens spart er massiv Tokens, weil die große Menge an Regel-Inhalt nur selten geladen wird. Zweitens macht er das Projektwissen strukturierter, weil jedes Thema einen festen Ort hat, an dem es wohnt. Die CLAUDE.md wird damit zu dem, was sie sein sollte: ein Inhaltsverzeichnis mit drei, vier wirklich wichtigen Grundsätzen, nicht das Buch selbst. Wer das gleichzeitig mit einer sauberen Regelarchitektur für die KI-Zusammenarbeit aufsetzt, hat danach ein Projekt, in dem jede Regel genau einen Ort hat und kein Wort doppelt steht.

Das Audit-Beispiel: 329 auf rund 100 Zeilen

Zurück zu der Datei vom Anfang. 329 Zeilen, in jedem Sitzungsstart komplett geladen. Was stand drin? Grob: eine zweiseitige Projektbeschreibung, eine Senior-Rolle-Definition, ein Architektur-ASCII-Diagramm, ein Abschnitt zu Coding-Style mit Beispielen, eine Definition-of-Done-Liste mit fünfzehn Punkten, eine Tabelle zu Naming-Konventionen, mehrere Blöcke zu Test-Strategie, Sicherheitsregeln mit Erklärungen, ein Abschnitt zum Deployment-Workflow und am Ende — fast zärtlich — eine Erinnerung, keine Listen in den veröffentlichten Texten zu verwenden. Jeder dieser Blöcke war für sich sinnvoll. Die Summe war teuer.

Die Aufräumung war weniger Kunst als Schreibtischarbeit. Der Architektur-Block wanderte nach .ai/context/architecture.md, der Coding-Stil nach .ai/rules/coding.md, die Definition-of-Done in .ai/rules/general.md, die Test-Strategie in .ai/rules/testing.md, Sicherheit in .ai/rules/security.md. An ihre Stelle trat jeweils eine Zeile mit Verweis auf die neue Datei. Was blieb in der CLAUDE.md? Die Rolle. Ein kurzer Projekt-Kontext in zwei Sätzen. Die vier oder fünf wirklich harten Workflow-Regeln, bei denen ich nicht riskieren wollte, dass sie irgendwann doch nicht gelesen werden. Und eine kompakte Tabelle, in welcher Regeldatei welches Thema zu finden ist.

Die neue Datei hat rund hundert Zeilen. Inhaltlich ist kein einziger Gedanke verloren gegangen — er steht nur woanders. Der Assistent verhält sich genauso wie vorher, bei manchen Sachen besser, weil die Regeln in ihrer neuen Umgebung präziser formuliert werden konnten. Und in jeder einzelnen Sitzung spare ich mir in der Größenordnung zweihundert bis zweihundertfünfzig Zeilen, die zuvor systematisch mitgeladen und mitbezahlt wurden. Bei fünfzig Sitzungen pro Woche ist das kein Rechenfehler mehr, das ist eine Kategorie.

Die globale CLAUDE.md ist die teuerste

Es gibt noch eine zweite CLAUDE.md, und die ist pro Zeile der teuerste Ort überhaupt. Sie liegt im User-Profil, typischerweise unter ~/.claude/CLAUDE.md, und sie wird in jedem Projekt geladen, das du mit Claude Code öffnest. Jede Zeile dort zahlt sich über alle Projekte. Wenn du in einem Monat an fünf Projekten arbeitest, hast du jede Zeile in dieser Datei in fünf Projekten komplett bezahlt — in jeder Sitzung, in jedem Request.

Daraus folgt eine harte Regel: In die globale CLAUDE.md gehört nur, was wirklich technologie-unabhängig für alle Projekte gilt. Sprache und Sonderzeichen. Die Goldregel zur KI-Datei-Hygiene. Die Push-Freigabe-Politik. Vielleicht noch die Topic-Regel für neue GitHub-Repositories. Mehr nicht. Alles Technologie-spezifische gehört in die jeweilige Vorlage oder Projekt-CLAUDE.md. Eine Tabelle mit Shopware-Core-Pfaden in der globalen Datei ist ein Senior-Anti-Pattern: Sie kostet auch dann Tokens, wenn du gerade an einem Symfony-Projekt arbeitest, das mit Shopware überhaupt nichts zu tun hat.

Das war bei mir selbst so, und ich habe eine Weile gebraucht, um zu sehen, warum es ein Fehler ist. Der Reflex ist nachvollziehbar: Man hat mehrere Shopware-Projekte, will die Pfade nur einmal aufschreiben, und der globale Ort scheint der logische zu sein. Er ist es nicht. Er ist der teuerste. Das richtige Pattern sind Technologie-Vorlagen unter _ai-Vorlagen//, die nur in Projekten dieses Typs geladen werden. Global bleibt nur, was tatsächlich überall gilt.

Das Gegenbeispiel — was trotzdem reingehört

Damit der Eindruck nicht entsteht, die CLAUDE.md sollte möglichst leer sein: Es gibt Inhalte, bei denen der Token-Preis der Daueranwesenheit völlig gerechtfertigt ist. Die Push-Freigabe-Regel gehört dazu — „Push auf GitHub nur nach expliziter Freigabe durch den Nutzer, niemals automatisch, nie als Teil eines anderen Workflows“. Wenn die KI diese Regel nicht präsent hat, riskierst du ein versehentliches Veröffentlichen von halbfertigem Code. Das sind zwei Zeilen, und sie sind ihren Tokenpreis wert.

Genauso die Goldregel zur KI-Datei-Hygiene — .ai/, CLAUDE.md, Brief-Templates werden in keinem Repository committet. Ein Fehler an dieser Stelle ist schwer zurückzurollen und öffentlich sichtbar. Die Regel muss immer präsent sein, sie darf nicht auf einen Verweis verschoben werden, der nur bei Bedarf gelesen wird. Denn der Fall, in dem sie gebraucht wird, ist derselbe Fall, in dem sie nicht aktiv abgefragt wird — ein nebenläufiges git add -A, das die falschen Dateien mitnimmt.

Die Faustregel, die sich bei mir durchgesetzt hat: In die CLAUDE.md gehört, was bei Nichtpräsenz ein reales Problem verursacht. Nicht, was beim Lesen nützlich wäre. Der Unterschied ist entscheidend, und er ist der Grund, warum dieselbe Information manchmal rein- und manchmal rausgehört. Eine Coding-Konvention wird beim Bedarf nachgelesen — kein Problem. Eine Push-Freigabe-Regel, die der Assistent nicht kennt, führt zu einem Push, den man nicht wollte — reales Problem. Genau an dieser Grenze trennt sich Senior-Disziplin von Sammelwut.

Wie es weitergeht

Die CLAUDE.md ist der größte sichtbare Token-Hebel in einem KI-Setup, und sie ist derjenige, bei dem sich eine Stunde Aufräumarbeit am schnellsten rechnet. Der größte unsichtbare Hebel liegt aber noch davor: in der Disziplin, mit der im Alltag Dateien gelesen werden. Jede einzelne Read-Operation kann größer sein als die gesamte CLAUDE.md, und wenn sie zehnmal pro Sitzung falsch eingesetzt wird, macht keine CLAUDE.md-Diät den Unterschied wieder wett. Dazu kommt der Cache-Präfix, der bei vielen Projekten durch eine einzige flüchtige Datumszeile im Memory zerstört wird, ohne dass es irgendjemand mitbekommt. Teil 3 dieser Serie geht diesen beiden unsichtbaren Hebeln nach — und zeigt, warum ein gutes Regel-Setup allein noch keine Token-Disziplin ist.

Wer nach diesem Teil direkt weiter aufräumen will, findet den Begleitartikel zum Memory-Management auf derselben Logik-Ebene und kann parallel dazu die eigenen technischen Schulden in den Regeln durchgehen. Die Patterns greifen ineinander: Eine schlanke CLAUDE.md ohne verdichtetes Memory bringt fast nichts, und umgekehrt genauso. Die Summe ist der Punkt, nicht die einzelne Datei.