Erklärtext · aktualisiert Oct 10, 2026

Was ist AGENTS.md und wie Coding-Agenten sie nutzen

AGENTS.md ist eine einfache Markdown-Datei in einem Repository, die Coding-Agenten Build-Schritte, Tests und Konventionen liefert. Sie hat keine Pflichtfelder, und Agenten lesen die nächstgelegene Datei im Verzeichnisbaum.

AGENTS.md →

Was AGENTS.md ist

AGENTS.md ist eine einfache Markdown-Datei, die Sie in ein Repository legen, um Coding-Agenten die Projektanweisungen zu geben, die sie brauchen, etwa Build-Schritte, Tests und Konventionen. Die AGENTS.md-Website beschreibt sie als README für Agenten. Menschen lesen weiter die normale README, während Agenten einen verlässlichen Ort für die Details bekommen, die sie überfrachten würden. Laut der Website wird das Format von der Agentic AI Foundation unter der Linux Foundation betreut. Zu den Agenten, die sie lesen, gehören Claude Code, OpenAI Codex, Gemini CLI, Cursor und GitHub Copilot.

Es gibt keine Pflichtfelder und kein Schema. Es ist Standard-Markdown, Sie können also beliebige Überschriften verwenden. Wie ein Agent den Inhalt behandelt, hängt vom jeweiligen Agenten ab. Das sollten Sie wissen, bevor Sie sich darauf verlassen. Weil das Format keine Regeln für den Inhalt vorgibt, können zwei Agenten dieselbe Datei lesen und unterschiedlich darauf reagieren. Prüfen Sie deshalb, wie jedes von Ihnen genutzte Tool damit umgeht.

Eine README für Menschen, eine AGENTS.md für Agenten: Build-Schritte, Tests und Konventionen

Wie AGENTS.md funktioniert

Ein Agent liest die AGENTS.md, die der bearbeiteten Datei am nächsten liegt. In einem Monorepo können Sie daher eine Datei im Stammverzeichnis des Repositories führen und in jedem Paket eine weitere ergänzen, sodass jedes Teilprojekt eigene Anweisungen erhält. Widersprechen sich zwei Dateien, gewinnt die nächstgelegene. Ausdrückliche Prompts des Nutzers im Chat haben Vorrang vor allem, auch vor der Datei. AGENTS.md ist damit eine Orientierung für den Agenten, keine harte Regel. Darüber liegen toolspezifische Ebenen: Cursor Rules, Claude-Code-Skills und MCP-Server für externe Tools.

Verschachtelte AGENTS.md-Dateien: Die nächstgelegene gewinnt, und Ihr Chat-Prompt hat vor allen Vorrang

Gibt Agenten einen verlässlichen Ort für Anweisungen zu Setup, Tests und Code-Stil
Hält agentenbezogene Details aus der README für Menschen heraus
Unterstützt verschachtelte AGENTS.md-Dateien; die der bearbeiteten Datei nächstgelegene gewinnt
Funktioniert mit vielen Agenten über eine Datei statt über Formate pro Tool

Was AGENTS.md kostet

AGENTS.md ist ein Dateiformat und kein kostenpflichtiges Produkt, es gibt also keine Tarife oder Preise zu vergleichen. Unser Profil nennt keine Lizenz und kein Erscheinungsdatum, und das öffentliche Quell-Repository konnten wir nicht verifizieren, daher geben wir beides nicht an. Voraussetzung ist nur ein Agent, der AGENTS.md liest. Alles Weitere ist der Zeitaufwand, die Datei zu schreiben und zu pflegen. Wenn Sie sich noch für einen Agenten entscheiden, beginnen Sie mit Codex vs Claude Code, Cursor vs GitHub Copilot oder der Liste Beste KI-Agenten. Der Ratgeber KI-Coding-Tools behandelt das weitere Feld, und Prompt Engineering erklärt, wie Sie die Datei formulieren.

Für wen AGENTS.md gedacht ist und für wen nicht

