Agentenkontext für Java-Repositories

Agentenkontext für Java-Repositories

0:00 Es gibt einen Satz, der die Arbeit mit Coding Agents besser zusammenfasst als jede Werkzeugbeschreibung: Nicht nur Code wird gepflegt — der Kontext für den Agenten gehört ebenfalls ins Repository. Das ist eine neue Sorte Artefakt. Keine Dokumentation für Menschen, kein Konfigurationsfile, sondern eine Betriebsanleitung für einen Mitarbeiter, der jeden Morgen ohne Gedächtnis erscheint.

0:22 In diesem Modul schreiben wir eine solche Anleitung für Lagerwerk. Und wir werden sehen, dass die Kunst nicht im Aufschreiben liegt, sondern im Weglassen.

Agentenkontext für Java-Repositories

0:31 Dieses Modul ist das Scharnier des Seminars. Bis hierher haben wir beobachtet und geprüft. Ab hier geben wir dem Werkzeug etwas an die Hand. Wir sammeln die Fragen, die ein Agent zu einem Maven-Projekt hat, schreiben Bauvorgang, Grenzen und Regeln so auf, dass sie befolgt werden, und klammern das aus, was nur Platz frisst.

0:50 Am Ende steht eine Datei, die wir in den Modulen sechs und sieben tatsächlich benutzen. Vier Schritte bis zur fertigen Anweisungsdatei. Wir sammeln zuerst die Fragen, die ein Agent zu einem Maven-Projekt hat — und Sie werden sehen, dass der Quelltext die wenigsten davon beantwortet. Dann schreiben wir Bauvorgang, Modulgrenzen und Regeln so auf, dass sie wirken statt nur gut zu klingen. Danach klammern wir aus, was flutet ohne auszusagen.

1:16 Und zum Schluss kürzen wir — das ist der Schritt, den fast alle auslassen und der am meisten bringt.

Was ein Agent über ein Maven-Projekt wissen muss

1:22 Beginnen wir mit einer Bestandsaufnahme. Welche Fragen hat jemand, der Ihr Projekt zum ersten Mal sieht und trotzdem etwas ändern soll? Holen Sie dafür bitte die Notizen von gestern hervor — die Liste dessen, was beim Erschließen von Lagerwerk unklar geblieben ist. Diese Liste ist erstaunlich nah an dem, was ein Agent wissen müsste. Denn er ist im Grunde ein sehr schneller neuer Kollege ohne Vorwissen.

1:46 Ein Agent braucht mehr als den Quelltext. Er braucht das, was in Ihrem Team ungeschrieben gilt: wie gebaut und getestet wird, welche Module wovon abhängen, was generiert ist, welche Regeln bei Fehlern gelten. Nichts davon steht im Code. Stellen Sie sich eine neue Kollegin am ersten Tag vor. Sie kann lesen, sie kann programmieren — aber sie weiß nicht, dass man hier vor dem Abschluss immer den Modultest laufen lässt und dass der Kern niemals auf die API zugreifen darf.

2:13 Diese Dinge sagt man ihr. Einem Agenten muss man sie aufschreiben. Die Logik dieser Tabelle ist eine einzige Spalte: Steht die Antwort im Code? Und Sie sehen, wie oft dort „Nein" steht. Bemerkenswert ist die Zeile zur Java-Version — sie steht in der pom.xml, aber verstreut über mehrere Module, und wer daraus den Zielstand ableiten will, muss vier Dateien vergleichen und raten.

2:37 Die Fußzeile ist die eigentliche Handlungsanweisung: Alles mit „Nein" gehört in die Anweisungsdatei. Denn eines ist sicher — geraten wird immer. Die Frage ist nur, ob richtig. Der zweite Punkt ist der, um den es hier eigentlich geht: Eine geschriebene Regel ist überprüfbar, eine mündliche nicht. Sie können ein Ergebnis gegen eine Datei halten und sagen, hier weicht es ab. Gegen eine Erinnerung können Sie das nicht.

3:02 Der dritte Punkt ist der angenehme Nebeneffekt, den ich für unterschätzt halte: Neue Teammitglieder profitieren von derselben Datei. Sie schreiben also nicht für ein Werkzeug, Sie schreiben für jeden, der neu dazukommt — und das Werkzeug liest mit. Der erste Punkt ist der häufigste: Die Datei wird angelegt und nie wieder angesehen.

