Claude Code: Projektregeln füllen das Kontextfenster, bevor die erste Anfrage startet

Veröffentlicht am 22. Oktober • Zuerst erschienen auf sql.marcus-belz.de

Ein Subagent in Claude Code soll eine einzeilige Frage zur Dokumentation des Tools beantworten. Er bricht ab, bevor er seinen ersten Schritt macht: Prompt is too long, 347.814 Tokens gegen ein Limit von 200.000. Die Frage selbst hatte nichts geladen. Geladen hatten die Projektanweisungen, die jede Sitzung in diesem Repository beim Start erhält. Der Subagent lief auf einem Modell mit einem Kontextfenster von 200.000 Tokens, und die Anfrage, die ihn starten sollte, war bereits fast doppelt so groß wie dieses Fenster. Die Hauptsitzung, die ihn gestartet hatte, lief mit einem Fenster von einer Million Tokens. Sie brach nicht ab, sie war halb voll, bevor irgendjemand etwas eingetippt hatte.

Dieser Artikel beschreibt, wie diese Projektanweisungen im privaten DI²-Projekt so groß werden konnten. Er zeigt, was eine Messung mit /context ergab und welche drei Hebel danach angesetzt wurden. Die Mechanik und alle Zahlen beziehen sich auf Claude Code vom 15. Oktober 2026.

Die Messung wurde mit Version 2.1.145 durchgeführt, der Fehler des Subagenten stammt aus einer Sitzung mit Version 2.1.292. Die Ursache beschränkt sich jedoch nicht auf Claude Code. Sie betrifft jedes Tool, das einem Agenten beim Start Projektregeln mitgibt.

In solchen Regeldateien sammeln sich im Laufe der Zeit zwei Arten von Text an: Anweisungen für den nächsten Schritt, etwa wohin eine neue Testdatei gehört, und Belege vergangener Schritte, etwa welche Testdatei welchen Bug absichert. Dieser Artikel nennt das erste eine Regel und das zweite einen Eintrag. Beide gehören ins Repository.

In den Kontext, den jede Sitzung beim Start lädt, gehört nur die Regel, denn nur die Regel wird für den nächsten Schritt benötigt.

Voraussetzung: Die Grundlagen von Claude Code werden dort kurz erklärt, wo sie benötigt werden. Alle Tokenzahlen stammen aus /context in einer frischen Sitzung, mit Datum und Version. Wo eine Zahl nur geschätzt oder hochgerechnet ist, wird das gesagt.

Beim Start einer Sitzung liest Claude Code drei Arten von Projektanweisungen. Die CLAUDE.md des Projekts im Wurzelverzeichnis des Repositorys. Alles, was diese Datei über @-Importe hereinzieht, bis zu vier Ebenen tief. Und jede Regeldatei unter.claude/rules/, die kein paths-Frontmatter trägt. Wie ein Repository zu 30 solchen Regeldateien kommt und was in ihnen steht, ist in 27 Rule Files Instead of One CLAUDE.md beschrieben. Entscheidend ist hier, dass diese drei Punkte im Kontext liegen, bevor der erste Prompt eingetippt wird, und zwar in jeder Sitzung, unabhängig davon, ob die Aufgabe eine Zeile oder ein ganzer Arbeitstag dauert.

Wie viel das ist, zeigt der Befehl /context. Er listet jede geladene Anweisungsdatei einzeln mit einer Tokenzahl auf, die das Tool selbst ermittelt und auf Hundert gerundet. Die Zählung hängt vom Modell der Sitzung ab: Eine Messung zählte dieselben Dateien unter Haiku 4.5 spürbar niedriger als unter Opus 4.7. Der Grund ist der Tokenizer: Modelle ab Claude 4.7 verwenden einen neueren, der laut Dokumentation denselben Text mit rund 30 Prozent mehr Tokens zählt als der ältere, je nach Text etwas mehr oder weniger. Es hängt auch vom Inhalt ab, pro Datei lagen zwischen 1,9 und 2,2 Bytes auf einen Token, und für denselben Stand und dasselbe Modell ist das Ergebnis reproduzierbar. Für eine wiederholbare Messung genügt ein Start ohne die interaktive Oberfläche, mit /context als einziger Eingabe:

claude -p "/context" Enter fullscreen mode Exit fullscreen mode Im DI²-Repository ergab das am 15. Oktober 2026 mit dem Modell Opus 5.5, vor jeder Änderung, Folgendes:

Die erste Zeile ist die fixe Kostenposition, um die es in diesem Artikel geht: die Projektanweisungen, die bei jedem Start geladen werden und die das Projekt selbst steuert. Die beiden anderen Posten kommen hinzu, hängen aber nicht vom Repository ab.

Welches Fenster diese Zahl füllt, hängt vom Modell ab. Die Hauptsitzung lief auf Fable 5.1 und Opus 5. Beide haben in Claude Code ein Fenster von einer Million Tokens, und beide zählen Text wie Opus 5.5: Eine Messung mit denselben beiden Dateien ergab unter allen drei Modellen dieselben Werte.