Sie passt zu Teams, die mehr als einen Coding-Agenten im selben Repository einsetzen, weil eine Datei das separate Format für jedes Tool ersetzt. Sie passt auch zu Monorepos, die Anweisungen pro Paket brauchen, und zu allen, die möchten, dass Agenten die aufgeführten Testbefehle ausführen, bevor sie fertig sind. Wenn dieses Detail aus der README für Menschen herausbleibt, bleiben beide Dokumente kürzer und leichter lesbar.

Sie ist kein Mittel, um Richtlinien durchzusetzen. Die Datei ist ein Hinweistext, und ausdrückliche Nutzer-Prompts im Chat haben Vorrang. Wenn eine Regel immer gelten muss, braucht sie einen Mechanismus außerhalb der Datei, denn das Format verpflichtet keinen Agenten, bestimmten Inhalten zu folgen. Betrachten Sie sie als gemeinsamen Satz von Anweisungen, den viele Agenten lesen, und prüfen Sie das Verhalten jedes Agenten selbst.

Welche Agenten AGENTS.md lesen

Die Website listet Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Copilot coding agent, Windsurf und weitere. Unser Katalog verlinkt verwandte Profile für OpenAI Codex, Cursor, Gemini CLI und Windsurf Editor. Manche Tools brauchen eine Einstellung: Gemini CLI liest die Datei, sobald context.fileName in .gemini/settings.json auf AGENTS.md gesetzt ist, und Aider braucht read: AGENTS.md in .aider.conf.yml.

Agenten, die die Website listet, und die zwei Einstellungen, die Gemini CLI und Aider brauchen

Erste Schritte mit AGENTS.md

Legen Sie im Stammverzeichnis des Repositories eine AGENTS.md an und ergänzen Sie Abschnitte wie Projektüberblick, Build- und Testbefehle, Code-Stil, Tests und PR-Anweisungen. Für ein Monorepo fügen Sie in jedem Paket eine weitere Datei hinzu. Falls Sie bereits eine AGENT.md haben, steht der Migrationsbefehl ebenfalls unten. Konfigurieren Sie dann jeden Agenten, der die Datei nicht standardmäßig erkennt.

Datei im Stammverzeichnis anlegen, Abschnitte ergänzen, dann eine pro Paket hinzufügen

Eine AGENTS.md im Stammverzeichnis des Repositories anlegen
Abschnitte ergänzen wie Projektüberblick, Build- und Testbefehle, Code-Stil, Tests und PR-Anweisungen
Bei Monorepos in jedem Paket eine weitere AGENTS.md hinzufügen
Zur Migration: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
Gemini CLI: context.fileName in .gemini/settings.json auf AGENTS.md setzen; Aider: read: AGENTS.md in .aider.conf.yml ergänzen

Als Nächstes lesen

Häufig gestellte Fragen

Was ist AGENTS.md?

AGENTS.md ist eine einfache Markdown-Datei in einem Repository, die Coding-Agenten Build-Schritte, Tests und Konventionen liefert. Die Website nennt sie eine README für Agenten.

Was gehört in die AGENTS.md?

Alles, was ein Agent braucht, um in Ihrem Repository zu arbeiten: Projektüberblick, Build- und Testbefehle, Code-Stil, Testregeln und PR-Anweisungen. Details für Menschen gehören in die README, und in einem Monorepo ergänzen Sie pro Paket eine verschachtelte AGENTS.md.

Was passiert, wenn sich AGENTS.md-Dateien widersprechen?

Die der bearbeiteten Datei nächstgelegene AGENTS.md gewinnt, und ausdrückliche Chat-Prompts des Nutzers haben vor allem Vorrang.

Welche Agenten unterstützen AGENTS.md?

Die Website listet Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Copilot coding agent, Windsurf und weitere.

Wie bringe ich Gemini CLI dazu, AGENTS.md zu lesen?

Setzen Sie context.fileName in .gemini/settings.json auf AGENTS.md.