Coding-Agents vergessen mein Repo. Darum baute ich eine Karte

Meine Coding-Agents erinnern sich zwischen zwei Sessions nicht an das Repository. Deshalb gebe ich ihnen einen festen Lesepfad. Vier Ebenen aus einfachen Textdateien zeigen, was aktuell ist, welche Entscheidungen feststehen und wo der relevante Code liegt. So verbraucht der Agent weniger Kontext, um das Repo erneut zu verstehen. Die Karte aktuell zu halten, bleibt jedoch die eigentliche Schwierigkeit.

Was ist ein Kontextmanagement-System? Ein fester Lesepfad

Bei einer Änderung an der Abrechnung schickt mein Kontextmanagement-System den Agenten zu einem Index, der zwei Dokumente und einen Ordner nennt. Dieser feste Lesepfad ersetzt eine offene Suche durch das gesamte Repository. Der Agent beginnt deshalb mit den Dateien, die für die Aufgabe am ehesten relevant sind.

Die Dokumentation von Claude Code erklärt, warum ein wiederholbarer Einstieg nötig ist: „Jede Claude-Code-Session beginnt mit einem frischen Kontextfenster“ [1]. Der Agent kennt das Repository zunächst nicht und kann sein Wissen nicht in die nächste Session mitnehmen. Kontinuität entsteht deshalb nur durch Informationen, die er wiederfinden kann.

Die Karte soll nicht alles speichern, was der Agent irgendwann brauchen könnte. Eine automatisch geladene Instruktionsdatei verweist auf den aktuellen Stand, frühere Entscheidungen und relevante Stellen im Code. Details lädt der Agent erst, wenn die Aufgabe sie erfordert. Diese erste Auswahl ist wichtig, weil sie die Grundlage für alle folgenden Entscheidungen bildet.

Was kostet eine leere Session? Token und Genauigkeit

Eine leere Session kostet Qualität und Token, weil der Agent das System erst weit genug verstehen muss, bevor er es ändern kann. Hängt dieses Verständnis von Stichworttreffern ab, übersieht er leicht wichtige Details. Die Änderung kann dann plausibel wirken und trotzdem falsch sein. Schon die Suche verbraucht Kontext, bevor die eigentliche Arbeit beginnt.

Mehr Dateien zu laden, löst das Problem nicht automatisch. Ein Modell bleibt in einem langen Kontextfenster nicht durchgehend gleich aufmerksam. Chroma Research testete 18 Modelle und stellte fest, dass ihre Leistung mit längeren Eingaben sank, selbst bei Aufgaben, die dieselben Modelle mit einem kurzen Prompt gut lösten [2].

Lange Kontexte scheitern nicht nur an fehlendem Platz. Drew Breunig beschreibt, wie frühe Fehler das spätere Denken beeinflussen, vergangene Aktionen das Modell ablenken und verschiedene Teile der Eingabe einander widersprechen können. Er zitiert außerdem eine Databricks-Studie, in der Llama 3.1 405B ab etwa 32.000 Token an Korrektheit verlor. Selbst bei Modellen mit einem Kontextfenster von einer Million Token schnitten Agenten jenseits von 100.000 Token schlechter ab [3].

Das Engineering-Team von Anthropic beschreibt dieselbe Grenze als Aufmerksamkeitsbudget [4]. In der Praxis bleibt für die gewünschte Änderung weniger Aufmerksamkeit übrig, wenn der Agent einen großen Teil dieses Budgets auf das Verständnis des Repositorys verwenden muss.

Die Zahlen aus meinem Haupt-Repository machen diese Abwägung unvermeidlich. Seine 418 Markdown-Dateien enthalten rund 7 MB Text. Je nach Schätzmethode würde eine vollständige Lektüre zwischen 5,7 und 8,75 Kontextfenster mit je 200.000 Token erfordern. Der Agent muss also eine Auswahl treffen. Ich gebe dafür eine dokumentierte Lesereihenfolge vor, statt die ersten Stichworttreffer entscheiden zu lassen.

Vier Textdatei-Ebenen geben aktuellen Fakten Vorrang

Das System führt jede Session durch Regeln, den aktuellen Stand, Entscheidungen und eine optionale Historie. Normale Dateien im Repository lassen sich leicht prüfen, im Review besprechen und aktualisieren. Das ist mir wichtiger als eine aufwendige Suche.

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

