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

URL: https://www.mikebild.dev/de/blog/vergebliche-versuche-instruktionsdateien/

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](https://www.mikebild.dev/de/blog/von-der-session-zum-system-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](https://www.mikebild.dev/de/blog/mein-erfolg-laesst-sich-nicht-kopieren/) 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, weil sich diese Konvention seit ihrem Start im August 2025 erstaunlich schnell durchgesetzt hatte – ein gemeinsames Format, das Codex, Cursor, Copilot und etliche andere Werkzeuge gleichermaßen lesen, seit Ende 2025 sogar unter dem Dach der Linux Foundation. Die Idee ist bestechend: eine README für Agenten. Build-Kommandos, Testläufe, Konventionen, Projektwissen – alles an einem verabredeten Ort, versioniert im Repo, für jedes Werkzeug und jeden im Team gleich.

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

```markdown
# 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. Die Agenten-Sessions im Team wurden sichtbar besser: richtige Testkommandos statt geratener, Code im Stil des Projekts statt im Stil von Stack Overflow, weniger Grundsatzdiskussionen im Review. 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.

## Zweiter Anlauf: lauter schreiben

Also habe ich die Formulierungen verschärft. Aus „please avoid" wurde „NEVER", aus einem Absatz wurden Großbuchstaben, aus einer Regel wurden drei Wiederholungen an drei Stellen. Das ist die Eskalationslogik des Prompt-Schreibens – wenn es nicht gehört wird, sag es lauter.

Es half messbar. Und es half nicht verlässlich. Die Quote wurde besser, aber der Charakter des Problems blieb unverändert: Ich konnte die Wahrscheinlichkeit erhöhen, dass eine Regel befolgt wird. Ich konnte sie nicht auf eins bringen. Nebenbei wuchs die Datei, und mit ihrer Länge sank spürbar die Aufmerksamkeit für den einzelnen Eintrag – ein Effekt, den ich damals nur beobachtete und erst später verstand.

## Dritter Anlauf: Skills

Im Oktober 2025 hatte Anthropic Agent Skills vorgestellt – Ordner mit Anleitungen, Beispielskripten und Ressourcen, die ein Agent bei Bedarf lädt, statt alles dauerhaft im Kontext zu tragen; seit Dezember 2025 ist auch das ein offener Standard. Das schien mir ein echter Fortschritt gegenüber der einen großen Datei: modular, wiederverwendbar, über Projekte hinweg teilbar. Ich habe für unser Team Skills gebaut – einen für unsere Review-Kriterien, einen für den Umgang mit Datenbankänderungen, einen für das Release-Vorgehen. Sauber beschrieben, mit Beispielen, mit Checklisten am Ende.

Für Abläufe funktionierte das erkennbar besser als Prosa in der AGENTS.md. Ein Skill, der Schritt für Schritt beschreibt, wie ein Release vorbereitet wird, wird erstaunlich zuverlässig abgearbeitet – die Struktur aus nummerierten Schritten gibt dem Modell etwas, woran es sich entlangarbeiten kann. Aber zwei Schwächen blieben. Erstens: Der Skill muss überhaupt geladen werden, und ob das Modell erkennt, dass er relevant ist, ist selbst wieder eine Wahrscheinlichkeitsfrage. Zweitens: Auch ein geladener Skill ist am Ende Text im Kontext. Bei Schritt sieben einer langen Session, wenn der Kontext voll ist mit Dateien, Fehlermeldungen und Zwischenständen, kann derselbe Agent, der Schritt eins bis sechs mustergültig befolgt hat, bei Schritt sieben eine eigene Abkürzung nehmen. Habe ich erlebt. Mehrfach.

## Vierter Anlauf: Systemprompts und Checklisten

Die letzte Eskalationsstufe war, die wichtigsten Regeln aus dem Repo in die Werkzeugkonfiguration zu heben – in Systemprompts, die jeder Session vorangestellt werden, näher dran am Modell, mit mehr Gewicht. Dazu Checklisten am Ende jeder Aufgabe: Bevor du fertig meldest, prüfe diese fünf Punkte. Das ist handwerklich das Beste, was sich mit Text erreichen lässt, und ich will es nicht kleinreden. Die Befolgungsquote stieg noch einmal.

Aber inzwischen ahnte ich, dass ich einem strukturellen Problem mit immer besserem Wortlaut hinterherlief. Vier Stufen, viermal echte Hoffnung, viermal dieselbe Sorte Ernüchterung. Irgendwann kippte die Frage: weg von „wie formuliere ich das noch klarer?" – hin zu „warum wirkt Klarheit hier überhaupt nur statistisch?"

## Der Befund: Empfehlungen, keine Regeln

Was am Ende dieser vier Stufen stand, ist die Kernthese dieser Folge und die wichtigste Einsicht der ganzen Serie: **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 freier Wildbahn 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. In langen Sessions wird gekürzt, zusammengefasst, verdrängt; was vor zwei Stunden prominent im Kontext stand, ist jetzt ein blasser Rest. Meine Regel von Zeile 14 muss sich in jedem einzelnen Moment gegen zehntausende andere Tokens behaupten.
- Instruktionen widersprechen einander. Der Systemprompt sagt „sei hilfreich und erledige die Aufgabe", meine Datei sagt „fass die Migration nicht an", die Aufgabe verlangt etwas, das ohne Migrationsänderung schwer geht. Das Modell muss diesen Konflikt auflösen, und es tut das nicht nach einer Rangordnung, die irgendjemand garantiert, sondern nach gelernten Gewichtungen. 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](https://www.mikebild.dev/de/blog/mein-erfolg-laesst-sich-nicht-kopieren/) zwischen Menschen beschrieben habe, nur dass sie hier innerhalb ein und desselben Werkzeugs auftritt, von Session zu Session.
- Und der tiefste Punkt: Das Modell kann gar nicht gehorchen. Es gibt in einem Sprachmodell keinen Interpreter, der Regeln durchsetzt, keine Instanz, die „NEVER" als harte Bedingung auswertet. Es gibt nur Gewichtung – jedes Stück Text im Kontext verschiebt Wahrscheinlichkeiten für die nächste Ausgabe, mehr nicht. „NEVER" in Großbuchstaben verschiebt sie stärker als ein höfliches „bitte nicht". Aber verschieben ist alles, was Text tun kann. Ein Modell befolgt keine Regel; es wird von ihr beeinflusst.

Wenn man das einmal so sieht, hört das Verhalten auf, rätselhaft zu sein. Es ist kein Bug einer Version, der mit dem nächsten Release verschwindet. Bessere Modelle gewichten besser – die Befolgungsquoten sind zwischen 2023 und heute deutlich gestiegen, das will ich ausdrücklich festhalten. Aber 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

Nun wäre es unfair und auch falsch, daraus zu schließen, Instruktionsdateien seien wertlos. Das Gegenteil ist der Fall, und ich pflege unsere bis heute mit einiger Sorgfalt. Sie leisten sehr viel – nur eben eine bestimmte Sorte Leistung: Sie transportieren Konventionen, Ton, Projektwissen und sinnvolle Defaults. Sie ersparen jedem im Team das immer gleiche Vorgeplänkel am Session-Anfang. Sie heben den Durchschnitt aller Sessions, und zwar deutlich. Wer heute ein Repository ohne AGENTS.md oder CLAUDE.md betreibt und regelmäßig Agenten darauf arbeiten lässt, verschenkt viel.

Der entscheidende Gedanke ist ein anderer, und er hat bei mir eine Weile gebraucht: Es kommt auf die Sorte Anforderung an. „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, werden korrigiert, kein Schaden entstanden. „Berühre nie das Produktionsschema" ist eine Anforderung, die keine 99 Prozent verträgt. Bei tausend Agenten-Sessions im Quartal sind 99 Prozent 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.

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, der Compiler garantiert eine Eigenschaft. Wir haben in unseren Teams beides, und wir wissen genau, welche Anforderung in welche Kategorie gehört. 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 vor einem halben Jahr 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 gerade gewichtet. In [Folge 3](https://www.mikebild.dev/de/blog/harness-macht-den-unterschied/) habe ich beschrieben, dass der Harness – die Umgebung um das Modell herum, mit ihren Werkzeugen und Berechtigungen – den Unterschied zwischen den 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 – im Treffer wie im Fehlgriff, ununterscheidbar. 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

- [AGENTS.md – offizielle Seite der Konvention](https://agents.md/)
- [InfoQ: AGENTS.md Emerges as Open Standard for AI Coding Agents (August 2025)](https://www.infoq.com/news/2025/08/agents-md/)
- [Anthropic Engineering: Equipping agents for the real world with Agent Skills (Oktober 2025)](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [Anthropic Engineering: Claude Code Best Practices (u. a. zu CLAUDE.md)](https://www.anthropic.com/engineering/claude-code-best-practices)
- [Anthropic Engineering: Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)