AGENTS.md ist kein Kontext. Es ist eine Steuerfläche.

Die kurze Version

Es gibt eine verführerische Geschichte über Repo-Instruktionsdateien wie AGENTS.md, CLAUDE.md oder .cursorrules.

Sie geht so: Coding Agents scheitern, weil sie das Repo nicht verstehen. Also geben wir ihnen mehr Kontext. Architekturhinweise. Testkommandos. Stilregeln. “So arbeiten wir hier.” Dann verhält sich der Agent eher wie ein Senior Developer, der seit Jahren im Code lebt.

Das ist eine schöne Geschichte.

Sie ist aber unvollständig.

Ein neues Paper, Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?, prüft genau diese Frage. Die Autoren vergleichen Coding-Agent-Performance ohne Kontextdatei, mit LLM-generierter Kontextdatei und mit developer-geschriebener Kontextdatei.

Der unbequeme Befund ist nicht, dass Kontextdateien ignoriert werden.

Der unbequeme Befund ist, dass sie oft funktionieren.

Sie verändern Verhalten. Agents lesen mehr Dateien, suchen mehr, testen mehr und nutzen mehr repo-spezifische Tools. Manchmal ist genau das richtig. Manchmal wird aus einem kleinen Patch ein Ritual.

3

Setups: none, generated, developer-written

138

AGENTBENCH Python Tasks

1

Frage: welches Verhalten erzeugt die Datei?

Die falsche Frage

Die offensichtliche Frage lautet:

Helfen AGENTS.md-Dateien?

Die bessere Frage lautet:

Welches Verhalten erzeugt diese Datei,
und wann ist dieses Verhalten den Preis wert?

Dieser Unterschied ist wichtig.

Viele Teams behandeln AGENTS.md noch wie Onboarding-Dokumentation. Aber Coding Agents sind keine neuen Mitarbeiter. Ein Mensch kann ein langes Dokument überfliegen, irrelevante Abschnitte ignorieren, den Geist einer Regel behalten und Urteilskraft anwenden.

Ein Agent kann jeden Satz als operative Anweisung behandeln.

Wenn die Root-Kontextdatei sagt:

• lies immer die Architekturdocs
• führe immer die komplette Testsuite aus
• prüfe immer diese fünf Verzeichnisse
• nutze immer dieses repo-spezifische Tool
• bedenke immer Edge Cases in jedem Subsystem

dann zieht der Agent auch einen Zwei-Zeilen-Fix durch diesen Prozess.

Aus Benchmark-Sicht wirkt das ineffizient. Aus Harness-Sicht ist es genauer: Die Instruktionsdatei wurde zu einem bedingungslosen Steuermechanismus.

Das ist der entscheidende Shift.

AGENTS.md ist nicht nur Kontext.

Es ist eine Steuerfläche.

AGENTS.md als Steuerfläche

nicht Repo-Wissen → besserer Agent, sondern Instruktion → Verhalten

1. 01
   Instruktion
2. 02
   Aufmerksamkeit
3. 03
   Tool-Nutzung
4. 04
   Verifikation
5. 05
   Kosten
6. 06
   Ergebnis

Mehr Kontext kann Arbeit verschlechtern

Sobald du AGENTS.md als Steuerfläche siehst, klingt “mehr Kontext” nicht mehr automatisch gut.

Mehr Kontext kann mehr Reibung bedeuten.

Mehr Regeln können mehr falsche Pflichten erzeugen.

Mehr Repo-Wissen kann mehr irrelevante Exploration auslösen.

Mehr hilfreiche Hinweise können mehr Wege schaffen, den Agenten von der eigentlichen Aufgabe abzulenken.

Das heißt nicht, dass AGENTS.md schlecht ist. Es heißt, dass stumpfes Kontext-Injizieren schlecht ist.

Der Befund aus dem Paper passt zu einem Muster, das viele Agent-Teams praktisch sehen: Instruktionen können Agents gründlicher machen, ohne sie erfolgreicher zu machen.