Dort bedeuteten 487.500 Tokens eine Belegung von 49 Prozent, bevor irgendjemand etwas eingetippt hatte. Bei einem Modell mit einem 200.000-Token-Fenster sind es 244 Prozent. Nach Abzug der Reserve von 33.000 Tokens, die Claude Code in der gemessenen Version 2.1.145 für die automatische Kompaktierung freihält, bleibt dort nichts übrig, und genau auf so einem Modell lief der Subagent aus der Einleitung dieses Artikels.

Seine Fehlermeldung nannte 347.814 Tokens, nicht 487.500, weil beide nicht dasselbe zählen: Die Meldung zählt die Anfrage des Subagenten mit dem Haiku-4.5-Tokenizer, /context zählt den Start der Hauptsitzung mit dem Opus-5.5-Tokenizer. Dieser Artikel vergleicht daher nur innerhalb von /context mit demselben Modell, die Fehlermeldung belegt das Ja oder Nein. Drei Dateien trugen knapp die Hälfte: die Testregel mit 124.000 Tokens, die Regel für das Registerlayout der Anwendung mit 70.700 und die Markenregel mit 28.600.

Die Anfrage, die zu dieser Messung führte, kam am Vorabend, mit der Testregel im Editor geöffnet. Sie stammt aus dem Sitzungsprotokoll, wurde diktiert und ist hier sprachlich geglättet und aus dem Deutschen übersetzt:

Mir ist aufgefallen, dass sich das Kontextfenster ziemlich schnell füllt, wenn ich neue Features entwickle oder einen Bug behebe. Ich habe gerade die Datei testing.md geöffnet und gesehen, dass sie ziemlich lang ist. Sie vermutlich jedes Mal vollständig ins Kontextfenster geladen, wenn ein Unittest läuft, oder überhaupt, und verbraucht so einen großen Teil davon.

Kannst du bitte analysieren, wo und bei welchen Aktionen sich das Kontextfenster schnell füllt, und Vorschläge machen, wie wir damit umgehen? Enter fullscreen mode Exit fullscreen mode Gefragt war eine Analyse mit Vorschlägen, keine Messung. Der Agent antwortete mit „Ich messe zuerst, was beim Sitzungsstart tatsächlich geladen wird“, und was folgte, war eine Schätzung: die Größe der geladenen Dateien in Bytes geteilt durch 3,7, eine Faustregel für Bytes pro Token.

Die Dateien sumsammten sich an jenem Tag auf 902.576 Bytes, das Ergebnis war 243.939, gerundet 244.000 Tokens. Beobachtet statt geschätzt war nur ein Teil, nämlich welche Dateien tatsächlich geladen wurden. Das konnte der Agent in seinen eigenen Anweisungen nachschlagen.

Genau drei Regeldateien fehlten dort, die für Backend, Frontend und Security, und das sind nicht die drei eben genannten größten, sondern die drei, die zu diesem Zeitpunkt bereits an Dateipfade gebunden waren und daher beim Start nicht laden. Wie das funktioniert, zeigt der Hebel „Regeln mit Pfaden an Dateien binden“. Die Messung kam erst am Tag darauf, und sie ergab 454.900 Tokens für 909.920 Bytes, also 2,0 Bytes pro Token.

Die Faustregel hatte die Tokenzahl des deutschsprachigen Markdowns mit Tabellen, Pfaden und Codebezeichnern um fast die Hälfte unterschätzt. Alle Zahlen in diesem Artikel sind daher entweder gemessen oder ausdrücklich als Schätzung oder Hochrechnung gekennzeichnet. Wer seine eigene Fixkostenposition kennen will, misst sie.

Die 454.900 Tokens waren das Ergebnis von etwas mehr als einem halben Jahr Pflege. Die erste Regeldatei entstand Ende März 2026, und die History des Repositorys erlaubt es nachzuvollziehen, wie viele Tokens die Regeldateien am Ersten eines jeden Monats gekostet hätten. Diese Werte sind nicht gemessen, das hätte für jeden Monat eine eigene Sitzung in einem eigenen Worktree gebraucht. Sie sind aus den Dateigrößen hochgerechnet mit dem am 15. Oktober gemessenen Verhältnis von 2,0 Bytes pro Token. Ob die historischen Zustände dasselbe Verhältnis hatten, wurde nicht geprüft, pro Datei lag es am Messtag zwischen 1,9 und 2,2. Als Größenordnung reicht das, und die Tabelle beansprucht nicht mehr.

Seit Juni hat sich das Volumen fast vervierfacht, und allein zwischen September und Oktober kamen rund 140.000 Tokens hinzu, davon 72.000 in der Testregel. Hinter diesem Sprung steht eine Pflicht. Die Testregel verlangte, dass jede neue Testdatei eine Zeile in ihrem Bestandsverzeichnis ergänzt: welche Datei was prüft, warum der Test entstanden ist und welcher Kontrolllauf bewies, dass er den Bug abfängt. Jede einzelne dieser Zeilen ergibt für sich Sinn. Wer später wissen will, ob eine Funktion bereits einen Test hat, findet die Antwort dort. In der Summe machte die Pflicht aus der Regeldatei jedoch einen Eintrag, den jede Sitzung bezahlt.

