AGENTS.md: eine Kontextdatei für jeden Coding-Agenten (Codex, Antigravity, Claude)

Du hast einen halben Nachmittag damit verbracht, eine saubere CLAUDE.md zu schreiben. Dein Agent hört endlich auf, deinen Stack zu erraten, und führt jetzt den richtigen Test-Befehl aus. Und dann öffnet ein Kollege dasselbe Repo mit Codex, du probierst Antigravity CLI auf einem Nebenbranch, und nichts von diesem mühsam erarbeiteten Kontext kommt mit. Jedes Tool will seine eigene Datei, an seinem eigenen Ort.

AGENTS.md ist die Antwort auf dieses Chaos: eine einzige Datei in reinem Markdown, im Wurzelverzeichnis deines Repos, die jeder Coding-Agent liest, bevor er deinen Code anfasst.

Was AGENTS.md eigentlich ist

Keine Magie. Es ist eine Markdown-Datei namens AGENTS.md, meist im Wurzelverzeichnis des Repos, die ein Agent als ständige Anweisung lädt, bevor er loslegt. Sieh sie als die README, die du für deine KI-Teamkollegen schreibst statt für deine menschlichen: was das Projekt ist, wie man es baut und testet, welche Konventionen zu beachten sind und welche Fallen zu vermeiden.

Es ist eine offene Konvention, die schon von Codex und einer wachsenden Liste von Agent-Tools gelesen wird, mit dem ausdrücklichen Ziel, über sie alle hinweg portabel zu sein. Eine Datei, viele Agenten, statt einer maßgeschneiderten Datei pro Tool.

AGENTS.md vs CLAUDE.md vs GEMINI.md

Als dieser Leitfaden zuerst geschrieben wurde, suchte jedes Tool nach seiner eigenen Datei. Die meisten haben sich inzwischen auf AGENTS.md eingependelt:

• Codex liest AGENTS.md, ebenso GitHub Copilot CLI, Cursor, Amp und die meisten neueren Agent-CLIs.
• Claude Code liest CLAUDE.md, und seit Version 2.1.277 liest es AGENTS.md auch von selbst, wenn dein Arbeitsverzeichnis und die Verzeichnisse darüber keine CLAUDE.md oder CLAUDE.local.md haben. Gibt es eine CLAUDE.md, liest Claude nur diese, außer du änderst die Einstellung Project instructions in /config.
• Antigravity CLI liest AGENTS.md oder GEMINI.md, im Wurzelverzeichnis des Repos oder in jedem Unterverzeichnis, dazu einen Ordner .agents/rules/ und globale Regeln unter ~/.gemini/.

Der Inhalt ist in allen dreien fast identisch: Projektkontext, Befehle, Konventionen. Was sich noch unterscheidet, ist, welche Datei ein Tool wählt, wenn mehrere vorhanden sind. Genau deshalb ist es ein von vornherein verlorener Kampf, dieselben Regeln von Hand in drei Dateien zu duplizieren (wie du sie synchron hältst, kommt weiter unten). Wir haben dieses Verhalten am 10. Oktober 2026 anhand der Memory-Dokumentation von Claude Code und der Regel-Dokumentation von Antigravity überprüft.

Wenn du hauptsächlich in Claude Code arbeitest, geht unser CLAUDE.md-Leitfaden tief auf die Claude-spezifische Struktur ein. AGENTS.md ist das providerneutrale Geschwister dieser Datei.

Was reingehört

Halte sie kurz und signalstark. Ein Agent liest sie bei jeder Aufgabe, also konkurriert jede Zeile um Aufmerksamkeit. Das Wesentliche:

• Der Stack, in einem Satz. "Next.js 16, TypeScript, Prisma, MariaDB." Keine Historie, kein Marketing.
• Die Befehle, die zählen. Wie man installiert, startet, baut, testet und linted. Exakte Befehle: npm test, nicht "führ die Tests aus."
• Die Konventionen. Benennung, Dateistruktur, Fehlerbehandlung, die Muster, die du im Review wirklich durchsetzt.
• Eine Verzeichniskarte. Zwei Zeilen dazu, wo was liegt, damit der Agent aufhört, blind zu greppen.
• Lesen-bevor-Anfassen-Regeln. "Lies docs/payments.md, bevor du irgendetwas unter billing/ änderst." Diese eine Angewohnheit verhindert eine Menge Schaden.
• Harte Verbote. "Niemals einen Branch anlegen, ohne dass danach gefragt wurde." "Keine absoluten, maschinengebundenen Pfade in committeten Dateien."

Die Fehler, die Agenten die Datei ignorieren lassen

Eine Kontextdatei scheitert leise. Der Agent wirft keinen Fehler, er driftet einfach ab. Die üblichen Ursachen:

1. Zu lang. Eine Datei mit 600 Zeilen begräbt die fünf Regeln, die zählen. Streiche alles, was der Agent aus dem Code selbst ableiten kann.
2. Widersprüche. "Immer Tests schreiben" in einem Abschnitt, "Tests bei Prototypen überspringen" in einem anderen. Der Agent wählt zufällig eins.
3. Maschinengebundene Pfade. /Users/you/project/... in einer committeten Datei bricht für jeden Kollegen und für jeden Agenten auf jeder anderen Maschine. Halte Pfade relativ.
4. Veraltete Befehle. Der Test-Befehl hat sich vor einem halben Jahr geändert, die Datei nicht. Jetzt führt der Agent das Falsche mit voller Überzeugung aus.
5. Keine Prioritäten. Alles ist "wichtig," also ist nichts wichtig. Stell die nicht verhandelbaren Punkte nach vorn und kennzeichne sie.
6. Doku-Abladen. Das sind Anweisungen, kein Wiki. Verlinke auf deine Doku, kopier sie nicht hinein.

Einen einzigen Kontext über Provider hinweg behalten

Hier kommt der praktische Teil, den die meisten Leitfäden überspringen. Wenn du oder dein Team mehr als eine Agent-CLI nutzt, willst du nicht drei auseinanderdriftende Kopien derselben Regeln.

Zwei saubere Ansätze:

• Eine einzige AGENTS.md, sonst nichts. Wenn niemand Regeln braucht, die nur für Claude gelten, behalte eine einzige AGENTS.md: Codex, Antigravity CLI und Claude Code 2.1.277 oder neuer lesen sie alle. Der Haken ist leise: Eine CLAUDE.md oder eine persönliche CLAUDE.local.md, die später dazukommt, sorgt dafür, dass Claude Code AGENTS.md nicht mehr liest.
• Eine kanonische Datei, ein Import. Pack alles in AGENTS.md, beginne CLAUDE.md mit der Zeile @AGENTS.md und schreib die Regeln, die nur für Claude gelten, darunter. Claude liest zuerst die importierte Datei. Unser eigenes Repo funktioniert so: Seine CLAUDE.md besteht aus genau dieser einen Zeile. Ein Symlink (ln -s AGENTS.md CLAUDE.md) geht auch, aber schlecht unter Windows: Dort braucht man zum Anlegen Administratorrechte oder den Entwicklermodus, und ein Klon ohne core.symlinks bekommt statt deiner Anweisungen eine einzeilige Textdatei.

So oder so lautet die Regel gleich: schreib den Kontext einmal, nicht einmal pro Provider. Das ist auch der einzige Weg, auf dem er korrekt bleibt, denn eine einzige Datei ist die einzige Datei, die Leute tatsächlich pflegen.

Wenn du mehrere Agenten gleichzeitig laufen lässt

Eine AGENTS.md auf Repo-Ebene beantwortet "was ist dieses Projekt." Sie beantwortet nicht "wer ist dieser Agent." Wenn du einen Backend-Agenten, einen Frontend-Agenten und einen QA-Agenten parallel auf demselben Code laufen lässt, braucht jeder den geteilten Projektkontext plus seine eigene Rolle.

