Verteilter Kontext: warum Agenten nicht das ganze Projekt lesen sollten

Angefangen habe ich so, wie die meisten anfangen: eine Spezifikation pro Vorhaben und eine große Datei mit dem Projektkontext daneben. Das trägt ein paar Wochen. Dann wächst beides, und irgendwann kippt es. Nicht weil die Informationen falsch wären, sondern weil zu viele davon an einer Stelle liegen. Der Agent liest alles, gewichtet das Falsche und beantwortet eine Frage, die ich nicht gestellt habe.

Die Lösung war nicht, weniger aufzuschreiben. Sie war, das Geschriebene danach zu trennen, auf welche Frage es antwortet.

Die Ausgangslage, die das nötig macht

Ein Kontextdokument beginnt als Hilfe und wird zur Last, sobald es die Größe erreicht, ab der niemand mehr weiß, was drinsteht. Bei Menschen führt das dazu, dass die Datei nicht mehr gelesen wird. Bei einem Agenten führt es zum Gegenteil: Er liest sie vollständig, jedes Mal, und behandelt jeden Satz darin als gleich wichtig.

Das ist der Unterschied, der die Aufteilung erzwingt. Ein Mensch überfliegt und sucht sich, was er braucht. Ein Modell hat kein Gefühl dafür, welcher Absatz für die Aufgabe relevant ist, wenn nichts in der Struktur es ihm sagt. Zwanzig Seiten gemischtes Wissen sind für Menschen unbequem und für Agenten eine Fehlerquelle.

Dazu kommt ein zweites Problem, das in einem einzigen Dokument unsichtbar bleibt: Wissen hat unterschiedliche Haltbarkeit. Ein Befehl zum Starten der Tests ändert sich mit dem Werkzeug. Eine architektonische Regel gilt, bis sie widerrufen wird. Die Begründung, warum sie so lautet, gilt für immer, weil sie ein historisches Ereignis beschreibt. Liegt das alles nebeneinander, altert das Dokument mit dem Tempo seines flüchtigsten Teils.

Die Trennung nach der Frage, nicht nach dem Thema

Ich teile Projektwissen heute in drei Quellen, und das Kriterium ist nicht das Thema, sondern die Frage, die eine Datei beantwortet.

Die erste Quelle beantwortet: wie arbeite ich mit diesem Repository? Befehle, Gates, was grün sein muss, bevor etwas eingeht. Das ist die kürzeste der drei und die einzige, die ein Agent praktisch immer braucht.

Die zweite beantwortet: wie ist es gebaut und nach welchen Regeln? Das ist der normative Teil: Schichten, erlaubte Abhängigkeitsrichtungen, wie Komponenten kommunizieren dürfen. Hier steht, was gilt, nicht warum es gilt und nicht, ob es schon umgesetzt ist.

Die dritte beantwortet: warum wurde so entschieden? Das sind die Spezifikationen: Alternativen, Abwägungen, verworfene Wege. Sie sind Archiv, kein Arbeitsdokument. Ein Agent, der ein Ticket umsetzt, muss sie nicht lesen; ein Mensch, der eine Regel in Frage stellt, schon.

Die Regel, die den Aufbau zusammenhält, lautet: diese drei niemals vermischen. Eine Regel im normativen Teil erklärt ihre Begründung nicht, sie verlinkt sie. Sobald eine Datei anfängt, zwei dieser Fragen gleichzeitig zu beantworten, ist sie auf dem Weg zurück zum großen Dokument.

Der normative Teil ist dabei selbst wieder aufgeteilt, entlang derselben Logik: allgemeine Regeln getrennt von den Beschreibungen einzelner Bausteine. Architektonische Leitplanken, also die Prüfliste vor jedem Pull Request, sind ein eigenes Dokument und kein Abschnitt in einer Baustein-Beschreibung. Sie gelten überall und dürfen deshalb nirgends spezifisch einsortiert sein.

Auf der Festplatte sieht das ungefähr so aus:

AGENTS.md                  → Wie arbeite ich mit dem Repo? (Befehle, Gates)
context/
  README.md                → Index: eine Zeile pro Datei
  core/
    architecture.md        → Was gilt: Schichten, Abhängigkeitsrichtungen
    guardrails.md          → Prüfliste vor jedem Pull Request
  modules/
    <modul>.md             → Was dieser Baustein ist, seine Fallstricke
docs/specs/
  YYYY-MM-DD-<thema>.md    → Warum so entschieden, Alternativen

Die Ordnernamen sind beliebig. Wichtig ist die Spalte rechts: Jede Datei hat genau eine Frage, die sie beantwortet, und keine zweite.

Der Index ist der eigentliche Mechanismus

Verteilen allein bringt nichts. Zwanzig Dateien statt einer sind schlimmer als eine, wenn der Agent nicht weiß, welche er öffnen soll. Dann liest er entweder alle oder rät.

Was die Aufteilung funktionsfähig macht, ist eine Indexdatei: eine Tabelle mit einer Zeile pro Dokument, die in einem Satz sagt, was darin steht. Nicht mehr als das, und vor allem keine Zusammenfassung des Inhalts, denn dann liest der Agent am Ende doch wieder alles auf einmal.

