AGENTS.md im Benchmark: Wie viel Repository-Kontext Coding Agents wirklich brauchen

Bei meinem ersten vollständigen Lauf passierte etwas, das für einen Benchmark zunächst ziemlich unpraktisch ist: Alle 45 Aufgaben wurden korrekt gelöst.

Fünf Coding-Tasks, drei Varianten des Repository-Kontexts, drei Wiederholungen pro Zelle. Kimi K3 bestand jeden einzelnen Run. Ohne AGENTS.md, mit einer kompakten Datei und mit einer deutlich längeren Variante.

Damit war die naheliegende Frage erst einmal erledigt. Zumindest in diesem kleinen Repository machte AGENTS.md den Agenten nicht erfolgreicher.

Interessant wurde es erst beim Blick darauf, wie er zur Lösung kam.

Bei einer Aufgabe mit generiertem Code brauchte der Agent ohne Repository-Instruktionen im Median 11 Tool Calls. Mit einer kompakten AGENTS.md waren es 7, mit der ausführlichen Variante 5. Die Lösung war jedes Mal richtig. Ohne Hinweis musste der Agent den richtigen Weg nur erst im Repository suchen.

Bei einer anderen Aufgabe passierte das Gegenteil: Die Instruktionen sorgten dafür, dass der Agent zusätzliche Tests ausführte. Das kostete Zeit, war aber genau das Verhalten, das die Repository-Regeln verlangten.

Der vollständige Benchmark mit Harness, Rohdaten, Transkripten und Diffs liegt auf GitHub.

Drei Dateien, ansonsten derselbe Run

Ich wollte keinen allgemeinen Coding-Benchmark bauen. Dafür gibt es bessere und wesentlich grössere Testsets. Mich interessierte nur der Einfluss von Repository-Instruktionen.

Deshalb bleibt innerhalb eines Vergleichs alles gleich: Modell, Agent-Version, Prompt, Fixture, Timeout und Ausgangszustand. Geändert wird nur, welche Datei im Root des Arbeitsverzeichnisses liegt.

Bedingung	Repository-Kontext	Umfang
none	keine AGENTS.md	0 Wörter
concise	nur nicht offensichtliche Arbeitsregeln	129 Wörter
verbose	dieselben Regeln plus Architektur- und Modulbeschreibung	726 Wörter

Die kompakte Variante enthält zum Beispiel diese Hinweise:

Run make test-fast while iterating.
Run make check before finishing.

All user facing failures go through ledger.errors.fail(...).

src/ledger/currency_codes.py is generated.
Edit data/currencies.json and run make gen.

Die lange Variante sagt inhaltlich dasselbe, erklärt zusätzlich aber Repository-Aufbau, Module, Datenmodell, Testing-Philosophie und Projektgeschichte.

Das Testrepository selbst ist absichtlich klein. ledger ist ein Python-Paket ohne externe Abhängigkeiten. Es verarbeitet einfache Finanztransaktionen und enthält genug Struktur, um typische Situationen aus realen Projekten nachzubilden: generierten Code, eine projektspezifische Fehlerkonvention, schnelle und langsame Tests sowie ein Acceptance Gate, das mehr prüft als die normalen Unit Tests.

Fünf Tasks statt eines grossen Tickets

Die Tasks testen unterschiedliche Arten von Kontext.

Task	Zweck
t01_obvious_command	Kontrollfall: der richtige Testbefehl ist bereits offensichtlich
t02_error_convention	eine nicht im README erklärte Error-Handling-Regel
t03_generated_file	generierter Code mit separater Source of Truth
t04_local_bugfix	Kontrollfall: ein lokaler Einzeiler ohne Repository-Spezialwissen
t05_slow_suite	schneller Entwicklungs-Loop gegen vollständiges Acceptance Gate

Jeder Task läuft dreimal unter jeder der drei Bedingungen. Insgesamt ergibt das 45 Agent-Runs.

