AGENTS.md: Hilfreiches Agentenbriefing oder Tokenfresser?

Inhaltsverzeichnis

close notice

This article is also available in English. It was translated with technical assistance and editorially reviewed before publication.

Don’t show this again.

Die Datei AGENTS.md ist ein Readme für KI-Agenten: Ein fester Ort im Repository, an dem Build‑Schritte, Testkommandos, Tooling, Architekturlinien und Coding-Guidelines speziell für autonome Coding-Agenten beschrieben sind. Die Idee ist, dass Agenten diese Datei früh lesen und dadurch schneller verstehen, wie sie Tests ausführen, den Code strukturieren und welche Konventionen sie beachten müssen.

Anbieter wie OpenAI, Anthropic, GitHub und Qwen bewerben dieses Muster offensiv. Zudem bringen viele Frameworks Kommandozeilenbefehle wie /init mit, die aus einem bestehenden Repository automatisch eine AGENTS.md oder eine ähnliche Datei wie CLAUDE.md generieren. Dadurch hat sich der Standard rasant verbreitet: Im Jahr 2025 waren bereits zehntausende öffentliche GitHub-Repositorys mit Kontextdateien ausgestattet, die Tendenz ist steigend. Das AGENTS.md-Repository auf GitHub listet die Vorteile auf und zeigt Beispiele für den Aufbau solch einer Datei.

Ein Team an der ETH Zürich hat den Aufbau und die Nützlichkeit von AGENTS.md unter die Lupe genommen. Die Studie „Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?“ untersucht erstmals systematisch, welchen Effekt solche Dateien auf reale Agentenworkflows haben. Die Forschenden kombinieren dafür zwei Benchmarks: das etablierte SWE‑bench Lite mit 300 Aufgaben aus elf populären Python-Repositorys und das Benchmarktool AgentBench mit 138 Aufgaben aus zwölf weniger bekannten Repos, die alle echte, von Entwicklern geschriebene Kontextdateien enthalten.

Getestet hat das Team der Studie die Coding-Agenten Claude Code mit Sonnet 4.5, OpenAI Codex mit GPT-5.2 und GPT-5.1 mini sowie Qwen Code mit Qwen3-30B-Coder, jeweils in drei Varianten: ohne Kontextdatei, mit automatisch generierter Kontextdatei nach Empfehlung des jeweiligen Agentenentwicklers und – auf AgentBench – mit der real vorhandenen, von Entwicklern gepflegten Kontextdatei. Alle Agenten haben die Datei in ihren Kontext geladen, entweder AGENTS.md (für Codex- und Qwen-Code) oder CLAUDE.md (Claude Code). Die Erfolgsquote hat das Team dabei streng über Testsuites gemessen: Ein Task gilt nur dann als gelöst, wenn alle zugehörigen Tests nach Anwenden des Agentenpatches grün laufen.

Die Erkenntnis: kaum Nutzen, spürbare Kosten

Das Ergebnis ist ernüchternd: LLM‑generierte Kontextdateien reduzieren die Erfolgsrate im Mittel leicht – um etwa 0,5 Prozentpunkte bei SWE‑bench Lite und rund 2 bis 3 Prozentpunkte bei AgentBench, je nach Modell. Gleichzeitig steigen die Inferenzkosten im Schnitt um 20 bis 23 Prozent, weil die Agenten mehr Schritte ausführen und längere Reasoning‑Passagen produzieren.

Auch menschlich gepflegte Kontextdateien schneiden nur moderat besser ab: Sie verbessern die Erfolgsrate auf AgentBench im Mittel um etwa 4 Prozentpunkte gegenüber dem Szenario ganz ohne Kontextdatei, erhöhen aber ebenfalls die Anzahl der Agentenschritte und damit die Kosten – in einzelnen Set-ups um knapp 20 Prozent. Überspitzt formuliert bedeutet das: Für ein paar Prozentpunkte Erfolgsgewinn bezahlt man mit deutlich mehr Tokenverbrauch, längeren Laufzeiten und komplexeren Agenten-Traces.

Die Studie zeigt, dass Agenten die Anweisungen in Kontextdateien ernst nehmen: Sind bestimmte Tools oder Workflows erwähnt, nutzen Agenten sie häufiger – etwa Projektskripte, pytest, uv oder repositoryspezifische Hilfstools. Kontextdateien führen auch zu mehr Tests, mehr Dateizugriffen und ausführlicherer Repositorynavigation. Das Problem ist also nicht, dass die Modelle Kontextinstruktionen ignorieren.

Die zusätzliche Aktivität macht die Aufgaben jedoch schwieriger: Mehr Anweisungen bedeuten mehr Dinge, die der Agent berücksichtigen und gegeneinander abwägen muss, was sich in mehr Reasoning-Token pro Task niederschlägt. Gleichzeitig funktionieren Kontextdateien schlecht als Repository-Overview: Die Agenten finden die für einen Bugfix relevanten Dateien im Schnitt nicht schneller als ohne AGENTS.md, obwohl viele Dateien explizit Verzeichnisstrukturen, Komponenten und Einstiegspunkte beschreiben.

Redundante Dokumentation statt gezielten Mehrwerts

