Kontext ist alles.

3.1 Warum Kontext über Qualität entscheidet

Ein Sprachmodell hat kein Gedächtnis zwischen zwei Aufrufen und kein Wissen über dein Projekt, das nicht im Aufruf selbst steht. Was es über deine Anwendung „weiß“, stammt aus genau zwei Quellen: aus seinem allgemeinen Training (Sprachen, Frameworks, verbreitete Muster) und aus dem, was im Kontextfenster dieses einen Laufs liegt. Ein Coding-Agent erweitert das Kontextfenster zwar selbst, indem er Dateien liest, Befehle ausführt und Ergebnisse auswertet (siehe Kapitel 2). Aber was er liest, wonach er sucht und wie er das Gefundene gewichtet, hängt davon ab, womit du ihn startest.

Das klingt banal, hat aber weitreichende Folgen. Stell dir vor, du gibst einem erfahrenen Entwickler, der deine Firma nie betreten hat, nur einen Satz: „Bau eine Benutzerverwaltung.“ Er wird etwas Vernünftiges bauen — aber eben sein Vernünftiges. Vielleicht mit einem anderen Framework, einem anderen Paketschema, einer eigenen Passwort-Logik statt eurem SSO, englischen Kommentaren in einem deutschsprachigen Team. Nichts davon ist „falsch“ im Sinne von kaputt. Alles davon ist falsch im Sinne von „passt nicht zu uns“. Ein Agent verhält sich genauso, nur schneller und ohne nachzufragen.

Müll rein, Müll raus — in drei Varianten

Bei klassischen Programmen meint „Garbage in, garbage out“ fehlerhafte Eingabedaten. Bei Agenten gibt es drei typische Ausprägungen:

• Fehlender Kontext. Der Agent rät. Er wählt plausible Standards — die nicht deine sind. Das Ergebnis ist in sich stimmig, aber fremd: falscher Stack, falsche Struktur, falsche Sprache.
• Widersprüchlicher Kontext. In der README steht „Java 21“, in der Projektbeschreibung „Java 25“, in einer alten Anleitung „Java 17“. Der Agent entscheidet sich für eine Variante — welche, ist kaum vorhersehbar. Widersprüche sind schlimmer als Lücken, weil sie das Ergebnis zufällig machen.
• Überladener Kontext. Zwanzig Seiten Firmenrichtlinien, alte Protokolle und ganze Wikis „zur Sicherheit“. Das Wichtige geht im Unwichtigen unter, das Kontextbudget ist verbraucht, bevor der Agent die eigentliche Aufgabe angeht, und jede zusätzliche Zeile erhöht die Chance auf Widersprüche.

Guter Kontext ist deshalb nicht viel Kontext, sondern zutreffender, knapper und widerspruchsfreier Kontext. Diese drei Eigenschaften ziehen sich durch das ganze Kapitel.

3.2 Welche Arten von Kontext es gibt

Es hilft, Kontext nicht als einen großen Textblock zu denken, sondern als Schichten mit unterschiedlicher Lebensdauer und unterschiedlichem Zweck. Je stabiler eine Information ist, desto weiter „unten“ gehört sie hin — und desto seltener sollte sie sich ändern.

Zwei Beobachtungen dazu. Erstens: Der Auftrag ist die einzige Schicht, die sich bei jedem Lauf ändert. Wer alles in den Auftrag packt, schreibt bei jedem Lauf dieselben Grundlagen neu — und jedes Mal ein bisschen anders. Zweitens: Die Schichten haben eine natürliche Rangfolge. Eine projektspezifische Entscheidung („wir verwenden hier bewusst keine Lombok-Annotationen“) sollte eine allgemeine Leitplanke übersteuern können, nicht umgekehrt. Diese Rangfolge muss irgendwo ausdrücklich stehen, sonst entscheidet der Agent sie selbst.

Konventionen als Kontext

