Eine riesige CLAUDE.md um 91 % schrumpfen und messen, was kaputtging

Stellen Sie sich vor, jede Session in einem Repo beginnt damit, eine CLAUDE.md mit 194.492 Zeichen zu laden. Das sind rund 48.600 Tokens, bevor Sie ein Wort getippt haben, wiederholt bei jeder Nachricht, und fast das Fünffache der Größe, ab der Claude Code vor einer Memory-Datei warnt. Stellen Sie sich außerdem vor, nichts davon ist Ballast. Es sind zwei Jahre hart erkämpftes Betriebswissen: der Migrationsbefehl, der stillschweigend einen Index löscht, der Platzindex, der ewig denselben Platz erneut versucht, die Farbfunktion, deren Ausgabesyntax zwei Kontrastprüfer nicht lesen konnten. Löschen kommt nicht infrage.

Der praktikable Weg brachte die Datei auf 17.283 Zeichen, eine Kürzung um 91 %, bei der vier Wörter verloren gingen, alle aus absichtlich entfernten Überschriften. Dann kam der Teil, den sich kaum jemand antut: messen, ob die Umstrukturierung tatsächlich funktioniert hat. Im Folgenden die vollständige Methode, samt Fehler.

Ein Hinweis, bevor Sie es ausprobieren. Die Umstrukturierung schreibt CLAUDE.md direkt um und legt Dateien unter .claude/ an, committen oder stashen Sie also vorher, dann macht git checkout alles rückgängig. Das Test-Harness startet echte headless Claude-Code-Sessions, eine pro Prompt, verbraucht API-Kontingent und manchmal mehrere Minuten pro Lauf. Probieren Sie zuerst zwei oder drei Prompts statt zwanzig. Und weil jede Codebasis anders ist, lesen Sie jeden Befehl und jedes Skript, bevor Sie es auf Ihrem System ausführen.

Warum die naheliegenden Lösungen scheitern

Veraltete Teile zu löschen klingt vernünftig, aber was veraltet ist, lässt sich nicht wissen, ohne den Code erneut zu lesen, den jede Notiz beschreibt. „Das sieht überholt aus“ ist eine Vermutung, und eine falsche Vermutung entfernt genau die Notiz, die eine künftige Debugging-Session gerettet hätte.

Zusammenfassen ist die gefährliche Option, und dazu gibt es unten einen eigenen Abschnitt.

Aufteilen mit @import hilft ebenfalls nicht. Importe werden inline expandiert, man bekommt also eine aufgeräumtere Datei bei gleichen Kontextkosten.

Das eigentliche Problem ist nicht die Größe. Es ist, dass alles für jede Aufgabe geladen wird, einschließlich der 90 %, die mit der aktuellen nichts zu tun haben. Ein CSS-Bug braucht keine Regeln zur Reihenfolge von Stripe-Webhooks.

Drei Schichten

Denken Sie in Ebenen: ein schlanker Kern, der immer geladen ist, Skills, die nachgeladen werden, wenn das Modell ihre Beschreibung für passend hält, und Referenzdateien, die nur bei Bedarf geöffnet werden. Ein vierter Mechanismus bekommt zu wenig Aufmerksamkeit. Regeldateien unter .claude/rules/ können paths:-Frontmatter tragen und werden dann geladen, sobald Sie passende Dateien anfassen. Das ist Glob-Matching, niemand muss etwas entscheiden.

Ergebnis: eine CLAUDE.md mit 17KB plus 12 Skills und 28 Referenzdateien.

Entscheiden, was geladen bleibt

Ein Skill wird geladen, wenn das Modell seine Beschreibung für passend hält. Dieses Urteil ist sehr gut, bleibt aber ein Urteil. Darum ist „Ist das wichtig?“ der falsche Test, denn wichtig war alles in der Datei. Fragen Sie stattdessen: Wenn diese Regel genau in dem Moment nicht geladen würde, in dem es darauf ankommt, wie schlimm wäre das?

