AGENTS.md nicht per /init automatisch erzeugen – das erhöht nur die Kosten um 20 %

Zentrale These

• Wenn die Kontextdatei für AI-Coding-Agenten (AGENTS.md) automatisch per /init erzeugt wird, sinkt die Leistung der Agenten sogar und die Kosten steigen um mehr als 20 %
• Der Kern des Problems ist, dass Informationen doppelt bereitgestellt werden, die der Agent selbst finden kann
• In AGENTS.md sollte nur das stehen, was ein Agent nicht allein durch Lesen des Codes herausfinden kann

Forschungsergebnisse: Hilft AGENTS.md oder schadet es?

• Lulla et al. (ICSE JAWs 2026): Gepaarter Versuch mit 124 GitHub-PRs, bei dem nur das Vorhandensein von AGENTS.md variiert wurde
  • Mit AGENTS.md sank die Laufzeit um 28,64 %, die Ausgabetokens um 16,58 %
  • Die in dieser Studie verwendete Datei wurde tatsächlich von Entwicklern gepflegt und enthielt projektspezifisches Wissen
• ETH-Zurich-Studie: Vier Agenten wurden auf SWE-bench u. a. getestet, wobei automatisch von LLMs erzeugte Dateien und von Entwicklern geschriebene Dateien getrennt betrachtet wurden
  • Automatisch von LLMs erzeugter Kontext: Erfolgsquote 2–3 % niedriger, Kosten um 20 %+ höher
    • In einer Umgebung, in der bestehende Dokumente wie das README vollständig entfernt wurden, steigerte die von LLMs erzeugte Datei die Leistung dagegen um 2,7 %
  • Direkt von Entwicklern geschriebene Dateien: Erfolgsquote etwa 4 % höher, Kosten bis zu 19 % höher
• Fazit: Nicht der automatisch erzeugte Inhalt ist das Problem, sondern die Redundanz
  • Wenn dieselbe Information doppelt gegeben wird, entsteht nur zusätzliches Rauschen; wirklich hilfreich ist nur von Entwicklern bereitgestelltes nicht auffindbares Wissen

Warum automatische Erzeugung schadet

• Automatisch erzeugte AGENTS.md-Dateien enthalten meist Informationen, die der Agent ohnehin selbst findet
  • Überblick über die Codebasis (100 % der Sonnet-4.5-Ausgaben, 99 % der GPT-5.2-Ausgaben enthielten das)
  • Verzeichnisstruktur, Tech-Stack, Modulbeschreibungen
• Bereits bekannte Informationen erneut zu liefern verbraucht nur Tokens und bringt keinen Mehrwert
• Anchoring-Effekt: Wenn Legacy-Muster erwähnt werden, bleibt der Agent daran hängen, selbst wenn es bessere Alternativen gibt
  • Das passt zur Studie "Lost in the Middle" (Liu et al., 2024) — lange Kontexte zerstreuen die Aufmerksamkeit und verschlechtern die Leistung

Was in AGENTS.md hinein sollte – und was nicht

• Sollte hinein (Informationen, die der Agent nicht selbst finden kann)
  • Tool-Vorgaben: "uv für das Paketmanagement verwenden"
  • Nicht intuitive Regeln: "Tests müssen unbedingt mit --no-cache laufen, sonst erzeugen Fixtures False Positives"
  • Systemeinschränkungen: "Das auth-Modul nutzt Custom Middleware, kein Refactoring auf Standard-Express"
  • Wenn ein Tool in der Dokumentation erwähnt wird, verwendet es der Agent 1,6–2,5 Mal pro Aufgabe; ohne Dokumentation fällt das auf unter 0,05 Mal
• Sollte nicht hinein (was der Agent selbst entdecken kann)
  • Verzeichnisstruktur, Monorepo-Layout
  • Überblick über den Tech-Stack, standardisierte Architekturmuster

Strukturelle Grenzen statischer Dateien

• Selbst eine gut geschriebene AGENTS.md hat eine grundlegende Schwäche — die Datei ist statisch, die Aufgaben sind dynamisch
• Anweisungen in einer einzelnen Datei können nicht je nach Aufgabentyp verzweigen
  • Selbst bei einer Dokumentationsänderung gilt dann die Anweisung „vor dem Commit vollständige Tests ausführen“, was Tokens und Zeit verschwendet
  • Bei einem CSS-Refactoring werden Warnungen zu DB-Migrationen geladen, bei einem Sicherheitsfix Hinweise zur Performance-Optimierung
• ACE Framework (ICLR 2026): Ein Agentic-Context-Engineering-Ansatz, bei dem sich Kontext über eine Generator-/Reflector-/Curator-Pipeline dynamisch entwickelt, erzielte 12,3 % bessere Ergebnisse als statische Methoden

Die bessere Struktur, die noch nicht gebaut ist

• Rund um AGENTS.md sind mehrere Menschen unabhängig voneinander zum selben Schluss gekommen
  • Nicht eine einzelne Datei, sondern eine Routing-Schicht plus fokussierter, bei Bedarf geladener Kontext ist die richtige Struktur
• Layer 1 – Protokolldatei: kein Überblick über die Codebasis und kein Styleguide, sondern ein Routing-Dokument
  • Definiert verfügbare Personas und Aufrufbedingungen, Skills und zuständige Aufgabentypen, MCP-Verbindungen und deren Zweck
  • Enthält nur die minimalen Repo-Fakten, die ein Agent nicht selbst entdecken kann, und sonst nichts
• Layer 2 – Persona-/Skill-Dateien: werden je nach Aufgabentyp selektiv geladen
  • Ein UX-Agent und ein Backend-Agent laden unterschiedliche Kontexte und nicht gegenseitig den Kontext des anderen