Und jede dieser Regeln ging aus einem echten Bug hervor, und jede verhindert, dass derselbe Bug zurückkehrt. Ihr Wert steht nicht zur Debatte. Teuer macht sie der Zeitpunkt, zu dem sie laden, der für alle derselbe ist, nämlich immer, und die Tatsache, dass in derselben Datei zwei Arten von Text wachsen, die zu unterschiedlichen Zeitpunkten gebraucht werden.

Die Testregel des DI²-Projekts war mit 124.000 Tokens die größte Regeldatei, gemessen mit /context. Davon gingen rund 104.000 Tokens auf die Inventartabelle mit je einer Zeile pro Testdatei, am Messtag 162 Zeilen. Das sind 84 Prozent der Datei, berechnet über den Anteil der Tabelle an den Bytes, weil /context pro Datei und nicht pro Abschnitt zählt. Die Messung nach dem Auszug der Tabelle bestätigte die Rechnung: Ohne sie kostete die Datei 20.300 Tokens. Die restlichen 16 Prozent waren die eigentlichen Regeln: wohin Testdateien gehören, welche Testumgebung zu wählen ist, Mock-Muster, Zeitbudgets, Lasttests und eine Liste von Dingen, die man nicht tut. Die längste einzelne Tabellenzeile hatte 15.129 Zeichen, mehr als die gesamte Regeldatei für Functions oder die für Triggers.

Was die Inventarzeilen beantworten, ist eine Protokollfrage: Was wurde damals geprüft, warum und mit welchem Gegencheck? Was beim Schreiben eines neuen Tests gebraucht wird, ist eine Regelfrage: Wohin gehört die Datei, welche Umgebung, welches Mock-Muster? Die Zeilen sind nicht schlecht. Sie stehen am falschen Ort, und am falschen Ort werden sie bei jedem Sitzungsstart bezahlt, auch in den Sitzungen, in denen niemand einen Test schreibt.

Dasselbe Muster zeigte sich in vier weiteren Regeldateien, dort bei harmloser Größe. Die Regel für Dropdown-Menüs bestand zu 35 Prozent aus einem Inventar ihrer Nutzer, die für das Benennen von Toasts zu 33 Prozent, die für Bestätigungsdialoge zu 33 Prozent, die für Dialoge zu 28 Prozent. Absolut waren das jeweils nur einige tausend Tokens, weshalb es nie auffiel. Von ihnen unterscheidet sich die Testregel nicht im Muster, sondern nur in der Größenordnung: eine Zeile pro Testdatei, mit wachsender Testabdeckung.

Die Trennlinie verläuft entlang der Funktion eines Texts, nicht seiner Form. Dieselbe Testregel enthält eine Liste bekannter Lücken, die bewusst nicht von Tests abgedeckt sind. Sie sieht aus wie ein Inventar, ist aber eine Regel, weil sie beim nächsten Eingriff wirken soll: Wer eine dieser Stellen anfasst, soll wissen, dass kein Test ihn auffängt. Diese Liste blieb in der Regeldatei.

Die Fixkosten sind nur der Anfang. Sobald eine Sitzung arbeitet, kommen Lesezugriffe hinzu, und der größte davon ist fast halb so groß wie die Fixkosten selbst. Die folgenden Werte sind extrapoliert, nicht mit /context gemessen, weil der Befehl nur den Start zeigt. Sie beruhen auf den Dateigrößen und dem gemessenen Verhältnis von 2,0 Bytes pro Token.

Die erste Zeile ist die interessante. Benötigt wird dort eine einzige Zahl, die höchste vergebene. Die Tabelle ist absteigend sortiert, also trägt die erste Datenzeile die Antwort. Dass stattdessen das gesamte Register in den Kontext wandert, mehr als ein volles Kontextfenster, ist nicht die Schuld des Werkzeugs. Sie kommt aus der Anweisung „lies das Register und bestimme die nächste Nummer“. Der Agent tut, was dort steht.

Zusammen mit den Fixkosten erklärt das die Beobachtung vom Anfang: Start, Werkzeugleitfaden, eine große Datei, und die Sitzung ist voll, noch bevor die erste Codezeile geschrieben ist. Für Subagents ist das mehr als eine Plage. Ein Subagent erhält in der Regel die Projekthinweise, nur die eingebauten Explore- und Plan-Agents starten ohne sie.

Das Kontextfenster der Hauptsitzung erbt es nicht: Sein Fenster folgt seinem eigenen Modell, und einige der eingebauten Agents laufen auf kleineren Modellen als die Hauptsitzung. Der Agent, der Fragen zur Claude-Code-Dokumentation beantwortet, lief in Version 2.1.292 auf Haiku 4.5 mit einem 200.000-Token-Fenster. Mit 454.900 Tokens an Hinweisen konnte er in diesem Repository nicht starten, während ein Agent, der das Modell der Hauptsitzung erbt, mit einer Million Tokens noch Luft hatte.

Das Scheitern aus der Einleitung dieses Artikels war genau das, hier die Meldung im Wortlaut:

Prompt is too long · the request is ~347814 tokens (limit 200000) but this conversation is only ~227482 tokens — the rest is system prompt, tool definitions, and attachment content. A single-exchange conversation cannot be compacted; reduce attached files/tools or start with less context. Enter fullscreen mode Exit fullscreen mode Das Scheitern verhinderte sogar seine eigene Untersuchung: Der Versuch, die Laderegeln des Werkzeugs über einen Subagenten aus der Dokumentation zu klären, scheiterte genau an der Kontextgrenze, die er hätte erklären sollen.

Seit Version 2.1.293 läuft derselbe Agent auf Haiku 5.5 mit einem Fenster von einer Million Tokens. Nachgestellt am 20. Oktober 2026 mit Version 2.1.301 auf dem Stand vor der Überarbeitung: Der Agent startete, seine Anfrage hatte 485.056 Tokens, gezählt mit dem neueren Tokenizer dieses Modells, und er beantwortete die Testfrage. Kleiner geworden sind die Fixkosten dadurch nicht.

Nur die Schwelle, an der sie sichtbar werden, hat sich nach hinten verschoben.

Die zweite Zeile der Tabelle, die größte Komponente, gilt für den Messtag. Sie hat sich inzwischen von selbst erledigt, aus einem Grund, der mit dem Kontextfenster nichts zu tun hatte. Die größte Komponente hatte 7.103 Zeilen.

Im September war darauf eine Fehlerbehebung gescheitert, weil die Wechselwirkung zweier Lastläufe in keinem Diff sichtbar war, und seitdem lag die Datei unter einer Sperre für jede nichttriviale Änderung. Am selben Tag wie die Überarbeitung der Regeln begann deshalb ihre Zerlegung, verhaltensneutral und in Schnitten, jeder ein eigener Commit. Am 19. Oktober 2026 bestand sie aus einem Orchestrator mit 1.607 Zeilen und 23 Einheiten für Lastpfade, Locks, Mutationen und Dialoge, keine über 1.000 Zeilen, daneben mit 21 eigenen Testdateien.

Der Code ist dabei nicht kleiner geworden, sondern um ein Drittel gewachsen, weil jede Einheit einen Kopf, ein Interface und Imports braucht. Gefallen ist, was eine einzelne Aufgabe laden muss. Wer heute einen Lastpfad ändert, liest einen Hook mit 900 Zeilen, extrapoliert rund 22.000 Tokens, statt der ganzen Datei mit rund 155.000.

Das ist dieselbe Trennlinie wie bei den Regeln, nur im Quelltext: Gekürzt wurde nichts, geändert hat sich, was in den Kontext kommt und wann. Den Schnitt brauchte zuerst der Mensch, der eine Wechselwirkung im Diff sehen will. Der Agent, der die Datei liest, hat denselben Nutzen.

Für alle drei gilt dieselbe Regel: Keine Regel wird in der Substanz gekürzt. Jede entstand aus einem echten Fehler. Geändert wird nur, wann sie lädt und was neben ihr in derselben Datei liegt.

Claude Code kennt ein paths:-Frontmatter für Regeldateien. Eine Regel, die es trägt, lädt nicht beim Start, sondern erst dann, wenn der Agent eine Datei liest, schreibt oder bearbeitet, die auf eines der Muster passt. Für Write und Edit gilt das seit Version 2.1.288 vom 2. Oktober 2026, vorher lud nur ein Lesezugriff die Regel. Die Messung in diesem Artikel mit 2.1.145 ist davon unberührt, sie zählt nur den Start. Die Muster sind Glob-Muster, relativ zum Repository:

--- paths: - "src/components/**" - "src/app/**" - "src/lib/**" --- Enter fullscreen mode Exit fullscreen mode Im DI²-Repository nutzten am Messtag 3 von 30 Regeldateien dies, obwohl die meisten Regeln an einen Dateityp gebunden sind. Die SQL-Regeln gelten für Dateien unter db/, die Regeln für Registerlayout, Dialoge und Toasts für Komponenten. Nach der Überarbeitung trugen 24 von 30 Dateien ein paths:-Frontmatter. Das waren 264.300 Tokens und damit ein gut Drittel mehr als zwei Drittel der Gesamteinsparung.

Der Hebel hat eine Grenze. Eine gebundene Regel kommt erst mit dem Ergebnis des Toolaufrufs, weil der Aufruf auf einer passenden Datei das ist, was sie lädt. Ein Test am 15. Oktober 2026 in Claude Code 2.1.292 zeigte es: In einer Sitzung, deren Kontext die Frontend-Regel noch nicht enthielt, lud ein Lesezugriff auf eine Komponente sie erst im Ergebnis genau dieses Lesezugriffs.

Beim Bearbeiten einer bestehenden Datei ist das harmlos, weil Claude Codes Edit-Werkzeug einen vorherigen Lesezugriff auf die Datei verlangt und die Regel dann schon da ist. Ändert der Agent die Datei stattdessen über die Shell, lädt er die Regel nicht. Beim Schreiben einer neuen Datei wird der Inhalt geschrieben, bevor die Regel eintrifft.

