Großes Repo, kleiner Kontext: wie Agents Code lesen

Ein Digest aller versionierten Dateien dieses Repositories ergibt etwa 1,3 Millionen Zeichen, grob 324.000 Tokens nach der üblichen Abschätzung von vier Zeichen pro Token. Das passt nicht in das Standardfenster von 200.000 Tokens, geschweige denn mit Platz zum Arbeiten. Jedes Tool, das einen Agenten auf eine große Codebasis loslässt, löst dieses Problem vor dem ersten Prompt, und die Lösungen fallen in vier Familien: Anweisungen, die mitreisen, Karten des Codes, Retrieval bei Bedarf und Zustand, der die Session überlebt.

Was kostet eine frische Session wirklich?#

Die Arithmetik für dieses Repository, heute gemessen: 258 versionierte Dateien ohne die Lock-Datei, 99 davon Quellcode mit rund 105.000 Tokens, 74 davon Blog-Inhalte mit rund 129.000. Die Wörter wiegen mehr als der Code, was auch mich überrascht hat.

Der komplette Digest als frischer Input kostete zu Claude-Opus-5.5-Listenpreisen etwa 1,30 $ pro Sessionstart, 324.000 Tokens zu 4 $ pro Million. Dieselben Tokens als Cache-Read kosten rund sechs Cent zu 0,20 $ pro Million, und der Cache ist die Rechnung für Agentenbetrieb. Dieser Artikel behandelt die andere Hälfte: von vornherein weniger zu senden, denn kein Cache hilft, wenn das Fenster selbst zu klein ist.

Die günstigste richtige Antwort für eine Aufgabe ist meist ein kleiner Ausschnitt. Der Blog-Workflow auf dieser Seite braucht den Style-Guide, die Kategorienliste und die zwei letzten Artikel, zusammen etwa 21.600 Zeichen oder 5.400 Tokens. Das ist ein Sechzigstel des Digests, rund zwei Cent als frischer Input, und es passt in die erste Nachricht.

Die Map-Datei reist mit jeder Session mit#

Eine AGENTS.md oder CLAUDE.md ist die kleinste der vier Familien und die erste, die man baut. Claude Code lädt sie beim Sessionstart als persistenten Kontext, zusammen mit selbst geschriebenen Memory-Notizen, und injiziert sie nach jeder Compaction neu von der Festplatte (Memory-Doku). Das agents.md-Format nennt sich selbst „a README for agents“ und zählt über 60.000 Open-Source-Projekte, die es nutzen. Es ist aus einer Arbeitsgruppe von OpenAI, Google, Cursor und anderen entstanden und sieht eine Datei pro Paket vor, die nächstgelegene gewinnt. OpenAIs eigenes Repository trägt 88 davon.

Dieses Repository hat eine, und ich habe sie nicht geschrieben. Sie ist 678 Byte groß, etwa 170 Tokens, und next dev schreibt sie selbst und fügt sie selbst wieder ein, mit der Warnung an jeden Agenten, dass diese Next.js-Version Breaking Changes hat, und mit dem Verweis auf die mitgelieferte Dokumentation. Das Framework pflegt Agent-Kontext für sein eigenes Ökosystem, ein deutliches Zeichen dafür, wo die Branche das Thema verortet. Die Doku empfiehlt außerdem, diese Dateien unter 200 Zeilen zu halten, denn Länge kostet bei jeder Nachricht sowohl Befolgung als auch Kontext.

Karten, Indizes, Symbole#

Die Repo-Map von Aider ist die klassische Konstruktion. Tree-sitter parst jede Datei in einen Syntaxbaum, Definitionen und Referenzen werden extrahiert, und ein Graph-Ranking-Algorithmus behandelt Dateien als Knoten und Abhängigkeiten als Kanten, um die am häufigsten referenzierten Bezeichner auszuwählen (Konstruktionspost von Aider). Das Ergebnis ist ein Skelett des gesamten Repositories, Signaturen ohne Rümpfe, bemessen auf ein Token-Budget mit dem Standardwert tausend, das sich dem Gesprächsverlauf anpasst (Doku). Das Modell liest die Karte, entscheidet, welche Dateien zur Aufgabe gehören, und nur diese kommen in den Kontext.

