Vergebliche Versuche: Skills, AGENTS.md und die Grenze der Empfehlung

Diesen Beitrag anhören (10 Min.)

Dienstagmorgen, Code-Review. In unserer AGENTS.md steht seit Wochen ein Abschnitt „Hard rules“, und die erste Zeile darin lautet sinngemäß: Migrationsdateien werden niemals von Hand editiert. Der Pull Request, den ich vor mir habe, wurde von einem Agenten erzeugt, und er enthält genau das – eine von Hand nachgezogene Migrationsdatei, hübsch formatiert, mit einem Kommentar, der erklärt, warum das hier ausnahmsweise der sauberste Weg sei. Ich scrolle durch das Session-Protokoll. Der Agent hat die AGENTS.md gelesen. Sie stand in seinem Kontext. Er hat sich trotzdem anders entschieden.

Teil 6 der Serie „Von der Session zum System“ – hier geht es zum Auftakt.

Das ist keine Anekdote über ein schlechtes Modell. Es war ein aktuelles, fähiges Modell, und die Regel war unmissverständlich formuliert. Es ist auch keine Anekdote über einen schlampigen Kollegen – der hatte alles richtig gemacht, was man nach Stand der gängigen Empfehlungen richtig machen kann. Es ist die Anekdote, auf die diese ganze Folge zuläuft, und sie hat eine Vorgeschichte von etwa einem halben Jahr. In Folge 5 hatte ich beschrieben, warum sich mein persönlicher Erfolg mit KI-Werkzeugen nicht auf ein Team kopieren lässt: zu viel steckt in impliziten Arbeitsweisen, zu groß ist die Varianz zwischen Personen, Aufgaben und Sessions. Die naheliegende Antwort darauf schien mir damals offensichtlich – wir schreiben das Implizite auf. In Dateien, die die KI liest. Das muss doch reichen.

Es hat nicht gereicht. Und ich will ehrlich erzählen, wie ich das herausgefunden habe, Stufe für Stufe, denn jede Stufe habe ich mit echter Hoffnung begonnen.

Erster Anlauf: eine Datei im Repo

Der Anfang war eine CLAUDE.md im Repository, kurz darauf ergänzt um eine AGENTS.md – ein offenes Format, mit dem Repository-spezifische Hinweise für Coding-Agenten versioniert bereitgestellt werden, inzwischen zusammen mit MCP in die Agentic AI Foundation unter dem Dach der Linux Foundation eingebracht. Die Idee: eine README für Agenten. Dort liegen Build-Kommandos, Testläufe, Konventionen und Projektwissen versioniert im Repository – für Werkzeuge, die das Format unterstützen, und für das Team.

Unsere erste Fassung sah ungefähr so aus, wie sie in vielen Repositories aussieht:

# AGENTS.md

## Build & Test
- Install dependencies with `pnpm install`
- Run `pnpm test` for unit tests, `pnpm test:e2e` for integration
- Run `pnpm lint` before every commit

## Conventions
- TypeScript strict mode, no `any` in new code
- New endpoints follow the router structure in `src/api/`
- Tests follow Arrange/Act/Assert, one behavior per test

## Hard rules
- NEVER edit files in `migrations/` by hand
- NEVER modify the production schema without a migration
- Do not commit directly to `main`

Und zunächst wirkte es. In den Sessions tauchten häufiger die richtigen Testkommandos auf statt geratener, der Code folgte dem Stil des Projekts statt dem von Stack Overflow, und im Review gab es weniger Grundsatzdiskussionen. Ich war in dieser Phase ziemlich zuversichtlich und habe die Datei gepflegt wie Dokumentation, die zum ersten Mal wirklich gelesen wird.

Die Ernüchterung kam schleichend. Erst waren es Kleinigkeiten – ein Agent benannte Dinge anders als vereinbart, einer übersprang den Lint-Lauf. Dann waren es keine Kleinigkeiten mehr. Die Migrationsgeschichte vom Anfang war nicht die erste ihrer Art, nur die anschaulichste. Das Muster war immer dasselbe: mal wurde die Datei befolgt, mal halb, mal gar nicht. Und zwar ohne erkennbares System – dieselbe Regel, dieselbe Aufgabe, zwei Sessions, zwei Ergebnisse.

Die weiteren Anläufe: lauter, modularer, prominenter