Eine Styling-Falle kostet Sie etwas Zeit. Versagt eine Sicherheitsregel, liefern Sie genau den Bug aus, den sie verhindern soll. Deshalb blieben alle Sicherheitsregeln resident, alle 26, dazu 21 Architektur-Invarianten (eine Datenbank pro Mandant, ein Append-only-Ledger, ein partieller Unique-Index, der Konkurrenz um Plätze auflöst) und die Befehle, die ständig gebraucht werden und wenig kosten. Gebühren, Buchungen, Benachrichtigungen, Mobile-Apps, gerenderte Seiten, Testpraktiken und die Liste bekannter Lücken wanderten alle aus.

Regeln extrahieren, nicht umschreiben

47 Regeln in etwa 200 Zeilen zu quetschen verleitet dazu, jede als knackigen Einzeiler neu zu formulieren. Lassen Sie es. Eine Zeile aus der repo-eigenen Anleitung, geschrieben nach schlechten Erfahrungen, bringt es auf den Punkt: Eine veraltete Aussage, die ohne Prüfung bearbeitet wird, ist nicht korrigiert, sondern reingewaschen, also entweder den Code neu lesen, den die Zeile beschreibt, oder die Zeile in Ruhe lassen.

47 ungeprüfte Regeln zu paraphrasieren ergibt 47 selbstsichere Behauptungen, die niemand geprüft hat, und sie sähen frisch überarbeitet aus, was schlimmer ist, als alt auszusehen.

Der Ausweg: Ihre Regeln beginnen wahrscheinlich schon mit der Regel selbst als erstem Satz. Übernehmen Sie diesen Satz wortwörtlich und verschieben Sie die Begründung in eine Referenzdatei. Nichts wird umgeschrieben. Die Regel lebt in CLAUDE.md, und das „Warum“ liegt einen Schritt entfernt. Ein residenter Eintrag sieht so aus:

- **The card never touches this server.** A SetupIntent hands the browser a
  client secret and Stripe's own SDK collects the number, which is why no
  endpoint here takes one.

Ein Satz bleibt geladen, die übrigen 400 Wörter Begründung wandern nach hard-rules/references/security.md.

Zwei Einträge begannen mit einem Befund statt mit einer Anweisung, etwa einem Großbuchstaben, der einen anonymen Crawler in das Rate-Limit für Studiomitglieder verschob. Beide endeten außerdem mit einem Satz, der mit "The general rule" („Die allgemeine Regel“) begann, und diese Zeile wurde unverändert übernommen.

Beweisen, dass nichts verschwunden ist

Ein zeilenweiser Diff bringt nichts, weil verschobener Text neu umbricht und alles als geändert erscheint. Satzabgleich ist nur wenig besser, da Fettmarkierungen und Überschriften verschieben, wo Sätze anfangen und enden. Wörter als Multimenge zu zählen umgeht beides: Jedes Wort aus dem alten Korpus muss im neuen mindestens so oft vorkommen wie vorher.

Der letzte Lauf zeigte 4 von 31.697 Wortvorkommen als fehlend: Traps, bitten, Invariants und simplify, alle aus zwei gelöschten Abschnittsüberschriften. So sieht „fertig“ aus.

Prüfen Sie auch, dass die Prüfung fehlschlägt, wenn sie soll. Ein Skill-Verzeichnis zu löschen und erneut laufen zu lassen ergab 2.522 Verluste, darunter vierzigmal das Wort fee. Eine Prüfung, die Sie nie scheitern sahen, ist keine Prüfung.

Der Fehler

Das Build-Skript hängte verschobene Einträge an zwei bestehende Skill-Dateien an und lief während der Iterationen zweimal. Das Ergebnis waren 36 Eintragsblöcke statt 28, stille Duplizierung, genau der Fehler, vor dem jede Anleitung warnt. Entdeckt wurde er nur, weil jeder Eintrag über alle Dateien gezählt und geprüft wurde, dass er genau einmal vorkommt. Bauen Sie diese Prüfung ein. Machen Sie das Skript idempotent oder lassen Sie es Dateien neu schreiben statt anhängen.

