Kontext und Arbeitsregeln für Coding Agents

Kontext und Arbeitsregeln für Coding Agents

0:00 Ein Agent ist so gut wie das, was er im Repository vorfindet. Das klingt banal, hat aber eine unbequeme Konsequenz: Wissen, das nur in Köpfen steckt, existiert für ihn nicht. Jede Konvention, die Ihr Team seit Jahren mündlich weitergibt, jede Architekturentscheidung, an die sich zwei Leute erinnern — für einen Agenten sind das leere Stellen, und er füllt sie nach eigenem Ermessen.

0:22 Dieses Modul zeigt, wie man das ändert, ohne ein Handbuch zu schreiben.

Kontext und Arbeitsregeln für Coding Agents

0:27 Der zweite Tag verlässt die Technik und wendet sich der Arbeitsweise zu. Das ist der Teil, der sich am schlechtesten kaufen lässt und am meisten bringt. Wir beginnen beim Kontext — was der Agent überhaupt vorfindet —, gehen dann über Spezifikation und Plan zur Umsetzung und schließen mit der Frage, wie man Qualität nachweist.

0:45 Ein roter Faden zieht sich durch alle fünf Module: Was nicht aufgeschrieben ist, passiert nicht.

Das Repository als Arbeitsumgebung

0:51 Fangen wir damit an, was ein Agent sieht, wenn er ein Repository zum ersten Mal öffnet — und was er eben nicht sieht. Für einen Coding Agent ist das Repository die Arbeitsumgebung. Es liefert den Code, die Konventionen und die Begründungen — vorausgesetzt, sie stehen dort. Alles andere ist außer Reichweite: das Wiki, der Chatverlauf, die Absprache vom Dienstag.

1:14 Es gibt genau eine Möglichkeit, dieses externe Wissen zugänglich zu machen, und darum geht es in diesem Seminar: ein MCP-Server, der es bereitstellt. Aber auch der macht aus Flurwissen keinen Text. Drei Schichten, und die unterste ist die interessante. Was dort steht — Flurwissen, Chats, mündliche Absprachen — ist in jedem Team der größte Wissensbestand, und er ist für einen Agenten schlicht nicht vorhanden.

1:39 Die praktische Frage lautet deshalb nicht, wie man alles verfügbar macht, sondern welcher kleine Teil davon tatsächlich gebraucht wird. Meine Erfahrung: Es sind überraschend wenige Dinge, und sie passen auf eine Seite. Der erste Satz erklärt vieles: Ein Agent liest gezielt, nicht vollständig. Er durchsucht, findet etwas, arbeitet damit.

2:00 Daraus folgt, dass Auffindbarkeit über Vollständigkeit geht — zwanzig gute Zeilen an der richtigen Stelle wirken mehr als zwanzig Seiten Handbuch. Und der letzte Punkt ist einer, der im Alltag oft vergessen wird: Der Arbeitsbereich braucht eine Grenze. Ohne sie wandert der Agent in Nachbarverzeichnisse ab, weil dort auch etwas Passendes stand.

2:21 Der zweite Punkt ist der, der zu den unerklärlichsten Ergebnissen führt: Mehrere Verzeichnisse enthalten widersprüchliche Beispielimplementierungen. Der Agent findet eine davon — welche, ist Zufall — und baut konsequent in deren Stil. Der vierte Punkt hat denselben Effekt aus anderer Richtung: Generierte Verzeichnisse liegen im Suchraum.

2:40 Dann findet die Suche zehnmal dieselbe Sache, einmal im Quellcode und neunmal im Erzeugnis, und die Gewichtung ist dahin.

Projektanweisungen und Architekturregeln

2:48 Kommen wir zu dem Dokument, das inzwischen fast jedes Projekt hat — und das in den meisten Projekten zu lang ist. Projektanweisungen sind eine knappe, versionierte Datei im Repository. Sie hält fest, wie in diesem Projekt gearbeitet wird: Aufbau, Konventionen, Teststrategie, verbotene Wege. Das entscheidende Wort ist knapp. Sie ersetzt kein Handbuch, sondern verweist auf die Stellen, an denen die Begründung steht.