Der Agent liest den Index, wählt zwei oder drei Dateien und ignoriert den Rest. Das ist der ganze Trick. Über die Qualität der Arbeit entscheidet nicht die Menge des Kontexts, sondern wie genau ausgewählt wurde.

Damit dieser Index nicht selbst verrottet, hängt an ihm eine Regel: Wer eine Datei anlegt, ergänzt im selben Schritt die Zeile im Index. Eine nicht indizierte Datei existiert für den Agenten faktisch nicht.

Eine zweite Regel hält das Ganze ehrlich: Kontext wird im selben Ticket geschrieben wie der Code, den er beschreibt. Keine Dokumentation für Funktionalität, die es noch nicht gibt. Das klingt nach Disziplin, ist aber vor allem eine Entlastung. Es gibt keinen Rückstand, der irgendwann aufgeholt werden müsste, und keine Datei, die Absichten statt Zustände beschreibt.

Dazu gehört die Regel, die ich am längsten gebraucht habe: In den normativen Teil kommen keine Statusangaben. Kein "noch nicht umgesetzt", keine Ticketnummern. Status gehört ins Ticketsystem. Sobald er in die Regeln wandert, altert das Dokument bei jedem Sprint, und ein Agent kann nicht mehr unterscheiden, ob eine Zeile eine Norm oder eine Notiz ist.

Wer prüft, ob die Regeln eingehalten wurden

Regeln aufschreiben heißt nicht, dass sie befolgt werden. Aufgefangen wird das in der letzten Phase jeder Aufgabe: einem Review-Durchgang, der die Änderung gegen genau diese architektonischen Leitplanken prüft. Punkt für Punkt, gegen ein Dokument, das existiert. Nicht allgemein gegen Codequalität.

Das ist der Grund, warum sich die Trennung überhaupt auszahlt. Eine Prüfliste, die in einem großen Dokument zwischen Befehlen und Begründungen steht, kann man nicht durchgehen. Eine, die für sich steht, schon.

Dann fallen die stillen Abweichungen auf: die, die eine grüne Test-Suite übersieht, weil sie nichts kaputtmachen und nur eine Grenze verschieben.

Genau hier liegt auch die Antwort auf die Frage, wem die Architektur gehört, wenn Agenten den Code schreiben. Sie gehört dem, der festlegt, was laut scheitern muss. Ein grünes Gate ist notwendig und nie hinreichend; jede Garantie, die die Architektur gibt, braucht einen Anker, der bricht, wenn sie verletzt wird. Diese Anker zu wählen, ist die Arbeit, die nicht delegiert wird. Die Umsetzung darunter schon.

Der unangenehme Teil der Rechnung

Die Pflege selbst kostet wenig, weil sie Teil der Aufgabe ist und nicht danach kommt. Der Preis liegt woanders, und er ist unangenehmer.

Der Kontext wird verbindlich. Ein veralteter Kommentar im Code ist harmlos, weil ein Entwickler ihn überliest. Eine veraltete Regel in einem normativen Dokument wird befolgt: zuverlässig, wörtlich und ohne Rückfrage. Damit verschiebt sich der Fehler von "der Agent hat es nicht gewusst" zu "der Agent hat gemacht, was dastand". Der zweite ist schwerer zu finden, weil das Ergebnis vollkommen konsistent aussieht.

Der zweite Preis: Die Konstruktion hört nicht auf zu wachsen. Sie wächst jetzt verteilt statt an einer Stelle, was die Wirkung verzögert, aber nicht aufhebt. Irgendwann ist auch der Index lang, und dann steht dieselbe Frage noch einmal an, nur eine Ebene höher.

Wo ich das nicht machen würde

Bei einem kleinen Projekt mit klarem, begrenztem Umfang ist der Aufwand nicht gerechtfertigt. Wenn der ganze Code in eine Sitzung passt und die Regeln in einen Absatz, ist die Aufteilung reine Zeremonie: Man baut einen Index für ein Dokument, das man auch am Stück lesen könnte.

Die Schwelle liegt dort, wo ein Agent anfängt, bei jeder Aufgabe Dinge zu lesen, die mit ihr nichts zu tun haben. Vorher löst die Struktur ein Problem, das man noch nicht hat.

Weglassen können, nicht alles wissen

Die Frage ist nicht, wie ich einem Agenten möglichst viel Kontext gebe. Sie lautet, wie ich ihm ermögliche, das Richtige wegzulassen. Das ist eine Strukturfrage, keine Mengenfrage, und sie wird mit größeren Kontextfenstern nicht kleiner. Ein Modell, das alles lesen kann, gewichtet deshalb noch lange nicht richtig.

Was dabei am meisten überrascht hat: Der Aufbau ist für Menschen genauso nützlich geworden. Die Trennung nach der beantworteten Frage ist keine Konzession an die Maschine, sondern die Ordnung, die man ohnehin hätte haben sollen.