Agents starten jede Session bei null. Meine haben eine Karte

Ein Kontextmanagement-System ist ein Satz reiner Textdateien, eingecheckt ins Repo, der einem frisch gestarteten KI-Agent eine Karte in die Hand drückt: was zuerst zu lesen ist, wo die aktuelle Wahrheit liegt, welche Entscheidungen abgeschlossen sind. Meins hat mehrere Umbauten hinter sich. Das hier ist die Version, die überlebt hat, mitsamt ihren gemessenen Kosten.

Was ist ein Kontextmanagement-System?

Ein Satz Dateien, der dem Agent sagt, wo er hinschauen soll, statt ihn suchen zu lassen: eine Instruktionsdatei, die jede Session von selbst lädt und die auf die wenigen Dokumente zeigt, die sagen, was gerade wahr ist, was entschieden wurde und warum, und wo der Code jedes Bereichs liegt.

Die Ausgangslage, für die es existiert, steht wörtlich in der Dokumentation von Claude Code: “Jede Claude-Code-Session beginnt mit einem frischen Kontextfenster” [1]. Jede Session ist ein neuer Mitarbeiter mit Amnesie. Ein fähiger, aber einer, der dein Repo nie gesehen hat und sich nie daran erinnern wird, es gesehen zu haben.

Der Vergleich, zu dem ich immer wieder zurückkomme, ist Google Maps. Wenn ich in einem kartierten Repo eine Änderung an der Abrechnung will, routet die erste Lektüre den Agent: die Regeldatei zeigt auf einen Index, der Index hat eine Zeile für Abrechnung, die Zeile nennt zwei Dokumente und einen Ordner. Er geht dorthin. Ohne Karte grept er, öffnet, was zufällig passt, und setzt sein Bild vom System aus den fünf Dateien zusammen, die er zufällig zuerst gesehen hat.

Dieses Bild ist das Produkt. Alles, was der Agent danach tut, erbt davon.

Was kostet eine leere Session wirklich?

Zwei Dinge: Qualität und Token. Ein Agent, der sich per Stichwortglück orientiert, versteht das System zu flach und liefert plausible, aber falsche Änderungen. Und die Orientierung selbst verbrennt das Kontextfenster, bevor die eigentliche Arbeit anfängt, was sich als die teurere Hälfte herausstellt.

Kontext ist keine flache Ressource, die man beliebig ausgeben kann. Chroma Research hat 18 Modelle evaluiert und gezeigt, dass die Leistung mit wachsender Eingabelänge sinkt, selbst bei Aufgaben, die ein kurzer Prompt sauber löst [2]. Drew Breunig hat katalogisiert, wie es scheitert: Kontexte vergiften sich mit früheren Fehlern, lenken das Modell aufs Wiederholen alter Aktionen oder widersprechen sich intern; er zitiert eine Databricks-Studie, in der die Korrektheit bei Llama 3.1 405B ab etwa 32.000 Token zu fallen beginnt, und Agents, die jenseits von 100.000 Token abbauen, auf Modellen mit Millionen-Token-Fenstern [3]. Anthropics Engineering-Team nennt das Budget beim Namen, Aufmerksamkeit: jeder Token, der fürs Orientieren draufgeht, ist Aufmerksamkeit, die das Modell für die eigentlich beauftragte Änderung nicht mehr hat [4].

Mein Haupt-Repo macht die Arithmetik konkret. Sein Dokumentationskorpus sind 418 Markdown-Dateien, rund 7 MB Text. Alles zu lesen würde zwischen 5,7 und 8,75 Mal ein Kontextfenster von 200.000 Token kosten, je nach Schätzmethode. Es passt nicht, und keine Modell-Roadmap lässt es elegant passen. Die Frage war also nie, ob der Agent eine Teilmenge liest. Sondern wer die Teilmenge auswählt: der Agent, per Grep-Glück, oder ich, per Design.

Vier Ebenen und ein Satz

Das System, bei dem ich gelandet bin, sind vier Ebenen aus reinem Text. Nichts daran ist raffiniert, und nachdem ich die raffinierteren Versionen habe scheitern sehen (dazu gleich mehr), halte ich genau das für das Feature.

