Der größte Hebel bei Coding Agents ist nicht das Modell, sondern der Kontext

Ein Team betreibt einen Coding Agent mit einem aktuellen Spitzenmodell. Der Agent kennt die gesamte Repository-Historie, alle Tickets der letzten Monate, Architekturentscheidungen, CI-Logs und den Chatverlauf des Tages. Trotzdem produziert er große, unsichere Änderungen, fragt selten nach und korrigiert sich oft erst nach mehreren Schleifen.

Die naheliegende Reaktion lautet: ein besseres Modell, mehr Kontextfenster, mehr Tool-Aufrufe.

In vielen Fällen ist das die falsche Diagnose.

Der größte Hebel bei Coding Agents ist häufig nicht das Modell, sondern die Qualität und Zuschnitt des Kontexts. Ein starkes Modell mit zu viel irrelevanter Historie kann teurer und schlechter arbeiten als ein kleinerer, spezialisierter Agent mit einem präzisen Briefing.

Das ist keine Aussage gegen leistungsfähige Modelle. Sie sind wichtig. Aber ein Modell kann nicht zuverlässig entscheiden, welche von 80.000 gelieferten Tokens für die aktuelle Änderung tatsächlich normativ sind. Je mehr widersprüchliche, veraltete oder nebensächliche Informationen wir in den Kontext legen, desto mehr Interpretationsarbeit verlagern wir in das Modell.

Genau dort beginnt Kontextarchitektur.

Kontext ist kein Speicherplatz

Viele Agenten-Implementierungen behandeln das Kontextfenster wie eine größere Festplatte: Was vorhanden ist, wird angehängt. Repository-Tree, Dateien, Chatverlauf, Suchtreffer, Tickets und Tool-Ausgaben wandern in einen immer längeren Prompt.

Das ist technisch einfach, aber architektonisch schwach.

Kontext erfüllt unterschiedliche Funktionen:

• Normativer Kontext definiert, was gelten muss: Schnittstellen, Sicherheitsregeln, Domäneninvarianten, Coding-Standards.
• Arbeitskontext beschreibt die konkrete Aufgabe: gewünschtes Verhalten, Akzeptanzkriterien, betroffene Komponenten, bekannte Risiken.
• Evidenz liefert die Fakten zur Umsetzung: relevante Dateien, Tests, aktuelle Implementierung, Compiler- oder Laufzeitfehler.
• Historischer Kontext erklärt, warum etwas einmal entschieden wurde.
• Nebeninformation kann nützlich sein, ist für die aktuelle Entscheidung aber nicht erforderlich.

Diese Kategorien sollten nicht gleich behandelt werden. Ein API-Vertrag und ein drei Monate alter Slack-Thread sind nicht gleichwertig. Werden beide als unstrukturierter Text geliefert, muss das Modell die Gewichtung selbst erraten.

Das kostet Tokens, Latenz und vor allem Zuverlässigkeit.

Warum zu viel Kontext die Qualität senken kann

Mehr Kontext erhöht nicht linear die Qualität. Ab einem Punkt entstehen mehrere bekannte Effekte.

Relevanz wird verdünnt

Wenn die relevante Regel in einer langen Sammlung aus ähnlichen Regeln, alten Tickets und generischen Dokumenten steckt, sinkt ihre praktische Sichtbarkeit. Das Modell kann sie zwar theoretisch lesen, aber es muss sie gegen konkurrierende Signale abwägen.

Ein typischer Fall: Das Repository enthält drei Dokumente zur Authentifizierung. Eines beschreibt den aktuellen OAuth-Flow, eines eine abgelöste Session-Strategie und eines eine geplante Zielarchitektur. Ohne klare Kennzeichnung ist nicht die Wissenslücke das Problem, sondern die Mehrdeutigkeit.

Veraltete Informationen erhalten unverdientes Gewicht

Historie ist wertvoll, aber nicht automatisch handlungsleitend. Alte Incident-Analysen, geschlossene Tickets oder frühere Architekturentscheidungen können aktive Regeln überlagern. Besonders problematisch wird das, wenn ein Agent in einem Chatverlauf bereits einen falschen Pfad eingeschlagen hat und diese Annahme bei jeder weiteren Runde erneut mitliefert.

Tool-Ausgaben erzeugen Kontextmüll

Build-Logs, rekursive Dateilisten und breite Suchergebnisse werden häufig ungefiltert in den Prompt übernommen. Ein 5.000-Zeilen-Log enthält vielleicht zwei relevante Fehlermeldungen. Der Rest ist keine Evidenz, sondern Rauschen.

Kosten und Latenz steigen in jeder Schleife

Bei agentischen Workflows wird Kontext nicht einmal, sondern wiederholt verarbeitet. Ein übergroßer Arbeitskontext wird bei Planung, Implementierung, Review und Fehlerkorrektur immer wieder bezahlt.