3:22 Nach einem halben Jahr steht darin ein Bauvorgang, den es nicht mehr gibt, und Regeln, die das Team längst anders handhabt. Dann ist sie schlimmer als keine Datei, weil sie aktiv in die falsche Richtung führt. Der dritte Punkt ist der unangenehme: Regeln formulieren, die man selbst nicht einhält. Der Agent hält sich dann daran — und produziert Code, der nicht zum Rest des Projekts passt. Schreiben Sie also auf, was gilt, nicht was gelten sollte.

Build- und Testkommandos verbindlich hinterlegen

3:48 Im zweiten Kapitel kommt der Abschnitt, der von allen den größten Unterschied macht — und der zugleich am schnellsten geschrieben ist. Es geht um den Bauvorgang. Erinnern Sie sich an die Zeitmessung aus dem dritten Modul, an den Unterschied zwischen dem vollständigen Lauf und dem gezielten Kommando? Genau der zahlt sich jetzt aus.

4:06 Wir schreiben auf, was ausgeführt werden soll, damit niemand mehr probieren muss — weder der Agent noch der neue Kollege. Der teuerste Teil einer Agentenschleife ist der Bauvorgang. Nicht das Nachdenken, nicht das Schreiben — das Warten. Und wenn kein verbindliches Kommando bereitsteht, probiert der Agent. Er hat ja keinen Grund, sparsam zu sein: Der vollständige Reaktorlauf ist die sichere Variante, also nimmt er die.

4:31 Aus Ihrer Sicht bedeutet das drei Minuten statt zwanzig Sekunden, und zwar bei jedem einzelnen Schritt. Über einen Vormittag summiert sich das zu einer Größenordnung, die niemand einplant. Sechs Zeilen, und sie sind die wirtschaftlich wertvollsten des ganzen Moduls. Oben steht, was vor jedem Abschluss laufen muss — auf Modulebene, mit den abhängigen Modulen.

4:53 Unten steht ausdrücklich, wann der vollständige Lauf angebracht ist: nur auf Bitte. Diese zweite Zeile ist wichtiger, als sie aussieht. Ohne sie weiß der Agent nicht, dass es die teure Variante überhaupt gibt, und improvisiert. Und beachten Sie die Fußzeile — der Zusatz für die abhängigen Module ist kein Detail. Ohne ihn scheitert der Modultest an fehlenden Abhängigkeiten, und niemand versteht warum.

5:18 Der zweite Punkt ist der, der im Seminar sofort spürbar wird: Ergebnisse werden vergleichbar, weil alle dasselbe ausführen. Wenn bei Ihnen etwas grün ist und beim Nachbarn nicht, liegt es dann am Code oder am Kommando? Mit einer verbindlichen Zeile fällt diese Frage weg. Der vierte Punkt ist der schöne Nebeneffekt: Das Kommando dokumentiert nebenbei den Einstieg für Menschen.

5:40 Wie oft haben Sie in einem fremden Projekt gesucht, wie man eigentlich nur dieses eine Modul testet? Genau. Jetzt steht es da. Der zweite Punkt ist der, der die Datei still entwertet: ein Kommando hinterlegen, das im Team so niemand benutzt. Dann arbeitet der Agent anders als die Menschen, und die Ergebnisse lassen sich nicht vergleichen. Nehmen Sie das Kommando, das Sie tatsächlich tippen.

6:04 Der letzte Punkt ist der technischste: Testkommandos, die stumm sind. Wenn ein Lauf nichts ausgibt, bekommt der Agent keine Rückmeldung, an der er sich orientieren kann — und interpretiert Stille im Zweifel als Erfolg. Ein bisschen Ausgabe ist hier besser als gar keine.

Modul- und Paketgrenzen beschreiben

6:20 Im dritten Kapitel schreiben wir auf, was in Ihrem Team jeder weiß und niemand dokumentiert hat: welches Modul auf welches zugreifen darf und wo Fachlogik hingehört. Dabei stoßen wir auf ein Problem, das jedes gewachsene Projekt hat — die Regeln und der Bestand stimmen nicht überein. Damit müssen wir umgehen, und zwar bewusst.