Gemessen habe ich mit kimi-code 0.31.1 und kimi-code/k3. Jeder Run bekommt ein frisches Git-Repository. Danach werden Fixture, Task-Seed und die jeweilige Kontextvariante hineinkopiert und als Ausgangszustand committed.

Der Agent sieht die Hidden Tests nicht. Sie werden erst nach seinem Lauf in das Arbeitsverzeichnis kopiert. Zusätzlich prüft der Harness je nach Aufgabe konkrete Repository-Regeln: ob Tests angelegt wurden, ob die richtige Quelldatei geändert wurde oder ob eine Konvention verletzt wurde.

Zu jedem Run bleiben Prompt, Modell, Hashes, Tool Calls, Tokens, geänderte Dateien, Verifier-Ausgabe, vollständiger Agent-Stream und Git-Diff erhalten.

Das ist für einen kleinen Blog-Benchmark mehr Aufwand als ein paar Prompts hintereinander auszuführen. Ohne diese Daten wäre die interessanteste Beobachtung aber kaum nachvollziehbar.

45 von 45 bestanden

Das Gesamtergebnis sieht zunächst langweilig aus:

Bedingung	Runs	Bestanden	Median Laufzeit	Median Output-Tokens	Median Tool Calls
ohne Kontext	15	15	52,6 s	772	7
kompakt	15	15	41,8 s	603	6
ausführlich	15	15	42,2 s	642	5

Aus den Laufzeiten würde ich keine Rangliste ableiten. Drei Wiederholungen pro Task sind dafür viel zu wenig, und der Remote-Backend-Anteil macht die Wanduhrzeit zusätzlich unruhig.

Auch die gepoolten Tool- und Token-Mediane sind nur eine Übersicht. Die fünf Tasks messen bewusst unterschiedliche Situationen.

Der wichtige Wert steht deshalb in der zweiten Spalte: 100 Prozent Erfolgsrate in allen drei Bedingungen.

Das Experiment hat damit einen Ceiling Effect. Kimi K3 war für diese Aufgaben schlicht zu stark.

Das gilt sogar für die beiden Fälle, bei denen ich eigentlich Fehler provozieren wollte.

Bei t02 sollte eine negative Summe abgefangen werden. Im Projekt müssen benutzerseitige Fehler über ledger.errors.fail(code, message) laufen. Ein direktes ValueError würde in der CLI als Traceback herausfallen. Die normalen Tests erkennen diesen Verstoss nicht; erst make check prüft die Konvention.

Auch ohne AGENTS.md fand der Agent errors.py, erkannte das bestehende Muster und verwendete den richtigen Helper.

Bei t03 war src/ledger/currency_codes.py absichtlich eine Falle. Die Datei ist generiert. Die eigentliche Quelle liegt in data/currencies.json. Wer nur das Python-Modul editiert, kann die sichtbaren Tests bestehen und trotzdem einen inkonsistenten Repository-Zustand hinterlassen.

Auch darauf fiel Kimi ohne Kontext kein einziges Mal herein.

Für die Frage, ob Repository-Instruktionen die Korrektheit erhöhen, liefert dieser Lauf also keine belastbare Antwort.

Beim generierten Code halbierte sich die Sucharbeit

t03 ist trotzdem der interessanteste Task des Benchmarks.

Die Aufgabe lautet sinngemäss: Unterstütze zusätzlich Schweizer Franken. parse_line soll CHF akzeptieren und format_amount(1250, 'CHF') den Wert korrekt formatieren.

Ohne AGENTS.md weiss der Agent nicht, dass currency_codes.py generiert ist. Die Information ist aber auffindbar. Im File selbst steht ein Hinweis, daneben existiert das Generator-Script und im Makefile gibt es ein entsprechendes Target.

Kimi findet das alles. Er muss danach nur suchen.

Die Mediane:

Bedingung	Output-Tokens	Bash Calls	Tool Calls
ohne Kontext	1.197	5	11
kompakt	791	3	7
ausführlich	642	2	5

Bei den einzelnen Wiederholungen wird der Unterschied noch anschaulicher:

Tool Calls

none:    11, 11, 10
concise:  4,  9,  7
verbose:  5,  5,  5

Ohne Instruktionen liest und durchsucht der Agent mehrere Dateien, bis er die Beziehung zwischen JSON-Datei, Generator und generiertem Modul rekonstruiert hat.

Mit Instruktionen kennt er diese Beziehung vor dem ersten Tool Call.

Das ist für mich der praktisch wichtigste Unterschied. Die AGENTS.md liefert hier keine Fähigkeit, die dem Modell fehlt. Sie spart Discovery.

In einem kleinen Repository sind das ein paar Reads, Greps und Shell-Befehle. In einem Monorepo mit mehreren Buildsystemen, generierten Clients und projektspezifischen Deployment-Schritten kann derselbe Effekt wesentlich teurer werden.

Die Kontrollfälle zeigen fast keinen Effekt

Ein Benchmark, in dem Kontext überall hilft, wäre verdächtig.

Deshalb gibt es zwei Aufgaben, bei denen die Datei wenig beitragen sollte.

t01 verlangt eine kleine Parser-Korrektur. Der relevante Testbefehl steht bereits im README und im Makefile. In allen drei Bedingungen benötigte der Agent im Median genau einen Bash Call und vier Tool Calls.

t04 ist ein lokaler Bugfix ohne besondere Projektregel. Auch dort liegen die Bedingungen eng beieinander.

Das ist kein Beweis für Kausalität bei t03. Es ist aber ein brauchbarer Sanity Check: Die zusätzliche Datei beschleunigt den Agenten nicht einfach bei jeder beliebigen Aufgabe.

Mehr Instruktionen können auch mehr Arbeit bedeuten

t05 dreht die Effizienzgeschichte um.

Die Aufgabe selbst ist klein: Eine Funktion totals_by_month() ergänzen und einen Unit Test schreiben.

Die AGENTS.md enthält aber zwei Regeln für den Entwicklungsablauf:

Iterate with make test-fast.
Run make check before you consider a task done.

make check startet auch die langsame Suite.

Ohne Kontext führte Kimi in keinem der drei Runs einen Full-Suite-Test aus:

none:    0, 0, 0
concise: 0, 0, 1
verbose: 1, 1, 0

Das sieht aus Effizienzsicht zunächst schlechter aus. Der Agent macht mehr Arbeit, weil man ihm mehr Regeln gegeben hat.

Aus Sicht des Repository-Maintainers kann genau das richtig sein.

Wenn make check das Acceptance Gate ist, ist ein zusätzlicher Lauf kein verschwendeter Tool Call. Er ist die gewünschte Qualitätskontrolle.

Damit wird auch klar, warum Aussagen wie „AGENTS.md reduziert Tool Calls“ allein nicht reichen. Repository-Instruktionen sollen das Verhalten steuern. Manchmal bedeutet richtiges Verhalten gerade, einen zusätzlichen Test auszuführen.

Die lange Datei war überraschend unproblematisch

Vor dem Experiment hätte ich erwartet, dass die 726 Wörter der ausführlichen Variante eher schaden.

Sie enthält viel, was Kimi selbst aus dem Repository ableiten kann: Verzeichnisstruktur, Modulbeschreibungen, Architekturhinweise und Projekthistorie. Die operativen Regeln sind dieselben wie in der 129-Wörter-Fassung.

Im Benchmark sehe ich dafür keinen Verhaltensnachteil. Bei t03 hatte die ausführliche Variante sogar die wenigsten Tool Calls und Output-Tokens.

Daraus würde ich trotzdem nicht folgern, dass lange AGENTS.md-Dateien genauso gut oder besser sind.