3:14 Ein Dokument, das alles erklärt, wird nicht gelesen — auch nicht von einem Agenten, denn es verbraucht Kontext, der dann für den eigentlichen Auftrag fehlt. Die Trennlinie verläuft zwischen dem Wie und dem Warum. Wie ein Modul aufgebaut wird, gehört hinein. Warum diese Architektur gewählt wurde, gehört in eine Architekturentscheidung — verlinkt, nicht ausgeschrieben.

3:37 Welche Tests Pflicht sind, gehört hinein; die Testfälle selbst nicht. Der Grund für diese Trennung ist pragmatisch: Das Wie ändert sich selten und muss immer präsent sein. Das Warum ändert sich nie und wird nur gebraucht, wenn jemand eine Regel infrage stellt. Das ist die vielleicht wichtigste Aussage des Kapitels. Eine Lücke merkt ein Agent — er hat keine Information und fragt im besten Fall nach.

4:01 Einen Widerspruch merkt er nicht: Eine veraltete Regel wird genauso ernst genommen wie eine gültige, und er wählt einfach eine. Und er meldet das nicht, weil es für ihn kein Konflikt ist. Daraus folgt eine unbequeme Pflege-Aufgabe: Veraltete Abschnitte müssen gelöscht werden, nicht durchgestrichen. Der erste Punkt ist die natürliche Entwicklung jeder solchen Datei: Sie wächst zum Handbuch und wird dann nicht mehr gelesen.

4:26 Setzen Sie sich eine Obergrenze — und wenn etwas Neues dazukommt, muss etwas Altes raus. Der zweite Punkt ist der, vor dem ich am deutlichsten warne und der uns an Tag drei wieder begegnet: Die Datei enthält Berechtigungsregeln, die technisch nicht durchgesetzt werden. Das ist Sicherheit als Bitte. Und der vierte ist die Frage, die man sich einmal im Quartal stellen sollte: Stimmt das noch, was da steht?

Globaler und aufgabenspezifischer Kontext

4:50 Jetzt zu einer Unterscheidung, die selten bewusst getroffen wird und die viel Ordnung schafft. Globaler Kontext gilt für jede Aufgabe im Projekt und ändert sich selten. Aufgabenspezifischer Kontext gilt für genau einen Auftrag und verschwindet danach. Beides zu mischen hat zwei unangenehme Folgen: Auftragsdetails werden zu Dauerregeln und bleiben für immer stehen, und Dauerregeln gehen in einer langen Aufgabenbeschreibung unter.

5:15 Die Trennung kostet nichts außer der Entscheidung, wo etwas hingehört — und die muss man einmal treffen. Hier schließt sich der Kreis zu Tag eins. Eine Resource liefert Kontext ohne Wirkung und ohne Werkzeugrecht — das ist genau die Eigenschaft, die man für globales Wissen will. Dazu die Annotationen, die wir in Modul 5 gesehen haben: Die Zielgruppe trennt Inhalte für Menschen von Inhalten für das Modell, die Priorität hilft dem Client bei der Auswahl.

5:41 Und nutzerabhängige Inhalte bekommen die private Zwischenspeicher-Kennzeichnung — sonst landen sie bei jemand anderem. Fünf Schritte, und der zweite ist der, auf den es ankommt: Die Filterung gehört in den Server, nicht in den Client. Alles, was der Server ausliefert, ist draußen — was der Client damit macht, haben Sie nicht in der Hand.

6:01 Der OWASP- Leitfaden für KI-Agenten verlangt genau das: sensible Muster vor der Speicherung redigieren. Und der fünfte Schritt ist der, den man gern überspringt: Die Filterung testen. Eine dokumentierte Filterung, die nicht greift, ist schlimmer als keine, weil sich alle darauf verlassen. Der zweite Punkt ist die Falle, die uns an Tag drei noch beschäftigen wird: Der Freitext einer Serviceanfrage gilt als vertrauenswürdiger Kontext.

6:27 Er ist es nicht — er wurde von jemandem geschrieben, der nicht in Ihrem Team sitzt. Der vierte ist ein Pflegeproblem, das schleichend kommt: Der Kontext wächst mit jedem Auftrag, und niemand räumt auf. Nach einem Jahr ist die Hälfte davon veraltet, und wir sind wieder bei den Widersprüchen aus dem vorigen Kapitel.