Viele Teams haben Konventionen, die nirgends aufgeschrieben sind: wie Tests heißen, wo DTOs liegen, ob Commit-Nachrichten Deutsch oder Englisch sind, welche Bibliotheken unerwünscht sind. Menschen lernen das durch Code-Reviews und Mitlesen. Ein Agent kann das nur, wenn er genug repräsentativen Bestandscode liest — und selbst dann übernimmt er Fehler der Vergangenheit ebenso bereitwillig wie gute Muster. Aufgeschriebene Konventionen sind deshalb für Agenten wertvoller als für Menschen. Sie sind ein Hebel mit langer Wirkung: einmal sauber formuliert, wirken sie in jedem Lauf.

Gedächtnis als Kontext

Ein Agent startet jeden Lauf bei null. Alles, was in Lauf 1 mühsam herausgefunden wurde — dass ein bestimmter Test flackert, dass ein Modul nicht angefasst werden soll, dass man sich gegen eine Bibliothek entschieden hat — ist in Lauf 2 vergessen, wenn es nicht irgendwo festgehalten wird. Ein gepflegtes Projektgedächtnis ist die Antwort darauf: eine kuratierte, kurze Liste von Entscheidungen und Erkenntnissen, die jedem Folgelauf mitgegeben wird. Kuratiert heißt: Ein Mensch entscheidet, was dauerhaft gilt. Ein Gedächtnis, in das jeder Lauf ungefiltert hineinschreibt, wächst zu genau dem überladenen Kontext, vor dem 3.1 warnt.

3.3 Eine gute Projektbeschreibung schreiben

Die Projektbeschreibung ist die Charta des Vorhabens. Sie beantwortet die Fragen, die ein neues Teammitglied in der ersten Woche stellen würde. Für Agenten gelten dabei ein paar Regeln, die über normales „gutes Schreiben“ hinausgehen.

Konkret statt wohlklingend

„Moderne, skalierbare, sichere Architektur“ ist für einen Agenten wertlos — jede Architektur hält sich selbst für modern, skalierbar und sicher. Wertvoll ist: „Hexagonal (Ports & Adapters), Basis-Paket io.beispiel.maint, REST unter /api/v1, keine JPA-Annotationen in der Domäne.“ Faustregel: Wenn ein Satz für jedes beliebige Projekt stimmen würde, trägt er nichts bei.

Versionen und Namen ausschreiben

Agenten kennen viele Versionen eines Frameworks und mischen sie gern. Schreib die Version hin, die du willst, und den Build-Befehl, der grün sein muss. Je näher eine Angabe an etwas Prüfbarem ist, desto zuverlässiger wird sie eingehalten.

Nicht-Ziele benennen

Agenten neigen zu Übererfüllung: Sie fügen „der Vollständigkeit halber“ Features, Konfigurationsoptionen oder Abstraktionen hinzu. Ein Abschnitt, der klar sagt, was nicht gebaut wird („kein Mehrmandantenbetrieb in Version 1“, „keine eigene Benutzerverwaltung, Login nur über OIDC“), ist eine der wirksamsten Maßnahmen gegen Scope-Creep. In Specs ist der Abschnitt „Nicht-Ziele“ deshalb Pflicht (Kapitel 4).

Domänensprache festlegen

Heißt es „Auftrag“, „Ticket“ oder „Job“? „Kunde“ oder „Mandant“? Wenn die Beschreibung die Begriffe festlegt, übernimmt der Agent sie in Klassennamen, Tabellen und Oberflächen. Wenn nicht, erfindet er eigene — und du hast ab dem zweiten Lauf zwei Begriffe für dieselbe Sache.

Sicherheits- und Qualitätsanforderungen gehören dazu

Dass Passwörter nicht im Klartext gespeichert werden, „weiß“ jedes Modell. Dass ihr ausschließlich über OIDC anmeldet, die Rollen ADMIN und DISPONENT habt und WCAG 2.1 AA einhalten müsst, weiß es nicht. Projektspezifische Anforderungen sind genau die, die ohne Aufschreiben verloren gehen.

Schwach:  "Eine sichere, moderne Web-App für Wartungsaufträge."

Stark:    "Web-Portal + REST-API zur Verwaltung von Wartungsaufträgen.
           Disponenten planen im Web; die API bedient später eine Mobile-App.
           Backend Spring Boot / Java 21 / PostgreSQL / Maven, hexagonal,
           Basis-Paket io.beispiel.maint, REST unter /api/v1.
           Login nur OIDC, Rollen ADMIN und DISPONENT.
           Nicht in Version 1: Mobile-App, Mehrmandantenbetrieb."