Ein zweiter Test am 20. Oktober 2026 zeigte das in zwei Versionen: Eine Regel verlangte eine bestimmte erste Zeile für jede neue Datei unter src/. In 2.1.145 lud der Write-Aufruf die Regel gar nicht, in 2.1.301 traf sie nach dem Ergebnis des Aufrufs ein, und in beiden Fällen entstand die Datei ohne diese Zeile. Ob der Agent das danach bemerkt, hängt vom Lauf ab: In einem dritten Test mit 2.1.301 schrieb er die Datei erneut ohne die Zeile, sah die Regel mit dem Ergebnis des Aufrufs und ergänzte die Zeile mit einem zweiten Aufruf.

Darauf kann man sich nicht verlassen. Genau dann, wenn eine Konvention verhindern soll, dass etwas falsch angelegt wird, ist sie nicht da.

Der Kommentar am Kopf der Testregel, aus dem Deutschen übersetzt:

<!-- Bewusst OHNE paths:-Frontmatter. Eine gebundene Regel lädt erst mit dem Ergebnis von Read/Write/Edit auf einer passenden Datei. Für eine Datei, die noch nicht existiert, ist das zu spät. Gilt beim ANLEGEN einer Testdatei (Ort, Suffix, Mocks, Budgets). Nicht binden. --> Enter fullscreen mode Exit fullscreen mode Zwei Zeilen aus der Map:

-.claude/rules/sql.md — übergreifender SQL-Stilguide (Namensvergabe, Ausrichtung), db/** -.claude/rules/tables.md — Tabellen-DDL, Constraints, Kommentare, db/** Enter fullscreen mode Exit fullscreen mode Damit gehen zwei Stolperfallen einher. Das Frontmatter ist YAML, und Claude Code liest es zu Beginn jeder Sitzung, um zu entscheiden, welche Regeln gebunden sind. Ein Glob-Muster, das mit einem Sternchen beginnt und ohne Anführungszeichen steht, etwa - **/*.tsx, wird von YAML als Referenz auf einen Anker gelesen, nicht als Text.

Der Parser bricht ab, und Claude Code lädt die Regel danach so, als hätte sie keine Pfade:, das heißt bei jedem Start. Im normalen Betrieb meldet es das nicht. Ein Test in Claude Code 2.1.145 bestätigte es: Von drei Regeln mit Pfaden erschien genau die mit dem unbequoten Sternchen unter den beim Start geladenen Dateien, und nur claude --debug meldete den Parserfehler, ohne die Datei zu nennen.

Die Einsparung ist damit weg, und niemand merkt es. Muster im Frontmatter gehören daher immer in Anführungszeichen.

Die zweite Stolperfalle ist eine zu enge Bindung. Die Markenregel, die unter anderem Anführungszeichen und Interpunktion in benutzergerichteten Texten regelt, war zunächst an die Wörterbuchdateien und eine weitere einzelne Datei gebunden. Benutzergerichtete Texte leben jedoch auch in anderen Dateien neben diesen, und aus genau einer solchen Datei stammte der Fehler, der die Regel einmal ausgelöst hatte. Sie ist inzwischen an das gesamte Verzeichnis gebunden. Eine zu weite Bindung kostet nur etwas, wenn die Regel geladen wird. Eine zu enge lädt sie nie dort, wo sie gebraucht wird.

Der Bestandstabelle der Testregel zog in eine eigene Datei unter docs/ um, mit allen 162 Zeilen unverändert. Die Testregel selbst behielt ihre Regeln und zwei Sätze über den Bestand: wo er liegt und dass jede neue Testdatei dort eine Zeile ergänzt. Ohne diese Pflegepflicht in der Regel verwaist der Bestand. Die Regeldatei schrumpfte damit von 124.000 auf 20.300 Tokens. Das sind 103.700 eingesparte Tokens, ein gutes Viertel der Gesamtsumme.

So sieht die Trennung konkret aus. Seitdem steht in der Testregel nur noch der Verweis, hier gekürzt und aus dem Deutschen übersetzt:

## Bestand Der Bestand der Testdateien (eine Zeile pro Datei: was sie prüft, auslösender Bug, negative Kontrolle) liegt außerhalb dieser Regeldatei in docs/inventories/unit-tests.md. Lies nicht den ganzen Bestand, suche stattdessen nach dem Dateinamen. Enter fullscreen mode Exit fullscreen mode Die ausgelagerte Datei beginnt mit einem Hinweis, was sie ist und wie man sie liest. Dann folgt eine Zeile pro Testdatei, hier eine der kürzeren:

# Bestand der Unit-Test-Dateien > Aufzeichnung, keine Regel. Eine Zeile pro Testdatei: was sie prüft und warum, > oft mit auslösendem Bug und negativer Kontrolle. Die Regeln für Unit-Tests > liegen in.claude/rules/testing.md. > > Selektiv lesen, nicht im Ganzen: Der Dateiname steht am Anfang > jeder Zeile, eine Suche danach findet genau diese eine Zeile. > > Pflegepflicht: für jede neue Testdatei eine Zeile ergänzen. | Testdatei | Projekt | Tests | |----------------------------|---------|--------------------------------------------| | src/lib/topo-order.test.ts | unit | computeProcessingOrder + refineWithinLevel | | | | (levels, cycles, tie-break, isStale) | Enter fullscreen mode Exit fullscreen mode Entscheidend ist, wie die ausgelagerte Datei aufgebaut ist.