AGENTS.md            # the rules; auto-loaded (CLAUDE.md is a symlink to it)
docs/
  STATE.md           # current truth: live, in flight, not yet verified
  INDEX.md           # the router: which docs to read for which task
  decisions/         # one numbered file per decision; superseded, never edited
  sessions/          # history: what happened when, explicitly not authority

Die Regeldatei ist der Einstiegspunkt, weil sie die eine Datei ist, die Agents von selbst laden. AGENTS.md ist ein offener Standard, den mehr als 60.000 Open-Source-Projekte verwenden [5]; Claude Code liest stattdessen CLAUDE.md, und seine Doku empfiehlt genau die Brücke, die ich nutze, einen Symlink, dazu ein Größenziel von unter 200 Zeilen [1]. Meine verbrachte ihre ersten Wochen als zwei getrennte Dateien, gepflegt aus zwei verschiedenen Tools, und die Regeln drifteten still auseinander, bis der Symlink das Problem per Konstruktion beendete. Eine Datei, jeder Agent, Drift unmöglich.

Der Snapshot ist das, was die Regeldatei jeder Session als Erstes zu lesen befiehlt: was live ist, was in Arbeit ist und, in der Praxis am wertvollsten, was ausdrücklich nicht verifiziert ist. Ein Agent, der weiß, dass etwas unverifiziert ist, hört auf, ihm zu vertrauen. Entscheidungsdokumente sind das ADR-Muster, eine Datei, die eine einzelne Entscheidung samt Begründung festhält [6]; mein Repo hat in acht Wochen 74 davon angesammelt, und eine neue Entscheidung ersetzt die alte Datei, statt sie zu editieren, sodass die Spur ehrlich bleibt. Die Historie ist der nur wachsende Stapel Session-Logs, der riesig sein darf, gerade weil sich nichts auf ihn stützen darf.

Ein einziger Satz hält die Ebenen zusammen, wiederholt an jedem Einstiegspunkt des Repos: Code schlägt Entscheidungsdokumente, Entscheidungsdokumente schlagen den Snapshot, der Snapshot schlägt die Historie. Diese Ordnung ist das eigentliche System. Eine Stichwortsuche über ein Repo dieser Größe liefert fünf Treffer aus fünf Epochen; der Satz sagt dem Agent, welcher gewinnt und dass die Verlierer korrigiert oder gemeldet werden, nie stillschweigend geglaubt.

jede Session

• AGENTS.md Regeln und Lesereihenfolge, lädt automatisch

zeigt auf

die Karte

• STATE.md aktuelle Wahrheit, zuerst lesen
• INDEX.md welche Docs für diese Aufgabe

leitet weiter zu

die Aufgabe

• Bereichs-Docs und Code nur, was die Änderung berührt
• decisions/ warum es so ist, wie es ist
• sessions/ Historie, nie Autorität

Die verbannte Historien-Ebene verdient sich die kleinste Box im Diagramm mit einer Zahl: Session-Logs sind 73 % aller Dokumentationsbytes in dem Repo. Nimm sie aus dem Alles-lesen-Szenario heraus, und der restliche Korpus fällt von 8,75 Kontextfenstern auf etwa 2,3. Die Historie für nicht autoritativ zu erklären ist keine Ordnungsliebe. Es ist das, was den Rest überhaupt navigierbar macht.

Was hält die Karte davon ab zu lügen?

Vor allem eine Regel: Docs sind Teil der Änderung. Eine Änderung, die einen Architektur-Fakt kippt, aktualisiert das betroffene Dokument im selben Commit, nicht in einem Aufräumen, das nie kommt. Die Instruktionsdatei des Agents sagt das, und sie wiederholt es in einem Selbst-Check genau in dem Moment, in dem ein Agent beschließt, fertig zu sein, weil Instruktionen genau dann verlässlich seine Aufmerksamkeit haben.

