Das Kontextfenster ist voll, bevor der erste Prompt da ist — wenn Projekt-Regeln in Claude Code zu Fixkosten jeder Sitzung werden

Ein Subagent in Claude Code soll eine einzeilige Frage zur Dokumentation des Werkzeugs beantworten. Er bricht ab, bevor er den ersten Schritt tut: Prompt is too long, 347.814 Token bei einem Limit von 200.000. Die Frage selbst hatte nichts geladen. Geladen waren die Projekt-Instruktionen, die jede Sitzung in diesem Repository beim Start bekommt. Der Subagent lief auf einem Modell mit einem Kontextfenster von 200.000 Token, und schon die Anfrage, die ihn starten sollte, war fast doppelt so groß wie dieses Fenster. Die Hauptsitzung, die ihn gestartet hatte, lief mit einem Fenster von einer Million Token. Sie brach nicht ab, sie war zur Hälfte voll, bevor jemand etwas getippt hatte.

Dieser Artikel beschreibt, wie diese Projekt-Instruktionen im privaten DI²-Projekt so umfangreich werden konnten. Er zeigt, was eine Messung mit /context ergab und was drei Hebel gebracht haben, die danach umgesetzt wurden. Die Mechanik und alle Zahlen gelten für Claude Code am 15. Oktober 2026. Gemessen wurde mit der Version 2.1.145, der Fehlschlag des Subagenten stammt aus einer Sitzung mit der Version 2.1.292. Die Ursache ist aber nicht auf Claude Code beschränkt. Sie betrifft jedes Werkzeug, das einem Agenten beim Start Projekt-Regeln mitgibt. In solchen Regel-Dateien sammeln sich mit der Zeit zwei Arten von Text: Anweisungen für den nächsten Schritt, etwa wohin eine neue Testdatei gehört, und Belege für vergangene Schritte, etwa welche Testdatei welchen Fehler absichert. Der Artikel nennt das erste Regel und das zweite Protokoll. Beides gehört ins Repository. In den Kontext, den jede Sitzung beim Start lädt, gehört nur die Regel, denn nur sie wird beim nächsten Schritt gebraucht.

Das Wichtigste vorab:

• Projekt-Regeln sind Fixkosten jeder Sitzung: Alles, was in der Projekt-Anweisung CLAUDE.md, ihren Imports und den Regel-Dateien ohne Datei-Bezug steht, lädt Claude Code beim Start, bevor der erste Prompt da ist. Im DI²-Repository waren das am 15. Oktober 2026 gemessene 454.900 Token, knapp die Hälfte eines Kontextfensters von einer Million Token und mehr als das Doppelte eines Fensters von 200.000.
• Die Trennlinie ist Regel gegen Protokoll, nicht lang gegen kurz: Eine Regel sagt, wohin eine Datei gehört und welches Muster sie verwendet, ein Protokoll belegt, was damals geprüft wurde und warum. Die größte Regel-Datei bestand nach gut sechs Monaten Pflege zu 84 Prozent aus einer Inventur-Tabelle mit einer Zeile pro Testdatei. Beim Schreiben eines Tests braucht sie niemand, bezahlt hat sie trotzdem jede Sitzung beim Start.
• Drei Hebel, vorher und nachher gemessen: Regeln mit Datei-Bezug an Pfade binden, Inventuren in eine Nachbardatei verschieben und Anweisungen so formulieren, dass der Agent nachschlägt, statt alles vorzuladen. Danach lagen die Projekt-Instruktionen bei 64.700 statt 454.900 Token, und der Subagent, der vorher abbrach, startete wieder.
• Das Binden an Pfade hat eine Grenze: Eine gebundene Regel kommt erst mit dem Ergebnis des Werkzeug-Aufrufs an, und für eine Datei, die gerade neu entsteht, ist das zu spät. Dagegen helfen drei Netze, und ohne eine Leitplanke in der CI kommt das Wachstum zurück.

Voraussetzung: Claude-Code-Grundbegriffe werden kurz erklärt, wo sie gebraucht werden. Alle Token-Zahlen stammen aus /context in einer frischen Sitzung, mit Datum und Version. Wo eine Zahl nur geschätzt oder hochgerechnet ist, steht das dabei.

Inhalt

• Was eine Sitzung kostet, bevor jemand tippt
• Gewachsen mit der Arbeit
• Regel oder Protokoll: der 84-Prozent-Fall
• Was beim Arbeiten dazukommt
• Drei Hebel, und was sie kosten
• Vorher und nachher: 454.900 zu 64.700 Token
• Ohne Leitplanke kommt das Wachstum zurück
• Was nicht die Lösung ist
• Zusammenfassung
• FAQ
• Verwandte Artikel

Was eine Sitzung kostet, bevor jemand tippt

Claude Code liest beim Start einer Sitzung drei Arten von Projekt-Instruktionen. Die Projekt-Anweisung CLAUDE.md im Wurzelverzeichnis des Repositorys. Alles, was diese Datei per @-Import einbindet, bis zu vier Ebenen tief. Und jede Regel-Datei unter .claude/rules/, die kein paths:-Frontmatter trägt. Wie ein Repository zu 30 solchen Regel-Dateien kommt und was in ihnen steht, beschreibt 27 Regel-Dateien statt einer CLAUDE.md. Hier geht es darum, dass diese drei Posten im Kontext liegen, bevor der erste Prompt getippt ist, und zwar bei jeder Sitzung, unabhängig davon, ob die Aufgabe eine Zeile oder einen Tag braucht.