Ein bloßes Verschieben hätte das Problem nur verlagert, denn 104.000 Tokens auf einen Schlag zu lesen, sobald der Agent den Bestand braucht, wäre kaum besser. Die Datei hat daher eine Zeile pro Testdatei, und der Dateiname steht am Anfang der Zeile. Eine Suche nach einem Dateinamen findet die Zeile, ohne dass die ganze Datei gelesen wird.

Der Kopf der Datei sagt das ausdrücklich: nicht lesen, suchen.

Im Projekt DI² ist das inzwischen eine Konvention, die selbst 1.500 Tokens kostet, weil sie in einer global geladenen Regel steht. Ein neuer Bestand wird unter docs/ angelegt, nie als Abschnitt einer Regeldatei. Die Regel nennt den Ort und die Pflegepflicht in einem Satz. Und große Dateien werden nicht per @ import in CLAUDE.md gezogen, denn was es importiert, lädt bei jedem Start mit. Eine große Datei auf mehrere Imports aufzuteilen spart daher nichts.

Der dritte Hebel ändert keine Regel, sondern Anweisungen. Der Skill, der einen neuen Bug anlegt, las das Bugregister vollständig, um die nächste Nummer zu finden. Jetzt liest er höchstens die ersten 30 Zeilen, denn das Register ist absteigend sortiert und die erste Datenzeile trägt die höchste Nummer. Zwei weitere Stellen, die das Register nach einem bestimmten Eintrag durchsuchten, suchen nun mit grep statt zu lesen. Derselbe Gedanke führte zu zwei Änderungen an CLAUDE.md: Die Roadmap-Tabelle der Produktbeschreibung, 89 Prozent dieser Datei, zog in eine eigene Datei, und der Feature-Index wird nicht mehr per Import hereingezogen. Der Agent liest beides, wenn er es braucht, und die Skills, die es brauchen, sagen das ausdrücklich. Zusammen 25.500 Tokens.

Nicht jedes vollständige Lesen ist Verschwendung. Die Durchsicht aller Skills fand drei, die bleiben bleiben. Den Feature-Index lesen acht Skills vollständig, weil der Kontext dort tatsächlich gebraucht wird. Die Produktbeschreibung ist nach der Überarbeitung klein. Der Testfall-Index wird dort angehängt, wo er gelesen wird. Der Hebel greift bei Anweisungen der Form „lies die Datei, um einen einzelnen Wert zu finden“. Bei einer Datei, deren gesamter Inhalt die Entscheidung trägt, greift er nicht.

Die Überarbeitung lief in fünf Schritten, jeder ein eigener Commit und einzeln revertierbar. Zuerst kamen die rein verschiebenden, dann die Bindung an Pfade als der riskanteste Schritt, zuletzt die Absicherung. Es gab keine ausformulierten Umsetzungsanfrage. Der Agent hatte aus der Analyse eine Spezifikation vorgeschlagen und dazu Fragen gestellt, die der Betreuer durch Auswahl beantwortete. Fragen und Antworten stehen im Transkript wörtlich, hier aus dem Deutschen übersetzt:

Wie weit soll ich die Kontext-Überarbeitung jetzt treiben? -> Alles, inklusive des Scoping-Durchgangs Ein Feature für alle vier Hebel oder aufteilen? -> Ein Feature, vier Bausteine Register- und Layout-Regeln scopen? Das ist der große Posten, aber der riskante. -> Die Entscheidung an /architecture delegieren Die PRD-Roadmap und den Feature-Index von den Always-Includes der CLAUDE.md abkoppeln? -> Ja, mit einem schlanken Rest Soll eine Absicherung gegen Rückfall entstehen? Ohne sie wächst die nächste Regeldatei unbemerkt wieder zu einer Ablagentextwüste. -> Ja, als CI-Guard mit Baseline Enter fullscreen mode Exit fullscreen mode Die vier Hebel in dieser Zählung sind die drei dieses Artikels und der Guard, den dieser Artikel gesondert als Absicherung behandelt.

Die Umsetzungsanfrage danach bestand aus zwei Wörtern: „sofort umsetzen“. Während der Umsetzung kam, nachdem die Lade-Semantik geklärt war, noch eine letzte Frage: ob auch die Register- und Layout-Regeln gebunden werden sollten, nach damaliger Schätzung zusammen 115.000 Tokens, darunter die Registerregel mit gemessenen 70.700. Die Antwort war ja, und das wurde der größte Posten der Einsparung.

Die Akzeptanzkriterien, darunter die Messung mit /context in einer frischen Sitzung und der Subagent, der neu starten muss, hatte der Agent in die Spezifikation geschrieben. Der Betreuer übernahm sie mit der Spezifikation, statt sie zu formulieren, schreibt kein Node und hätte das Prüfskript nicht schreiben können. Die Überarbeitung der Regeldateien, das Skript und die Entscheidung, welche Regeln global bleiben, arbeitete der Agent aus.