Es funktioniert mit Maschinen besser, als es mit Menschen je funktioniert hat, aus einem wenig schmeichelhaften Grund: ein Agent führt den vorgeschriebenen Check tatsächlich aus. Als ich die Regel auf nutzerseitige Dokumentation ausweitete, stieg der Anteil der UI-Commits, die die passenden Docs im selben Commit aktualisierten, von 12,3 % auf 31,9 %. Keine volle Befolgung, aber 2,6 Mal mehr davon, und die Ausreißer häufen sich dort, wo kein einzelner Agent die Änderung von Anfang bis Ende besaß.

Die zweite Gewohnheit ist billiger: der Agent schreibt ein kurzes Session-Log und frischt den Snapshot auf, bevor er aufhört, aus eigenem Antrieb, und behandelt “der Nutzer ist zu etwas anderem übergegangen” als Fertig-Signal. Dokumentation, die darauf wartet, dass jemand Lust aufs Dokumentieren hat, überlebt den Kontakt mit einem gewöhnlichen Dienstag nicht.

Warum keine Embeddings, kein Memory-MCP-Server?

Weil ich genau die zuerst probiert habe, und sie scheiterten immer gleich: das Abrufen war nie das Problem, die Frische war es. Ein Memory-MCP-Server mit Vektorindex vor meinen Repos lieferte verlässlich das richtige Thema aus dem falschen Monat, und ein Embedding der März-Architektur kann nicht wissen, dass der Refactor vom Dienstag es ungültig gemacht hat. Jeder dieser Aufbauten war außerdem ein zweites System, dessen Wahrhaftigkeit ich nun pflegen musste, und genau diesen Fehler soll die Karte verhindern. Und bei mehreren der Open-Source-Memory-Frameworks, die ich evaluiert habe, war der Abstand zwischen dem, was das README versprach, und dem, was der Code durchsetzte, groß genug, dass ich aufgehört habe zu evaluieren.

Anthropics Leitfaden zum Context Engineering landet, wo ich gelandet bin: leichte Bezeichner im Kontext halten, Dateipfade und Queries, und den Agent Details just in time laden lassen, statt alles vorzuberechnen, was er brauchen könnte [4]. Reine Textdateien haben die Eigenschaft, die für diese Strategie am meisten zählt: sie altern im Sichtbaren. Sie lassen sich grepen, diffen und im selben Pull Request reviewen wie der Code, den sie beschreiben. Eine veraltete Markdown-Datei ist wenigstens sichtbar veraltet. Ein veralteter Embedding-Index führt mit voller Überzeugung in die Irre.

Die ehrlichen Kosten, gemessen

Im Juli 2026 habe ich den ganzen Apparat in meinem Haupt-Repo einem Nur-Lese-Audit unterzogen, einem produktiven Monorepo mit rund 277.000 Zeilen TypeScript, bearbeitet von drei verschiedenen Agent-Tools. Die Kurzfassung: die Struktur hält, die Prosa-Disziplin nicht.

der Docs automatisch geladen

0,22 %

eine 15,5-KB-Regeldatei gegen einen 7-MB-Korpus

eines 200K-Fensters, um alles zu lesen

8,75×

5,7× mit der Wort-Schätzung

Snapshot-Wachstum in 26 Tagen

9,5×

von 75 Zeilen auf 711, nie geschrumpft

Der Abstand zwischen den ersten beiden Zahlen ist das ganze Design: der Agent startet bei 0,22 % und navigiert nach außen. Die dritte Zahl ist der Dauerfehler des Designs. Der Snapshot war als kleine, an Ort und Stelle überschriebene Datei gedacht und wuchs stattdessen in unter einem Monat auf das 9,5-Fache. Schlimmer: zum Audit-Zeitpunkt war seine Schlagzeile falsch. Er warnte vor einem Stapel ungepushter Commits, obwohl der Push Tage zuvor passiert war. Die Datei, die jede Session zuerst liest, behauptete einen veralteten Fakt mit voller Überzeugung.

