AGENTS.md – Hilfreiches Agentenbriefing oder Tokenfresser?

AGENTS.md ist eine Konventionsdatei für KI-Agenten in Software-Repositories. Ähnlich wie ein README für Menschen beschreibt sie Build-Schritte, Testkommandos, Tooling, Architekturlinien und Coding-Guidelines – jedoch speziell für autonome Coding-Agenten. Die Idee: Agenten lesen die Datei frühzeitig und verstehen dadurch schneller, wie sie Tests ausführen, Code strukturieren und welche Konventionen gelten.

Anbieter wie OpenAI, Anthropic, GitHub und Qwen bewerben dieses Muster. Viele Frameworks erzeugen per Kommando (z. B. /init) automatisch eine AGENTS.md oder eine äquivalente Datei wie CLAUDE.md. Bis 2025 waren bereits zehntausende öffentliche GitHub-Repositories damit ausgestattet.

Was sagt die Forschung?

Ein Team der ETH Zürich hat Aufbau und Nutzen von AGENTS.md systematisch untersucht (Studie: „Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?"). Zwei Benchmarks kamen zum Einsatz:

• SWE-bench Lite: 300 Aufgaben aus elf populären Python-Repositories
• AgentBench: 138 Aufgaben aus zwölf weniger bekannten Repos mit echten, von Entwicklern geschriebenen Kontextdateien

Getestete Agenten: Claude Code (Sonnet 4.5), OpenAI Codex (GPT-5.2 und GPT-5.1 mini), Qwen Code (Qwen3-30B-Coder) – jeweils ohne Kontextdatei, mit automatisch generierter und mit manuell gepflegter Kontextdatei.

Ergebnis: Kaum Nutzen, spürbare Kosten

Agenten nehmen die Anweisungen ernst – sie nutzen erwähnte Tools, führen mehr Tests durch und navigieren ausführlicher durch das Repository. Das Problem: Mehr Anweisungen = mehr Abwägungen = mehr Reasoning-Tokens bei kaum besserem Ergebnis.

Relevante Dateien für einen Bugfix finden die Agenten mit AGENTS.md im Schnitt nicht schneller als ohne, obwohl viele Dateien explizit Verzeichnisstrukturen beschreiben.

Redundanz als Kernproblem

LLM-generierte Kontextdateien wiederholen meist nur, was bereits in README, CONTRIBUTING oder Docs steht. In einem Ablationsexperiment, bei dem alle anderen Dokumentationsdateien entfernt wurden, kehrte sich das Bild um: Kontextdateien verbesserten die Erfolgsrate um ~2,7 Prozentpunkte – und schnitten teils besser ab als die ursprüngliche Entwicklerdoku.

Schlussfolgerung: AGENTS.md ist dann hilfreich, wenn sie echte Wissenslücken füllt – nicht wenn sie vorhandene Informationen redundant wiederholt.

Eine empirische Analyse von über 2.300 Agenten-READMEs zeigt, was Entwickler heute hineinschreiben:

• Build- und Run-Kommandos: ~60 %
• Implementationsdetails: ~70 %
• Architekturhinweise: ~68 %
• Sicherheit & Performance: jeweils nur ~15 %

Viele Dateien sind lang, schwer lesbar und eher gewachsene Konfigurationsartefakte als klar kuratierte Dokumente.

Praktische Empfehlungen

Aus den Studienergebnissen und der GitHub-Analyse von über 2.500 AGENTS.md-Dateien ergeben sich folgende Leitlinien:

1. Keine Redundanz – Nichts wiederholen, was bereits in README oder Docs steht.
2. Wissenslücken füllen – Projektspezifische Skripte, besondere Test-Setups, nicht offensichtliche Fallstricke oder domänenspezifische Invarianten beschreiben.
3. Minimalistisch und testbar – Wenige, klar begründete Regeln statt einer langen Wunschliste. Beispiel: „Tests immer über make test-ci laufen lassen."
4. Agentenrolle klar zuschneiden – Spezialisierte Rollen (z. B. Testagent, Docs-Agent) funktionieren besser als generische Anweisungen.
5. Iterativ verbessern – Typische Fehler des Agenten beobachten und daraus knappe Korrekturanweisungen ableiten.
6. KI für Optimierung nutzen – Den Agenten selbst die eigene AGENTS.md analysieren und verbessern lassen; anschließend mit Beispielaufgaben validieren.

Fazit

AGENTS.md ist kein kostenloser Produktivitätsturbo, sondern ein Steuerungsinstrument mit Kompromissen. Automatisch generierte, redundante Kontextdateien verschlechtern aktuell die Erfolgsraten, verteuern jeden Agentenlauf und erzeugen komplexere Traces. Gezielt eingesetzt – in schlecht dokumentierten Codebasen, für Nischen-Toolchains oder klar abgegrenzte Agentenrollen – können sie jedoch echten Mehrwert liefern. Der Leitgedanke: so viel Kontext wie nötig, kein Token mehr.

Quellen

• AGENTS.md: Hilfreiches Agentenbriefing oder Tokenfresser? (heise online) — externe Quelle
• Studie: Evaluating AGENTS.md (arXiv) — Primärstudie ETH Zürich
• Studie: Agent READMEs – Empirical Study (arXiv) — empirische Analyse von 2.300+ Agenten-READMEs
• How to write a great agents.md (GitHub Blog) — praktische Leitlinien
• Quelldatei ansehen — archiviertes Original