Vereinfacht:

Gesamtkosten ≈ Anzahl der Modellaufrufe × (Eingabe-Tokens + Ausgabe-Tokens)

Wenn ein Agent zehn Schleifen macht und jedes Mal 40.000 unnötige Eingabe-Tokens trägt, ist das kein kleines Optimierungsproblem. Es prägt die Wirtschaftlichkeit des gesamten Systems.

Die zentrale Designfrage: Was muss dieser Agent jetzt wissen?

Nicht: „Welche Informationen haben wir?"

Sondern: „Welche Informationen braucht dieser Agent, um diese konkrete Entscheidung korrekt zu treffen?"

Diese Frage führt zu einer anderen Architektur. Statt eines universellen Agents mit maximalem Gedächtnis entstehen spezialisierte Rollen mit kleinen, überprüfbaren Kontextpaketen.

Ein möglicher Zuschnitt:

Diese Agenten brauchen nicht denselben Kontext. Ein Review-Agent muss nicht den kompletten Explorationsverlauf sehen. Ein Implementierungs-Agent muss nicht jede frühere Diskussion zur Produktstrategie kennen. Der Triage-Agent darf Unsicherheit sichtbar machen, statt sie durch massiven Kontext zu kaschieren.

Spezialisierung reduziert nicht nur Kosten. Sie macht Fehler besser lokalisierbar: War die Recherche falsch, das Briefing unklar oder die Umsetzung fehlerhaft?

Kanonische Informationen: Eine Quelle mit klarer Geltung

Der wichtigste Baustein einer Kontextarchitektur sind kanonische Quellen. Das sind Informationen, die für einen bestimmten Bereich verbindlich gelten und deren Status eindeutig ist.

Für ein Software-System sind das häufig:

• API-Verträge und Schema-Definitionen
• Architekturentscheidungen in kurzen, versionierten ADRs
• Domäneninvarianten und fachliche Begriffe
• Sicherheits- und Compliance-Regeln
• Ownership und Grenzen zwischen Teams oder Services
• Build-, Test- und Deployment-Anweisungen
• Migrationsregeln für Daten und Schnittstellen

Kanonisch bedeutet nicht zwingend „ein Wiki-Dokument“. Im Idealfall liegt die Information dort, wo sie technisch geprüft werden kann:

• OpenAPI-Spezifikationen statt Beschreibungen in Tickets
• Datenbank-Migrationen und Constraints statt implizitem Wissen
• Contract-Tests statt alleiniger Konventionen
• Linter- und Policy-Regeln statt langer Stilhandbücher
• Versionierte ADRs im Repository statt verstreuter Chat-Entscheidungen

Für Agents ist das entscheidend. Sie brauchen nicht nur Wissen, sondern eine Antwort auf die Frage: Welche Quelle gewinnt bei Widerspruch?

Eine einfache Prioritätsregel kann bereits viel bewirken:

1. Ausführbare Verträge, Tests und Policies
2. Aktuelle, versionierte Architektur- und Domänendokumentation
3. Ticket mit Akzeptanzkriterien
4. Relevanter Quellcode
5. Historische Diskussionen und Suchtreffer

Diese Reihenfolge muss nicht für jedes Unternehmen identisch sein. Sie sollte aber explizit sein. Ohne sie wird der Agent zum Schiedsrichter zwischen Quellen, die Menschen selbst nie konsolidiert haben.

Was in das Briefing gehört

Ein gutes Agent-Briefing ist keine Zusammenfassung aller verfügbaren Informationen. Es ist ein Arbeitsvertrag für eine konkrete Aufgabe.

Für eine typische Implementierungsaufgabe reichen oft diese Elemente:

1. Zielzustand: Welches beobachtbare Verhalten soll nach der Änderung gelten?
2. Scope: Welche Komponenten, Dateien oder Schnittstellen sind betroffen – und welche ausdrücklich nicht?
3. Invarianten: Was darf nicht verletzt werden? Etwa Mandantentrennung, Rückwärtskompatibilität oder Berechtigungslogik.
4. Kanonische Quellen: Welche Spezifikationen, ADRs oder Tests sind verbindlich?
5. Akzeptanzkriterien: Wie wird Erfolg geprüft?
6. Arbeitsregeln: Darf der Agent Datenbankschemata ändern, neue Abhängigkeiten einführen oder externe APIs aufrufen?
7. Offene Fragen: Was ist bewusst unklar und muss eskaliert werden?

Beispiel:

Ziel: Der Endpoint `POST /orders` soll bei doppelter Idempotency-Key
keine zweite Bestellung anlegen und die ursprüngliche Antwort liefern.
 
Scope: `orders-api`, `order-service`, zugehörige Integrationstests.
Nicht im Scope: Änderungen am Payment Provider oder am öffentlichen API-Schema.
 