Messen statt zitierten Zahlen vertrauen

Eine viel geteilte Zahl besagt, dass Skills in etwa 79 % der Fälle aktiviert werden, gegenüber 100 % bei einer Regel direkt in CLAUDE.md. Als Warnung ist das nützlich, aber es ist die Messung einer einzelnen Person an ihrem eigenen Setup, keine Konstante. Messen Sie Ihres:

1. Schreiben Sie 14 Prompts, die ein echter Nutzer tippen könnte, die alle Skills abdecken und als Symptome statt als Themen formuliert sind. "The Booked screen crashes with RangeError" („Der Booked-Screen stürzt mit RangeError ab“) funktioniert. "Tell me about the mobile app" („Erzähl mir von der Mobile-App“) verrät die Antwort schon selbst.
2. Führen Sie jeden in einer frischen headless Session mit claude -p aus. Die Session, die die Umstrukturierung durchgeführt hat, hat bereits jeden Skill im Kontext, sie danach zu fragen, was sie geladen hätte, sagt also nichts aus.
3. Erfassen Sie die session_id jedes Laufs über --output-format json, damit parallele Proben nicht durcheinandergeraten.
4. Öffnen Sie das Transkript dieser Session und notieren Sie, welche Skills geladen wurden.
5. Sperren Sie Edit und Write, damit die Messung das gemessene Repo nicht verändern kann.

Zwei Ereignisse zählen als Erfolg: der Aufruf des Tools Skill oder das manuelle Öffnen einer Skill-Datei durch das Modell. Kommt es durch das Lesen der Datei an das richtige Wissen, zählt das ebenfalls.

Das Ergebnis war 13 von 14, also 93 %, nicht 79 %. Und bei jedem Treffer wurde der Skill als allererster Tool-Aufruf aktiviert, bevor irgendeine Datei geöffnet wurde.

Ein Fehltreffer kostet Geld, nicht Korrektheit

Der einzige Fehltreffer lieferte trotzdem eine richtige Antwort. Er baute das Wissen nur von Grund auf neu auf: 56 Tool-Aufrufe gegenüber einem Median von 16 bei Treffern. Er las vier Quelldateien neu und durchsuchte die API mit grep, um herzuleiten, was der Skill mit einem einzigen Lesen geliefert hätte. Die residente Schicht wirkte außerdem als Sicherheitsnetz: Eine harte Regel zu Kalenderdaten reichte, um ihn trotzdem zur richtigen Referenz zu führen.

Das verändert den Blick auf das Risiko. Ein Fehltreffer heißt nicht, dass die Regel nicht angewendet wird. Er heißt eine etwa 3,5-mal teurere Session, ein weit weniger beängstigender Fehler.

Der Fehltreffer war ein Schreibfehler

Beide Mobile-Prompts zielten auf denselben Skill, aber nur der mit dem Wort "Expo" löste ihn aus. Die Skill-Beschreibung warb mit Tooling, etwa SDK-Pinning, Metro unter pnpm und der Steuerung eines Simulators. Sie enthielt aber auch Fallen auf Screen-Ebene: einen Book-Button für einen Kurs, den das Mitglied schon gebucht hat, ein abstürzendes Datumsfeld. Ein Prompt über den abstürzenden Booked-Screen passte zu keinem der beworbenen Wörter.

Beschreiben Sie also Symptome, nicht Werkzeuge. Fragen Sie, was der Nutzer tatsächlich sehen wird. Eine schwache Beschreibung listet pnpm-Einstellungen, Node-Test-Globs, tsc-Ausgabe und Docker-Image-Aufbau auf. Eine starke greift, wenn ein Build aus Gründen außerhalb des Codes bricht, zum Beispiel MODULE_NOT_FOUND, keine vorhandene Query Engine, ein aufgeblähtes Image oder ein Fix, der erst beim zweiten Versuch funktioniert.