3.4 Das Kontextbudget: was hineingehört und was nicht

Jedes Modell hat ein begrenztes Kontextfenster, gemessen in Tokens. Was hineinpasst, ist zwar mit den Modellgenerationen gewachsen, aber zwei Dinge bleiben: Erstens kostet jedes Token Zeit und — je nach Abrechnung — Geld, und zwar in jedem Schritt der Agenten-Schleife erneut, weil der bisherige Verlauf immer wieder mitgeschickt wird (Caching mildert das, siehe Kapitel 10). Zweitens werden Modelle mit sehr langen Kontexten nicht automatisch besser: Informationen in der Mitte langer Texte werden erfahrungsgemäß weniger zuverlässig berücksichtigt als am Anfang oder Ende, und jede zusätzliche Information konkurriert mit der eigentlichen Aufgabe um Aufmerksamkeit.

Daraus ergibt sich eine einfache Haushaltsregel: Der feste Kontext, der in jeden Lauf geht, soll klein und hochwertig sein. Der variable Kontext — Bestandscode, Logs, Dokumentation — soll der Agent sich bei Bedarf selbst holen, indem er Dateien liest und sucht.

Grafik in voller Größe öffnenGrafik in voller Größe öffnen

Gehört in den festen Kontext

• Zielbild und Nicht-Ziele in wenigen Sätzen
• Stack, Versionen, Build- und Testbefehl
• Architekturregeln, die nicht aus dem Code ablesbar sind
• Verhaltensleitplanken (kleine Änderungen, Annahmen offenlegen, Erfolg prüfbar machen)
• kuratierte Entscheidungen aus dem Gedächtnis
• die Akzeptanzkriterien dieses Auftrags — nicht die aller Features

Gehört nicht in den festen Kontext

• ganze Wikis, Protokolle, E-Mail-Verläufe
• Informationen, die im Code stehen und dort gelesen werden können
• veraltete Anleitungen „zur Sicherheit“
• Geheimnisse jeder Art (API-Keys, Passwörter, Tokens) — mehr dazu in Kapitel 8
• Wiederholungen derselben Regel in leicht unterschiedlicher Formulierung

Widersprüche aktiv suchen

Die gefährlichste Form schlechten Kontexts ist der Widerspruch, den niemand bemerkt. Er entsteht fast immer, wenn dieselbe Information an mehreren Stellen gepflegt wird: im Wiki, in der README, in einer Werkzeug-spezifischen Konfigurationsdatei, im Prompt. Die wirksamste Gegenmaßnahme ist strukturell: eine Quelle, mehrere Projektionen. Jede Information wird an genau einer Stelle gepflegt und von dort automatisch dorthin verteilt, wo sie gebraucht wird. Genau dieses Prinzip verfolgt die Fabrik mit ihren Artefakten und Guardrails.

3.5 AGENTS.md: eine Konvention für alle Werkzeuge

Fast jedes Coding-Werkzeug liest beim Start eine Projektdatei mit Hinweisen ein — aber jedes hat historisch seine eigene: Claude Code liest CLAUDE.md, Gemini CLI GEMINI.md, andere Werkzeuge eigene Dateien oder Konfigurationsverzeichnisse. Wer mehrere Werkzeuge einsetzt, pflegt schnell drei Dateien mit fast demselben Inhalt — und hat nach wenigen Wochen drei leicht unterschiedliche Wahrheiten.

AGENTS.md hat sich als werkzeugübergreifende Konvention dafür etabliert: eine schlichte Markdown-Datei im Repository-Wurzelverzeichnis, die beschreibt, wie in diesem Projekt gearbeitet wird — Build- und Testbefehle, Konventionen, Verbote, Hinweise. Viele Werkzeuge lesen sie direkt, andere lassen sich per Konfiguration darauf verweisen oder bekommen eine kleine eigene Datei, die nur auf AGENTS.md zeigt.

Was in eine gute AGENTS.md gehört