Invarianten:
- Mandanten dürfen niemals gegenseitige Bestellungen lesen.
- Bestehende Clients müssen unverändert funktionieren.
 
Verbindliche Quellen:
- `contracts/orders.openapi.yaml`
- `docs/adr/0042-idempotency.md`
- `tests/integration/orders_idempotency_test.ts`
 
Akzeptanz:
- Zwei identische Requests erzeugen genau einen Datensatz.
- Abweichender Request-Body mit gleichem Key liefert einen definierten Fehler.
- Integrationstests und Linter laufen grün.

Das ist deutlich wertvoller als ein pauschales „Analysiere das Repository und implementiere Idempotency“.

Was ausgelagert gehört

Nicht jede Information muss im Modellkontext liegen. Vieles ist besser als Tool, Index oder deterministische Prüfung aufgehoben.

Große Dokumentbestände: Retrieval statt Dauerbeilage

Produktdokumentation, alte ADRs, Runbooks und Tickets sollten durchsuchbar sein, aber nicht standardmäßig in jeder Unterhaltung landen. Retrieval muss dabei nicht nur semantisch sein. Für Code sind symbolbasierte Suche, Import-Graphen, Ownership-Metadaten und Dateipfade oft präziser als reine Vektorähnlichkeit.

Entscheidend ist, dass Retrieval Quellen mitliefert: Dateiname, Version, Gültigkeitsstatus und idealerweise einen Auszug statt eines vollständigen Dokuments.

Laufzeitfakten: Abfragen statt Annahmen

„Wie viele Kunden nutzen diese API-Version?“ oder „Welche Feature Flags sind aktiv?“ sind keine Wissensfragen für den Prompt. Sie sind Abfragen gegen Observability-, Konfigurations- oder Deployment-Systeme. Das Ergebnis sollte strukturiert und zeitlich eingeordnet in den Arbeitskontext kommen.

Regeln: Wenn möglich erzwingen statt beschreiben

Eine Regel wie „Keine PII in Logs“ sollte nicht nur als Satz im System Prompt stehen. Sie gehört in Logging-Bibliotheken, Code-Scanning, Tests und Review-Gates. Der Agent darf die Regel kennen; verlassen sollte man sich auf automatisierte Durchsetzung.

Historie: Verdichten statt mitschleppen

Lange Chatverläufe brauchen eine explizite Verdichtung. Diese Zusammenfassung sollte nicht bloß kürzer sein, sondern Status enthalten:

• bestätigte Fakten
• getroffene Entscheidungen
• verworfene Optionen mit Grund
• offene Annahmen
• nächste Prüfschritte

Der Rohverlauf bleibt abrufbar, ist aber kein permanenter Teil des aktiven Kontextes.

Kontextkompression braucht Verantwortlichkeit

Zusammenfassungen können selbst Fehler einführen. Deshalb darf ein Agent nicht beliebig aus seiner eigenen Zusammenfassung zitieren und sie damit zur Wahrheit machen.

Praktisch hilft ein einfaches Datenmodell für Kontextartefakte:

Quelle: docs/adr/0042-idempotency.md
Gültig ab: 2026-04-12
Status: kanonisch
Aussage: Idempotency Keys gelten pro Mandant und Endpoint.
Vertrauen: hoch

Eine vom Agenten erzeugte Arbeitsnotiz sieht anders aus:

Quelle: Agent-Zusammenfassung aus Recherchelauf 3
Status: abgeleitet
Aussage: Der bestehende Redis-Key enthält vermutlich keinen Endpoint.
Vertrauen: mittel
Zu prüfen in: src/idempotency/key.ts

Die Unterscheidung zwischen Quelle, Ableitung und Hypothese verhindert, dass Vermutungen im nächsten Schleifendurchlauf als feste Anforderungen erscheinen.

Ein Referenzablauf für Coding Agents

Ein belastbarer Ablauf kann so aussehen:

1. Triage: Anfrage klassifizieren, Risiken und betroffene Domänen bestimmen.
2. Kontextplan: Festlegen, welche kanonischen Quellen und welche Codebereiche benötigt werden.
3. Recherche: Gezielt Dateien, Symbole, Tests und Dokumente abrufen. Breite Treffer zunächst nur als Metadaten behandeln.
4. Briefing erzeugen: Ziel, Scope, Invarianten, Quellen und offene Fragen in ein kompaktes Arbeitsartefakt überführen.
5. Implementierung: Nur mit dem für die Änderung relevanten Kontext arbeiten.
6. Deterministische Validierung: Build, Tests, Linter, Security-Checks und Contract-Tests ausführen.
7. Review: Diff gegen Zielarchitektur und Regeln prüfen; keine vollständige Recherchehistorie beilegen, sofern sie nicht relevant ist.
8. Lernen: Wiederkehrende Rückfragen und Fehler als Lücken in Dokumentation, Tooling oder Briefing-Vorlagen behandeln.