6:39 Denn der Agent liest nicht die Regeln in Ihrem Kopf, er liest den Bestand. Architekturregeln existieren in den meisten Teams mündlich. Jeder weiß, dass Fachlogik in den Kern gehört und nicht in die Schnittstelle. Nur steht es nirgends. Ein Agent hat diesen Flurfunk nicht — er leitet aus dem Bestand ab. Und jetzt kommt der unangenehme Teil: Er leitet auch aus den Verletzungen ab.

7:02 Findet er drei Stellen, an denen Fachlogik in der API-Schicht sitzt, hält er das für das Muster dieses Hauses und macht es genauso. Er ist ein sehr aufmerksamer Beobachter mit einem schlechten Vorbild. Achten Sie darauf, wie diese Regeln formuliert sind: als Aussagen über konkrete Module, nicht als Absichtserklärungen. „Der Kern kennt keine anderen Module" ist überprüfbar — Sie können in die pom.xml sehen und feststellen, ob es stimmt. „Wir achten auf saubere Abhängigkeiten" ist es nicht.

7:32 Und beachten Sie die letzte Zeile: Eine neue Abhängigkeit zwischen Modulen ist eine Architekturentscheidung, keine technische Kleinigkeit. Deshalb steht sie hier unter Rückfragevorbehalt. Diese eine Zeile verhindert eine ganze Klasse von schleichenden Verschlechterungen. Der dritte Punkt ist der, den man beim Schreiben nicht erwartet: Grenzen begrenzen zugleich den nötigen Kontext.

7:55 Wenn feststeht, dass der Kern nichts von den anderen Modulen weiß, muss für eine Änderung im Kern auch nichts anderes im Kontext liegen. Die Architekturregel spart also unmittelbar Geld und Zeit. Der zweite Punkt ist der menschliche: Eine geschriebene Grenze macht ihre Verletzung besprechbar. Solange die Regel nur in den Köpfen ist, endet jede Diskussion darüber bei Geschmacksfragen und Dienstalter.

8:18 Der erste Punkt ist genau das Problem, das ich eben angesprochen habe: Grenzen beschreiben, die im Code längst durchbrochen sind. Das ist kein Grund, sie wegzulassen — im Gegenteil. Aber Sie sollten es wissen und benennen, sonst wundern Sie sich über widersprüchliche Ergebnisse. Der zweite Punkt ist ein Formulierungsfehler mit großer Wirkung: nur Verbote schreiben, ohne den erlaubten Weg zu nennen. Wer nur hört, was nicht geht, sucht sich einen Umweg.

8:45 Und Umwege sind in der Architektur meist schlimmer als der direkte Verstoß.

Generierte Quellen und Lombok ausklammern

8:50 Das vierte Kapitel ist kurz und hat einen der besten Ertrag-pro-Aufwand-Werte des ganzen Seminars. Es geht darum, Material auszuschließen, das nur Platz kostet und keine einzige Entscheidung dokumentiert. Und um einen Sonderfall, der viele überrascht, weil er in Java-Projekten so verbreitet ist — Lombok. Denn hier reicht Ausschließen nicht.

9:10 Hier müssen wir erklären, sonst richten wir mehr Schaden an als Nutzen. Generierter Code, Zielverzeichnisse, übersetzte Klassen: All das füllt den Kontext und dokumentiert keine einzige menschliche Entscheidung. Es ist Rauschen mit Dateiendung. Der Sonderfall ist Lombok, und der ist heimtückischer. Dort sehen Sie im Quelltext Felder und Annotationen — die Getter, Setter und Builder entstehen erst beim Übersetzen.

9:35 Für einen Leser, der nur den Text sieht, existieren sie schlicht nicht. Das ist, als würden Sie jemandem einen Bauplan geben, auf dem die Türen fehlen, und sich dann wundern, dass er neue einzeichnet. Zwei Abschnitte, und der zweite ist der interessante. Oben stehen die Ausschlüsse — schnell geschrieben, sofort wirksam. Unten steht die Erklärung zu Lombok, und die ist der eigentliche Trick.

9:59 Ohne diesen Absatz passiert genau das, was in der Fußzeile steht: Der Agent hält existierende Methoden für fehlend und schlägt vor, sie zu ergänzen. Sie bekommen also Vorschläge, die einen Getter hinzufügen, den es längst gibt. Drei Zeilen Erklärung ersparen Ihnen diese Diskussion dauerhaft. Der zweite Punkt ist der unmittelbare Nutzen: Der Agent erfindet keine Methoden, die es schon gibt.

