Kontext Engineering für Codebasen

Kontext Engineering für Codebasen

0:00 Willkommen zum zweiten Tag. Wir beginnen mit einer Verschiebung, die viele überrascht: Die Qualität einer Agentenantwort hängt weniger an der Formulierung der Frage als daran, was der Agent über Ihr Projekt weiß. Damit ist die Suche nach dem perfekten Prompt der falsche Weg. Der richtige besteht darin, eine dauerhafte Umgebung zu bauen, in der auch mittelmäßig formulierte Aufträge zu brauchbaren Ergebnissen führen.

0:23 Und am Ende des Moduls steht ein Satz, der alles zusammenfasst: Was ein Check erzwingen kann, gehört nicht in Prosa.

Kontext Engineering für Codebasen

0:30 Der zweite Tag dreht sich um Kontext, Tests und Verifikation — also um alles, was aus einem Vorschlag ein belastbares Ergebnis macht. Wir beginnen mit dem Kontext, weil er zeitlich zuerst kommt: Was ein Agent weiß, bevor er anfängt, bestimmt, wie viel Sie hinterher prüfen müssen. Am Ende des Tages steht wieder eine Tagesübung, dann zum Thema Review — ein bewusst problematischer Pull Request.

Kontext Engineering statt einzelner Prompt

0:54 Fangen wir mit der Grundfrage an: Woraus besteht der Kontext eines Agenten eigentlich? Die Antwort hat drei Teile, und das ist mehr als eine akademische Aufteilung. Denn einer dieser drei Teile ist deutlich stärker als die anderen beiden — so viel stärker, dass sich daraus die gesamte Arbeitsanweisung dieses Moduls ableiten lässt.

1:13 Sehen wir uns an, welcher das ist und warum. Der Unterschied lässt sich mit einem neuen Kollegen erklären. Sie können ihm bei jeder einzelnen Aufgabe erklären, worauf zu achten ist — das ist der Prompt. Oder Sie können dafür sorgen, dass das Projekt selbst ihm die Antworten gibt: durch Struktur, durch eine Einführungsseite, durch Tests, die anschlagen, wenn er etwas falsch macht.

1:36 Das Zweite ist mühsamer und wirkt dauerhaft. Genau das meint Kontext Engineering: nicht der eine perfekte Prompt, sondern eine Umgebung, in der auch ein mittelmäßiger Auftrag trägt. Achten Sie auf die rechte Spalte, sie ist der Kern dieser Folie. Was der Agent liest — Struktur, Code, Tests, Konventionen — muss geglaubt werden.

1:56 Was ihm ausdrücklich gesagt wird, ebenfalls. Aber der dritte Teil, das, was er selbst ausführen kann, muss nicht geglaubt werden. Ein Test schlägt an oder nicht. Ein Build läuft oder nicht. Da gibt es keine Interpretation. Und daraus folgt die Arbeitsanweisung dieses ganzen Moduls: So viel Wissen wie möglich aus den ersten beiden Teilen in den dritten überführen.

2:19 Alles, was ausführbar wird, ist Prüfaufwand, der Sie nichts mehr kostet. Vier Gründe, warum sich die Mühe lohnt. Ein guter Prompt hilft einmal, eine gute Umgebung hilft bei jedem Auftrag. Sie wirkt auch dann, wenn der Auftrag schlecht formuliert ist — und seien wir ehrlich, das ist oft der Fall. Sie wirkt für jeden im Team gleich, nicht nur für die Kollegin, die den guten Prompt kennt.

2:42 Das ist übrigens der Punkt, an dem private Prompt-Sammlungen scheitern, worauf wir in Modul zwölf zurückkommen. Und der vierte Grund ist der stärkste: Ausführbares muss nicht geglaubt werden.

Was in eine Projektanweisung gehört

2:54 Kommen wir zum konkretesten Teil dieses Moduls: der Projektanweisung. Also der Datei im Wurzelverzeichnis, die einem Agenten sagt, was er über Ihr Projekt wissen muss, bevor er sinnvoll arbeiten kann. Die überraschende Nachricht vorweg — eine gute Anweisung ist deutlich kürzer, als die meisten erwarten. Sie besteht überwiegend aus Ausnahmen, und das Auswahlkriterium dafür ist erfreulich eindeutig.