Wie viel das ist, zeigt der Befehl /context. Er listet jede geladene Instruktions-Datei einzeln mit einer Token-Zahl, die das Werkzeug selbst ermittelt, auf hundert Token gerundet. Die Zahl hängt vom Modell der Sitzung ab: Dieselben Dateien zählte eine Probe unter Haiku 4.5 deutlich niedriger als unter Opus 4.7. Der Grund ist der Tokenizer: Die Modelle ab Claude 4.7 verwenden einen neueren, der laut Dokumentation denselben Text mit rund 30 Prozent mehr Token zählt als der ältere, je nach Text etwas mehr oder weniger. Sie hängt außerdem vom Inhalt ab, je Datei lagen zwischen 1,9 und 2,2 Bytes auf einem Token, und sie ist für denselben Stand und dasselbe Modell reproduzierbar. Für eine wiederholbare Messung genügt ein Start ohne interaktive Oberfläche, bei dem /context die einzige Eingabe ist:

claude -p "/context"

claude -p "/context"

Im DI²-Repository ergab das am 15. Oktober 2026 mit dem Modell Opus 5.5, vor jeder Änderung:

Die erste Zeile sind die Fixkosten, von denen dieser Artikel spricht: die Projekt-Instruktionen, die bei jedem Start laden und die das Projekt selbst in der Hand hat. Die beiden anderen Posten kommen dazu, hängen aber nicht vom Repository ab.

Welches Fenster diese Zahl füllt, hängt vom Modell ab. Die Hauptsitzung lief mit Fable 5.1 und Opus 5. Beide haben in Claude Code ein Fenster von einer Million Token, und beide zählen Text wie Opus 5.5: Eine Probe mit denselben zwei Dateien ergab unter allen drei Modellen dieselben Werte. Dort waren mit 487.500 Token 49 Prozent belegt, bevor jemand etwas getippt hatte. Für ein Modell mit einem Fenster von 200.000 Token sind es 244 Prozent. Nach Abzug der Reserve von 33.000 Token, die Claude Code in der gemessenen Version 2.1.145 für die automatische Zusammenfassung freihält, bleibt dort nichts übrig, und auf so einem Modell lief der Subagent aus dem Einstieg dieses Artikels. Seine Fehlermeldung nannte 347.814 Token, nicht 487.500, denn beide zählen nicht dasselbe: Die Meldung zählt die Anfrage des Subagenten mit dem Tokenizer von Haiku 4.5, /context den Start der Hauptsitzung mit dem von Opus 5.5. Verglichen wird in diesem Artikel deshalb nur innerhalb von /context mit demselben Modell, die Fehlermeldung belegt das Ja oder Nein. Drei Dateien trugen knapp die Hälfte: die Test-Regel mit 124.000 Token, die Regel für das Register-Layout der Anwendung mit 70.700 und die Marken-Regel mit 28.600.

Der Auftrag, der zu dieser Messung führte, stand am Abend davor, mit der geöffneten Test-Regel im Editor. Er stammt aus dem Sitzungs-Transkript, war diktiert und ist hier sprachlich geglättet:

Mir ist aufgefallen, dass das Kontextfenster ziemlich schnell voll wird,
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.
Wahrscheinlich wird sie komplett in das Kontextfenster geladen, wenn ein
Unit-Test ausgeführt wird, oder wann auch immer, und verbraucht damit
sehr viel davon. Kannst du bitte analysieren, wo und bei welchen Aktionen
das Kontextfenster schnell voll wird, und Vorschläge machen, wie wir
damit umgehen?

Mir ist aufgefallen, dass das Kontextfenster ziemlich schnell voll wird,
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.
Wahrscheinlich wird sie komplett in das Kontextfenster geladen, wenn ein
Unit-Test ausgeführt wird, oder wann auch immer, und verbraucht damit
sehr viel davon. Kannst du bitte analysieren, wo und bei welchen Aktionen
das Kontextfenster schnell voll wird, und Vorschläge machen, wie wir
damit umgehen?

Verlangt war eine Analyse mit Vorschlägen, keine Messung. Der Agent antwortete mit „Ich messe zuerst, was tatsächlich beim Session-Start geladen wird“, und was dann kam, war eine Schätzung: die Größe der geladenen Dateien in Bytes geteilt durch 3,7, einer Faustformel für Bytes je Token. Die Dateien hatten an diesem Tag zusammen 902.576 Bytes, das Ergebnis lautete 243.939, gerundet 244.000 Token. Beobachtet statt geschätzt war nur ein Teil, nämlich welche Dateien tatsächlich geladen waren. Das konnte der Agent in seinen eigenen Instruktionen nachsehen. Dort fehlten genau drei Regel-Dateien, die für Backend, Frontend und Sicherheit, und das sind nicht die drei größten, die gerade genannt wurden, sondern die drei, die damals schon an Dateipfade gebunden waren und deshalb beim Start nicht laden. Wie das funktioniert, zeigt der Hebel „Regeln mit paths: an Dateien binden“. Gemessen wurde erst am Tag darauf, und die Messung ergab 454.900 Token für 909.920 Bytes, also 2,0 Bytes pro Token. Die Faustformel hatte die Token-Zahl von deutschsprachigem Markdown mit Tabellen, Pfaden und Code-Bezeichnern um fast die Hälfte unterschätzt. Alle Zahlen in diesem Artikel sind deshalb entweder gemessen oder ausdrücklich als Schätzung oder Hochrechnung gekennzeichnet. Wer seine eigenen Fixkosten kennen will, misst sie.

Gewachsen mit der Arbeit