Cursor baut einen Index. Jede Datei zerfällt in syntaktische Chunks, die Chunks werden zu Embeddings, und ein Merkle-Baum aus Datei-Hashes lässt den Index nur das synchronisieren, was sich geändert hat, mit Embeddings gecacht nach Chunk-Inhalt (Engineering-Post von Cursor). Die eigene Evaluation von Cursor gibt der semantischen Suche durchschnittlich 12,5 Prozent mehr Genauigkeit, und derselbe Post zeigt, warum der Index geteilt werden muss: Klone einer Codebasis sind innerhalb einer Organisation zu 92 Prozent ähnlich, und die Wiederverwendung eines Team-Index senkt die Zeit bis zur ersten Abfrage im 99. Perzentil von 4 Stunden auf 21 Sekunden.

Serena geht den dritten Weg: Der Agent bekommt das Language Server Protocol über MCP, über 40 Sprachen, mit Operationen auf Symbol-Ebene wie Symbol finden, Referenzen finden und Symbol-Rumpf ersetzen (oraios/serena). Ein Agent aus der dortigen Evaluation beschreibt die Wirkung auf übergreifende Renames und Referenz-Suchen, Vorgänge, die er in roher Form auf acht bis zwölf sorgfältige, fehleranfällige Schritte veranschlagt: sie „collapse into one atomic call“.

Die Digest-Zeile verlangt Vorsicht. Repomix packt eine Codebasis in KI-freundliche Formate, und für eine einmalige Durchsicht von etwas Kleinem ist das genau richtig. Als Gewohnheit auf einem wachsenden Repository zahlt es das volle Fenster bei jeder Session neu, genau die Kosten, die die anderen vier Zeilen vermeiden sollen.

Was Compaction bewahrt und was sie riskiert#

Lange Sessions passen ebenfalls nicht, also kompaktiert Claude Code automatisch nahe der Grenze: Die Unterhaltung wird zu einer strukturierten Zusammenfassung, Projektanweisungen und Memory werden neu von der Festplatte injiziert, und bis zu fünf kürzlich bearbeitete Dateien kommen zurück, wobei alles über 5.000 Tokens nur noch als Pfadangabe ohne Inhalt zurückkehrt (Context-Window-Doku). Subagents lösen denselben Druck von der anderen Seite, indem sie große Dateien in ihrem eigenen Fenster lesen und nur die Zusammenfassung zurückgeben.

Die Summary, die eine Compaction erzeugt, ist Zustand, den das Modell selbst geschrieben hat und später als eigenen Kontext zugrunde legt, und für diesen Kanal existiert ein dokumentierter Fehlermodus: OpenAIs Misalignment-Reports haben Modelle erwischt, die Anweisungen genau auf diesem Weg schmuggelten, Summarys, die spätere Instanzen anwiesen, Fehler zu verbergen. Die Ausarbeitung dieser Reports behandelt die Mechanik; die praktische Regel lautet, das vom Modell Selbstgeschriebene mit derselben Skepsis zu behandeln wie Tool-Output. Dauerhaften Zustand in eigenen Dateien zu halten, in der Map-Datei und in der Codebasis, hält die Summary klein und weniger tragend.

Der Durchlauf auf diesem Repository#

Der Blog-Workflow hier ist das Messbeispiel. Ein neuer Artikel braucht docs/blog-style.md, src/content/categories.json und die zwei letzten Artikel: 5.400 Tokens Kontext, eine Map-Datei von 170, eine AGENTS.md, die das Framework gratis pflegt, und nirgends einen Digest. Eine Repo-Map oder ein Index auf Repository-Ebene verdient sich ihren Platz an dem Tag, an dem eine Aufgabe nicht mehr lokal bleibt, bei einer Umbenennung über viele Dateien hinweg, bei einer Architekturfrage, und die Tabelle oben sagt, welches Werkzeug dann passt.

Das Muster gilt über Code hinaus. Was sich wiederholt, gehört in ein stabiles Präfix, Anweisungen, Konventionen, Schemata, denn das lässt sich gut cachen. Was variiert, gehört in Retrieval, Karten, Indizes, Symbol-Werkzeuge, denn das hält das Fenster klein genug zum Denken. Die Agenten, die sich auf großer Codebasis schnell anfühlen, lesen nicht schneller. Sie lesen weniger, und die vier Familien oben sind das gesamte Rezeptbuch dafür.