• Layer 3 – Wartungs-Subagent: ein dedizierter Agent, der die Korrektheit der Protokolldatei aufrechterhält
  • Dokumentation verrottet — selbst die ETH-Zurich-Studie testete mit frisch erzeugten Dateien und beobachtete dennoch Leistungsabfall
  • Noch gravierender wird es, wenn eine sechs Monate lang unbeachtete AGENTS.md bereits ersetzte Abhängigkeiten oder geänderte Verzeichnisstrukturen beschreibt
• Aktuell bietet keiner der großen Coding-Agenten Lifecycle-Hooks, mit denen sich diese Architektur einfach umsetzen ließe — mit Subagenten und Scoped Context lässt sie sich annähern, aber hier besteht noch eine offene Tool-Lücke

Automatische Optimierung

• Arize AI verwendet statt manuell geschriebener Anweisungen in CLAUDE.md eine automatische Optimierungsschleife
  • Agent auf Trainingsaufgaben ausführen → Ergebnis bewerten → LLM-Feedback zur Fehlerursache erzeugen → Anweisungen per Meta-Prompting verbessern → wiederholen
  • In Cross-Repo-Tests +5,19 %, in In-Repo-Tests +10,87 % mehr Genauigkeit
• Die unbequeme Erkenntnis des Optimierers: Was Menschen beim Verständnis einer Codebasis hilft, ist nicht dasselbe wie das, was ein LLM für die Navigation braucht
  • Informationen wie „Dieser Service verwendet das Repository-Pattern“ wirken für Entwickler offensichtlich nützlich, können für das Modell aber Rauschen sein
  • Umgekehrt sind Dinge, die das Modell wirklich braucht (Unterscheidung bestimmter Import-Pfade, nicht intuitive Dateibenennungsregeln usw.), oft so stark von Entwicklern internalisiert, dass sie gar nicht daran denken, sie aufzuschreiben
• Manuelles Schreiben von AGENTS.md setzt voraus, dass Entwickler wissen, was der Agent braucht
  • Die empirische Evidenz deutet darauf hin, dass das wahrscheinlich nicht der Fall ist
  • Der Optimierer findet die Lücke zwischen „was wir für wichtig halten“ und „was das Ergebnis tatsächlich verändert“
• Das heißt nicht, dass man das Schreiben ganz aufgeben soll — 5 % sind relevant, aber nicht transformativ. Gemeint ist: Verlasst euch nur locker auf eure Intuition und testet es tatsächlich

Die richtige Denkweise gegenüber AGENTS.md

• AGENTS.md sollte als Aufzeichnung eines noch nicht behobenen Prozesses verstanden werden
• Jede zusätzliche Zeile ist ein Signal dafür, dass es in der Codebasis Unklarheiten gibt, die AI-Agenten verwirren — und dass neue menschliche Mitwirkende dort wahrscheinlich ebenfalls stolpern würden
• Die richtige Reaktion ist nicht, die Kontextdatei zu vergrößern, sondern die eigentliche Ursache zu beheben
  • Der Agent legt Utilities im falschen Verzeichnis ab → dann ist die Verzeichnisstruktur selbst verwirrend und sollte neu geordnet werden
  • Der Agent verwendet weiterhin veraltete Abhängigkeiten → dann macht die Import-Struktur es zu leicht, zu der falschen Lösung zu greifen, und sollte korrigiert werden
  • Der Agent überspringt Typprüfungen → dann sollte das nicht über Anweisungen geregelt werden, sondern automatisch in der Build-Pipeline abgefangen werden
• AGENTS.md ist keine permanente Konfiguration, sondern ein Diagnosewerkzeug — eine Zeile hinzufügen, untersuchen, warum der Agent diesen Fehler wiederholt macht, die Ursache beheben und die Zeile danach wieder löschen
• Eine mögliche Technik: Mit fast leerer AGENTS.md starten und nur die Anweisung aufnehmen: „Wenn du in diesem Projekt etwas Überraschendes oder Verwirrendes findest, hinterlasse einen Kommentar.“ Die meisten vom Agenten vorgeschlagenen Ergänzungen sind nicht für die dauerhafte Aufbewahrung gedacht, sondern Markierungen für Stellen in der Codebasis, die unklar sind

Praktische Empfehlungen

• Die Ausführung von /init beenden — sofern das Repo nicht völlig ohne Dokumentation ist, überschneiden sich die automatisch erzeugten Ergebnisse mit bestehender Dokumentation
• Bevor ihr eine Zeile in AGENTS.md ergänzt, fragt euch: „Kann der Agent das durch Lesen des Codes erkennen?“ Wenn ja, dann nicht aufschreiben
• Wenn ein Agent wiederholt scheitert, zuerst die Codebasis selbst korrigieren, bevor die Kontextdatei erweitert wird
  • Code-Struktur verbessern, Linter-Regeln ergänzen, Testabdeckung erhöhen — und erst wenn das nicht reicht, AGENTS.md anpassen
• Wenn Agenten in CI/CD oder automatisierten Review-Pipelines in großem Maßstab eingesetzt werden, sollte klar sein, dass ein Kosten-Overhead von 15–20 % sich über Tausende Ausführungen mit Zinseszinseffekt aufsummiert
• Der Impuls, Agenten wie neue Mitarbeitende zu onboarden (Büroführung, Organigramm, Architektur-Erklärung), ist zwar natürlich, aber Coding-Agenten sind keine Berufsanfänger — sie können die gesamte Codebasis durchsuchen, noch bevor ihr den Prompt fertig eingegeben habt. Was Agenten brauchen, ist keine Karte, sondern die Position der Landminen