3:19 Die Datei heißt üblicherweise AGENTS.md oder CLAUDE.md, und sie beantwortet genau die Fragen, die ein neuer Kollege am ersten Tag stellt — die, deren Antwort nirgends im Code steht. Das Auswahlkriterium ist dabei erstaunlich einfach und wird trotzdem selten angewendet: Alles, was ein Agent ohnehin richtig rät, muss nicht aufgeschrieben werden.

3:39 Alles, was er systematisch falsch rät, gehört hinein. Deshalb ist eine gute Anweisung kurz. Sie ist kein Handbuch, sie ist eine Sammlung von Ausnahmen. Vier Fragen, und die letzte trägt am meisten. Wie baue ich das Projekt, wie führe ich die Tests aus — und ausdrücklich auch: wie führe ich einen einzelnen Test aus? Diese letzte Frage wird fast immer vergessen und ist im Alltag die nützlichste. Wie ist der Code geschnitten, und warum so?

4:06 Welche fachlichen Begriffe bedeuten hier etwas Bestimmtes — im Fahrtenbuch etwa Buchung, Fahrt und Abrechnung, die nicht dasselbe sind. Und schließlich: Was ist so ungewöhnlich, dass ein erfahrener Entwickler es falsch raten würde? Wenn Sie nur eine Frage beantworten, dann diese. Kurz zur Einordnung, wie verbreitet das inzwischen ist.

4:26 Die Konvention wird mittlerweile von der Agentic AI Foundation bei der Linux Foundation betreut, wird von über dreißig Werkzeugen gelesen und findet sich in Zehntausenden von Repositories. Verschachtelung wird unterstützt — die dem geänderten Code nächstgelegene Datei gewinnt, was gleich im nächsten Kapitel wichtig wird.

4:45 Zwei Hinweise zur Vorsicht: Die Verbreitungszahlen sind Größenordnungen aus Sekundärquellen, keine Messung. Und die Werkzeugliste veraltet schnell — deshalb steht sie bewusst nicht auf der Folie. Die Konvention bleibt, die Werkzeuge wechseln. Die ersten beiden Punkte sind die zwei Seiten desselben Auswahlkriteriums. Aufzuschreiben, was der Agent ohnehin richtig rät, kostet nur Aufmerksamkeit — und Aufmerksamkeit ist hier ein knappes Gut, wie wir später sehen werden.

5:13 Zu verschweigen, was er systematisch falsch rät, verschenkt den ganzen Nutzen. Der dritte Punkt ist die häufigste Fehlform: die Datei als Handbuch anlegen. Und der vierte betrifft die Haltbarkeit — wer sich auf eine Werkzeugliste festlegt, pflegt sie in drei Monaten hinterher.

Globale und verzeichnisspezifische Regeln

5:29 Jetzt zu einem Punkt, der über die Glaubwürdigkeit der ganzen Datei entscheidet. So zu tun, als gälte jede Regel überall, ist der schnellste Weg zu einer Anweisungsdatei, die niemand mehr ernst nimmt. Denn sobald die erste Regel erkennbar nicht überall gilt, wird auch der Rest infrage gestellt — von Menschen wie von Agenten.

5:48 Die Lösung ist einfach und wird trotzdem selten genutzt. Globale Regeln sind die wenigen, die im ganzen Projekt tragen: Sprache der Bezeichner, Umgang mit Fehlern, Testpflicht bei Verhaltensänderungen. Das sind Handvoll, nicht Dutzende. Alles andere ist lokal und gehört dorthin, wo es gilt — in eine Anweisung im jeweiligen Verzeichnis.

6:08 Und das hat einen zweiten Nutzen, den man leicht übersieht: Lokale Regeln stehen näher am Code, den sie betreffen. Sie veralten dadurch langsamer, weil sie beim Ändern desselben Bereichs ohnehin ins Blickfeld geraten. Ein konkretes Beispiel aus dem Fahrtenbuch. Im Abrechnungsteil ist die Regel verbindlich, dass jede Geldberechnung über einen bestimmten Typ läuft und Fließkommazahlen dort nichts zu suchen haben.