Die 454.900 Token waren das Ergebnis von gut sechs Monaten Pflege. Die erste Regel-Datei entstand Ende März 2026, und über die Historie des Repositorys lässt sich nachvollziehen, wie viele Token die Regel-Dateien am Ersten jedes Monats gekostet hätten. Gemessen sind diese Werte nicht, das hätte je 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 Stände dasselbe Verhältnis hatten, ist nicht geprüft, je Datei lag es am Messtag zwischen 1,9 und 2,2. Als Größenordnung reicht das, mehr behauptet die Tabelle nicht.

Seit Juni hat sich der Umfang knapp vervierfacht, und zwischen September und Oktober allein kamen rund 140.000 Token dazu, davon 72.000 in der Test-Regel. Hinter diesem Sprung steht eine Pflegepflicht. Die Test-Regel verlangte, bei jeder neuen Testdatei eine Zeile in ihrer Inventur zu ergänzen: welche Datei was prüft, warum der Test entstanden ist und welche Gegenprobe belegt hat, dass er trifft. Jede einzelne dieser Zeilen ist sinnvoll. Wer später wissen will, ob es für eine Funktion schon einen Test gibt, findet dort die Antwort. In der Summe hat die Pflicht die Regel-Datei aber zu einem Protokoll gemacht, das jede Sitzung mitbezahlt.

Dabei ist jede dieser Regeln aus einem echten Fehler entstanden, und jede verhindert, dass derselbe Fehler wiederkommt. Ihr Wert steht nicht in Frage. Teuer macht sie der Ladezeitpunkt, der für alle gleich ist, nämlich immer, und der Umstand, dass in derselben Datei zwei Arten von Text wachsen, die zu verschiedenen Zeitpunkten gebraucht werden.

Regel oder Protokoll: der 84-Prozent-Fall

Die Test-Regel des DI²-Projekts war mit 124.000 Token die größte Regel-Datei, gemessen mit /context. Davon entfielen rund 104.000 Token auf die Inventur-Tabelle mit einer Zeile pro Testdatei, 162 Zeilen am Tag der Messung. Das sind 84 Prozent der Datei, gerechnet über den Anteil der Tabelle an den Bytes, denn /context zählt je Datei, nicht je Abschnitt. Die Messung nach dem Auszug der Tabelle bestätigte die Rechnung: Ohne sie kostete die Datei 20.300 Token. Die restlichen 16 Prozent waren die eigentlichen Regeln: Ablage der Testdateien, Wahl der Testumgebung, 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 ganze Regel-Datei für Funktionen oder die für Trigger.

Was die Inventur-Zeilen beantworten, ist eine Protokoll-Frage: Was wurde damals geprüft, warum, und mit welcher Gegenprobe? Was beim Schreiben eines neuen Tests gebraucht wird, ist eine Regel-Frage: Wohin gehört die Datei, welche Umgebung, welches Mock-Muster? Die Zeilen sind nicht schlecht. Sie sind 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 fand sich in vier weiteren Regel-Dateien, dort in harmloser Größe. Die Regel für Dropdown-Menüs bestand zu 35 Prozent aus einer Inventur ihrer Verwender, die für die Benennung von Toasts zu 33 Prozent, die für Bestätigungs-Dialoge zu 33 Prozent, die für Dialoge zu 28 Prozent. Absolut waren das je nur ein paar tausend Token, und deshalb ist es nie aufgefallen. Die Test-Regel unterscheidet sich von ihnen nicht im Muster, sondern nur in der Skalierung: eine Zeile pro Testdatei, bei wachsender Testabdeckung.

Die Trennlinie verläuft dabei an der Funktion eines Textes, nicht an seiner Form. In derselben Test-Regel steht eine Liste bekannter Lücken, die bewusst nicht durch Tests abgesichert sind. Sie sieht aus wie eine Inventur, ist aber eine Regel, denn sie soll beim nächsten Eingriff wirken: Wer eine dieser Stellen anfasst, soll wissen, dass kein Test ihn auffängt. Diese Liste blieb in der Regel-Datei.

Was beim Arbeiten dazukommt

Die Fixkosten sind nur der Anfang. Sobald eine Sitzung arbeitet, kommen Lesevorgänge dazu, und der größte davon ist fast halb so groß wie die Fixkosten selbst. Die folgenden Werte sind hochgerechnet, 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. Gebraucht wird dort eine einzige Zahl, die höchste vergebene Nummer. Die Tabelle ist absteigend sortiert, die erste Datenzeile trägt also die Antwort. Dass stattdessen das ganze Register in den Kontext wandert, mehr als ein komplettes Kontextfenster, liegt nicht am Werkzeug. Es liegt an der Anweisung „lies das Register und ermittle die nächste Nummer“. Der Agent tut, was dort steht.

Zusammen mit den Fixkosten erklärt das die Beobachtung, die am Anfang stand: Start, Werkzeug-Anleitung, eine große Datei, und die Sitzung ist voll, bevor die erste Zeile Code geschrieben ist. Für Subagenten ist es mehr als ein Ärgernis. Ein Subagent bekommt die Projekt-Instruktionen in der Regel mit, nur die eingebauten Agenten Explore und Plan starten ohne sie. Das Kontextfenster der Hauptsitzung erbt er nicht: Sein Fenster richtet sich nach seinem eigenen Modell, und einige der eingebauten Agenten laufen auf kleineren Modellen als die Hauptsitzung. Der Agent, der Fragen zur Dokumentation von Claude Code beantwortet, lief in der Version 2.1.292 auf Haiku 4.5 mit einem Fenster von 200.000 Token. Bei 454.900 Token Instruktionen konnte er in diesem Repository nicht starten, während ein Agent, der das Modell der Hauptsitzung erbt, mit einer Million Token noch Platz hatte. Der Fehlschlag aus dem Einstieg 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.

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.