Vom Betreuer kamen die Problembeschreibung, die Antworten oben und am Ende die Messung selbst: /context und der Subagent-Test in einer frischen Sitzung, von Hand gestartet, denn eine laufende Sitzung kann ihren eigenen Startzustand nicht neu messen. Entscheidend war, dass die Messung von Anfang an als Akzeptanz in der Spezifikation stand und nicht nach dem Ergebnis festgelegt wurde.

Die Messung wurde mit dem Werkzeug selbst genommen. Beide Zustände lagen als separate Git-Worktrees vor, /context war die erste und einzige Eingabe einer neuen Sitzung ohne die interaktive Oberfläche, Claude Code 2.1.145 mit dem Modell Opus 5.5, beide Läufe am 15. Oktober 2026, Minuten auseinander auf derselben Maschine. Ein Gegencheck in einer interaktiven Sitzung zählte Datei für Datei dasselbe.

Der zweite Beweis ist ein Ja oder Nein. Derselbe Subagent, der zuvor abgebrochen war, startete nach der Überarbeitung in einer frischen Sitzung mit 66.887 Tokens Kontext und beantwortete die Testfrage richtig.

Das Wachstum aus dem Abschnitt „Mit der Arbeit gewachsen“ kam von einer Pflegepflicht ohne Obergrenze. Ohne Obergrenze wäre die Einsparung ein Schnappschuss, und der nächste gut gemeinte Bestand hätte in einem halben Jahr dieselbe Zahl erneut erzeugt. Mit der Überarbeitung kam daher ein Prüfskript in die CI, ohne Abhängigkeiten, als blockierender Schritt. Es rechnet mit Bytes geteilt durch 2.0, dem gemessenen Verhältnis, und lag am Stand des 15. Oktober damit etwa zwei Prozent neben /context. Das ist eine Näherung mit dem Verhältnis eines Tages, keine Messung. Gemessen wird weiter mit /context, der Guard zieht nur die Linie, und das Budget von 80.000 Tokens lässt gegenüber den gemessenen 64.700 Raum für den Fehler der Näherung. Es prüft sieben Dinge:

Die Wache prueft Dateien, nicht Verhalten. Ob ein Skill tatsaechlich eine gebundene Regel liest, bevor er prueft, kann sie nicht sehen. Den Review-Skill ohne SQL-Regeln aus dem Abschnitt davor hat die Qualitaetssicherung gefunden, nicht die Wache.

Der erste Lauf brachte sofort einen Befund, den niemand erwartet hatte. Der Check auf verwaiste Inventory-Eintraege fand fuenf Testdateien ohne Inventory-Zeile, alle aus der Zeit vor der Ueberarbeitung. Die Pflicht „eine Zeile fuer jede neue Testdatei“ hatte das Inventory so auf 104.000 Tokens wachsen lassen und war dennoch nicht eingehalten worden. Eine Pflicht, die niemand prueft, haelt daher weder das Inventory vollstaendig noch die Regeldatei klein.

Die Zerlegung der groessten Komponente endete mit einer zweiten Wache nach demselben Muster, diesmal fuer Quelldateien. Sie prueft jede Datei unter src/ auf hoechstens 1.000 Zeilen, Tests eingerechnet, mit einer Baseline fuer den Altbestand, die nur schrumpfen darf, und einer Toleranz von zwei Prozent, damit ein Bugfix an einer alten Datei durchgeht und ein Feature nicht. Ihr erster Lauf fand 33 Dateien ueber der Grenze, erwartet waren sechs. Die Regel dazu sitzt nicht in einer Datei, die bei jedem Start geladen wird, sondern in der Regel fuer Komponenten, Seiten und Hooks, die an genau diese Pfade gebunden ist. Sie gelangt damit nur in die Sitzungen, in denen eine solche Datei wachsen kann. Fuer alle anderen Dateien meldet sich die Wache von selbst.

Regeln so zu kuerzen, bis sie nichts mehr sagen, ist es nicht. Nach der Ueberarbeitung blieben 20.300 Tokens reine Regelprosa in der Testregel, und das Abnahmekriterium hatte „hoechstens 12.000“ gefordert. Diese Zahl stammte aus der Faustregel des Vortags, mit demselben Fehler wie alle Schaetzungen. Die Zahl wurde korrigiert, nicht die Regel. Was eine Regel sagt, hat sie sich durch einen Bug verdient, und ein Tokenbudget ist kein Grund, das wieder zu vergessen.

Eine Produktkritik ist es ebenfalls nicht. Der Bindungsmechanismus existierte die ganze Zeit, er war dokumentiert, und er hat nachweislich funktioniert. Dass 3 von 30 Dateien ihn nutzten, ist eine Frage der Pflegetreue. Dass ein Agent eine Regel in seinem Kontext hat, wenn er sie braucht, ist zudem die Voraussetzung dafuer, dass er die Regel ueberhaupt befolgt.

Und am wenigsten ist es ein Check, der mit derselben falschen Annahme rechnet wie das, was er prueft. Die Wache aus dem Abschnitt „Ohne Guardrail kommt das Wachstum zurueck“, das Pruefskript in CI, wurde zunaechst nicht mit den 3,7 der ersten Schaetzung kalibriert, sondern mit einer zweiten falschen Zahl: Die Fehlermeldung des gescheiterten Subagenten nannte neben den 347.814 Tokens der gesamten Anfrage rund 227.000 Tokens fuer die Konversation, und die Dateigroesse geteilt durch diese Zahl ergab 4,0 Bytes pro Token. Nur zaehlte die Nachricht nicht dasselbe wie /context.