jede Session

• AGENTS.md Regeln und Lesereihenfolge, automatisch geladen

verweist auf

die Karte

• STATE.md aktueller Stand, zuerst lesen
• INDEX.md welche Dokumente für diese Aufgabe

führt weiter zu

die Aufgabe

• Bereichsdokumente und Code nur, was die Änderung berührt
• decisions/ warum der aktuelle Stand so ist
• sessions/ Historie, nie maßgeblich

Die Regeldatei steht am Anfang, weil Agenten sie automatisch laden. Die Agentic AI Foundation beschreibt AGENTS.md als offenen Standard, den mehr als 60.000 Open-Source-Projekte verwenden [5], während Claude Code stattdessen CLAUDE.md liest. Die Dokumentation von Claude Code empfiehlt die Verbindung, die ich nutze: CLAUDE.md wird zum symbolischen Link auf AGENTS.md, und die gemeinsame Datei bleibt unter 200 Zeilen [1].

Anfangs pflegte ich für jedes Tool eine eigene Datei, doch ihre Regeln entwickelten sich allmählich auseinander. Der symbolische Link beseitigte diese Fehlerquelle. Beide Tools lesen nun dieselbe Datei, und ich muss nur eine Kopie aktualisieren.

Von der Regeldatei führt der Lesepfad jeder Session zum Snapshot. Er hält fest, was produktiv ist, woran noch gearbeitet wird und, besonders hilfreich, was noch nicht geprüft wurde. Diese letzte Kategorie verhindert, dass der Agent unfertige Arbeit oder eine ungeprüfte Annahme als Tatsache behandelt.

Hinter dem Snapshot liegen die Entscheidungen und die Historie. Das ADR-Projekt definiert ein Architekturentscheidungsprotokoll als Dokument zu einer wichtigen Architekturentscheidung [6]. In meinem System hält jedes Protokoll sowohl die Entscheidung als auch ihre Begründung fest. Mein Repository sammelte in acht Wochen 74 solcher Protokolle. Ändert sich eine Entscheidung, ersetzt ein neues Protokoll das alte, ohne es umzuschreiben. Session-Logs erfüllen einen anderen Zweck: Sie bilden eine Historie, die nur ergänzt wird und die der Agent einsehen darf, aber nie als Quelle für den aktuellen Stand.

Eine Rangfolge löst widersprüchliche Antworten auf

Die Ebenen funktionieren nur, wenn der Agent Widersprüche zwischen ihnen auflösen kann. Deshalb steht an jedem Einstiegspunkt dieselbe Rangfolge: Code hat Vorrang vor Entscheidungsdokumenten, diese vor dem Snapshot und der Snapshot vor der Historie. Findet eine Suche fünf Antworten aus verschiedenen Zeiträumen, kann der Agent der höchstrangigen Quelle folgen und den Rest aktualisieren oder kennzeichnen.

Die Historie aus dem normalen Lesepfad herauszuhalten, hat eine große praktische Wirkung. Session-Logs machen 73 % aller Dokumentationsbytes in diesem Repository aus. Ohne sie sinkt die Schätzung, um alles zu lesen, von 8,75 Kontextfenstern auf etwa 2,3. Die aktuelle Dokumentation bleibt umfangreich, lässt sich vom Agenten aber deutlich leichter durchgehen.

Wie halte ich Kontextdateien aktuell? Doku mit Code ändern

Ich behandle Dokumentation als Teil der Codeänderung. Sobald Code eine Tatsache über die Architektur ändert, muss derselbe Commit das zugehörige Dokument aktualisieren. Die Arbeit bleibt nicht für ein späteres Aufräumen liegen. Die Instruktionsdatei nennt diese Regel am Anfang und wiederholt sie im abschließenden Selbsttest des Agenten, wo sie schwer zu übersehen ist.

In meinem Repository hielten sich Agenten verlässlicher an diesen Test als Menschen. Nachdem ich die Regel auf Dokumentation für Nutzer ausgeweitet hatte, stieg der Anteil der UI-Commits mit passender Aktualisierung von 12,3 % auf 31,9 %. Eine Quote von 31,9 % ist noch weit von einer verlässlichen Befolgung entfernt, liegt aber 2,6-mal so hoch wie zuvor. Die meisten Fehler traten bei Änderungen auf, für die kein einzelner Agent von Anfang bis Ende verantwortlich war.