6:33 Das ist wichtig und richtig. In der Fahrzeugverwaltung ist dieselbe Regel schlicht gegenstandslos — dort gibt es keine Geldbeträge. Wer sie trotzdem global stellt, hat eine Regel in der Datei, die in der Hälfte der Fälle sinnlos ist. Und genau daran erodiert das Vertrauen in die übrigen. Die dritte Zeile zeigt den Gegenfall: Deutsche Bezeichner gelten überall, das gehört nach oben.

6:56 Der erste Punkt ist der eben besprochene und der folgenreichste: eine bereichsspezifische Regel global stellen und sie damit unglaubwürdig machen. Der zweite ist die Sammelmentalität — alle Regeln in eine Datei, bis niemand sie mehr liest. Der dritte ist ein Pflegeproblem, das erst später auffällt: Lokale Anweisungen anlegen und beim Umbau des Verzeichnisses vergessen.

7:17 Und der vierte ist ein logischer: Globale Regeln so weit fassen, dass jede Ausnahme sie widerlegt. Dann steht dort ein Satz, der nichts mehr aussagt.

Beispielcode als wirksamste Konvention

7:26 Und jetzt zum wirksamsten Mittel überhaupt. Wirksamer als jede Beschreibung, und zwar aus einem Grund, der in der Natur der Sache liegt und den man nur einmal verstehen muss. Es geht um Referenzstellen im eigenen Code — also darum, zu zeigen statt zu beschreiben. Wenn Sie in Ihrer Projektanweisung nur eine Sache richtig machen, dann sollte es dieser Punkt sein.

7:47 Warum wirkt ein Beispiel stärker als eine Beschreibung? Weil ein Beispiel vollständig und widerspruchsfrei ist — eine Beschreibung ist beides selten. Wenn im Auftrag steht, eine neue Prüfregel solle so aufgebaut sein wie die Doppelbuchungsprüfung in dieser Datei, dann sind Namensgebung, Fehlerbehandlung, Teststil und Ablageort in einem Zug geklärt.

8:07 Und zwar in der Fassung, die tatsächlich im Projekt gilt — nicht in der, die jemand vor zwei Jahren aufgeschrieben hat und die seither dreimal überholt wurde. Fünf Punkte, und die Voraussetzung steckt in Punkt zwei: Die Referenzstelle muss die Vorbildrolle wirklich verdienen. Eine mittelmäßige Stelle als Referenz zu benennen, vervielfacht die Mittelmäßigkeit.

8:28 Punkt vier ist der Pflegeaufwand — ändert sich das Muster, muss die Referenz mitziehen, sonst wird sie zur Quelle veralteter Kopien. Und Punkt fünf ist der, den viele überspringen: Kennzeichnen Sie die Stelle ausdrücklich als Referenz. Ohne Kennzeichnung hofft man darauf, dass alle dieselbe Stelle für vorbildlich halten. Das tun sie nicht.

8:49 Der erste Punkt ist der gefährlichste: auf eine Stelle zeigen, die niemand gepflegt hat. Dann verbreitet sich der Fehler systematisch. Der zweite ist eine Frage des Maßes — zu viele Referenzstellen bedeuten, dass keine gepflegt wird. Der dritte ist tückisch, weil er gut gemeint ist: das Muster zusätzlich in Worten beschreiben. Dann haben Sie zwei Quellen, die auseinanderlaufen, und niemand weiß, welche gilt.

9:14 Der vierte ist die Konsequenz aus dem ersten — eine veraltete Referenz erzeugt veraltete Kopien, zuverlässig und in Serie.

Was nicht hineingehört

9:22 Nach dem, was hineingehört, jetzt die Gegenliste — und die ist mindestens ebenso wichtig. Drei Dinge haben in Anweisungsdateien nichts verloren, und bei jedem gibt es einen konkreten, nachvollziehbaren Grund. Zweimal geht es um Sicherheit, einmal um Wirksamkeit. Alle drei passieren regelmäßig, und zwar nicht aus Nachlässigkeit, sondern weil sie im Moment jeweils vernünftig erscheinen.