Sie stammte von einem anderen Modell und bezog sich auf einen Teil der Anfrage. Gemessen sind es 2,0. Qualitaetssicherung und Code-Review rechneten mit demselben Faktor, bestaetigten „33.000 von 45.000 Tokens“ und hielten das Ziel fuer erreicht.

Richtig waren 64.700 von 80.000. Das kam erst ans Licht, als /context in einer frischen Sitzung lief. Zwei Checks, die Gruen melden, beweisen nichts, wenn sie dieselbe Zahl aus derselben Quelle nehmen.

Warum ein gruenes Testergebnis auf genau diese Weise genau den Bug bestaetigen kann, den es finden sollte, zeigt Der gruene Test, der nichts beweist.

Eine Einschraenkung gehoert hierher. Die Analyse, die diesen Artikel ausgeloest hat, lief in derselben Sitzung, deren Kontextfenster sie untersuchte. Sich selbst zu messen kostet Kontext.

Wie misst man, was eine Claude-Code-Sitzung beim Start laedt?

Mit dem Befehl /context als erste Eingabe einer neuen Sitzung. Er listet jede geladene Instruktionsdatei einzeln mit ihrer Tokenzahl auf. Fuer eine wiederholbare Messung genuegt claude -p "/context" ohne die interaktive Oberflaeche, geprueft mit Claude Code 2.1.145. In Git Bash muss dafuer die Pfadkonvertierung ausgeschaltet sein ( MSYS_NO_PATHCONV=1 ), sonst erreicht /context das Modell als Dateipfad. Die frische Sitzung ist entscheidend: Eine laufende Sitzung oder ein Subagent traegt den Instruktionszustand von seinem eigenen Start mit sich.

Reicht es nicht, Zeichen zu zaehlen und durch vier zu teilen?

Fuer englische Prosa ist das ungefaehr richtig, fuer deutschsprachiges Markdown mit Tabellen, Pfaden und Code-Bezeichnern ist es das nicht. Gemessen lagen die Regeldateien bei 2,0 Bytes pro Token, je Datei zwischen 1,9 und 2,2. Eine Schaetzung mit dem Faktor 3,7 kam fast halb so gross zu niedrig herein, und eine Wache, die mit 4,0 rechnete, halbierte alle Ergebnisse, ohne dass jemand es bemerkte. Hinzu kommt, dass die Zahl vom Modell abhaengt: Der neuere Tokenizer ab Claude 4.7 zaehlt denselben Text mit rund 30 Prozent mehr Tokens als der aeltere, je nach Text etwas mehr oder weniger.

Laedt eine Regel mit paths: rechtzeitig, wenn der Agent eine neue Datei anlegt?

Nein. Die Regel kommt fruehestens mit dem Ergebnis des Toolaufrufs an, fuer eine neue Datei ist der Inhalt bis dahin schon geschrieben, und vor Version 2.1.288 lud ein Write-Aufruf sie ueberhaupt nicht. Ob der Agent die Datei dann von selbst nachzieht, haengt vom Lauf ab. Beim Bearbeiten einer bestehenden Datei gibt es keine Luecke, weil das Edit-Tool ein vorheriges Lesen verlangt. Fuer Regeln, die beim Anlegen wirken muessen, bleiben drei Wege: sie global ohne paths: lassen, sie in dem anlegenden Skill vorher explizit lesen und eine Karte in CLAUDE.md pflegen, damit der Agent weiss, dass die Regel existiert. Geprueft in Claude Code 2.1.145, 2.1.292 und 2.1.301.

Weil jede Regel aus einem Bug stammt, der ohne sie zurueckkommt. Die Testregel des DI²-Projekts behielt nach der Ueberarbeitung 20.300 Tokens reine Regelprosa, obwohl das Ziel „hoechstens 12.000“ lautete: Die Zielzahl stammte aus einer falschen Schaetzung, und korrigiert wurde die Zahl. Die Einsparungen kommen daher, wann eine Regel laedt, und daraus, dass sie nicht mehr mit Ablauftext vermischt wird, nicht aus ihrem Inhalt. Wer dennoch kuerzen will, prueft zuerst, ob ein Abschnitt eine fruehere Entscheidung belegt. Dann ist er Ablauf und kann ausziehen.

Sieht der Agent eine gebundene Regel noch, wenn er keine passende Datei anfasst?

Nur wenn er weiss, dass die Regel existiert. Eine Frage zur SQL-Benennungskonvention im Gespraech laedt die SQL-Regel nicht, weil keine Datei unter db/ gelesen wird. Dasselbe gilt fuer ein Review, das den Diff ueber git diff liest statt ueber eine Datei. Deshalb haelt CLAUDE.md eine Karte mit einer Zeile pro gebundener Regel, und Skills, die ohne Dateizugriff pruefen, lesen die relevanten Regeln explizit. Sonst waere Bindung ein unbemerkter Verlust von Konventionen.