Der Fehlschlag verhinderte sogar seine eigene Aufklärung: Der Versuch, die Lade-Regeln des Werkzeugs per Subagent aus der Dokumentation zu klären, scheiterte an dem Kontext-Limit, das es zu erklären galt. Seit der Version 2.1.293 läuft derselbe Agent auf Haiku 5.5 mit einem Fenster von einer Million Token. Nachgestellt am 20. Oktober 2026 mit der Version 2.1.301 auf dem Stand vor dem Umbau: Der Agent startete, seine Anfrage hatte 485.056 Token, mit dem neueren Tokenizer dieses Modells gezählt, und er beantwortete die Probefrage. Die Fixkosten sind damit nicht kleiner geworden. Nur die Schwelle, an der sie sichtbar werden, ist nach hinten gerückt.

Die zweite Zeile der Tabelle, die größte Komponente, gilt für den Tag der Messung. Seitdem hat sie sich erledigt, aus einem Grund, der mit dem Kontextfenster nichts zu tun hatte. Die größte Komponente hatte 7.103 Zeilen. An ihr war im September eine Fehlerbehebung gescheitert, weil die Wechselwirkung zweier Ladeläufe in keinem Diff zu sehen war, und seitdem galt für die Datei eine Sperre für jeden nicht-trivialen Eingriff. Am selben Tag wie der Umbau 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 Ladepfade, Sperren, Mutationen und Dialoge, keine über 1.000 Zeilen, mit 21 eigenen Testdateien daneben. Der Code ist dabei nicht kleiner geworden, sondern um ein Drittel gewachsen, weil jede Einheit einen Kopf, eine Schnittstelle und Importe braucht. Gesunken ist, was eine einzelne Aufgabe laden muss. Wer einen Ladepfad ändert, liest heute einen Hook mit 900 Zeilen, hochgerechnet rund 22.000 Token, statt der ganzen Datei mit rund 155.000. Das ist dieselbe Trennlinie wie bei den Regeln, nur im Quellcode: Nichts wurde gekürzt, geändert hat sich, was wann in den Kontext kommt. Gebraucht hat den Schnitt zuerst der Mensch, der eine Wechselwirkung im Diff sehen will. Der Agent, der die Datei liest, bekommt denselben Vorteil.

Drei Hebel, und was sie kosten

Für alle drei gilt dieselbe Vorgabe: Keine Regel wird inhaltlich gekürzt. Jede stammt aus einem echten Fehler. Verändert wird nur, wann sie lädt und was neben ihr in derselben Datei steht.

Regeln mit paths: an Dateien binden

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

---
paths:
  - "src/components/**"
  - "src/app/**"
  - "src/lib/**"
---

---
paths:
  - "src/components/**"
  - "src/app/**"
  - "src/lib/**"
---

Im DI²-Repository nutzten das am Tag der Messung 3 von 30 Regel-Dateien, obwohl die meisten Regeln an einen Dateityp gebunden sind. Die SQL-Regeln gelten für Dateien unter db/, die Regeln für Register-Layout, Dialoge und Toasts für Komponenten. Nach dem Umbau trugen 24 von 30 Dateien ein paths:-Frontmatter. Das waren 264.300 Token und damit gut zwei Drittel der gesamten Ersparnis.

Der Hebel hat eine Grenze. Eine gebundene Regel kommt erst mit dem Ergebnis des Werkzeug-Aufrufs an, denn der Aufruf auf eine passende Datei ist das, was sie lädt. Eine Probe am 15. Oktober 2026 in Claude Code 2.1.292 zeigte das: In einer Sitzung, in deren Kontext die Frontend-Regel noch nicht lag, lud ein Lesezugriff auf eine Komponente sie erst im Ergebnis des Lesevorgangs nach. Beim Ändern einer bestehenden Datei ist das harmlos, weil das Edit-Werkzeug von Claude Code 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 ist der Inhalt geschrieben, bevor die Regel ankommt. Eine zweite Probe am 20. Oktober 2026 zeigte das in zwei Versionen: Eine Regel verlangte für jede neue Datei unter src/ eine bestimmte erste Zeile. In 2.1.145 lud der Write-Aufruf die Regel gar nicht, in 2.1.301 kam sie nach dem Ergebnis des Aufrufs an, und in beiden Fällen entstand die Datei ohne diese Zeile. Ob der Agent das danach selbst bemerkt, hängt vom Lauf ab: In einer dritten Probe mit 2.1.301 schrieb er die Datei ebenfalls ohne die Zeile, sah die Regel mit dem Ergebnis des Aufrufs und trug sie mit einem zweiten Aufruf nach. Verlassen kann man sich darauf nicht. Genau dann, wenn eine Konvention verhindern soll, dass etwas falsch angelegt wird, ist sie nicht da.

Drei Netze schließen diese Lücke:

1. Neuanlage-Regeln bleiben global: Die Test-Regel und die Regel für Seiten-Gerüste gelten beim Anlegen von Dateien, die es noch nicht gibt. Beide bleiben ohne paths: und tragen am Dateianfang einen Kommentar, der das begründet. Ohne diesen Kommentar räumt sie die nächste Aufräum-Sitzung mit auf.
2. Workflow-Skills lesen vorher ausdrücklich: Der Skill, der Backend-Code anlegt, liest die SQL-Regeln, bevor er die erste Datei schreibt. Die Skills für Frontend und Oberflächen-Entwurf bekamen denselben Schritt für die Oberflächen-Regeln.
3. Eine Regel-Landkarte in der Projekt-Anweisung: Je gebundene Regel eine Zeile mit Dateiname und Geltungsbereich, ohne Inhalt. Die Landkarte kostet 1.800 Token und steht bewusst in der Projekt-Anweisung, weil die nach einer automatischen Zusammenfassung des Kontexts neu eingelesen wird. Ohne sie weiß der Agent nicht, dass eine Regel existiert, und fragt deshalb auch nicht nach ihr. Dann wäre das Binden keine Einsparung, sondern ein Substanzverlust.