726 Wörter sind für moderne Kontextfenster immer noch wenig. Drei Wiederholungen pro Zelle sind ebenfalls zu wenig, um kleine Effekte sauber zu messen.

Einen Preis bezahlt die lange Variante aber in jedem Run: Sie belegt mehr Input-Kontext. Im Median waren es ungefähr 450 zusätzliche Non-Cache-Input-Tokens gegenüber der kompakten Datei.

Das ist bei einem einzelnen Request kaum relevant. Bei Tausenden Agent-Turns oder permanent injizierten Instruktionen summiert sich solcher Kontext.

Drei Studien kommen zu unterschiedlichen Ergebnissen

Genau dieser Punkt taucht auch in der aktuellen Forschung auf.

Gloaguen et al. untersuchen in Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? Repository-Instruktionen in einer grösseren Evaluation. Sie finden keinen generellen Qualitätsgewinn und berichten gleichzeitig mehr als 20 Prozent höhere Inferenzkosten in den untersuchten Settings.¹

Ein Teil ihrer Analyse ist für die Praxis besonders interessant: Generierte Repository-Beschreibungen wiederholen oft Informationen, die bereits im README, in Projektdateien oder im Code stehen. Wenn andere Dokumentationsquellen entfernt werden, wird der zusätzliche Kontext nützlicher. In normal dokumentierten Repositories ist ein Teil davon schlicht redundant.¹

Lulla et al. kommen in On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents zu einem anderen Bild. In ihrem Versuchsaufbau reduzieren Repository-Instruktionen die Laufzeit um 28,64 Prozent und die Output-Tokens um 16,58 Prozent.²

Khatri vergleicht Context Files mit Claude Code und Codex CLI auf realen Repositories. Dort verändern vollständiger beziehungsweise selektiver Kontext die Erfolgsraten nur gering. Bei einzelnen Tasks verändert sich das Verhalten dagegen deutlich, zum Beispiel bei unnötigen Full-Suite-Runs.³

Diese Ergebnisse müssen sich nicht widersprechen.

Eine Datei, die dem Agenten eine schwer sichtbare Repository-Eigenschaft nennt, kann Sucharbeit sparen. Genau das sehe ich bei meinem generierten Currency-Modul.

Eine Datei, die überwiegend offensichtliche Architekturinformationen wiederholt, trägt dagegen vor allem zusätzlichen Kontext mit sich herum.

Und eine Datei, die explizit weitere Validierungen verlangt, kann den Tool-Aufwand erhöhen, obwohl der Agent dadurch näher am gewünschten Entwicklungsprozess arbeitet.

AGENTS.md ist für mich kein zweites README

Nach diesem Benchmark würde ich eine Repository-Instruktionsdatei nicht danach optimieren, möglichst viel über das Projekt zu erklären.

Ein Coding Agent kann Verzeichnisstrukturen lesen. Er findet package.json, pyproject.toml, Gradle-Dateien, Tests und bestehende Patterns selbst. Diese Exploration gehört zu seiner Arbeit und liefert ihm gleichzeitig den aktuellen Zustand des Repositories.

Wertvoller sind Informationen, die er zwar theoretisch finden könnte, bei denen Suche aber teuer oder fehleranfällig ist:

src/generated/ wird niemals direkt editiert.
Die Source of Truth liegt unter schema/.

Für schnelle Iteration nur :service:test ausführen.
Die vollständige Integration Suite braucht rund 15 Minuten.

Vor Abschluss muss ./gradlew acceptanceCheck grün sein.

Datenbankmigrationen müssen für ein Release rückwärtskompatibel bleiben.

Der Agent darf aus dieser Umgebung niemals pushen.

Das sind keine Architekturzusammenfassungen. Es sind Entscheidungsregeln.

Eine brauchbare Prüffrage für jede Zeile lautet deshalb:

Spart diese Information dem Agenten eine relevante Suche, einen plausiblen Fehler oder eine falsche Entscheidung?

Wenn nicht, gehört sie wahrscheinlich eher ins README oder in normale Projektdokumentation.

GitHub empfiehlt für Copilot Custom Instructions ebenfalls kurze, in sich geschlossene Anweisungen und unterstützt pfadspezifische Dateien, damit Regeln nur dort in den Kontext gelangen, wo sie gebraucht werden.⁴⁵

Was der Benchmark nicht zeigt

Der grösste Schwachpunkt ist offensichtlich: Die Aufgaben waren für Kimi K3 zu leicht.

Bei 45 von 45 erfolgreichen Runs kann ich nicht messen, ob Repository-Kontext aus einem falschen Patch einen richtigen macht. Dafür müsste die Baseline gelegentlich scheitern.

Ein zweiter Lauf sollte deshalb entweder schwierigere Tasks oder ein kleineres Modell verwenden. Sinnvoll wäre ein Bereich, in dem die No-Context-Bedingung vielleicht 50 bis 80 Prozent der Aufgaben löst. Erst dann wird Correctness als Metrik interessant.

Dazu kommen die üblichen Einschränkungen: ein synthetisches Repository, nur ein Agent, nur ein Modell und drei Wiederholungen pro Zelle. Eine reale Codebasis mit Hunderttausenden Zeilen kann sich anders verhalten.

Auch die Laufzeit ist keine besonders saubere Metrik. Der Agent läuft gegen einen entfernten Backend-Service. Tool Calls, Bash-Aufrufe und Output-Tokens lassen sich deshalb in diesem Versuch besser interpretieren als einzelne Sekunden Differenz.

Die Rohdaten bleiben bewusst im Repository. Ein negatives oder nicht diskriminierendes Ergebnis ist für mich kein Grund, den Versuch umzubauen, bis eine schönere Zahl herauskommt.

Weniger Dokumentation, mehr Betriebswissen

Mein erster Lauf liefert keinen Beleg dafür, dass jedes Repository eine AGENTS.md braucht.

Er zeigt aber recht gut, wo solche Dateien nützlich werden können.

Kimi konnte den generierten Code auch ohne Hinweis korrekt behandeln. Er brauchte dafür nur ungefähr doppelt so viele Tool Calls. Bei offensichtlichen Aufgaben brachte zusätzlicher Kontext praktisch nichts. Und eine explizite Acceptance-Regel führte dazu, dass der Agent mehr prüfte statt weniger.

Das ist näher an meiner praktischen Erwartung als die Vorstellung eines pauschalen Context Boosts.

Repository-Instruktionen machen ein starkes Modell nicht automatisch schlauer. Sie können ihm aber Entscheidungen abnehmen, die sonst erst durch Exploration entstehen.

Genau diese Informationen würde ich in AGENTS.md schreiben: wenig Beschreibung, wenig Wiederholung und möglichst viel projektspezifisches Wissen darüber, wie man in diesem Repository nichts kaputt macht.

Footnotes#

1. Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, Martin Vechev: Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?, 2026. Projektseite der ETH Zürich: https://www.sri.inf.ethz.ch/publications/gloaguen2026agentsmd ↩ ↩²

2. Jai Lal Lulla, Seyedmoein Mohsenimofidi, Matthias Galster, Jie M. Zhang, Sebastian Baltes, Christoph Treude: On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents, 2026. ↩

3. Prakhar Khatri: Do Context Files Help Coding Agents? A Two-Agent Ablation Study on Real Repositories, 2026. Reproduktionscode und aggregierte Ergebnisse: https://github.com/codeprakhar25/context-files-coding-agents ↩

4. GitHub Docs: Adding repository custom instructions for GitHub Copilot, abgerufen im August 2026. ↩

5. GitHub Docs: Adding path-specific custom instructions for GitHub Copilot, abgerufen im August 2026. ↩