Letztes Quartal hat Ihr Team eine AGENTS.md-Datei im Monorepo angelegt. Sauber strukturiert, nach der gängigen Anleitung, die gerade überall kursiert: Build- und Testbefehle, Architekturüberblick, Programmierkonventionen. Und trotzdem schlägt der Agent im billing-Modul Lombok vor, obwohl Lombok dort seit Jahren verboten ist. Er verwendet @Service, obwohl Ihr Team dafür ein eigenes Spring-Stereotyp nutzt. Für den Datenbankaufruf greift er zum falschen Transaction Manager. In der AGENTS.md-Datei steht an drei Stellen, dass dieser Weg verboten ist. Der Agent tut es trotzdem.
Die naheliegende Reaktion: noch mehr dokumentieren. Eine weitere Regel, noch ein Beispiel, ein zusätzlicher Abschnitt. Das ist die falsche Reaktion. Ihr Problem ist nicht, dass die AGENTS.md-Datei zu kurz ist. Sie ist zu lang.
Kurz gefasst: Kontext aus dem Repository hilft, wenn er festhält, was das Modell nicht aus dem Code ableiten kann. Er schadet, wenn er nur wiederholt, was das Modell ohnehin weiß. In einer gewachsenen Enterprise-Codebasis ist der nicht erschließbare Anteil viel größer als in einer Demo für ein Neuprojekt. Genau dort liegt die Arbeit, und genau dort versagen die aus Neuprojekten übertragenen Empfehlungen.
Wie Prompt-Patterns mit Einführung, Werkzeugen, Messung und Compliance zusammenspielen, zeigt der übergreifende Coding-Agents-Leitfaden.
Zwei Studien, ein scheinbarer Widerspruch
Anfang 2026 sind zwei Vorabveröffentlichungen erschienen, die sich auf den ersten Blick widersprechen.
Lulla und sein Team haben in einer Vorabveröffentlichung gemessen, wie sich eine AGENTS.md-Datei im Wurzelverzeichnis auf OpenAI Codex auswirkt. Zehn Repositories, 124 Pull Requests, jeweils mit und ohne diese Datei. Das Ergebnis: Mit der Datei lag die Median-Laufzeit um 28,6 Prozent niedriger (70,34 statt 98,57 Sekunden), die Ausgabe im Median um 16,6 Prozent kürzer (2.440 statt 2.925 Token). Gemessen wurden Laufzeit und Tokenverbrauch, nicht die fachliche Korrektheit der Änderungen; eine vollständige Qualitätsbewertung lag außerhalb des Studienumfangs. Klingt nach einem Argument für Kontextdateien.
Wenige Wochen später erschien eine zweite Vorabveröffentlichung von Gloaguen und seinem Team. Ihr Befund war unbequemer. Sie haben Coding-Agenten in drei Varianten getestet: ohne Kontextdatei, mit einer vom Modell generierten Datei und mit einer von Entwicklern geschriebenen. Die maschinell erzeugten Kontextdateien senkten die durchschnittliche Lösungsrate um 0,5 Prozentpunkte auf SWE-bench Lite und um 2 Prozentpunkte auf AGENTbench, und erhöhten die Inferenzkosten um rund 20 beziehungsweise 23 Prozent. Von Menschen geschriebene Dateien schlugen die generierten bei allen vier Agenten und verbesserten das Ergebnis gegenüber „kein Kontext" bei allen außer Claude Code, im Schnitt um 4 Prozent auf AGENTbench. Klingt nach einem Argument gegen Kontextdateien.
Beide Arbeiten sind Vorabveröffentlichungen, keine abschließend geprüften Befunde. Und beide messen nicht dasselbe. Die eine Arbeit prüft die Effizienz eines Agenten auf PR-Aufgaben, mit einer bereits vorhandenen Datei im Wurzelverzeichnis. Die andere prüft Lösungsrate und Kosten bei mehreren Agenten und unterschiedlichen Dateiarten, einschließlich der Dateien, die das Modell selbst geschrieben hat.
Liest man beide Arbeiten zusammen, entsteht kein Widerspruch, sondern eine nützliche Heuristik. Kontextdateien helfen nicht, weil sie lang sind. Sie helfen, wenn sie knappe, projektspezifische Anforderungen enthalten, die der Agent nicht zuverlässig aus Code, Tests oder Standardwissen ableitet. Sie schaden, wenn sie wiederholen, was der Agent ohnehin weiß, oder ihn mit allgemeinen Architekturübersichten in zusätzliche Exploration treiben. Alles Weitere folgt aus dieser Unterscheidung.
Warum Greenfield-Empfehlungen im Altsystem versagen
Die entscheidende Größe ist der Wissensabstand zwischen dem, was das Modell gelernt hat, und dem, was in Ihrer Codebasis gilt.
Frontier-Modelle kennen Millionen Spring-Boot-Tutorials aus ihren Trainingsdaten. Ihren BookingContextAwareTransactionManager kennen sie nicht. Wenn in einer AGENTS.md-Datei steht „Nutze die üblichen Spring-Boot-Konventionen", hätte das Modell das ohnehin getan. Diese Zeile ist reiner Ballast. Wenn dieselbe Datei festhält „Verwende im billing-Modul nie das standardmäßige @Transactional, sondern immer BookingContextAwareTransactionManager.wrap()", dann beschreibt sie etwas, das das Modell aus dem Code allein nicht ableiten kann. Zwei Zeilen, zwei völlig verschiedene Kategorien. In vielen AGENTS.md-Dateien dominiert genau die erste: wiederholtes Allgemeinwissen, kaum projektspezifisches Signal.
Dass das Format inzwischen überall gelesen wird, ändert daran nichts. OpenAI hat AGENTS.md im August 2025 als offene Konvention veröffentlicht. Bis Ende 2025 nutzten es über 60.000 Open-Source-Projekte, und zahlreiche Werkzeuge unterstützten das Format, darunter Codex, Cursor und Copilot. Im Dezember 2025 hat die Linux Foundation die Konvention unter dem Dach der Agentic AI Foundation neben dem Model Context Protocol und dem Goose-Framework von Block formalisiert. Diese Konvergenz gibt es tatsächlich. Aber Verbreitung ist kein Wirksamkeitsnachweis. Dass jedes Werkzeug eine AGENTS.md-Datei liest, heißt nicht, dass jede AGENTS.md-Datei lesenswert ist.
Bemerkenswert ist, wer das am deutlichsten sagt. In der eigenen Dokumentation zu Claude Code von Anthropic gilt die überfrachtete Kontextdatei als eine der typischen Fehlerquellen, und die Empfehlung lautet, jede Zeile zu streichen, ohne die das Modell die Aufgabe ebenfalls richtig löst. Der Hersteller, der das Werkzeug verkauft, rät den Kunden, weniger zu schreiben. Das ist selten genug, um es ernst zu nehmen.
In Ihrer 15 Jahre alten Codebasis liegt der technische Wert nicht in dem, was das Modell weiß. Er liegt in dem, was nur Ihr Team weiß. Genau dieser Anteil ist im Altsystem größer, stärker auf einzelne Module beschränkt und schlechter dokumentiert als in jedem Tutorial-Repository. Warum sich daran auch Standardrezepte aus Tool-Demos die Zähne ausbeißen, steht ausführlicher im Mittelstand-Pfad zur KI-Coding-Strategie. Die Disziplin besteht darin, genau das aufzuschreiben und sonst nichts.
Vier Patterns, die in gewachsenen Codebasen funktionieren
Aus dieser Regel folgen vier Muster. Sie sind nicht neu. Jedes stammt aus dem Kanon guter Softwareentwicklung. Neu ist nur, dass ein Agent sie ausführt, sobald man sie benennt.
Das Änderungsbudget, eng begrenzt. Die Formel aus den Magic Words taugt als enger Startwert: etwa drei Dateien und 80 geänderte Zeilen pro Durchlauf. In einem Neuprojekt ist das eine Leitplanke. Im Altsystem ist es eine Überlebensregel, weil der Agent dazu neigt, auch den umgebenden Code umzubauen, und dieser Code fünfzehn Jahre historisch gewachsene Gründe hat, so auszusehen, wie er aussieht. Der enge Rahmen zwingt den Agenten, nachzufragen, bevor er verallgemeinert.
Charakterisierungstests vor der Änderung. Tests, die das aktuelle Verhalten festhalten, bevor eine Zeile geändert wird. Michael Feathers hat den Begriff in seinem 2004 erschienenen Buch Working Effectively with Legacy Code geprägt. Ein Agent erzeugt sie zuverlässig, wenn das Muster an einer konkreten Stelle benannt wird: „Bevor du InvoiceCalculator änderst, schreibe Tests, die die aktuellen Rundungsfälle festhalten. Ändere danach nur die Logik für Storno-Rechnungen." Eine Anweisung, mit der der Agent etwas anfangen kann, statt eines Absatzes voller Bitten um Vorsicht. Wie das im Detail aussieht, steht im Vorgehen für den Legacy-Monolithen.
Negative Vorgaben vor guten Beispielen. Der Rat für Neuprojekte lautet: Zeigen Sie dem Modell ein gutes Beispiel. Im Bestandssystem ist oft das Gegenteil wirksamer, besonders bei Fehlern, die der Agent wiederholt macht: Zeigen Sie ihm den Fehler, den er gleich machen wird. Positive Beispiele konkurrieren mit dem, was das Modell ohnehin für richtig hält. Negative Vorgaben durchbrechen diese Voreinstellung. „Lombok ist in diesem Modul verboten. Verwende klassische Getter und Setter." Diese eine Zeile kostet dreißig Token und spart einen kompletten Revert. Ein Absatz über den Teamstil tut das nicht.
Verschachtelter Kontext, nah am Code. Codex unterstützt verschachtelte AGENTS.md-Dateien und führt sie von der Wurzel bis zum Arbeitsverzeichnis zusammen; spätere, näherliegende Anweisungen können frühere überstimmen. Claude Code nutzt dagegen CLAUDE.md. Wer AGENTS.md repoübergreifend als Standard setzt, bindet für Claude Code eine CLAUDE.md per Import oder Symlink an. Das Prinzip bleibt bei beiden gleich: Die Wurzeldatei ist für alles, was wirklich überall gilt, alles andere gehört dorthin, wo es falsch gemacht werden kann. In die Wurzeldatei kommen also Build- und Testbefehl und die wenigen globalen Regeln, die stillschweigenden Regeln eines Moduls in dessen eigene Datei. Das spiegelt, wie erfahrene Entwickler denken: Kontext ist lokal, Ausnahmen sind explizit, und für eine Änderung an zwei Dateien lädt niemand die ganze Architektur in den Kopf.
Die gemeinsame Regel bei allen vier Mustern: weniger Root-Kontext, mehr lokale Präzision. Wer das ernst nimmt, betreibt Context Engineering im Wortsinn, nicht das Anhäufen von Dokumentation.
Dokumentation oder Erzwingung? Eine Frage der Risikoklasse
An einem Punkt stößt auch das beste Prompt-Pattern an seine Grenze. Eine Zeile in der AGENTS.md-Datei ist ein Ratschlag, den der Agent lesen kann. Er muss ihn nicht befolgen.
Jesse Vincent hat daraus mit Superpowers eine andere Konsequenz gezogen: Prompt-Patterns als kombinierbare Skills mit verbindlichen Auslösern, nicht als Dokumentation, die der Agent vielleicht konsultiert. Das Projekt wächst seit dem Start im Oktober 2025 rasant, Stand Juni 2026 liegt es laut Star-History bei über 220.000 GitHub-Sternen. Die eigentliche Einsicht steckt aber nicht im Plugin, sondern in der Beobachtung dahinter: Eine Regel, die der Agent nur liest, ist weniger verbindlich als ein Skill oder Hook, den er ausführen muss. Die Dokumentation von Anthropic formuliert es nüchtern: Hooks sind deterministisch, die Kontextdatei berät nur. Dazwischen liegt der Skill, strukturierter und leichter auszulösen als freie Dokumentation, aber keine harte Policy wie ein Hook.
Simon Willisons Agentic Engineering Patterns gehen den umgekehrten Weg: dokumentierte Muster ohne erzwungene Auslösung. Beide haben recht, je nach Risikoprofil des Codes, den der Agent bearbeitet. Für einfache interne Werkzeuge reichen dokumentierte Muster. Bei Zahlungen, Authentifizierung und regulierten Modulen sind erzwungene Skills oder Hooks den Einrichtungsaufwand wert. Die Frage lautet nicht „Dokumentation oder Erzwingung", sondern: welche Form von Regel für welche Risikoklasse?
Was Sie diese Woche ändern können
Vier Schritte, ganz ohne neues Werkzeug.
Halbieren Sie Ihre AGENTS.md-Datei. Gehen Sie sie Zeile für Zeile durch und fragen Sie bei jeder: Würde ein Senior-Entwickler, der diese Codebasis nie gesehen hat, aber fünfzehn Jahre Java-Erfahrung hat, diese Zeile brauchen? Wenn ja, bleibt sie. Wenn nein, ist sie Ballast und lenkt den Agenten ab.
Verschieben Sie Regeln in modulnahe AGENTS.md-Dateien. In die Wurzeldatei gehören Build, Test und die wenigen globalen Regeln. In die modulnahen AGENTS.md-Dateien gehören die stillschweigenden Regeln des jeweiligen Moduls, dort, wo der Code steht, für den sie gelten.
Formulieren Sie Verbote ausdrücklich. Eine einzeilige Regel „Lombok ist in payments/ verboten. Verwende klassische Getter und Setter." schlägt jeden Absatz über Teamstil. Schreiben Sie auf, was der Agent nicht tun soll, nicht nur, was guter Code wäre.
Entscheiden Sie pro Modul: Dokumentation oder Erzwingung. Für risikoarme Module reicht eine kurze AGENTS.md-Datei. Für regulierte oder geschäftskritische Module setzen Sie Hooks ein, die die Regeln erzwingen: zum Beispiel Pre-Commit-Linter, Policy-Checks und Review-Gates. Genau hier kommen Prompt-Patterns und Compliance zusammen, und genau hier wird etwa die Frage relevant, was der Agent überhaupt sehen darf.
Zum Schluss
Eine Kontextdatei ist keine zweite Projektdokumentation. Sie ist eine Arbeitsanweisung für einen Agenten: Sie hält fest, was Ihr Team weiß und das Modell nicht wissen kann. Je älter Ihre Codebasis, desto größer dieser Abstand. Und desto präziser müssen Ihre Prompt-Patterns sein, nicht länger.
Im Workshop Coding Agents meistern üben wir diese Patterns am Code der Teilnehmenden