10:23 Der erste ist der wirtschaftliche: Kontextplatz bleibt für Code frei, den jemand entschieden hat. Und der letzte fasst zusammen, warum ich dieses Kapitel so mag: Ausschlüsse sind billig zu pflegen und wirken sofort. Sie brauchen keine Diskussion im Team, keine Architekturentscheidung, keine Migration. Sie schreiben fünf Zeilen und haben ein Problem weniger.

10:44 Solche Gelegenheiten sind selten — nutzen Sie sie. Der zweite Punkt ist der, den ich Ihnen ans Herz lege: Lombok nur ausschließen statt zu erklären. Wenn Sie die Lombok-Klassen aus dem Kontext nehmen, ohne zu sagen warum, fehlt dem Agenten der halbe Typ — und er weiß nicht einmal, dass ihm etwas fehlt. Ausschluss plus Erklärung ist die Kombination. Der dritte Punkt ist eine technische Warnung: Ausschlüsse als Suchmuster können zu viel treffen.

11:10 Ein zu weites Muster nimmt Ihnen Quellcode weg, den Sie eigentlich brauchen — und auch das merken Sie erst an schlechten Antworten.

Architekturregeln, die ein Agent einhält

11:18 Jetzt kommen wir zum interessantesten Kapitel dieses Moduls, und es hat weniger mit Technik zu tun als mit Sprache. Ob eine Regel befolgt wird, hängt nämlich weniger von ihrem Inhalt ab als von ihrer Form. Dieselbe Absicht, unterschiedlich formuliert, führt zu völlig unterschiedlichen Ergebnissen. Das klingt nach einer Behauptung, lässt sich aber in fünf Minuten ausprobieren — und genau das machen wir gleich.

11:42 Prüfbare, konkrete Regeln mit einem genannten erlaubten Weg wirken. Absichtserklärungen wirken nicht. Das gilt übrigens für Menschen genauso — „schreib sauberen Code" hat noch nie jemandem geholfen, der nicht schon wusste, was gemeint ist. Der Unterschied ist nur: Menschen fragen nach. Ein Agent fragt nicht, er interpretiert. Und er interpretiert in Richtung dessen, was er am häufigsten gesehen hat.

12:07 Womit wir wieder beim Java-8-Bias aus dem dritten Modul wären. Diese Tabelle liest sich am besten zeilenweise: Links und rechts steht jeweils dieselbe Absicht. Nehmen Sie die vierte Zeile — links „nutze modernes Java", rechts „Zielstand Java 25, keine anonymen inneren Klassen". Links ist ein Wunsch, rechts eine Entscheidung.

12:28 Und genau hier greifen wir den Bias aus dem dritten Modul an: Diese eine rechte Zelle ist die billige Gegenmaßnahme, von der ich gesprochen habe. Die Fußzeile bringt das Prinzip auf den Punkt: Links steht, was man sich wünscht. Rechts steht, was überprüfbar ist. Der erste Punkt ist der praktische Gewinn im Team: Prüfbare Regeln lassen sich im Review als eingehalten oder verletzt bewerten.

12:53 Damit verlassen Sie das Feld der Geschmacksdiskussion. Der dritte Punkt ist der, den man beim Formulieren gern vergisst: Ein genannter erlaubter Weg verhindert Ersatzlösungen. Wer nur ein Verbot bekommt, sucht eine Lücke — und findet meist eine, die schlechter ist als das Verbotene. Und der letzte Punkt zeigt die Richtung: Was messbar ist, kann später automatisiert geprüft werden.

13:15 Der dritte Punkt ist der java-spezifische: Regeln ohne Zielstand. „Modernes Java" ist keine Version — für ein Modell ist das eine Einladung zum Raten, und geraten wird nach Häufigkeit. Schreiben Sie die Zahl hin. Der zweite Punkt ist der, der in großen Dateien entsteht: widersprüchliche Regeln. Wenn oben steht, keine neuen Abhängigkeiten, und unten wird eine bestimmte Bibliothek empfohlen, entscheidet der Zufall.

13:40 Das ist übrigens ein guter Grund für das nächste Kapitel — kurze Dateien haben weniger Gelegenheit, sich selbst zu widersprechen.

Kurze Instruktionen statt Regelwerk