Wichtig: Nicht jeder Schritt muss ein eigenes Modell oder ein eigener Agent sein. Die Trennung ist zunächst eine Verantwortungsgrenze. Sie kann innerhalb eines Orchestrators, über mehrere Agenten oder teilweise deterministisch umgesetzt werden.

Kostenoptimierung beginnt vor der Modellauswahl

In Beratungsprojekten wird Kostenoptimierung oft als Tarifvergleich diskutiert: Welches Modell kostet wie viel pro Million Tokens? Das ist relevant, aber nachgelagert.

Die wirksameren Fragen sind:

• Wie oft wird derselbe Kontext erneut übertragen?
• Welche Tool-Ausgaben werden ungekürzt angehängt?
• Welche Informationen könnten als ID, Verweis oder strukturierte Abfrage statt als Fließtext vorliegen?
• Welche Aufgaben benötigen tatsächlich ein Spitzenmodell?
• Welche Prüfungen lassen sich deterministisch erledigen?
• Welche Fehler verursachen zusätzliche Agent-Schleifen?

Ein kleineres Modell mit einem klaren Auftrag kann für Klassifikation, Extraktion, Testauswertung oder einfache Refactorings ausreichend sein. Ein stärkeres Modell wird dann gezielt für Architekturentscheidungen, schwierige Fehleranalyse oder mehrdeutige Änderungen eingesetzt.

Das ist kein pauschales Routing nach Komplexitätsgefühl. Gute Systeme erfassen Signale: Anzahl betroffener Komponenten, Sicherheitsrelevanz, Unsicherheit der Recherche, fehlende Tests, Konflikte zwischen Quellen und Fehlerraten vergangener Läufe.

Messen statt vermuten

Kontextarchitektur ist eine technische Disziplin und sollte entsprechend beobachtbar sein. Sinnvolle Kennzahlen sind:

• Eingabe-Tokens pro erfolgreicher Änderung
• Anzahl der Agent-Schleifen bis zum grünen Testlauf
• Anteil der abgerufenen Quellen, die im finalen Ergebnis tatsächlich referenziert wurden
• Quote widersprüchlicher oder veralteter Retrieval-Treffer
• Anteil der Aufgaben mit Eskalation wegen fehlender Information
• Defect-Rate und Review-Nacharbeit pro Änderungstyp
• Latenz vom Auftrag bis zu einem validierten Diff

Eine besonders hilfreiche Metrik ist die Kontextnutzung: Welche gelieferten Quellen haben eine nachweisbare Rolle in Planung, Implementierung oder Review gespielt? Wenn ein System regelmäßig 30 Dokumente abruft, aber nur zwei relevant sind, ist nicht das Modell zu schwach. Das Retrieval oder die Kontextselektion ist zu breit.

Der organisatorische Teil wird oft unterschätzt

Kontextprobleme sind selten nur Prompt-Probleme. Sie machen Wissensprobleme im Unternehmen sichtbar:

• Architekturentscheidungen sind nicht versioniert.
• Teams verwenden unterschiedliche Begriffe für dieselbe Domäne.
• Tickets enthalten Anforderungen, die nie in Verträge oder Tests überführt wurden.
• Ownership ist unklar.
• Dokumentation beschreibt Wunschzustände statt Ist-Zustände.

Ein Agent verstärkt diese Schwächen, weil er keine impliziten sozialen Korrekturmechanismen besitzt. Ein erfahrener Entwickler fragt im Zweifel die zuständige Person. Ein Agent braucht entweder eine eindeutige Quelle oder einen expliziten Eskalationspfad.

Deshalb ist AI Architecture nicht bloß die Auswahl eines Modellproviders. Sie umfasst Informationsflüsse, Gültigkeit von Wissen, Tool-Grenzen, Berechtigungen, Qualitätsgates und Verantwortlichkeiten.

Fazit

Ein großes Kontextfenster ist eine Kapazität, keine Architektur.

Die entscheidende Frage bei Coding Agents lautet nicht, wie viel Wissen man in einen Prompt bekommt. Sie lautet, welche Information für die aktuelle Entscheidung verbindlich, relevant und überprüfbar ist.

Wer Kontext als gezielt konstruiertes Arbeitsmittel behandelt, erzielt meist drei Effekte gleichzeitig: bessere Änderungen, niedrigere Kosten und besser nachvollziehbare Fehler. Das Modell bleibt wichtig. Aber in produktiven Systemen ist es nur ein Teil der Lösung.

Der nachhaltige Hebel liegt davor: in kanonischen Quellen, klaren Agentenrollen, kleinen Briefings, gutem Retrieval und deterministischen Prüfungen.