Eine wichtige Beobachtung des ETH-Teams ist, dass LLM‑generierte Kontextdateien meist redundant zur bestehenden Dokumentation sind: Readme, Contributing, Docs‑Ordner und Beispiele enthalten bereits Build‑und Testhinweise, Architekturübersichten und Stilvorgaben, die die Agenten via Dateizugriff ebenfalls nutzen können. In einem Ablationsexperiment entfernten die Forschenden deshalb alle anderen Dokumentationsdateien aus dem Repository und ließen nur die generierte Kontextdatei stehen. Ein Ablationsexperiment (Ablation Study) ist eine Methode zur Evaluierung von KI-Modellen, bei der gezielt spezifische Komponenten wie ein Feature, ein Layer oder Module entfernt oder verändert wurden, um deren Einfluss auf die Gesamtleistung zu messen.

In solch einem dokumentationsarmen Setting kippt das Bild: Plötzlich verbessern die generierten Kontextdateien die Erfolgsrate der Agenten im Schnitt um rund 2,7 Prozentpunkte und schneiden teilweise sogar besser ab als die ursprünglichen Entwicklerdokumente. Die naheliegende Interpretation: Kontextdateien sind dann hilfreich, wenn sie echte Wissenslücken der Agenten füllen und nicht, wenn sie bereits vorhandene Informationen noch einmal in leicht anderer Form wiederholen.

Eine separate empirische Analyse von über 2.300 Agenten-Readmes aus knapp 2.000 Repositorys zeigt, wie Entwickler solche Dateien heute nutzen (siehe Studie „Agent READMEs: An Empirical Study of Context Files for Agentic Coding“). Am häufigsten enthalten sie funktionalen Kontext: Build‑ und Run‑Kommandos (in gut 60 Prozent der Fälle), Implementationsdetails (knapp 70 Prozent) und Architekturhinweise (rund 68 Prozent).

Deutlich unterrepräsentiert sind dagegen nicht funktionale Anforderungen wie Sicherheit und Performance, die nur jeweils in rund 15 Prozent der Dateien explizit adressiert sind. Zudem sind viele Dateien lang, schwer lesbar und entwickeln sich eher wie Konfigurationsartefakte mit vielen kleinen Ergänzungen als wie klar kuratierte Dokumente – ein weiterer Hinweis darauf, warum generalistische Kontextdateien für Agenten schnell zur kognitiven Last heranwachsen.

Praktische Leitlinien für den Einsatz

Aus Sicht der Praxis ergeben sich daraus einige Empfehlungen für den produktiven Einsatz von AGENTS.md (siehe GitHub-Blogartikel „How to write a great agents.md“):

• Nichts wiederholen, was schon im Readme und in Docs steht. Doppelte Projektbeschreibungen oder lange Architekturexkurse sind zu vermeiden, wenn sie bereits an anderer Stelle gepflegt sind.
• Schwerpunkt auf fehlendem, schwer zu erschließendem Kontext. Dazu gehören projekt- oder teamspezifische Skripte, besondere Test‑Set-ups, nicht offensichtliche Fallstricke oder domänenspezifische Invarianten, die der Agent sonst nur durch intensives Trial and Error lernen würde.
• Minimalistische testbare Regeln statt Wunschliste. Jede zusätzliche Regel erhöht die Suchfläche für den Agenten. Sinnvoll sind wenige, klar begründete Anforderungen, etwa „Tests immer über make test-ci laufen lassen“ statt eines halben Dutzends alternativer Workflows.
• Agentenrolle klar zuschneiden. GitHub berichtet aus der Analyse von über 2.500 AGENTS.md-Dateien, dass spezialisierte Rollen – beispielsweise ein reiner Testagent oder Docs‑Agent – besser funktionieren als generische Anweisungen.
• Iterativ verbessern statt im Vorfeld alles perfektionieren. Erfolgreiche Agenten-Readmes entstehen dadurch, dass Teams typische Fehlervarianten des Agenten beobachten und daraus gezielte, knappe Korrekturanweisungen ableiten.

Zudem kann es hilfreich sein, den Agenten selbst seine eigene AGENTS.md optimieren zu lassen. Das LLM kann eine AGENTS.md analysieren und verbessern, indem es unklare Formulierungen, Widersprüche, Redundanzen oder fehlende Entscheidungsregeln erkennt und präziser formuliert. Die überarbeiteten Anweisungen steuern später das Verhalten eines Agenten. Besonders sinnvoll ist das, wenn das Resultat nicht nur das Umschreiben der Datei ist, sondern diese anschließend auch mit Beispielaufgaben getestet wird, um zu sehen, ob der Agent die gewünschten Regeln tatsächlich besser befolgt. Am zuverlässigsten ist deshalb ein iterativer Prozess, der analysiert, überarbeitet und testet, statt sich nur auf eine sprachlich schönere Version zu verlassen.

Implikationen für Teams mit Coding-Agenten

Für Entwicklungsteams ist AGENTS.md kein kostenloser Produktivitätsturbo, sondern ein Steuerungsinstrument, bei dem sie Kompromisse eingehen müssen. Automatisch generierte, stark redundante Kontextdateien verschlechtern in der aktuellen Evidenzlage die Erfolgsraten, verteuern jeden Agentenlauf und erzeugen komplexere Traces, die schwerer zu debuggen sind.

Hilfreich sind Repositorykontextdateien vor allem dort, wo sie gezielt fehlende Informationen bereitstellen, etwa in schlecht dokumentierten oder speziellen Codebasen, für Nischen-Toolchains oder klar abgegrenzte Agentenrollen. Die Aussage „Readme für KI-Agenten“ der AGENTS.md-Website ist daher wörtlich zu nehmen: nicht als weitere vollständige Dokumentation, sondern als schlanke, präzise Betriebsanleitung, die Agenten genau so viel Kontext gibt, wie sie für robuste Ergebnisse brauchen – und kein Token mehr.

(nb)