Das ist ein teurer Failure Mode, weil er verantwortungsvoll aussieht.

Der Agent hat mehr gesucht. Mehr Kommandos ausgeführt. Mehr repo-spezifische Details erwähnt. Es wirkt sorgfältig.

Aber sorgfältig ist nicht dasselbe wie korrekt.

Gründlich ist nicht dasselbe wie fertig.

Generierter Kontext hat die falschen Anreize

LLM-generierte AGENTS.md-Dateien sind besonders fragil, weil sie meist zusammenfassen, was sichtbar ist.

Sichtbar ist nicht dasselbe wie wichtig.

Eine generierte Kontextdatei kann offensichtliche Ordnerstruktur nacherzählen, Tools erwähnen ohne zu wissen, wann sie relevant sind, oder weiche Konventionen zu harten Regeln aufblasen.

Developer-geschriebener Kontext ist besser, weil er Geschmack und Narben codieren kann:

Bearbeite diese generierte Datei nicht.
Diese Testsuite ist flaky; nutze zuerst dieses engere Kommando.
Dieses Package sieht ungenutzt aus, wird aber dynamisch geladen.
Ändere diese API nie ohne Check des Mobile Clients.
Bei reinen Copy-Änderungen: keine volle e2e-Suite.

Solche Instruktionen reduzieren Unsicherheit, statt sie zu erhöhen.

Der beste Repo-Kontext beschreibt nicht alles.

Er verhindert bekannte schlechte Verhaltensweisen.

Repo-Handbuch vs. Steuerfläche

Repo-Handbuch

• Erklärt die ganze Architektur.
• Gibt allgemeine Hinweise.
• Wird global geladen.
• Optimiert auf Vollständigkeit.
• Fühlt sich hilfreich an.

Steuerfläche

• Routet den Agenten zum relevanten Kontext.
• Definiert konkretes Verhalten.
• Wird bedingt nach Task und Pfad geladen.
• Optimiert auf Ergebnis und Kosten.
• Wird über Traces und Evals gemessen.

Root-AGENTS.md sollte langweilig sein

Eine gute Root-AGENTS.md sollte kurz sein. Sie sollte nur Instruktionen enthalten, die fast immer gelten.

Pack die langweiligen Invarianten hinein:

• bevorzugter Package Manager
• günstige Setup-Kommandos
• Default-Test- oder Lint-Kommandos
• generierte Dateien, die nicht editiert werden dürfen
• externe Aktionen, die Approval brauchen
• Regeln zu Secrets, Deploys, Migrationen, Payments und unrelated changes

Alles andere sollte bedingt sein.

Wenn du Frontend-Code anfasst, lies docs/frontend.md.
Wenn du Datenbankmigrationen änderst, lies docs/database.md.
Wenn du Auth editierst, stoppe und prüfe docs/security.md.
Wenn es nur Copy ist, führe nicht die volle Integration Suite aus.
Wenn der Diff mehr als 5 Dateien berührt, erkläre vorher warum.

Das ist eine andere Philosophie als “pack den ganzen Kontext in den Prompt”.

Es ist näher an Harness-Design.

Der Harness sollte entscheiden, welche Instruktionen geladen werden: nach Task, Pfad, Risiko und aktuellem Fehlermodus.

Ein kleiner CSS-Fix braucht nicht denselben operativen Kontext wie eine Datenbankmigration. Ein failing Unit Test braucht nicht dieselbe Schleife wie ein Multi-Service-Refactor. Ein Triage-Agent braucht anderen Kontext als ein Agent, der einen Produktionspatch vorbereitet.

Was in die Root-Datei gehört

• Regeln, die fast immer gelten.
• Kommandos, die günstig und zuverlässig sind.
• Grenzen, die teure Fehler verhindern.
• Approval Gates für externe oder destruktive Aktionen.
• Verweise auf bedingte Dateien statt den Volltext jeder Datei.

Kontext soll routen, nicht fluten

Die Zukunft sind nicht bessere One-Shot-Prompts.

