{"id":924668,"date":"2026-04-06T05:30:14","date_gmt":"2026-04-06T05:30:14","guid":{"rendered":"https:\/\/www.europesays.com\/de\/924668\/"},"modified":"2026-04-06T05:30:14","modified_gmt":"2026-04-06T05:30:14","slug":"agents-md-hilfreiches-agentenbriefing-oder-tokenfresser","status":"publish","type":"post","link":"https:\/\/www.europesays.com\/de\/924668\/","title":{"rendered":"AGENTS.md: Hilfreiches Agentenbriefing oder Tokenfresser?"},"content":{"rendered":"
    \n
  1. \n

    AGENTS.md: Hilfreiches Agentenbriefing oder Tokenfresser?<\/p>\n<\/li>\n<\/ol>\n

    close notice<\/p>\n

    \n This article is also available in
    \n English<\/a>.<\/p>\n

    It was translated with technical assistance and editorially reviewed before publication.\n <\/p>\n

    \n Don\u2019t show this again.\n<\/p>\n

    Die Datei AGENTS.md ist ein Readme f\u00fcr KI-Agenten: Ein fester Ort im Repository, an dem Build\u2011Schritte, Testkommandos, Tooling, Architekturlinien und Coding-Guidelines speziell f\u00fcr autonome Coding-Agenten beschrieben sind. Die Idee ist, dass Agenten diese Datei fr\u00fch lesen und dadurch schneller verstehen, wie sie Tests ausf\u00fchren, den Code strukturieren und welche Konventionen sie beachten m\u00fcssen.<\/p>\n

    Weiterlesen nach der Anzeige<\/p>\n

    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 \u00e4hnliche Datei wie CLAUDE.md generieren. Dadurch hat sich der Standard rasant verbreitet: Im Jahr 2025 waren bereits zehntausende \u00f6ffentliche GitHub-Repositorys mit Kontextdateien ausgestattet, die Tendenz ist steigend. Das AGENTS.md-Repository auf GitHub<\/a> listet die Vorteile auf und zeigt Beispiele f\u00fcr den Aufbau solch einer Datei.<\/p>\n

    Ein Team an der ETH Z\u00fcrich hat den Aufbau und die N\u00fctzlichkeit von AGENTS.md unter die Lupe genommen. Die Studie \u201eEvaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?\u201c<\/a> untersucht erstmals systematisch, welchen Effekt solche Dateien auf reale Agentenworkflows haben. Die Forschenden kombinieren daf\u00fcr zwei Benchmarks: das etablierte SWE\u2011bench Lite mit 300 Aufgaben aus elf popul\u00e4ren Python-Repositorys und das Benchmarktool AgentBench mit 138 Aufgaben aus zw\u00f6lf weniger bekannten Repos, die alle echte, von Entwicklern geschriebene Kontextdateien enthalten.<\/p>\n

    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 \u2013 auf AgentBench \u2013 mit der real vorhandenen, von Entwicklern gepflegten Kontextdatei. Alle Agenten haben die Datei in ihren Kontext geladen, entweder AGENTS.md (f\u00fcr Codex- und Qwen-Code) oder CLAUDE.md (Claude Code). Die Erfolgsquote hat das Team dabei streng \u00fcber Testsuites gemessen: Ein Task gilt nur dann als gel\u00f6st, wenn alle zugeh\u00f6rigen Tests nach Anwenden des Agentenpatches gr\u00fcn laufen.<\/p>\n

    Die Erkenntnis: kaum Nutzen, sp\u00fcrbare Kosten<\/p>\n

    Das Ergebnis ist ern\u00fcchternd: LLM\u2011generierte Kontextdateien reduzieren die Erfolgsrate im Mittel leicht \u2013 um etwa 0,5 Prozentpunkte bei SWE\u2011bench 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\u00fchren und l\u00e4ngere Reasoning\u2011Passagen produzieren.<\/p>\n

    Auch menschlich gepflegte Kontextdateien schneiden nur moderat besser ab: Sie verbessern die Erfolgsrate auf AgentBench im Mittel um etwa 4 Prozentpunkte gegen\u00fcber dem Szenario ganz ohne Kontextdatei, erh\u00f6hen aber ebenfalls die Anzahl der Agentenschritte und damit die Kosten \u2013 in einzelnen Set-ups um knapp 20 Prozent. \u00dcberspitzt formuliert bedeutet das: F\u00fcr ein paar Prozentpunkte Erfolgsgewinn bezahlt man mit deutlich mehr Tokenverbrauch, l\u00e4ngeren Laufzeiten und komplexeren Agenten-Traces.<\/p>\n

    Die Studie zeigt, dass Agenten die Anweisungen in Kontextdateien ernst nehmen: Sind bestimmte Tools oder Workflows erw\u00e4hnt, nutzen Agenten sie h\u00e4ufiger \u2013 etwa Projektskripte, pytest, uv oder repositoryspezifische Hilfstools. Kontextdateien f\u00fchren auch zu mehr Tests, mehr Dateizugriffen und ausf\u00fchrlicherer Repositorynavigation. Das Problem ist also nicht, dass die Modelle Kontextinstruktionen ignorieren.<\/p>\n

    Weiterlesen nach der Anzeige<\/p>\n

    Die zus\u00e4tzliche Aktivit\u00e4t macht die Aufgaben jedoch schwieriger: Mehr Anweisungen bedeuten mehr Dinge, die der Agent ber\u00fccksichtigen und gegeneinander abw\u00e4gen muss, was sich in mehr Reasoning-Token pro Task niederschl\u00e4gt. Gleichzeitig funktionieren Kontextdateien schlecht als Repository-Overview: Die Agenten finden die f\u00fcr einen Bugfix relevanten Dateien im Schnitt nicht schneller als ohne AGENTS.md, obwohl viele Dateien explizit Verzeichnisstrukturen, Komponenten und Einstiegspunkte beschreiben.<\/p>\n

    Redundante Dokumentation statt gezielten Mehrwerts<\/p>\n

    Eine wichtige Beobachtung des ETH-Teams ist, dass LLM\u2011generierte Kontextdateien meist redundant zur bestehenden Dokumentation sind: Readme, Contributing, Docs\u2011Ordner und Beispiele enthalten bereits Build\u2011und Testhinweise, Architektur\u00fcbersichten und Stilvorgaben, die die Agenten via Dateizugriff ebenfalls nutzen k\u00f6nnen. In einem Ablationsexperiment entfernten die Forschenden deshalb alle anderen Dokumentationsdateien aus dem Repository und lie\u00dfen 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\u00e4ndert wurden, um deren Einfluss auf die Gesamtleistung zu messen.<\/p>\n

    In solch einem dokumentationsarmen Setting kippt das Bild: Pl\u00f6tzlich verbessern die generierten Kontextdateien die Erfolgsrate der Agenten im Schnitt um rund 2,7 Prozentpunkte und schneiden teilweise sogar besser ab als die urspr\u00fcnglichen Entwicklerdokumente. Die naheliegende Interpretation: Kontextdateien sind dann hilfreich, wenn sie echte Wissensl\u00fccken der Agenten f\u00fcllen und nicht, wenn sie bereits vorhandene Informationen noch einmal in leicht anderer Form wiederholen.<\/p>\n

    Eine separate empirische Analyse von \u00fcber 2.300 Agenten-Readmes aus knapp 2.000 Repositorys zeigt, wie Entwickler solche Dateien heute nutzen (siehe Studie \u201eAgent READMEs: An Empirical Study of Context Files for Agentic Coding\u201c<\/a>). Am h\u00e4ufigsten enthalten sie funktionalen Kontext: Build\u2011 und Run\u2011Kommandos (in gut 60 Prozent der F\u00e4lle), Implementationsdetails (knapp 70 Prozent) und Architekturhinweise (rund 68 Prozent).<\/p>\n

    Deutlich unterrepr\u00e4sentiert 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\u00e4nzungen als wie klar kuratierte Dokumente \u2013 ein weiterer Hinweis darauf, warum generalistische Kontextdateien f\u00fcr Agenten schnell zur kognitiven Last heranwachsen.<\/p>\n

    Praktische Leitlinien f\u00fcr den Einsatz<\/p>\n

    Aus Sicht der Praxis ergeben sich daraus einige Empfehlungen f\u00fcr den produktiven Einsatz von AGENTS.md (siehe GitHub-Blogartikel \u201eHow to write a great agents.md\u201c<\/a>):<\/p>\n