Der Kommentar am Dateianfang der Test-Regel:

<!-- Bewusst OHNE paths:-Frontmatter. Eine gebundene Regel laedt erst mit dem
     Ergebnis des Read/Write/Edit auf eine passende Datei. Bei einer Datei,
     die es noch nicht gibt, ist das zu spaet. Gilt beim ANLEGEN einer
     Testdatei (Ablage, Endung, Mocks, Budgets). Nicht binden. -->

<!-- Bewusst OHNE paths:-Frontmatter. Eine gebundene Regel laedt erst mit dem
     Ergebnis des Read/Write/Edit auf eine passende Datei. Bei einer Datei,
     die es noch nicht gibt, ist das zu spaet. Gilt beim ANLEGEN einer
     Testdatei (Ablage, Endung, Mocks, Budgets). Nicht binden. -->

Zwei Zeilen aus der Landkarte:

- .claude/rules/sql.md — übergreifender SQL-Styleguide (Naming, Alignment), db/**
- .claude/rules/tables.md — Tabellen-DDL, Constraints, Comments, db/**

- .claude/rules/sql.md — übergreifender SQL-Styleguide (Naming, Alignment), db/**
- .claude/rules/tables.md — Tabellen-DDL, Constraints, Comments, db/**

Zwei Fallen gehören dazu. Das Frontmatter ist YAML, und Claude Code liest es beim Start jeder Sitzung, um zu entscheiden, welche Regeln gebunden sind. Ein Glob-Muster, das mit einem Stern beginnt und ohne Anführungszeichen steht, etwa - **/*.tsx, liest YAML als Verweis auf einen Anker, nicht als Text. Der Parser bricht ab, und Claude Code lädt die Regel dann so, als hätte sie kein paths:, also bei jedem Start. Im normalen Betrieb meldet es das nicht. Eine Probe in Claude Code 2.1.145 bestätigte das: Von drei Regeln mit paths: erschien genau die mit dem ungequoteten Stern unter den beim Start geladenen Dateien, und nur claude --debug meldete den Parser-Fehler, ohne den Dateinamen zu nennen. Die Ersparnis ist dann weg, und niemand merkt es. Muster im Frontmatter gehören deshalb immer in Anführungszeichen.

Die zweite Falle ist eine zu enge Bindung. Die Marken-Regel, die unter anderem Anführungszeichen und Interpunktion in Nutzertexten regelt, war zuerst an die Wörterbuch-Dateien und eine einzelne weitere Datei gebunden. Nutzertexte liegen aber auch in anderen Dateien daneben, und aus genau einer solchen Datei stammte der Fehler, der die Regel einst ausgelöst hatte. Gebunden ist sie jetzt an das ganze Verzeichnis. Eine zu weite Bindung kostet nur dann etwas, wenn die Regel lädt. Eine zu enge lädt sie nie dort, wo sie gebraucht wird.

Regel und Protokoll trennen

Die Inventur-Tabelle der Test-Regel wanderte in eine eigene Datei unter docs/, mit allen 162 Zeilen unverändert. Die Test-Regel selbst behielt ihre Regeln und zwei Sätze zur Inventur: wo sie liegt und dass bei jeder neuen Testdatei dort eine Zeile dazukommt. Ohne diese Pflegepflicht in der Regel verwaist die Inventur. Die Regel-Datei schrumpfte damit von 124.000 auf 20.300 Token. Das sind 103.700 Token Ersparnis, gut ein Viertel der Gesamtsumme.

So sieht die Trennung konkret aus. In der Test-Regel steht seitdem nur noch der Verweis, hier gekürzt:

## Inventur

Die Inventur der Testdateien (eine Zeile pro Datei: was sie prüft,
Bug-Anlass, Negativ-Kontrolle) liegt außerhalb dieser Regel-Datei in
docs/inventories/unit-tests.md. Nicht die ganze Inventur lesen, sondern
gezielt nach dem Dateinamen suchen.

## Inventur

Die Inventur der Testdateien (eine Zeile pro Datei: was sie prüft,
Bug-Anlass, Negativ-Kontrolle) liegt außerhalb dieser Regel-Datei in
docs/inventories/unit-tests.md. Nicht die ganze Inventur lesen, sondern
gezielt nach dem Dateinamen suchen.

Die ausgelagerte Datei beginnt mit dem Hinweis, was sie ist und wie man sie liest. Danach folgt eine Zeile pro Testdatei, hier eine der kürzeren:

# Inventur der Unit-Test-Dateien

> Protokoll, keine Regel. Eine Zeile pro Testdatei: was sie prüft und
> warum, oft mit Bug-Anlass und Negativ-Kontrolle. Die Regeln zu
> Unit-Tests stehen in .claude/rules/testing.md.
>
> Gezielt lesen, nicht vollständig: Der Dateiname steht am Anfang jeder
> Zeile, eine Suche nach ihm findet genau die eine Zeile.
>
> Pflegepflicht: bei jeder neuen Testdatei eine Zeile ergänzen.

| Testdatei                  | Projekt | Testet                                    |
|----------------------------|---------|-------------------------------------------|
| src/lib/topo-order.test.ts | unit    | computeProcessingOrder + refineWithinLevel |
|                            |         | (Ebenen, Zyklen, Tie-Break, isStale)       |