Danach habe ich an drei Stellen nachgeschärft. Zuerst wurde aus „please avoid“ ein „NEVER“, teilweise mehrfach in derselben Datei. Danach beobachtete ich weniger Verstöße, doch aus der Vorgabe wurde keine Garantie, und nebenbei blähte sich der Kontext auf.

Als zweite Stufe probierten wir Agent Skills aus, die Anthropic im Oktober 2025 beschrieben hat: modulare Anleitungen mit Beispielen, Skripten und Checklisten, die ein Agent passend zur Aufgabe laden kann. Für klar geschnittene Abläufe funktionierten sie bei uns besser als ein langer Absatz in der AGENTS.md. Das Problem verschob sich damit nur: Der Skill musste passend ausgewählt und bis zum Ende befolgt werden. Auch geladen war er weiterhin Text im Kontext.

Zuletzt habe ich wichtige Vorgaben in Systemprompts und Abschlusschecklisten gehoben. Das gab ihnen mehr Gewicht und verbesserte die Ergebnisse noch einmal. Nach diesen drei Versuchen war die Frage für mich aber nicht mehr, wie ich denselben Satz noch deutlicher formulieren könnte. Ich wollte wissen, warum selbst sehr klarer Text eine Vorgabe nur wahrscheinlicher, nicht verbindlich macht.

Der Befund: Empfehlungen, keine Regeln

Was am Ende dieser vier Stufen stand, ist die Kernthese dieser Folge: Instruktionsdateien sind Empfehlungen an ein probabilistisches System, keine Regeln. Nicht, weil die Dateien schlecht geschrieben wären. Nicht, weil das Modell zu schwach wäre. Sondern weil es strukturell gar nicht anders sein kann.

Das lässt sich an vier Mechanismen festmachen, die ich alle in echten Projekten beobachtet habe:

Die Datei konkurriert im Kontextfenster mit allem anderen. Eine AGENTS.md ist ein Textblock unter vielen – neben dem Systemprompt des Werkzeugs, der Aufgabenbeschreibung, dem gelesenen Code, den Fehlermeldungen, dem bisherigen Gesprächsverlauf. Wenn ein Werkzeug lange Verläufe kürzt oder zusammenfasst, kann dabei auch eine frühere Instruktion an Gewicht verlieren. Meine Regel von Zeile 14 muss sich in jedem einzelnen Moment gegen zehntausende andere Tokens behaupten.
Instruktionen widersprechen einander. Angenommen, der Systemprompt eines Werkzeugs verlangt sinngemäß, hilfreich zu sein und die Aufgabe zu erledigen; meine Datei sagt „fass die Migration nicht an“, und die Aufgabe verlangt etwas, das ohne Migrationsänderung schwer geht. Das Modell muss diesen Konflikt auflösen. Der freundliche Kommentar im Pull Request – „ausnahmsweise der sauberste Weg“ – ist genau das: eine plausible Konfliktauflösung. Nur eben nicht meine.
Das System ist nichtdeterministisch. Dieselbe Eingabe erzeugt nicht dieselbe Ausgabe. Was in neun Sessions klappt, kippt in der zehnten – ohne dass sich an Datei, Aufgabe oder Modell irgendetwas geändert hätte. Das ist dieselbe Varianz, die ich in Folge 5 zwischen Menschen beschrieben habe, nur dass sie hier innerhalb ein und desselben Werkzeugs auftritt, von Session zu Session.
Und der grundlegendste Punkt: Der Text selbst kann Gehorsam nicht erzwingen. In der reinen Modellinteraktion gibt es keinen separaten Interpreter, der „NEVER“ als harte Bedingung prüft und einen Verstoß technisch verhindert. Die Instruktion beeinflusst die Ausgabe, aber erst ein Mechanismus außerhalb der Textgenerierung – etwa Berechtigungen, Validierung oder ein blockierender Test – kann daraus eine durchgesetzte Regel machen.

Damit ist der Verstoß vom Anfang kein Beleg dafür, dass die Datei ungelesen blieb. Er ist auch kein Bug einer Version, der mit dem nächsten Release verschwindet. Eine Quote bleibt eine Quote. Der Abstand zwischen 95 und 100 Prozent ist kein gradueller Abstand, den das nächste Modell schließt. Es ist ein kategorialer.

Was die Dateien trotzdem leisten