Nachdem alle 11 Beschreibungen so umgeschrieben und sieben neue, als Symptome formulierte Prompts getestet waren, lautete das Ergebnis 7 von 7, jedes Mal beim ersten Tool-Aufruf. Der Prompt, der vorher danebenging, traf jetzt und brauchte 26 statt 56 Tool-Aufrufe.

Pfadbezogene Regeln als zweites Netz

Für alles, was einem Verzeichnis zugeordnet ist, schaltet .claude/rules/*.md das Urteil komplett aus:

---
paths:
  - "apps/mobile/**"
  - "apps/mobile-yoga/**"
---

You are in one of the two Expo member apps.

**Read `.claude/skills/mobile-apps/SKILL.md` before changing anything here.**m

Halten Sie diese als Verweise, nie als Kopien, damit das Wissen an genau einer Stelle lebt.

Ein zweiseitiger Canary-Test zeigt, ob die Pfadbindung wirklich funktioniert, denn ein Glob, der nichts trifft, verhält sich von außen genau wie ein funktionierender. Legen Sie eine Regel an, die auf ein Verzeichnis beschränkt ist und deren Text Claude anweist, eine erfundene Markierungszeichenkette auszugeben. Öffnen Sie eine Datei in diesem Verzeichnis, sollte die Markierung erscheinen. Öffnen Sie eine anderswo, sollte sie fehlen.

Den letzten Schritt lassen die meisten aus. Ohne ihn lässt sich „funktioniert“ nicht von „immer geladen“ unterscheiden, und Letzteres frisst Ihre Einsparungen unbemerkt auf. Hier verhielten sich beide Proben korrekt: 1 und 0.

Eine Warnung: Schreiben Sie Globs für Ihre echte Struktur. Die erste Vermutung war apps/api/src/fees/, doch Gebühren, Mitgliedschaften und Kurspakete lagen tatsächlich in apps/api/src/billing/. Ungeprüft hätten diese Regeln nie etwas getroffen, stillschweigend und für immer.

Was es kostet

Der Korpus wuchs um 14 %, von 194.492 auf 220.885 Zeichen. Die zusätzlichen 26.393 Zeichen sind Frontmatter, Indextabellen und Verweise, ohne neues Wissen; sie sind da, damit die richtige Datei Sie findet. Änderungen betreffen jetzt auch mehr Dateien, aus einer Änderung wurden drei. Eine Routing-Tabelle in CLAUDE.md verringert das Risiko veralteter Inhalte, beseitigt es aber nicht. Und Sie tauschen eine Datei, die immer etwas aufgebläht ist, gegen eine, die meist schlank und manchmal teuer ist. Ein Tausch, der sich zu wiederholen lohnt, solange man zugibt, dass er nicht kostenlos ist.

Fertig gepackte Version

Die Methode wurde als Claude-Code-Plugin mit zwei Skills gebündelt: Einer führt die Umstrukturierung mit eingebauten Sicherheitsregeln durch, der andere misst, ob Ihre Skills tatsächlich greifen. Installation:

/plugin marketplace add your-org/claude-md-progressive-disclosure

/plugin install progressive-claude-md

Sagen Sie Claude dann, dass Ihre CLAUDE.md zu groß ist, und bitten Sie um eine Umstrukturierung, später lassen Sie messen, ob Ihre Skills greifen.

Was immer Sie sonst mitnehmen: Messen Sie Ihre eigene Trefferquote, bevor Sie etwas bauen, um sie zu verbessern. Der Ausgangswert lag hier bei 93 %, bevor sich irgendetwas änderte, und der einzige echte Mangel war ein schlecht geschriebener Satz, nicht die Architektur.