• Befehle: wie man baut, testet, formatiert — exakt, kopierbar.
• Struktur: wo was liegt, welche Module tabu sind.
• Konventionen: Benennung, Testmuster, Commit-Format.
• Grenzen: was der Agent nicht tun darf (z. B. bestehende Datenbank-Migrationen ändern).
• Verweise: wo ausführlichere Dokumente liegen, statt sie einzukopieren.

Was nicht hineingehört

Alles, was eine eigene, bessere Heimat hat: Anforderungen gehören in Specs, Entscheidungen mit Begründung in ADRs, Lernerfahrungen in ein Gedächtnis. AGENTS.md ist die Bedienungsanleitung des Repositorys für Agenten, kein Sammelbecken.

3.6 Leitplanken: Verhalten statt Inhalt

Projektbeschreibung und Konventionen sagen dem Agenten, was und womit er bauen soll. Leitplanken (Guardrails) sagen ihm, wie er sich dabei verhalten soll — unabhängig vom Projekt. Typische Fehlverhalten von Coding-Agenten sind erstaunlich konstant über Modelle und Werkzeuge hinweg:

• Stilles Raten: Bei Mehrdeutigkeit wird eine Interpretation gewählt, ohne sie zu nennen.
• Übererfüllung: zusätzliche Features, Abstraktionen „für später“, unnötige Konfigurierbarkeit.
• Kollateralschäden: Nebenbei wird benachbarter Code umformatiert, refaktoriert oder „aufgeräumt“, was Diffs aufbläht und Reviews erschwert.
• Unprüfbarer Erfolg: „Fertig, sollte funktionieren“ — ohne Test, der es belegt.

Gute Leitplanken adressieren genau diese Muster, sind kurz und gelten für jedes Werkzeug gleich. Sie sind Standardverhalten: Ein Projekt darf sie übersteuern, wenn es einen Grund hat. Diese Rangfolge — Projekt vor Leitplanke — muss in den Leitplanken selbst stehen, damit der Agent bei Konflikten nicht abwägen muss.

Ein Detail verdient besondere Aufmerksamkeit: Ein Agent, der autonom läuft, hat niemanden, den er fragen kann. Eine Leitplanke wie „frag nach, wenn etwas unklar ist“ ist für einen Headless-Lauf deshalb sinnlos. Besser ist: „Lege Annahmen offen, wähle bei mehreren Deutungen die konservativste und mach Entscheidungen, die Umfang, Kosten oder Risiko verändern, im Plan und in der PR-Beschreibung unübersehbar.“ Das ist die Idee hinter surface, don't ask.

3.7 Gedächtnis: lernen über Läufe hinweg

Ein Projektgedächtnis schließt die Lücke zwischen zwei Läufen. Es ist kein Protokoll (was ist passiert?), sondern ein Destillat (was gilt seitdem?). Drei Arten von Einträgen haben sich bewährt:

• Entscheidungen: „Wir verwenden Testcontainers mit PostgreSQL statt H2, weil H2 die JSONB-Abfragen nicht unterstützt.“
• Fallstricke: „Der Integrationstest ImportIT braucht eine freie Portrange; nicht parallelisieren.“
• Grenzen: „Das Paket legacy.billing wird abgelöst; nur Fehlerbehebungen, keine neuen Features.“

Gute Einträge sind kurz, datiert oder versioniert und enthalten eine Begründung. Ohne Begründung kann niemand — weder Mensch noch Agent — später entscheiden, ob die Regel noch gilt. Und das Gedächtnis braucht Pflege: Veraltete Einträge sind widersprüchlicher Kontext mit Ansage.

Wer schreibt ins Gedächtnis?

Hier gibt es eine echte Abwägung. Lässt du nur Menschen schreiben, bleibt das Gedächtnis sauber, aber es veraltet, weil niemand Zeit hat. Lässt du Agenten frei schreiben, wird es aktuell, aber es wuchert und enthält bald Halbwahrheiten. Ein guter Mittelweg: Agenten dürfen Vorschläge ergänzen, ein Mensch kuratiert regelmäßig — streicht, präzisiert, fasst zusammen.

3.8 Rollen und Teams als Kontext