# Inventur der Unit-Test-Dateien

> Protokoll, keine Regel. Eine Zeile pro Testdatei: was sie prüft und
> warum, oft mit Bug-Anlass und Negativ-Kontrolle. Die Regeln zu
> Unit-Tests stehen in .claude/rules/testing.md.
>
> Gezielt lesen, nicht vollständig: Der Dateiname steht am Anfang jeder
> Zeile, eine Suche nach ihm findet genau die eine Zeile.
>
> Pflegepflicht: bei jeder neuen Testdatei eine Zeile ergänzen.

| Testdatei                  | Projekt | Testet                                    |
|----------------------------|---------|-------------------------------------------|
| src/lib/topo-order.test.ts | unit    | computeProcessingOrder + refineWithinLevel |
|                            |         | (Ebenen, Zyklen, Tie-Break, isStale)       |

Entscheidend ist, wie die ausgelagerte Datei gebaut ist. Verschieben allein hätte das Problem nur verlagert, denn 104.000 Token auf einmal zu lesen, sobald der Agent die Inventur braucht, wäre kaum besser. Die Datei hat deshalb eine Zeile pro Testdatei, und der Dateiname steht am Zeilenanfang. 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 DI²-Projekt ist daraus eine Konvention geworden, die selbst 1.500 Token kostet, weil sie in einer global geladenen Regel steht. Eine neue Inventur entsteht unter docs/, nie als Abschnitt einer Regel-Datei. Die Regel nennt den Ort und die Pflegepflicht in einem Satz. Und große Dateien werden nicht per @-Import in die Projekt-Anweisung eingebunden, denn was sie importiert, lädt mit ihr bei jedem Start. Eine große Datei auf mehrere Imports zu verteilen spart deshalb nichts.

Nachschlagen statt vorladen

Der dritte Hebel ändert keine Regel, sondern Anweisungen. Der Skill, der einen neuen Bug anlegt, las das Bug-Register 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 im Register nach einem bestimmten Eintrag suchten, suchen jetzt mit grep, statt zu lesen. Derselbe Gedanke führte zu zwei Änderungen an der Projekt-Anweisung: Die Roadmap-Tabelle der Produktbeschreibung, 89 Prozent dieser Datei, wanderte in eine eigene Datei, und der Feature-Index wird nicht mehr per Import eingebunden. Beide liest der Agent, wenn er sie braucht, und die Skills, die sie brauchen, sagen das ausdrücklich. Zusammen 25.500 Token.

Nicht jede Volllesung ist Verschwendung. Die Durchsicht aller Skills fand drei, die bleiben. Der Feature-Index wird von acht Skills vollständig gelesen, weil der Kontext dort tatsächlich gebraucht wird. Die Produktbeschreibung ist nach dem Umbau klein. Der Testfall-Index wird dort fortgeschrieben, wo er gelesen wird. Der Hebel gilt für Anweisungen der Form „lies die Datei, um einen Einzelwert zu finden“. Für eine Datei, deren ganzer Inhalt die Entscheidung trägt, gilt er nicht.

Vorher und nachher: 454.900 zu 64.700 Token

Der Umbau lief in fünf Schritten, jeder ein eigener Commit und einzeln zurücknehmbar. Zuerst kamen die rein verschiebenden, dann das Binden an Pfade als riskantester Schritt, zuletzt die Leitplanke. Einen ausformulierten Umsetzungs-Auftrag gab es nicht. Der Agent hatte aus der Analyse eine Spec vorgeschlagen und dazu Fragen gestellt, die der Maintainer per Auswahl beantwortete. Fragen und Antworten stehen wörtlich im Transkript:

Wie weit soll ich beim Kontext-Umbau jetzt gehen?
  -> Alles inklusive Scoping-Durchgang
Ein Feature für alle vier Hebel oder aufgeteilt?
  -> Ein Feature, vier Bausteine
Die Register- und Layout-Regeln scopen? Das ist der große Posten,
aber der riskante.
  -> Entscheidung an /architecture delegieren
PRD-Roadmap und Feature-Index aus den Always-Includes der CLAUDE.md lösen?
  -> Ja, mit schlankem Rest
Soll ein Guard gegen Rückfall entstehen? Ohne ihn wächst die nächste
Regel-Datei wieder zur Protokoll-Halde, ohne dass es auffällt.
  -> Ja, als CI-Guard mit Baseline
  

Wie weit soll ich beim Kontext-Umbau jetzt gehen?
  -> Alles inklusive Scoping-Durchgang
Ein Feature für alle vier Hebel oder aufgeteilt?
  -> Ein Feature, vier Bausteine
Die Register- und Layout-Regeln scopen? Das ist der große Posten,
aber der riskante.
  -> Entscheidung an /architecture delegieren
PRD-Roadmap und Feature-Index aus den Always-Includes der CLAUDE.md lösen?
  -> Ja, mit schlankem Rest
Soll ein Guard gegen Rückfall entstehen? Ohne ihn wächst die nächste
Regel-Datei wieder zur Protokoll-Halde, ohne dass es auffällt.
  -> Ja, als CI-Guard mit Baseline
  

Die vier Hebel in dieser Zählung sind die drei dieses Artikels und der Guard, den der Artikel als Leitplanke gesondert behandelt. Der Umsetzungs-Auftrag danach bestand aus zwei Wörtern: „sofort umsetzen“. Während der Umsetzung kam, nachdem die Lade-Semantik geklärt war, eine letzte Frage: ob die Register- und Layout-Regeln mitgebunden werden sollen, nach damaliger Schätzung zusammen 115.000 Token, darunter die Register-Regel mit gemessenen 70.700. Die Antwort war ja, und das wurde der größte Posten der Ersparnis.