9:46 Geheimnisse zuerst, und der Grund steht in der mittleren Spalte: Diese Dateien werden in den Kontext geladen, in Ausgaben zitiert und häufig weitergereicht. Ein Zugangsdatum dort ist praktisch veröffentlicht. Zweitens umfangreiche Handbücher — sie füllen den Kontext, und die wenigen wichtigen Sätze gehen darin unter. Ein Verweis auf die Datei ist besser als ihr Inhalt. Und drittens alles, was eine Maschine ohnehin erzwingt: Einrückung, Zeilenlänge, Anführungszeichen.

10:15 Der Merksatz dazu steht unten: Was der Formatierer richtet, muss nicht besprochen werden. Was der Linter erzwingt, ebenfalls nicht. Der erste Punkt passiert aus Bequemlichkeit: Interne Adressen oder Zugangsdaten wirken praktisch, weil man sie dann zur Hand hat. Der zweite ist gut gemeint — alles an einer Stelle haben, also das README hineinkopieren.

10:36 Das ist genau der Fall, vor dem die Praxis warnt: Doppelter Inhalt verschlechtert die Ergebnisse messbar, weil er als Ablenkung wirkt. Der dritte ist der Aufmerksamkeitsverbrauch durch Formatierungsregeln. Und der vierte beschreibt, wie diese Dateien typischerweise verwahrlosen: als Ablage für alles, was sonst nirgends passt.

Kontextüberladung und veraltete Vorgaben

10:56 Und damit zu dem Punkt, den ich für den überraschendsten dieses Moduls halte: Mehr Kontext ist nicht besser. Das klingt zunächst kontraintuitiv, gerade weil die Kontextfenster der Modelle immer größer werden und das als Fortschritt beworben wird. Aber dazu gibt es inzwischen belastbare Messungen über viele Modelle hinweg, und sie sind eindeutig. Sehen wir uns an, was sie zeigen.

11:18 Zwei Effekte überlagern sich. Der erste: Ab einer gewissen Menge sinkt die Trefferquote, weil das Wichtige zwischen dem Beiläufigen verschwindet. Der zweite ist subtiler und schlimmer: Mit wachsendem Umfang schleichen sich fast zwangsläufig Widersprüche ein. Und ein Widerspruch ist schlimmer als eine Lücke. Fehlt eine Vorgabe, rät der Agent erkennbar — Sie sehen, dass geraten wurde. Widersprechen sich zwei Regeln, folgt er einer davon und begründet das überzeugend. Sie merken nichts.

11:48 Zwei Untersuchungen. Die erste hat achtzehn aktuelle Modelle von vier Anbietern geprüft, und das Ergebnis ist bemerkenswert eindeutig: Jedes einzelne wird mit wachsender Eingabe schlechter. Und zwar selbst bei trivialen Aufgaben — beim wortgetreuen Wiederholen von Text. Die zweite ist die klassische Lost-in-the-Middle-Arbeit: Information am Anfang und am Ende wird am besten genutzt, in der Mitte bricht die Genauigkeit ein.

12:12 Die Einschränkung gehört dazu — die Studie erklärt nicht, warum das passiert. Aber sie schwächt die Aussage nicht, sie schärft sie: Wenn der Effekt schon beim Abschreiben auftritt, dann erst recht bei echter Arbeit. Der erste Punkt ist der Fehlschluss, der hier verlässlich kommt: Aus wachsenden Kontextfenstern zu folgern, mehr Inhalt sei unschädlich.

12:33 Fassungsvermögen und Trefferquote sind zwei Größen. Der zweite ist der schädlichste im Alltag: eine Anweisung, die einen Testbefehl nennt, den es nicht mehr gibt. Das richtet aktiven Schaden an, weil der Agent ihn ausführt und scheitert. Der dritte ist die Wachstumsdynamik — nur ergänzen, nie streichen. Eine Datei, die nur wächst, ist ein Warnzeichen. Und der vierte: Widersprüche dulden, weil beide Regeln für sich richtig sind.

