AGENTS.md: eine Kontextdatei für jeden Coding-Agenten (Codex, Gemini, 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 Gemini 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

Im Moment ist die Landschaft nach Tool aufgeteilt:

• CLAUDE.md ist das, wonach Claude Code sucht.
• GEMINI.md ist die Konvention von Gemini CLI.
• AGENTS.md ist der toolübergreifende Standard, gelesen von Codex und anderen, gedacht als die neutrale Datei.

Der Inhalt ist in allen dreien fast identisch: Projektkontext, Befehle, Konventionen. Der einzige echte Unterschied ist der Dateiname, den jedes Tool standardmäßig liest. 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).

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 kanonische Datei, schlanke Verweise. Pack alles in AGENTS.md und mach aus CLAUDE.md und GEMINI.md einzeilige Dateien, die "siehe AGENTS.md" sagen, oder verlinke sie per Symlink. Eine einzige Quelle der Wahrheit, jedes Tool versorgt.
• Eine Datei, per Konvention geteilt. Wenn deine Tools auf einen eigenen Pfad zeigen können, richte sie alle auf AGENTS.md und lösch den Rest.

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 Gemini 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.