Genau diese Schicht legt AgentsRoom über deine AGENTS.md. Jeder Agent bekommt eine eigene Rolle mit seinem eigenen System-Prompt (DevOps, Frontend, Security und mehr), damit die geteilte Datei schlank bleibt, während jeder Agent trotzdem weiß, was sein Job ist. Es ist von Grund auf providerunabhängig, also lässt dasselbe Setup Claude, Codex oder Antigravity nebeneinander laufen, und deine wiederverwendbaren Anweisungen leben in einer Prompt-Bibliothek, statt in jeder Session neu getippt zu werden.

Wenn du an diesem Punkt bist, ist die Methode, um mehrere Agenten parallel laufen zu lassen, ohne den Faden zu verlieren, die natürliche nächste Lektüre.

Das Fazit

Schreib eine einzige AGENTS.md. Halt sie kurz, halt sie aktuell, halt sie portabel. Zeig jedes Tool darauf, statt eine Datei pro Agent zu pflegen. Dein Kontext ist nicht mehr an die CLI gebunden, mit der du zufällig angefangen hast, und deine Agenten, welche auch immer du laufen lässt, starten alle von derselben Seite.

Willst du jeden Agenten auf einem Bildschirm, jeden mit seiner eigenen Rolle und deinem geteilten Kontext? Lade AgentsRoom herunter, verbinde deinen Provider und setz deine Flotte an die Arbeit.

Häufig gestellte Fragen

Was ist AGENTS.md?

Eine Markdown-Datei, meist im Wurzelverzeichnis eines Repos, die Coding-Agenten als ständige Anweisungen laden, bevor sie arbeiten: was das Projekt ist, wie man es baut und testet, welche Konventionen zu beachten und welche Fallen zu vermeiden sind. Sie ist eine offene, toolübergreifende Konvention statt der Datei eines einzelnen Tools und wird von Codex, Antigravity CLI, GitHub Copilot CLI, Cursor, Amp und, seit Version 2.1.277, Claude Code gelesen.

Liest Claude Code AGENTS.md?

Ja, seit Claude Code 2.1.277, aber nur, wenn es in deinem Arbeitsverzeichnis oder darüber keine CLAUDE.md, .claude/CLAUDE.md oder CLAUDE.local.md gibt. Dann lädt es jede AGENTS.md vom Arbeitsverzeichnis aufwärts und die AGENTS.md eines Unterverzeichnisses, sobald es dort eine Datei öffnet. Gibt es eine CLAUDE.md, liest Claude nur diese, außer du stellst Project instructions in /config auf claude-md-and-agents-md. Bei älteren Versionen setzt du die Zeile @AGENTS.md an den Anfang einer CLAUDE.md.

Nutzt Antigravity AGENTS.md oder GEMINI.md?

Beides. Antigravity liest eine AGENTS.md, eine GEMINI.md oder einen Ordner .agents/rules/ im Wurzelverzeichnis des Repos oder in jedem Unterverzeichnis, dazu globale Regeln aus ~/.gemini/. Die Regeln addieren sich, statt einander zu ersetzen, und wenn sich zwei davon widersprechen, gewinnt die Regel des spezifischeren Verzeichnisses.

Soll ich AGENTS.md oder CLAUDE.md behalten?

Behalte AGENTS.md als die eine Datei, die du pflegst. Brauchst du zusätzlich Regeln nur für Claude, leg eine CLAUDE.md an, deren erste Zeile @AGENTS.md ist, und schreib diese Regeln darunter: Claude liest zuerst die importierte Datei. Brauchst du keine, reicht AGENTS.md allein für Claude Code 2.1.277 oder neuer. Vermeide zwei vollständige Kopien derselben Regeln: Die, die niemand bearbeitet, veraltet.

Wo gehört AGENTS.md hin?

Ins Wurzelverzeichnis des Repos, für die Regeln, die überall gelten. Claude Code und Antigravity lesen auch AGENTS.md-Dateien in Unterverzeichnissen, also kann ein Paket oder ein Service mit eigenen Befehlen eine eigene Datei mitbringen, die gelesen wird, wenn der Agent in diesem Ordner arbeitet.