Für Informationen, die sich zwischen Sessions ändern, nutze ich eine zweite Regel: Vor dem Ende schreibt der Agent ein kurzes Session-Log und aktualisiert den Snapshot. Auch der Wechsel zu einer anderen Aufgabe löst diesen Ablauf aus. Ohne einen festen Zeitpunkt werden Updates, die später leicht erscheinen, ebenso leicht vergessen.

Warum ich Embeddings und Memory-MCP-Server aufgegeben habe

Ich habe beide Ansätze aufgegeben, weil das Abrufen nicht das Problem war. Die Systeme fanden relevante Informationen, konnten aber nicht zuverlässig erkennen, ob sie noch aktuell waren. Mein Memory-MCP-Server und der Vektorindex lieferten oft das richtige Thema aus dem falschen Monat. Embeddings, die vor einem Refactor entstanden sind, wissen nichts von der späteren Architekturänderung.

Jeder Ansatz schuf außerdem eine weitere Informationsquelle, die ich pflegen musste, und brachte damit das ursprüngliche Wartungsproblem zurück. Mehrere Open-Source-Frameworks für Memory brachten noch ein zweites Problem mit: Ihr Code erzwang oft nicht das Verhalten, das im README beschrieben war. Als ich sowohl Aktualität als auch Implementierung prüfen musste, brach ich die Evaluierung ab. Gehostete Agenten werfen dieselbe Frage auf, was zwischen Sessions erhalten bleibt, und genau darum geht es in OpenAIs Agents API und dem, was der Codex-Harness übernimmt.

Anthropic empfiehlt, kleine Bezeichner wie Dateipfade und Suchanfragen im Kontext zu halten und Details erst dann zu laden, wenn der Agent sie braucht [4]. Einfache Dateien passen dazu, weil man sie durchsuchen, vergleichen und im selben Pull Request wie den zugehörigen Code prüfen kann. Ein Reviewer erkennt eine alte Markdown-Datei. Ein veralteter Embedding-Index ist wesentlich schwieriger zu untersuchen.

Was kostete das System? Weniger Lesen, mehr Wartung

Das System ließ den Agenten zunächst nur 0,22 % der Dokumentation laden, hielt diese Dateien aber nicht aktuell. Ein Audit im Juli 2026 zeigte, dass der Snapshot in 26 Tagen auf das 9,5-Fache gewachsen war und eine veraltete Warnung enthielt.

Das Repository ist ein produktives Monorepo mit rund 277.000 Zeilen TypeScript, an dem ich mit drei verschiedenen Agent-Tools arbeite. Die Struktur erfüllte ihren Zweck: Jedes Tool bekam einen kurzen Einstiegspunkt und dieselbe Lesereihenfolge. Die Informationen innerhalb dieser Struktur waren deutlich weniger verlässlich. Wie zwei der heutigen Coding-Agents mit großen Features umgehen, ist ein eigener Vergleich: Claude gegen Codex bei großen Multi-Agent-Features.

der Dokumentation automatisch geladen

0,22 %

eine 15,5-KB-Regeldatei bei insgesamt 7 MB

eines 200K-Fensters für die gesamte Doku

8,75×

5,7× mit der Schätzung über Wörter

Snapshot-Wachstum in 26 Tagen

9,5×

von 75 auf 711 Zeilen, ohne je zu schrumpfen

Die ersten beiden Zahlen zeigen den Vorteil der Lesereihenfolge: Der Agent beginnt mit 0,22 % der Dokumentation und lädt nur dann mehr, wenn die Aufgabe es verlangt. Die dritte Zahl zeigt die dauerhafte Schwäche des Systems. STATE.md sollte klein bleiben und immer in derselben Datei überschrieben werden. Trotzdem wuchs sie in weniger als einem Monat auf das 9,5-Fache, und beim Audit war ihre wichtigste Warnung falsch. Sie meldete mehrere noch nicht gepushte Commits, obwohl der Push bereits Tage zuvor erfolgt war.