Die Abnahme-Kriterien, darunter die Messung mit /context in einer frischen Sitzung und der Subagent, der wieder starten muss, hatte der Agent in die Spec geschrieben. Der Maintainer hat sie mit der Spec abgenommen, nicht selbst formuliert. Er schreibt kein Node und könnte das Prüfskript nicht verfassen. Den Umbau der Regel-Dateien, das Skript und die Entscheidung, welche Regeln global bleiben, hat der Agent erarbeitet. Vom Maintainer kamen die Problembeschreibung, die Antworten oben und am Ende die Messung selbst: /context und die Subagent-Probe in einer frischen Sitzung, von Hand gestartet, weil eine laufende Sitzung ihren eigenen Startstand nicht neu messen kann. Entscheidend war, dass die Messung von Anfang an als Abnahme in der Spec stand und nicht erst nach dem Ergebnis festgelegt wurde.

Gemessen wurde mit dem Werkzeug selbst. Beide Stände lagen als eigener Git-Worktree vor, /context war die erste und einzige Eingabe einer neuen Sitzung ohne interaktive Oberfläche, Claude Code 2.1.145 mit dem Modell Opus 5.5, beide Läufe am 15. Oktober 2026 im Abstand weniger Minuten auf derselben Maschine. Eine Gegenprobe in einer interaktiven Sitzung zählte Datei für Datei gleich.

Aufgeteilt nach Hebel:

Der zweite Beleg ist ein Ja oder Nein. Derselbe Subagent, der vorher abbrach, startete nach dem Umbau in einer frischen Sitzung mit 66.887 Token Kontext und beantwortete die Probefrage richtig.

Drei Dinge sagen die Zahlen nicht.

• Gemessen sind Fixkosten, keine Arbeitskosten: Gebundene Regeln sind nicht weg. Eine Sitzung an der Register-Oberfläche lädt die Register-Regel mit 70.700 Token weiterhin, sobald sie die erste Komponente anfasst. Eine Sitzung an SQL oder Dokumentation lädt sie nicht mehr. Gemessen ist der Start, kein typischer Arbeitstag.
• Die Grenze des Bindens ist messbar: Von den 64.700 Token gehören 31.300 zu den zwei Regeln, die bewusst global bleiben, weil sie greifen müssen, bevor eine Datei existiert. Das ist knapp die Hälfte des Rests, und sie lässt sich nicht wegbekommen, ohne die Regeln zu kürzen.
• Das Binden verschiebt, wer eine Regel sieht: Vor dem Umbau hatte jeder Skill alle Regeln im Kontext, weil alle beim Start luden. Nach dem Umbau lädt eine gebundene Regel nur noch, wenn der Agent eine passende Datei liest oder ändert. Der Skill, der einen Diff prüft, tut das nicht. Er liest den Diff über git diff in der Shell und fasst dabei keine einzige Datei an. In seinem Kontext liegt deshalb keine der gebundenen Regeln, zum Beispiel nicht die SQL-Konventionen für Dateien unter db/. Er hätte SQL gegen Konventionen geprüft, die er nicht kennt, und nichts gefunden. Aufgefallen ist das erst in der Qualitätssicherung des Umbaus, nicht beim Umbau selbst. Der Skill gleicht jetzt die Pfade im Diff mit der Landkarte ab und liest die zugehörigen Regeln ausdrücklich, bevor er prüft. Dahinter steckt derselbe Reflex wie in Der Agent misst, wo der Mensch klickt: nicht annehmen, was der Agent sieht, sondern nachsehen.

Ohne Leitplanke kommt das Wachstum zurück

Das Wachstum aus dem Abschnitt „Gewachsen mit der Arbeit“ kam aus einer Pflegepflicht ohne Deckel. Ohne einen Deckel wäre die Ersparnis eine Momentaufnahme, und die nächste gut gemeinte Inventur würde in einem halben Jahr dieselbe Zahl erzeugen. Mit dem Umbau kam deshalb 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 damit auf dem Bestand vom 15. Oktober um rund 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 Schwelle, und das Budget von 80.000 Token lässt gegenüber den gemessenen 64.700 Luft für den Fehler der Näherung. Es prüft sieben Dinge:

Der Guard prüft Dateien, kein Verhalten. Ob ein Skill eine gebundene Regel tatsächlich liest, bevor er prüft, sieht er nicht. Den Review-Skill ohne SQL-Regeln aus dem Abschnitt davor hat die Qualitätssicherung gefunden, nicht der Guard.

Der erste Lauf lieferte gleich einen Befund, mit dem niemand gerechnet hatte. Die Prüfung auf verwaiste Inventur fand fünf Testdateien ohne Inventur-Zeile, alle aus der Zeit vor dem Umbau. Die Pflegepflicht „bei jeder neuen Testdatei eine Zeile“ hatte die Inventur also auf 104.000 Token wachsen lassen und war trotzdem nicht eingehalten worden. Eine Pflicht, die niemand prüft, hält also weder die Inventur vollständig noch die Regel-Datei klein.

Die Zerlegung der größten Komponente endete mit einem zweiten Guard nach demselben Muster, diesmal für Quelldateien. Er prüft jede Datei unter src/ auf höchstens 1.000 Zeilen, Tests eingeschlossen, mit einer Baseline für den Altbestand, die nur schrumpfen darf, und einem Spielraum von zwei Prozent, damit ein Bugfix an einer alten Datei durchkommt und ein Feature nicht. Sein erster Lauf fand 33 Dateien über der Grenze, erwartet waren sechs. Die Regel dazu steht nicht in einer Datei, die bei jedem Start lädt, sondern in der Regel für Komponenten, Seiten und Hooks, die an genau diese Pfade gebunden ist. Sie kommt also nur in die Sitzungen, in denen eine solche Datei wachsen kann. Für alle anderen Dateien meldet sich der Guard selbst.