Das war nicht die einzige Lüge, die das Audit hochspülte. Beim ersten Abgleich der Dokumentation gegen den Code behauptete das Schema-Dokument 20 bis 25 Tabellen, wo der Code 34 hatte, und der Durchgang löschte Dokumentation für Features, die nie existiert hatten. Von 2.873 relativen Links in den Docs waren 82 kaputt. Und meine liebste Typografie-Regel steht bei exakt null Verstößen in den UI-Strings, wo ein Test sie erzwingt, während ungefähr die Hälfte der reinen Doc-Dateien sie bricht, wo nichts sie erzwingt. Das Muster ist sauber: eine Prosa-Regel verrottet proportional zu ihrem Abstand von einem Test. Die einzigen deterministischen Teile des ganzen Systems sind ein Neun-Byte-Symlink und der Typechecker. Das Entscheidungsdokument, das die Struktur einführte, hat es von Anfang an gesagt: “Das senkt die Fehlerrate, es beseitigt sie nicht.”

Das Problem, das ich nicht gelöst habe, ist die Dosierung. Zu wenig in der Karte, und der Agent rät; zu viel, und ich habe die Langkontext-Degradation aus jener Chroma-Kurve mit meinen eigenen Dateien nachgebaut [2]. Ich justiere die Balance alle paar Wochen nach, und ich rechne damit, dass das so bleibt.

Die Light-Version, die ich auf der Arbeit fahre

Alles oben ist mein Aufbau für persönliche Projekte, und ich würde ihn keinem Arbeitgeber unverändert mitbringen. In professionellen Umgebungen liest sich so viel Agent-Apparat, nach meiner Erfahrung, als Vibe Coding, und Teams, die KI als Produktivitätswerkzeug wollen statt als autonome Autorin, haben wenig Appetit auf ein Repo, das für die Maschine gebaut wirkt. Fair oder nicht, die Wahrnehmung ist Teil des Engineerings.

Auf der Arbeit fahre ich deshalb dieselbe Idee, getarnt als das, was sie ehrlicherweise auch ist: ordentlich gemachte Dokumentation. Ein klarer Einstiegspunkt, Bereichs-Docs mit stabilen Namen, ein Index, der sagt, was wo liegt. Markdown-Dateien, für die dir ein neuer Kollege danken würde, und die nebenbei als Agent-Karte funktionieren.

Die Trennung hat eine strukturelle Ursache, keine rein optische. Auf der Arbeit fallen Entscheidungen außerhalb des Repos, in Meetings und auf dem Board, also würde eine Repo-Ebene, die Entscheidungsautorität beansprucht, vom ersten Tag an durch Auslassung lügen. In persönlichen Projekten gibt es kein Außerhalb: steht eine Entscheidung nicht im Repo, hört sie auf zu existieren, sobald die Session endet. Die Hardcore-Version ist keine Extra-Disziplin um ihrer selbst willen. Sie ist das, was ein Repo braucht, wenn es der einzige Ort ist, an dem irgendetwas leben kann.

Wo ich anfangen würde

Eine Regeldatei unter 200 Zeilen, die die Konventionen und die Lesereihenfolge festlegt; die Doku von Claude Code empfiehlt, sie immer dann zu erweitern, wenn der Agent denselben Fehler zum zweiten Mal macht [1], was zugleich der beste Wartungsauslöser ist, den ich kenne. Eine Zustandsdatei, auf die sie zeigt. Ein Index in der Woche, in der die Docs nicht mehr auf einen Bildschirm passen. Entscheidungsdokumente beim ersten Mal, wenn der Agent etwas neu aufrollt, das du vor einem Monat abgeschlossen hast, und ein Historien-Ordner an dem Tag, an dem du ein Protokoll willst, ohne ihm vertrauen zu wollen.

Und dann behandle die Karte wie Code. Wenn der Agent zweimal denselben Fehler macht, liegt der Bug meistens in der Karte, und der Fix ist ein Satz in der richtigen Datei. Der letzte Text, den ich geschrieben habe, plädierte für Backends, die klein genug sind, dass ein Agent sie im Kopf behalten kann. Das hier ist dasselbe Argument, gerichtet auf alles, was der Code nicht über sich selbst sagen kann. Der Agent wird nie aufhören, bei null zu starten. Die Karte ist das, was verhindert, dass das teuer wird.