AGENTS.md

Was ist AGENTS.md?

AGENTS.md ist eine einfache Markdown-Datei, die in einem Repository abgelegt wird, um KI-Coding-Agenten mitzuteilen, wie das Projekt funktioniert: Build- und Test-Befehle, Code-Konventionen, Architekturhinweise und einzuhaltende Regeln. Es handelt sich um eine herstellerneutrale Konvention, die oft als „README für Agenten" bezeichnet wird, und sie wird Stand 2026 von den meisten Coding-Agenten automatisch eingelesen.

Die wichtigsten Punkte

• Eine Datei bedient viele Tools. Der Sinn von AGENTS.md ist, dass Codex, Cursor, Gemini CLI, Jules und Dutzende weiterer Agenten alle dieselben Anweisungen lesen, statt dass jeder seine eigene Konfigurationsdatei verlangt.
• Sie enthält, was ein README auslässt. Menschen erhalten Kontext durch Onboarding und Team-Chats; Agenten brauchen exakte Befehle, Konventionen und Verbote schriftlich festgehalten.
• Die Platzierung ist hierarchisch. Ein AGENTS.md im Root deckt das gesamte Repo ab, und Dateien in Unterverzeichnissen überschreiben es für ihren Teilbaum, was sich für Monorepos eignet.
• Es ist einfaches Markdown ohne vorgeschriebenes Schema. Die Konvention standardisiert Dateiname und Ort, den Inhalt legt jedes Team selbst fest.
• Die Qualität zeigt sich direkt in der Ausgabe des Agenten. Vage oder veraltete Anweisungen führen zu Agenten, die raten, und ratende Agenten verursachen Nacharbeit.

So funktioniert es

Wenn ein Coding-Agent eine Session in einem Repository startet, sucht er im Projekt-Root nach AGENTS.md und lädt den Inhalt in seinen Kontext, bevor er irgendeine Arbeit verrichtet – ähnlich wie ein neuer Mitarbeiter zunächst das README lesen würde. Die Datei bestimmt danach jede Entscheidung des Agenten: welchen Paketmanager er aufruft, wie er die Testsuite ausführt, welche Namenskonventionen gelten und welche Verzeichnisse tabu sind. In Monorepos wenden Agenten das nächstgelegene AGENTS.md im Verzeichnisbaum ausgehend von den bearbeiteten Dateien an, sodass ein Python-Service und ein TypeScript-Frontend jeweils eigene Regeln tragen können, während sie repo-weite Standardwerte teilen. OpenAI treibt das weiter als die meisten: Das eigene Monorepo pflegt 88 AGENTS.md-Dateien, und die offizielle agents.md-Seite listet rund 25 unterstützende Agenten und Tools, darunter Codex, Gemini CLI, Cursor und GitHub Copilots Coding Agent [1].

Das Format entstand 2025 aus einer von OpenAI angeführten Initiative, den angehäuften Wildwuchs an tool-spezifischen Anweisungsdateien zu konsolidieren, und die Verbreitung ging schnell, weil der Aufwand eine einzige Markdown-Datei ist und der Nutzen jedem Agenten zugutekommt, der das Repo anfasst. Es gibt bewusst kein Schema. Effektive Dateien konvergieren trotzdem meist auf dieselben Abschnitte: Setup- und Build-Befehle, Test-Befehle in der Erwartung, dass Agenten sie ausführen, Code-Style-Regeln, Commit- und PR-Konventionen sowie Sicherheitsgrenzen wie nie zu verändernde Dateien. Eine empirische Studie aus dem Jahr 2025 mit 2.303 Agent-Kontextdateien aus 1.925 Repositories bestätigte dieses Muster: Testabläufe fanden sich in 75,9 % der Dateien, Implementierungsdetails in 70,8 % und Architektur in 68,1 %, während Sicherheitshinweise nur in 14,8 % auftauchten [2]. Manche Tools, die älter sind als die Konvention, behalten ihren eigenen Dateinamen, am sichtbarsten Claude Codes CLAUDE.md, und Teams pflegen häufig eine kanonische Datei, während die andere als Verweis oder Symlink dient.

Die Datei ist deshalb wichtig, weil sie Context Engineering zum Nulltarif ist. Anweisungen in AGENTS.md erreichen den Agenten bei jeder Session ohne zusätzlichen Aufwand pro Aufgabe, was sie zum natürlichen Ort für alles macht, was man sonst ständig in Prompts wiederholen würde.

Beispiel

Ein Team stellt fest, dass sein Coding-Agent in einem pnpm-Workspace immer wieder npm verwendet, die Lockfile zerstört und Tests im falschen Verzeichnis anlegt. Sie fügen im Root ein AGENTS.md hinzu: nur pnpm verwenden, vor Abschluss jeder Aufgabe pnpm test --filter <package> ausführen, Tests liegen als .spec.ts-Dateien neben dem Quellcode, generierte Dateien unter src/gen/ niemals bearbeiten, und alle API-Änderungen erfordern zuerst ein Update der OpenAPI-Spezifikation. In der nächsten Session baut derselbe Agent ein Feature auf Anhieb korrekt auf. Die Anweisungen haben das Modell nicht klüger gemacht; sie haben jede Stelle beseitigt, an der es zuvor raten musste.

Häufige Missverständnisse

Der häufigste Fehler ist, AGENTS.md einmal zu schreiben und dann verwahrlosen zu lassen. Agenten folgen der Datei wortwörtlich, sodass ein veralteter Build-Befehl oder eine Regel, die auf ein gelöschtes Verzeichnis verweist, sie aktiv in die Irre führt – schlimmer, als gar nichts zu sagen. Behandeln Sie die Datei wie Code: aktualisieren Sie sie im selben Pull Request, der den beschriebenen Workflow ändert, und entfernen Sie Regeln, die nicht mehr gelten. Eine kurze, aktuelle Datei schlägt eine lange, veraltete immer.

FAQ

Ist AGENTS.md ein offizieller Standard? Es ist eine offene Konvention mit einer öffentlichen, spezifikationsartigen Website und Unterstützung mehrerer Anbieter, aber keine formale Spezifikation eines Standardisierungsgremiums. In der Praxis behandelt das Ökosystem es als Standard: Die offizielle agents.md-Seite zählt mehr als 60.000 Open-Source-Projekte auf GitHub, die das Format nutzen [3].

Wie unterscheidet sich AGENTS.md von einem README? Zielgruppe und Präzision. Ein README wirbt und orientiert: was das Projekt ist, warum es existiert, wie man einsteigt. AGENTS.md instruiert einen Ausführenden ohne institutionelles Wissen und mit totalem Gehorsam, weshalb es exakte Befehle und harte Regeln der erzählerischen Form vorzieht.

Was sollte zuerst hinein? Beginnen Sie mit allem, was Sie einem Agenten bereits zweimal gesagt haben: den korrekten Test-Befehl, den Paketmanager, das eine Verzeichnis, das er nicht anfassen darf. Fügen Sie Konventionen hinzu, sobald Verstöße auftreten. Zehn präzise Zeilen liefern den Großteil des Nutzens.

Quellen

1. agents.md. "OpenAI monorepo AGENTS.md count and list of supporting agents and tools." https://agents.md/. Abgerufen im August 2026.
2. arXiv. "Agent READMEs: An Empirical Study of Context Files for Agentic Coding, section frequency across 2,303 context files." https://arxiv.org/abs/2511.12884. Abgerufen im August 2026.
3. agents.md. "Count of open-source projects using the AGENTS.md format." https://agents.md/. Abgerufen im August 2026.