Die Zukunft sind bessere Loops.

Ein Coding Loop sollte eher so aussehen:

Task klassifizieren
relevante Instruktionen laden
kleinsten sinnvollen Codebereich inspizieren
fokussierte Änderung machen
günstigste sinnvolle Verifikation laufen lassen
Diff prüfen
nur bei actionable failure erneut versuchen
bei Ambiguität oder Risiko eskalieren

In diesem Modell ist AGENTS.md nicht das ganze Gehirn. Es ist ein Input in den Loop.

Der Loop entscheidet, wann die Datei gelesen wird, wie viel davon gilt und wann Teile ignoriert werden.

Das ist der Punkt, den viele Teams verpassen. Sie verbessern die statische Datei, obwohl sie eigentlich die Context-Loading-Policy verbessern müssten.

Die Frage ist nicht:

Was können wir dem Agenten noch sagen?

Die Frage ist:

Was braucht der Agent jetzt, um die nächste Entscheidung zu treffen?

Das ist nicht dieselbe Frage.

Instruktionen wie Code messen

Agent-Instruktionen sollten wie Codeänderungen evaluiert werden.

Wenn eine neue Regel Agents langsamer macht, ohne sie korrekter zu machen, ist sie keine gute Regel.

Wenn eine Kontextdatei Agents “gründlicher” macht, aber nicht erfolgreicher, ist sie vielleicht nur teure Nervosität.

Wenn eine generierte AGENTS.md zusätzliche Exploration auslöst, ohne echte Fehler zu verhindern, lösche oder begrenze sie.

Wenn eine developer-geschriebene Regel wiederholt schlechte Diffs verhindert, behalte sie.

Die Traces zählen:

• welche Dateien hat der Agent gelesen?
• welche Kommandos hat er ausgeführt?
• welche Tools hat er genutzt?
• wie viele Retries gab es?
• wo hat er gestoppt?
• hat die Instruktion das Ergebnis verändert oder nur die Zeremonie?

So wird Context Engineering zu Engineering statt Prompt-Folklore.

Bessere AGENTS.md-Dateien schreiben

Machen

• ✓ Root-Instruktionen kurz und testbar halten
• ✓ Bedingte Dateien für task-spezifische Guidance nutzen
• ✓ Regeln gegen bekannte Failure Modes schreiben
• ✓ Verhaltensänderungen über Traces und Evals messen
• ✓ Regeln löschen, die nur Zeremonie hinzufügen

Nicht machen

• × AGENTS.md zum Architektur-Essay machen
• × Jede Regel für jeden Task laden
• × Generierten Kontext als Domain Expertise behandeln
• × Mehr Tool-Nutzung mit besserer Arbeit verwechseln
• × Annehmen, dass mehr Kontext mehr Zuverlässigkeit bedeutet

Die praktische Regel

Schreibe AGENTS.md, als würdest du Agent-Verhalten programmieren, nicht als würdest du das Repo dokumentieren.

Jede Instruktion muss sich lohnen.

Frag:

• gilt das für die meisten Aufgaben?
• ist es konkret genug, um ausgeführt zu werden?
• reduziert es Suche oder erhöht es sie?
• verhindert es einen echten Failure Mode?
• sollte es bedingt statt global sein?
• kann der Harness das besser erzwingen als Prosa?
• will ich diese Instruktion auch bei einem Ein-Zeilen-Fix anwenden?

Wenn die Antwort nein ist, gehört die Instruktion wahrscheinlich nicht in die Root-Datei.

Der beste Agent-Kontext ist nicht maximal.

Er ist selektiv.

Kurze Root-Datei. Hierarchische Task-Dateien. Klare Trigger. Konkrete Kommandos. Explizite Stop-Bedingungen. Gemessene Outcomes.

Das Ziel ist nicht, dem Agenten alles zu sagen.

Das Ziel ist, dass der Agent das Richtige lädt, zur richtigen Zeit, aus dem richtigen Grund, und stoppt, wenn der Job erledigt ist.