Was nicht die Lösung ist

Regeln kürzen, bis sie nichts mehr sagen, ist es nicht. Nach dem Umbau blieben in der Test-Regel 20.300 Token reine Regel-Prosa, und das Abnahme-Kriterium hatte „höchstens 12.000“ verlangt. Die Zahl stammte aus der Faustformel vom Vortag, mit demselben Fehler wie alle Schätzungen. Revidiert wurde die Zahl, nicht die Regel. Was eine Regel sagt, hat sie sich aus einem Fehler verdient, und ein Token-Budget ist kein Grund, das wieder zu vergessen.

Eine Produktkritik ist es auch nicht. Der Mechanismus zum Binden existierte die ganze Zeit, er war dokumentiert, und er griff nachweislich. Dass ihn 3 von 30 Dateien nutzten, ist eine Frage der Pflege-Disziplin. Dass ein Agent eine Regel im Kontext hat, wenn er sie braucht, ist zudem die Voraussetzung dafür, dass er sie überhaupt einhalten kann.

Und eine Prüfung, die mit derselben falschen Annahme rechnet wie das Geprüfte, ist es erst recht nicht. Der Guard aus dem Abschnitt „Ohne Leitplanke kommt das Wachstum zurück“, das Prüfskript in der CI, war zunächst nicht mit den 3,7 der ersten Schätzung kalibriert, sondern mit einer zweiten falschen Zahl: Die Fehlermeldung des gescheiterten Subagenten nannte neben den 347.814 Token der ganzen Anfrage rund 227.000 Token für das Gespräch, und die Dateigröße geteilt durch diese Zahl ergab 4,0 Bytes pro Token. Nur zählte die Meldung nicht dasselbe wie /context. Sie stammte von einem anderen Modell und bezog sich auf einen Teil der Anfrage. Gemessen sind es 2,0. Qualitätssicherung und Code-Review rechneten mit demselben Faktor, bestätigten „33.000 von 45.000 Token“ und hielten das Ziel für erreicht. Richtig waren 64.700 von 80.000. Aufgefallen ist das erst, als /context in einer frischen Sitzung lief. Zwei Prüfungen, die grün melden, beweisen nichts, wenn sie dieselbe Zahl aus derselben Quelle haben. Warum ein grüner Test auf diese Weise genau den Fehler bestätigen kann, den er finden sollte, zeigt Der grüne Test, der nichts beweist.

Eine Einschränkung gehört dazu. Die Analyse, die diesen Artikel ausgelöst hat, lief in derselben Sitzung, deren Kontextfenster sie untersuchte. Das Messen selbst kostet Kontext.

Zusammenfassung

• Projekt-Instruktionen lädt Claude Code vor dem ersten Prompt, bei jeder Sitzung. Im DI²-Repository waren das 454.900 Token, knapp die Hälfte eines Fensters von einer Million und mehr als das Doppelte eines Fensters von 200.000, gewachsen in gut sechs Monaten mit der Arbeit am Projekt.
• Die Trennlinie ist Regel gegen Protokoll. Eine Regel steuert die nächste Entscheidung, ein Protokoll belegt eine vergangene. Beides gehört ins Repository, nur die Regel in den Kontext beim Start. 84 Prozent der größten Regel-Datei waren Protokoll.
• Drei Hebel, von denen keiner eine Regel kürzt: Regeln mit Datei-Bezug an Pfade binden, Inventuren in eine Nachbardatei mit dem Dateinamen am Zeilenanfang verschieben, Anweisungen zum Nachschlagen statt zum Vorladen schreiben. Ergebnis 64.700 Token, und der Subagent startet wieder.
• Das Binden an Pfade kommt bei neuen Dateien zu spät und verschiebt, wer eine Regel sieht. Dagegen helfen Neuanlage-Regeln, die global bleiben, Skills, die ausdrücklich lesen, und eine Landkarte in der Projekt-Anweisung. Gegen das Wachstum hilft ein Guard in der CI, denn eine Pflicht, die niemand prüft, hält weder die Inventur vollständig noch die Regel-Datei klein.

FAQ

Verwandte Artikel

Übergeordnet:

• Agentic Coding aus Anwender-Sicht — der Sub-Hub dieses Astes: Die Arbeit verschwindet nicht, sie verlagert sich, unter anderem in die Pflege von Regeln.
• KI-gestützte SQL-Entwicklung mit Claude Code — der Einstieg in Rules, Skills und Agenten.

Geschwister-Artikel:

• Der Agent misst, wo der Mensch klickt — dort misst der Agent das Produkt, hier sein eigenes Arbeitsmaterial. Die Methode ist dieselbe: erst messen, dann deuten.
• Die Kontroll-Schleife — Regeln sind das Mittel, mit dem sich Code prüfen lässt, den man selbst nicht liest. Dieser Artikel zeigt, was das Mittel beim Sitzungsstart kostet.

Weiterführend:

• 27 Regel-Dateien statt einer CLAUDE.md — wie die Regel-Dateien aufgebaut sind, deren Ladezeitpunkt hier verschoben wird.
• SQL-Konventionen mit Claude Code ableiten — wie die Regeln entstehen, deren Betriebskosten hier gemessen werden.
• Der grüne Test, der nichts beweist — warum zwei Prüfungen mit derselben falschen Annahme das Ziel bestätigen, das sie verfehlen.