„Du bist ein erfahrener Security-Reviewer“ ist mehr als eine Höflichkeitsformel. Eine Rolle bündelt Erwartungen: worauf geachtet wird, was erlaubt ist, wann eskaliert wird. Für Menschen ist das selbstverständlich — ein Reviewer schreibt keinen Feature-Code, ein Architekt plant, bevor gebaut wird. Für Agenten muss es ausdrücklich gesagt werden.

Rollen als Kontext haben zwei Vorteile. Erstens werden Verantwortungen getrennt: Wer schreibt, gibt seine Arbeit nicht selbst frei. Zweitens werden Regeln wiederverwendbar: Die Sicherheitsregeln eines Security-Reviewers schreibst du einmal, nicht in jeden Auftrag neu.

Eine wichtige Einschränkung: Eine Rolle im Prompt ist eine Bitte, keine technische Grenze. Ob ein Reviewer wirklich nichts schreiben kann, entscheiden die Werkzeugrechte, mit denen er gestartet wird, nicht seine Rollenbeschreibung. Rollen und Rechte gehören zusammen — das vertiefen Kapitel 6 (read-only Reviewer) und Kapitel 8 (Permissions).

3.9 Zusammenfassung

• Ein Agent weiß über dein Projekt nur, was in seinem Kontext liegt. Fehlender, widersprüchlicher und überladener Kontext sind die drei Formen von „Müll rein, Müll raus“.
• Denk Kontext in Schichten: Projektbeschreibung, Konventionen, Leitplanken, Gedächtnis, Anforderungen, Auftrag. Stabile Information gehört nach unten, nur der Auftrag ändert sich je Lauf.
• Der feste Kontext soll klein und hochwertig sein; variablen Kontext holt sich der Agent selbst.
• „Eine Quelle, mehrere Projektionen“ verhindert Widersprüche: AGENTS.md als werkzeugübergreifende Datei, aus einer gepflegten Quelle erzeugt.
• In der Fabrik entsteht der Kontext aus Projektdefinition (13 Felder), Prompt-Artefakten, Engineering-Guardrails im Objective-Kopf, Project-Memory und Teams — versioniert, editierbar und attestiert.

Kapitelfragen

1. Nenne die drei Formen von „Müll rein, Müll raus“ bei Agenten und erkläre, warum widersprüchlicher Kontext oft schlimmer ist als fehlender.

   Musterantwort

   Fehlender Kontext (der Agent rät plausible, aber fremde Standards), widersprüchlicher Kontext (mehrere Quellen sagen Verschiedenes) und überladener Kontext (das Wichtige geht unter, Budget wird verbraucht). Widersprüche sind tückischer, weil das Ergebnis zufällig wird: Welche Variante der Agent wählt, ist kaum vorhersehbar und kann von Lauf zu Lauf wechseln. Eine Lücke führt wenigstens reproduzierbar zum selben Standardverhalten und fällt eher auf.

2. Warum sollte der feste Kontext eines Laufs klein sein, obwohl moderne Modelle sehr große Kontextfenster haben?

   Musterantwort

   Jedes Token kostet Zeit und gegebenenfalls Geld, und zwar in jedem Schritt der Agenten-Schleife erneut. Außerdem konkurriert jede zusätzliche Information mit der Aufgabe um Aufmerksamkeit; Informationen in langen Texten werden nicht gleichmäßig zuverlässig berücksichtigt. Mehr Text erhöht zudem die Wahrscheinlichkeit für Widersprüche. Variablen Kontext wie Bestandscode holt sich der Agent ohnehin selbst.

3. Was bedeutet das Prinzip „eine Quelle, mehrere Projektionen“, und wie setzt die Fabrik es bei den Engineering-Guardrails um?

   Musterantwort

   Jede Information wird an genau einer Stelle gepflegt und automatisch dorthin verteilt, wo sie gebraucht wird, statt mehrere Kopien zu pflegen. Die Guardrails liegen als eine versionierte Quelle vor; die Fabrik setzt sie als Kopf vor das Objective jedes Runs (für alle Adapter) und projiziert daraus AGENTS.md, eine minimale CLAUDE.md mit Verweis und .gemini/settings.json, das auf AGENTS.md zeigt. Niemand kopiert den Text von Hand.