13:48 Und damit zum letzten Kapitel, das gegen einen sehr menschlichen Impuls arbeitet. Wenn uns etwas wichtig ist, schreiben wir mehr darüber. Hier ist es genau umgekehrt: Je länger die Datei, desto geringer die Wirkung jeder einzelnen Regel. Wir kürzen deshalb gleich gemeinsam, und das Ziel ist ehrgeizig — alles Wesentliche auf eine Bildschirmseite.

14:09 Sie werden überrascht sein, wie viel dabei wegfällt und wie wenig fehlt. Eine Anweisungsdatei konkurriert mit dem Code um Kontextplatz. Jede Zeile, die Sie hinzufügen, geht von dem ab, was das Werkzeug vom eigentlichen Projekt sehen kann. Und je mehr Regeln nebeneinander stehen, desto weniger Gewicht hat jede einzelne. Das ist wie eine Betriebsanweisung an der Wand: Bei fünf Punkten liest man sie.

14:34 Bei fünfzig ist sie Tapete. Kürzen ist deshalb keine Nachlässigkeit, sondern Wirkungssteigerung — ein Satz, den man sich vermutlich zweimal sagen muss, bevor man ihn glaubt. Fünf Schritte, und der erste ist der strenge: Entscheidet diese Regel einen echten Fall? Wenn Ihnen dazu kein konkreter Fall aus den letzten Wochen einfällt, ist die Regel ein Wunsch.

14:56 Schritt zwei streicht, was ohnehin aus dem Code hervorgeht — das ist meist ein Drittel. Schritt vier ist das messbare Ziel: eine Bildschirmseite. Und Schritt fünf ist der, den fast alle auslassen: eine Woche arbeiten, dann nachschärfen. Genau deshalb altern diese Dateien so schnell. Sie werden einmal geschrieben und nie an der Wirklichkeit geprüft.

15:17 Der letzte Punkt ist die eigentliche Botschaft: Nachschärfen aus Erfahrung schlägt Vollständigkeit im ersten Wurf. Sie müssen jetzt nicht alles bedenken. Sie müssen anfangen, beobachten, wo der Agent danebenliegt, und genau dort eine Zeile ergänzen. Das ist deutlich effizienter, als sich vorab alle möglichen Fälle auszudenken — die meisten davon treten nämlich nie ein.

15:39 Und der dritte Punkt ist die praktische Begründung für die Kürze: Kurze Dateien werden tatsächlich gelesen und gepflegt. Lange werden zur Tapete, siehe eben. Der zweite Punkt ist der, der beim Kürzen fast immer passiert: Man streicht das Konkrete und behält das Allgemeine. Das fühlt sich richtig an — allgemeine Sätze klingen wichtiger.

15:59 In Wahrheit ist es genau falsch herum. Streichen Sie die Absichtserklärungen und behalten Sie die konkreten Kommandos und Grenzen. Und der letzte Punkt ist eine Bitte: Prüfen Sie nach dem Kürzen, ob das Ergebnis schlechter wurde. Kürzen ist kein Wert an sich — es ist eine Hypothese, und die sollte man testen. Jetzt bauen Sie die Datei, mit der wir den Rest des Seminars arbeiten. Eine Bildschirmseite, mehr nicht: Bauvorgang, Modulgrenzen, Ausschlüsse und drei prüfbare Regeln.

16:28 Das Erfolgskriterium ist bewusst kein formales — es lautet, dass derselbe Auftrag mit dieser Datei ein anderes Ergebnis liefert als ohne. Probieren Sie das aus, es ist der überzeugendste Moment dieses Tages. Und behandeln Sie die Datei ab jetzt wie Code: Sie wird uns in den nächsten beiden Modulen laufend begegnen, und wir werden sie ändern.

16:49 Damit haben Sie das zentrale Artefakt dieses Seminars in der Hand. Die Fragen, die ein Agent an ein Maven-Projekt hat, sind gesammelt und beantwortet. Bauvorgang und Modulgrenzen stehen verbindlich im Repository, nicht in Köpfen. Generierter Code und Lombok sind ausgeklammert und — wichtiger — erklärt. Und die Datei ist kurz genug, dass sie gelesen wird. Im nächsten Modul kommt der Härtetest: Wir geben dem Agenten eine echte Aufgabe und sehen zu, ob das Aufgeschriebene trägt.