Die veraltete Warnung war kein Einzelfall. Die Schema-Dokumentation nannte 20 bis 25 Tabellen, während der Code 34 enthielt. Das Audit entfernte außerdem Dokumentation zu Funktionen, die nie existiert hatten. Von 2.873 geprüften relativen Links in der Dokumentation waren 82 defekt.

Das beständigste Muster war der Unterschied zwischen geschriebenen Regeln und automatischen Prüfungen. Ein Test erzwingt meine Typografie-Regel in UI-Texten, wo das Audit keinen Verstoß fand. Etwa die Hälfte der normalen Dokumentationsdateien brach dieselbe Regel, weil dort nichts sie prüfte. In der Praxis wurden nur der symbolische Link und der Typechecker technisch verlässlich durchgesetzt. Das Entscheidungsdokument, das das System einführte, hatte diese Grenze klar benannt: „Das senkt die Fehlerrate, es beseitigt sie nicht.“

Die richtige Menge an Startinformationen habe ich noch nicht gefunden. Enthalten die Dateien zu wenig, muss der Agent raten. Enthalten sie zu viel, entsteht erneut das von Chroma Research gemessene Problem mit langen Kontexten [2]. Die Balance verändert sich mit dem Repository. Deshalb justiere ich sie alle paar Wochen nach, statt die Struktur als fertig zu betrachten.

Bei der Arbeit behalte ich den Lesepfad, aber nicht das Drumherum

Bei der Arbeit behalte ich die Idee des Lesepfads bei, führe sie aber als gewöhnliche Projektdokumentation. Das vollständige System gehört in meine persönlichen Projekte. Nach meiner Erfahrung betrachten viele Teams so viel agentenspezifische Struktur eher als Vibe Coding denn als Dokumentation für Entwickler.

In der Praxis sieht die Arbeitsversion wie normale Projektdokumentation aus: ein klarer Einstiegspunkt, Dokumente mit festen Namen für jeden Bereich und ein Index, der erklärt, wo etwas zu finden ist. Neue Kollegen profitieren von diesen Markdown-Dateien, und Coding-Agents können ihnen ebenfalls folgen.

Die beiden Varianten unterscheiden sich nicht nur äußerlich. Bei der Arbeit treffen Teams Entscheidungen in Meetings und auf Planungsboards. Das Repository kann deshalb keine vollständige Entscheidungshistorie enthalten, wenn ein großer Teil davon außerhalb liegt. Meine persönlichen Projekte haben keine vergleichbare externe Aufzeichnung. Schreibe ich eine Entscheidung nicht ins Repository, kann die nächste Session sie nicht finden.

So startest du: eine Regeldatei unter 200 Zeilen

Beginne mit einer Regeldatei unter 200 Zeilen, die die Konventionen des Repositorys und die Reihenfolge für weitere Dateien nennt. Die Dokumentation von Claude Code empfiehlt eine neue Regel, wenn der Agent einen Fehler wiederholt [1]. Denselben Auslöser nutze ich für die Pflege meiner Datei. Ein wiederholter Fehler zeigt, dass der Lesepfad etwas nicht deutlich genug erklärt hat.

Der Rest kann entstehen, sobald du ihn brauchst. Lege eine Zustandsdatei an und verweise in den Regeln darauf. Ein Index folgt, wenn die Dokumentation nicht mehr auf einen Bildschirm passt. Schreibe den ersten Entscheidungsbericht, wenn ein Agent eine bereits geklärte Frage wieder aufwirft. Ergänze einen Historienordner, sobald du frühere Arbeit festhalten willst, ohne sie als aktuellen Stand auszugeben. Ein klarer Lesepfad hat auch verändert, wie gut ein Modell für mich arbeitet, was ich in meinem Opus-5-Workflow aus klaren Plänen und kleineren Aufgaben beschreibe.

Pflege die Dateien anschließend mit derselben Sorgfalt wie Code. In meinem vorherigen Artikel ging es um Backends, die klein genug sind, damit ein Agent sie verstehen kann. Dieses System überträgt denselben Gedanken auf Informationen, die der Code nicht selbst erklärt. Der Agent beginnt weiterhin jede Session ohne Gedächtnis. Ein gepflegter Lesepfad führt ihn jedoch zum richtigen Kontext, ohne dass er das gesamte Repository lesen muss.