Ausführbare Leitplanken statt Prosa

13:00 Damit zum wichtigsten Satz dieses Moduls, auf den alles Bisherige hinausläuft. Jede Regel, die sich in einen ausführbaren Check überführen lässt, gehört dorthin und nicht in Prosa. Der Unterschied zwischen beidem ist nicht graduell, er ist grundsätzlich — und er wird durch die Zusammenarbeit mit Agenten noch größer, als er ohnehin schon war.

13:20 Sehen wir uns an, warum. Der Unterschied lässt sich in einem Satz fassen. Eine geschriebene Regel muss gelesen, verstanden und befolgt werden. Sie kann übersehen, missverstanden oder stillschweigend gebrochen werden — und niemand merkt es, bis der Schaden auftritt. Ein Check dagegen meldet sich von selbst. Er gilt für Mensch und Agent gleichermaßen, ohne Ansehen der Person und ohne Diskussion im Review.

13:44 Und er hat einen dritten Vorteil, der erst mit Agenten wirklich zählt und den wir uns gleich ansehen. Vier Zeilen, und alle vier gehen in dieselbe Richtung. Eine Prosaregel wird nur bemerkt, wenn jemand hinsieht — ein Check immer. Sie gilt für den, der sie gelesen hat; ein Check für alle. Die dritte Zeile ist die für Agenten entscheidende: Eine Prosaregel kann er stillschweigend brechen, einen roten Test nicht.

14:09 Und die vierte ist die wirtschaftliche: Der Aufwand für eine Prosaregel fällt in jedem Review erneut an, der für einen Check einmal. Das ist keine knappe Rechnung, das ist eine deutliche. Und jetzt der Punkt, der wirklich neu ist. Ein Check gibt dem Agenten etwas, mit dem er sich selbst korrigieren kann, bevor überhaupt ein Mensch hinsieht.

14:30 Damit wandert Prüfarbeit aus dem Review in die Schleife davor — also genau dorthin, wo sie nichts kostet. Bei einer Prosaregel passiert das Gegenteil: Er kann sie brechen, ohne dass es jemandem auffällt, und Sie entdecken es im besten Fall im Review. Das ist der dritte Teil der Umgebung vom Anfang dieses Moduls — der, der nicht geglaubt werden muss.

Übung: Agentenanweisung für das Fahrtenbuch

14:50 Zum Abschluss schreiben Sie selbst eine Projektanweisung — höchstens eine Bildschirmseite für das Fahrtenbuch. Und diese Beschränkung ist nicht Schikane, sie ist der eigentliche Teil der Übung. Denn sie zwingt zu genau der Auswahl, über die wir in diesem Modul die ganze Zeit gesprochen haben: Was rät ein Agent ohnehin richtig, und was rät er systematisch falsch?

15:11 Enthalten sein müssen: Build- und Testbefehle einschließlich des Aufrufs eines einzelnen Tests, der fachliche Schnitt in drei Sätzen, die verbindlichen Begriffe der Domäne und genau die Konventionen, die ein erfahrener Entwickler hier falsch raten würde. Für mindestens zwei wiederkehrende Muster zeigen Sie auf eine Referenzstelle im Code, statt sie zu beschreiben.

15:31 Und der Schlussteil ist der Kern: Markieren Sie jede Regel, die sich in einen ausführbaren Check überführen ließe. Was übrig bleibt, muss begründet werden. Eine Stunde, fünf Schritte. Die ersten vier bauen die Datei auf — Befehle, Schnitt, Begriffe, Referenzstellen. Der fünfte ist die Markierung. Und dann begründen Sie für jede verbleibende Prosaregel, warum sie in Prosa bleiben muss.

15:54 Sie werden feststellen, dass die Datei dabei deutlich kürzer wird, als Sie zunächst geplant hatten — und dass gerade das der Gewinn ist. Denn was ausführbar wird, muss niemand mehr lesen, verstehen und befolgen. Es meldet sich von selbst.