Instruktionsdateien transportieren Konventionen, Ton, Projektwissen und sinnvolle Defaults, und ich pflege unsere Stand April 2026 mit einiger Sorgfalt. Sie ersparen jedem im Team das immer gleiche Vorgeplänkel am Session-Anfang. Sie heben den Durchschnitt aller Sessions. Bei uns mussten Build-Kommandos und Projektkonventionen ohne eine solche Datei häufiger pro Session neu vermittelt werden.

Entscheidend ist die Art der Anforderung. Als Rechenbeispiel: „Schreib Tests im Arrange/Act/Assert-Stil“ ist eine Anforderung, die 90 Prozent Befolgung bestens verträgt – die restlichen zehn Prozent fallen im Review auf und werden korrigiert; in diesem Review-Fall entsteht kein Schaden. „Berühre nie das Produktionsschema“ ist eine Anforderung, die keine 99 Prozent verträgt. Angenommen, ein Team führt tausend Agenten-Sessions im Quartal durch: 99 Prozent Befolgung bedeuten zehn Vorfälle, und einer davon reicht. Für die erste Sorte sind Instruktionsdateien das richtige Werkzeug. Für die zweite sind sie es nicht – nicht, weil sie schlecht wären, sondern weil sie kategorial nicht das sein können, was diese Anforderung braucht: eine ausführbare Prüfung, begrenzte Rechte oder eine menschliche Freigabe außerhalb der Modellentscheidung.

Ich benutze dafür inzwischen gern einen Vergleich aus der klassischen Softwarearchitektur: Eine Coding-Guideline im Wiki und ein Typsystem im Compiler adressieren beide „so soll Code aussehen“ – aber niemand käme auf die Idee, sie für dieselbe Kategorie zu halten. Die Guideline hebt den Durchschnitt; ein aktivierter Typcheck weist dieselbe codierte Typverletzung bei gleicher Eingabe und Konfiguration reproduzierbar zurück. In unseren Teams trennen wir diese Kategorien bereits. Bei der Arbeit mit KI haben wir bisher fast nur die Guideline-Kategorie – und schreiben Compiler-Anforderungen hinein, in der Hoffnung, dass Großbuchstaben den Unterschied machen.

Empfehlung und Regel sind zwei Kategorien

Damit ist die Chronik am Ende, und das Fazit fällt nüchterner aus, als ich es beim Start dieser Versuche im Herbst 2025 erwartet hätte. Alle vier Stufen – Repo-Dateien, verschärfter Wortlaut, Skills, Systemprompts samt Checklisten – arbeiten mit demselben Material: Prosa im Kontext. Prosa im Kontext kann empfehlen, prägen, verschieben. Sie kann nicht garantieren. Wer eine Garantie braucht, braucht einen anderen Ort als den Kontext – einen Ort, an dem eine Regel geprüft und durchgesetzt wird, unabhängig davon, wie das Modell in der einzelnen Session entscheidet. In Folge 3 habe ich beschrieben, dass der Harness – die Umgebung um das Modell herum, mit ihren Tools und Berechtigungen – den Unterschied zwischen den KI-Werkzeugen ausmacht. Hier zeigt sich dieselbe Trennlinie noch einmal schärfer: Was das Modell liest, ist Empfehlung. Nur was die Umgebung erzwingt, ist Regel. Wie man solche Regeln baut, die wirklich halten, ist einen eigenen Beitrag wert, und der kommt später in dieser Serie.

Vorher lässt mir aber etwas anderes keine Ruhe, und es steckt schon in der Szene vom Anfang. Der Agent, der unsere Migrationsregel brach, hat das nicht kleinlaut getan. Er hat es begründet – flüssig, plausibel, mit dem Ton eines erfahrenen Kollegen, der genau weiß, was er tut. Kein Zögern, kein Hinweis, keine Unsicherheit. Das System hält sich nicht verlässlich an das, was ich ihm mitgebe, und klingt dabei in jedem einzelnen Fall vollkommen überzeugt – wenn es richtig liegt genauso wie wenn es danebenliegt, und ich höre dem Ton den Unterschied nicht an. Woher diese Überzeugtheit kommt und warum sie kein Versehen ist, sondern zur Bauart gehört, schaue ich mir als Nächstes an.

Weiterführende Quellen

Wie fandest du diesen Beitrag?