4. Warum verlässt sich die Fabrik nicht darauf, dass ein Coding-Werkzeug AGENTS.md oder CLAUDE.md selbst einliest?

   Musterantwort

   Die Autoload-Logik unterscheidet sich je Werkzeug und Version (Dateinamen, Größengrenzen, Konfiguration). Wer sich darauf verlässt, hat einen stillen Fehlerpunkt. Das Objective ist das einzige Feld, das alle Adapter verarbeiten; dort eingesetzter Kontext erreicht deterministisch jeden Agenten. Die Dateien im Repository sind zusätzlich da, damit Agent und Mensch dieselbe Grundlage lesen können.

5. In INSTRUCTIONS.md steht „Kommentare auf Englisch“, die Guardrails enthalten keine Sprachregel, im Memory steht „Kommentare auf Deutsch, Entscheidung vom März“. Was passiert, und was solltest du tun?

   Musterantwort

   Projektvorgaben in INSTRUCTIONS.md und MEMORY.md gehen beide den Guardrails vor, aber untereinander widersprechen sie sich — der Agent muss raten. Das ist genau der widersprüchliche Kontext aus 3.1. Du solltest die Quelle bereinigen: Wenn die Märzentscheidung gilt, das Feld languagePreference in der Projektdefinition auf de setzen, Artefakte neu generieren bzw. INSTRUCTIONS.md korrigieren und den Memory-Eintrag behalten oder streichen, damit es nur noch eine Aussage gibt.

6. Wie funktioniert das Project-Memory technisch, und warum ist es adapterunabhängig?

   Musterantwort

   Das Memory liegt in der Datenbank und wird unter Memory (/projects/{id}/memory) gepflegt. Vor jedem Run spiegelt die Fabrik es als MEMORY.md in den Workspace; nach dem Run liest sie eine vom Agenten aktualisierte Datei zurück. Weil die Quelle die Datenbank ist und nicht eine werkzeugspezifische Konfiguration, bekommt jeder Adapter dasselbe Gedächtnis — auch nach einem Adapterwechsel.

7. Ein Kollege schlägt vor, das komplette Team-Wiki (300 Seiten) als freeText in die Projektdefinition zu kopieren, „damit der Agent alles weiß“. Wie argumentierst du?

   Musterantwort

   Das erzeugt überladenen Kontext: hohes Tokenvolumen in jedem Lauf, wichtige Regeln gehen unter, veraltete Seiten erzeugen Widersprüche. Besser: die wenigen projektrelevanten, stabilen Regeln destillieren und in die passenden Felder schreiben (Architektur, Security, NFRs), Entscheidungen ins Memory, Anforderungen in Specs. Auf ausführliche Dokumente im Repository verweisen, damit der Agent sie bei Bedarf liest.

8. Warum ist eine Rolle wie „Reviewer“ im Prompt allein keine Sicherheitsgarantie, und was gehört ergänzend dazu?

   Musterantwort

   Die Rollenbeschreibung ist eine Bitte an das Modell, keine technische Grenze. Ob ein Reviewer schreiben kann, entscheiden die Werkzeugrechte, mit denen er gestartet wird. In der Fabrik laufen Reviewer deshalb technisch read-only (eingeschränkte Werkzeugrechte, kein Schreiben in den Workspace). Rolle und Rechte gehören zusammen.

9. Du übernimmst ein bestehendes Projekt in die Fabrik, in dessen Repository bereits eine handgepflegte CLAUDE.md mit wichtigen Konventionen liegt. Wie gehst du vor, damit diese Konventionen künftig in jedem Lauf wirken — auch mit anderen Adaptern?

   Musterantwort

   Die Fabrik projiziert bei aktivierten Guardrails eine eigene minimale CLAUDE.md, die auf AGENTS.md verweist; eine nur dort gepflegte Konvention ist also keine verlässliche Quelle mehr und wäre ohnehin Claude-spezifisch. Die Inhalte gehören in die werkzeugneutralen Quellen der Fabrik: dauerhafte technische Konventionen in die Projektdefinition (Architektur, Git, Doku), daraus generiert in INSTRUCTIONS.md/PROJECT.md; gelernte Entscheidungen ins Project-Memory. Danach wirken sie für jeden Adapter, und Projektvorgaben gehen den allgemeinen Guardrails vor.