Definition of Ready und Definition of Done

6:46 Zum Abschluss zwei Listen, die aus einer Einzelfallentscheidung eine wiederholbare Regel machen. Die beiden Begriffe kennen Sie vermutlich aus der agilen Arbeit, und sie funktionieren hier genauso. Startklar legt fest, was vorliegen muss, bevor ein Agent einen Auftrag bekommt. Fertig legt fest, welche Nachweise zur Fertigstellung gehören.

7:06 Der Wert liegt nicht im Inhalt der Listen — den finden Sie in jedem Buch —, sondern darin, dass sie im Team vereinbart sind. Damit muss niemand mehr im Einzelfall verhandeln, und niemand kann im Einzelfall abkürzen. Achten Sie auf die Fußzeile, sie ist mir wichtig: Beide Listen gelten unabhängig davon, ob ein Mensch oder ein Agent die Änderung geschrieben hat. Das ist keine Formalie.

7:29 Sobald es zwei Maßstäbe gibt, beginnt eine Diskussion darüber, welcher gilt — und in der Praxis gewinnt immer der lockerere. Derselbe Gedanke steht übrigens in der NIST-Leitlinie zur Entwicklung mit generativer KI, und wir kommen in Modul 12 darauf zurück. Der erste Satz beschreibt die Realität in vielen Teams: Ein Auftrag ohne benannte Abnahme bleibt liegen oder wird durchgewunken — beides kommt vor, beides ist schlecht.

7:54 Der OWASP-Leitfaden für KI-Agenten wird an dieser Stelle sehr konkret: Eine Freigabe soll an die exakte Aktion gebunden sein und Akteur, Werkzeug, Ziel, Parameter, Zeitpunkt und Ablaufdatum tragen. Eine pauschale Zustimmung erfüllt das nicht. Das klingt bürokratisch — aber es ist der Unterschied zwischen einer Freigabe und einem Häkchen.

8:15 Der erste Punkt ist der Grund, warum solche Listen nach drei Monaten wirkungslos sind: Sie existieren, werden aber nicht in der Pipeline geprüft. Der zweite ist die verbreitetste Abkürzung: Fertig heißt Pipeline grün und sonst nichts. Der dritte ist ein Organisationsfehler mit Ansage — die Freigabe erteilt derselbe, der den Auftrag gestellt hat.

8:36 Und der vierte ist die Ausrede, die immer zieht: Startklar wird abgekürzt, weil der Agent ja nachfragen kann. Kann er. Aber er tut es nicht zuverlässig.

Übung

8:46 Bauen wir das für unser Beispiel zusammen — und zwar vollständig, einschließlich des Teils, den man gern auslässt. Das Agent-Context-Paket bündelt alles, was ein Agent im Anliegenbuch braucht: kompakte Projektanweisungen, Architekturhinweise, Testkonventionen und den MCP-Zugriff auf das Handbuch. Versioniert, damit es überprüfbar ist. Und der Teil, den man gern auslässt, ist der Ausschluss: Welche Inhalte bekommt der Agent bewusst nicht zu sehen?

9:14 Projektanweisungen, drei Architekturhinweise, die Testkonventionen — und das Handbuch über anliegen-mcp erreichbar. Dazu für jeden Bestand mit personenbezogenen Daten der umgesetzte und getestete Ausschluss. Die Freitextfelder der Serviceanfragen sind der erste Kandidat: Dort stehen Namen und Rückrufnummern. Achten Sie auf das Wort getestet — dokumentiert reicht hier ausdrücklich nicht.

9:39 Der erste Punkt ist genau das: Der Ausschluss ist dokumentiert, aber nicht implementiert. Das ist der häufigste Befund in echten Projekten, und er fällt niemandem auf, weil nichts bricht. Der zweite ist ein Qualitätsthema — die Architekturhinweise wiederholen, was der Code ohnehin zeigt, und verbrauchen Kontext ohne Gegenwert.

9:59 Und der vierte ist die Pflegefrage: Das Paket entsteht einmal und veraltet dann ohne Prüfung. Im nächsten Modul geht es darum, den Auftrag selbst so zu formulieren, dass er trägt.