Kennst du das? Du startest mit einem KI-Coding-Tool, erklärst ihm geduldig dein Projekt – welche Technologien du nutzt, wie deine Ordner heißen, welche Befehle es zum Starten braucht. Dann wechselst du das Tool oder dein Kollege nutzt ein anderes – und alles geht von vorne los. Genau hier kommt AGENTS.md ins Spiel. Diese unscheinbare Textdatei löst ein nerviges Problem: Bisher wollte jedes KI-Tool den Projekt-Kontext auf seine eigene Art bekommen. AGENTS.md macht Schluss mit diesem Durcheinander und schafft einen gemeinsamen Standard, den verschiedene KI-Coding-Agenten verstehen.
Und das ist längst keine Nischen-Idee mehr. AGENTS.md steht heute unter dem Dach der Linux Foundation und wird laut deren offizieller Ankündigung von über 60.000 Open-Source-Projekten genutzt. Das ist die Liga von Kubernetes und PyTorch. Für so eine simple Textdatei? Ja. Genau deshalb lohnt sich der Blick.
In diesem Artikel zeige ich dir, was AGENTS.md genau ist, warum ein gemeinsamer Standard so praktisch ist, was in die Datei gehört und wie sich AGENTS.md von der bekannten CLAUDE.md unterscheidet. Auch wenn du dich nicht als Technik-Profi siehst – ich erkläre alles Schritt für Schritt.
Was ist AGENTS.md?
AGENTS.md ist im Kern eine ganz einfache Textdatei, die du in deinem Projekt ablegst. In dieser Datei erklärst du KI-Coding-Agenten – also den KI-Helfern, die dir beim Programmieren zur Hand gehen – wie dein Projekt funktioniert. Stell dir die Datei wie eine Begrüßungsmappe für neue Mitarbeiter vor: Sie fasst zusammen, worum es im Projekt geht, welche Werkzeuge im Einsatz sind und welche Spielregeln gelten.
Die offizielle Beschreibung auf agents.md bringt es schön auf den Punkt: ein „README für Agenten“. Deine README.md schreibst du für Menschen. Die AGENTS.md schreibst du für Maschinen. Da drin darf all der Kram stehen, der eine README nur zumüllen würde – Build-Schritte, Testbefehle, Namenskonventionen, No-Gos.
Der entscheidende Punkt: AGENTS.md ist tool-übergreifend. Sie ist nicht an ein einziges KI-Tool gebunden, sondern wird von verschiedenen KI-Coding-Agenten gelesen. Du schreibst den Kontext einmal auf – und egal, welches kompatible Tool du oder dein Team später nutzt, der KI-Agent weiß sofort Bescheid. Die Datei liegt dabei im Hauptordner deines Projekts (in der Technik-Welt nennt man so einen Projektordner samt Versionsverwaltung ein „Repository“ oder kurz „Repo“).
Geschrieben wird AGENTS.md in einem schlichten Textformat namens Markdown. Das klingt komplizierter, als es ist: Markdown ist einfach normaler Text mit ein paar Sonderzeichen für Überschriften und Listen. Du brauchst dafür kein Spezialwissen – ein simpler Texteditor reicht völlig. Und es gibt kein Pflichtschema. Keine YAML-Kopfzeile, keine erzwungenen Felder, keine Validierung. Der Agent liest den Text einfach als Ganzes. Herrlich unkompliziert!
Wo AGENTS.md herkommt
Die Geschichte ist erstaunlich kurz. Im August 2025 hat OpenAI das Format zusammen mit dem Codex CLI veröffentlicht – bewusst herstellerneutral, damit nicht schon wieder eine proprietäre Insellösung entsteht. Sourcegraph, Google, Cursor und Factory waren von Anfang an mit dabei.
Der eigentliche Ritterschlag kam im Dezember 2025: OpenAI, Anthropic und Block gründeten die Agentic AI Foundation unter dem Dach der Linux Foundation. OpenAI spendete AGENTS.md, Anthropic das Model Context Protocol (MCP), Block sein Agenten-Framework goose. Google, Microsoft, AWS, Bloomberg und Cloudflare sind als Unterstützer an Bord – nachzulesen bei OpenAI selbst. Übersetzt heißt das: Keine einzelne Firma kann den Standard mehr kapern.
Das Wachstum spricht für sich. Von ein paar tausend Repos zum Start auf über 60.000 in gut einem Jahr. So schnell setzt sich sonst kaum ein Format durch.
Warum ein gemeinsamer Standard?
Bisher hat fast jedes KI-Coding-Tool seine eigene Methode mitgebracht, um Projekt-Kontext zu bekommen. Cursor wollte eine .cursorrules, Claude Code eine CLAUDE.md, GitHub Copilot eine .github/copilot-instructions.md, Gemini eine GEMINI.md, Cline eine .clinerules. Dein Repo sah irgendwann aus wie ein Museum für verwirrte Bots.
Für dich als Solopreneur oder Entwickler bedeutete das: mehrfache Arbeit, doppelte Pflege, Chaos. Und das kostet real Zeit. In einer Umfrage unter Teams, die mit mehreren KI-Tools arbeiten, berichteten 61 Prozent von genau diesem Doppelaufwand – im Schnitt rund fünf Stunden pro Monat, nur um Dateien synchron zu halten. Fünf Stunden. Für Copy-Paste. Autsch.
Ein gemeinsamer Standard wie AGENTS.md dreht den Spieß um. Das Prinzip lautet: mehrere Tools, eine Datei. Du pflegst eine einzige Quelle der Wahrheit, und alle kompatiblen KI-Agenten greifen darauf zu. Das hat handfeste Vorteile:
- Weniger Aufwand: Du schreibst den Kontext nur einmal, statt ihn für jedes Tool neu aufzubereiten.
- Konsistenz im Team: Alle, die am Projekt arbeiten, geben den KI-Agenten dieselben Informationen mit – unabhängig vom verwendeten Tool.
- Portabilität: Du kannst den Agenten nach Leistung wählen statt nach Setup-Aufwand. Neues Tool? Läuft sofort.
- Open-Source-tauglich: Fremde Contributor sind sofort produktiv, egal welches Tool sie mitbringen.
- Bessere Ergebnisse: Ein KI-Agent, der dein Projekt versteht, macht weniger Fehler und liefert passendere Vorschläge.
Und der letzte Punkt ist keine Wohlfühl-Behauptung, sondern messbar. Vercel hat testen lassen, wie gut Agenten eine Aufgabe lösen – ohne Kontext, mit nachträglich abgerufenem Kontext und mit einer immer verfügbaren AGENTS.md. Ergebnis: 53 Prozent Erfolgsquote ohne Kontext, 79 Prozent mit Abruf auf Zuruf, 100 Prozent mit AGENTS.md. Kontext, der einfach immer da ist, schlägt Kontext, den sich der Agent erst zusammensuchen muss.
Eine Analyse auf arXiv (Januar) hat außerdem gemessen, dass eine gute AGENTS.md die Laufzeit einer Agenten-Session um rund 29 Prozent senkt und etwa 17 Prozent weniger Output-Tokens verbraucht. Heißt im Klartext: schneller fertig und günstiger. Weil der Agent nicht mehr planlos durch deine Ordner tapert.
Welche Tools lesen AGENTS.md wirklich?
Inzwischen ziemlich viele. Nativ, ohne Konfiguration, ohne Bastelei:
- OpenAI Codex CLI – der Initiator des Formats
- Cursor, Windsurf und Cline – lesen die AGENTS.md im Repo-Root direkt
- GitHub Copilot Coding Agent und VS Code
- Gemini CLI und Jules (Google)
- Devin, Factory, Amp, Zed, Warp, opencode, goose und JetBrains Junie
- Aider – mit einer Zeile in der
.aider.conf.yml
Die große Ausnahme? Claude Code. Dazu unten mehr – und keine Sorge, dafür gibt’s eine elegante Lösung mit genau einer Zeile.
Was gehört in eine AGENTS.md?
Es gibt keine starre Vorschrift, aber bewährt haben sich ein paar Bausteine. Je klarer und konkreter du wirst, desto besser kann der KI-Agent dir helfen. Hier ein Beispiel, wie eine AGENTS.md aussehen kann:
# AGENTS.md
## Projekt-Überblick
Eine kleine Web-App, mit der Nutzer ihre täglichen Aufgaben
verwalten können. Ziel: einfach, schnell, ohne Schnickschnack.
## Tech-Stack
- Frontend: React mit TypeScript
- Backend: Node.js 20.11 (siehe .nvmrc), Express
- Datenbank: PostgreSQL
- Paketmanager: pnpm (kein npm, kein yarn!)
## Wichtige Befehle
- Abhängigkeiten: pnpm install
- Projekt starten: pnpm dev
- Tests ausführen: pnpm test
- Linter: pnpm lint
- Typen prüfen: pnpm typecheck
- Für Produktion bauen: pnpm build
## Konventionen
- Komponenten-Dateien werden GROSS geschrieben (z. B. TaskList.tsx)
- Funktionen bekommen sprechende Namen, keine Abkürzungen
- Vor jedem Commit die Tests laufen lassen
- Kommentare auf Deutsch, Code-Namen auf Englisch
## Grenzen
- Immer: Session per requireSession() prüfen
- Erst fragen: Änderungen an Billing, Stripe, Migrationen
- Niemals: Raw SQL, Secrets im Code, "any" in TypeScript
Die wichtigsten Bereiche kurz erklärt:
- Projekt-Überblick: Worum geht es überhaupt? Zwei, drei Sätze reichen, damit der KI-Agent das große Ganze versteht.
- Tech-Stack: Welche Technologien nutzt du? Am besten mit Versionsangaben. So vermeidest du, dass die KI Vorschläge für Werkzeuge macht, die du gar nicht einsetzt.
- Befehle: Die typischen Kommandos zum Starten, Testen und Bauen. Der KI-Agent weiß dann, wie er dein Projekt zum Laufen bringt.
- Konventionen: Deine persönlichen Spielregeln – Namensgebung, Stil, Abläufe. Genau hier sorgst du dafür, dass die KI sich an deine Gewohnheiten hält.
- Grenzen: Was darf der Agent auf keinen Fall anfassen? Der unterschätzteste Abschnitt überhaupt.
Der zweitwichtigste Block sind die Grenzen. Und da hat sich ein simples Drei-Ebenen-Modell durchgesetzt: immer erlaubt, vorher fragen, niemals. Wichtig dabei: Ein Verbot ohne Alternative ist eine Sackgasse. Schreib also nicht „kein Raw SQL“, sondern „kein Raw SQL – nutze stattdessen $wpdb->prepare()„. Der Agent braucht keine Verbotstafel, er braucht einen Weg.
Und wenn dein Projekt größer wird?
Dann wird’s richtig charmant. AGENTS.md funktioniert hierarchisch: Der Agent liest immer die Datei, die am nächsten an der bearbeiteten Datei liegt. Die Regel heißt „closest AGENTS.md wins“ – die nächstgelegene gewinnt. Und deine direkte Anweisung im Chat schlägt sowieso alles.
In einem Monorepo (also einem Repo mit mehreren Teilprojekten) legst du deshalb ins Root die gemeinsamen Grundregeln – Branch-Naming, Secrets-Handling, Testkultur – und in jedes Paket nur die Abweichungen. Nicht wiederholen! Wie weit man das treiben kann, zeigt OpenAI selbst: deren Haupt-Repo hat laut agents.md stolze 88 AGENTS.md-Dateien. Eine pro Subprojekt.
Kleiner Bonus für Bastler: Mit einer AGENTS.override.md auf derselben Ebene überschreibst du einzelne Regeln, ohne die eigentliche Datei anzufassen. Ideal für persönliche Anpassungen, die niemanden im Team interessieren.
AGENTS.md vs. CLAUDE.md – wo ist der Unterschied?
Wenn du schon mit Claude-Tools gearbeitet hast, kennst du vielleicht die CLAUDE.md. Beide Dateien erfüllen einen ähnlichen Zweck: Sie geben KI-Agenten den nötigen Projekt-Kontext. Der Unterschied liegt in der Reichweite.
Die CLAUDE.md ist claude-spezifisch. Sie wird von Claude Code gelesen – und sonst von niemandem. Die AGENTS.md dagegen ist tool-übergreifend, offen und wird von der Agentic AI Foundation gepflegt. Sie ist nicht an einen einzigen Anbieter gebunden.
Klingt ärgerlich? Ist es nicht. Denn die Lösung ist eine einzige Zeile.
Workaround 1: Der @-Import (mein Favorit)
Claude Code kann in seiner CLAUDE.md andere Dateien importieren – mit einem simplen @ plus Pfad. Du legst also eine winzige CLAUDE.md an, die nichts anderes tut, als deine AGENTS.md hereinzuziehen:
# CLAUDE.md
@AGENTS.md
## Nur für Claude Code
- Für Änderungen unter `src/billing/` bitte den Plan-Modus nutzen.
Beim Sessionstart klappt Claude Code den Import auf und lädt den kompletten Inhalt der AGENTS.md, als stünde er direkt drin. Danach hängt es an, was du darunter geschrieben hast. Ergebnis: Eine Quelle der Wahrheit, null Drift. Damit habe ich die besten Erfahrungen gemacht – es läuft auf jedem Betriebssystem, überlebt jeden git clone und du kannst trotzdem Claude-spezifische Extras ergänzen.
Zwei kleine Details: Der Import funktioniert bis zu vier Ebenen tief (importierte Dateien dürfen also selbst importieren), und beim ersten Mal fragt Claude Code einmalig um Erlaubnis. Einmal bestätigen, fertig. Willst du einen Pfad nur erwähnen, ohne ihn zu importieren, setz ihn in Backticks.
Workaround 2: Der Symlink
Auf macOS und Linux geht’s noch radikaler. Ein Symlink macht aus einer Datei zwei Namen:
ln -s AGENTS.md CLAUDE.mdClaude Code folgt dem Link und liest die AGENTS.md eins zu eins. Keine zweite Datei, kein Abgleich, nichts. Der Haken: Unter Windows brauchst du dafür Admin-Rechte oder den Entwicklermodus. In gemischten Teams also lieber Workaround 1 – der funktioniert überall gleich.
Workaround 3: Du hast schon eine AGENTS.md
Dann tipp in Claude Code einfach /init. Der Befehl schaut sich dein Projekt an, liest vorhandene AGENTS.md- oder .cursorrules-Dateien und baut daraus eine CLAUDE.md. Das ist der schnellste Migrationspfad. Danach lohnt es sich trotzdem, auf den Import-Pattern umzustellen – sonst hast du wieder zwei Dateien, die auseinanderlaufen.
Die gute Nachricht bleibt also: Du musst dich nicht entscheiden. AGENTS.md als gemeinsamer Grundstock, CLAUDE.md als hauchdünne Schicht obendrauf. So machen es inzwischen auch Frameworks – create-next-app legt seit Next.js 16.2 beide Dateien automatisch an, inklusive @AGENTS.md-Import. Wenn das Referenzmuster gut genug für Next.js ist, ist es auch gut genug für dein Projekt.
So legst du eine AGENTS.md an
Keine Sorge, das ist in wenigen Minuten erledigt – auch ohne tiefes Technik-Wissen. Und du musst nicht alles auf einmal machen. Ich gehe da in Phasen vor:
- Phase 1 (10 Minuten): Erstelle im Hauptordner deines Projekts eine Datei namens exakt AGENTS.md (Groß- und Kleinschreibung beachten!) und schreib nur die Befehle rein: installieren, starten, testen, linten, Typen prüfen. Mehr nicht. Committen, fertig. Das ist schon 80 Prozent des Nutzens.
- Phase 2 (am nächsten Tag): Ergänze den Tech-Stack mit Versionen und die eine Architektur-Regel, die dir am wichtigsten ist.
- Phase 3 (laufend): Sammle Grenzen aus echten Fehlern. Immer wenn dir im Code-Review auffällt „das hätte der Agent nicht machen dürfen“ – rein damit. Und immer mit Alternative.
- Phase 4 (Feinschliff): Beobachte eine Agenten-Session. Jede Abweichung von dem, was du erwartet hast, ist eine neue Zeile. Nach drei bis fünf Sessions ist die Datei stabil.
Nutzt du Claude Code? Dann verdrahte es einmalig mit einem Einzeiler im Terminal:
echo "@AGENTS.md" > CLAUDE.mdDas war’s. Ab jetzt lesen alle deine Tools dieselbe Datei.
Fang ruhig klein an. Eine kurze, ehrliche AGENTS.md ist deutlich wertvoller als eine perfekte, die nie fertig wird. Und ein Roman, den keiner pflegt, ist schlimmer als drei gute Zeilen.
Best Practices für eine gute AGENTS.md
Ein paar Regeln haben sich in der Praxis herauskristallisiert. Die meisten davon habe ich mir selbst über verkorkste Sessions beigebracht – nimm sie gerne als Abkürzung:
- Befehle zuerst: Stell die zentralen Infos nach oben. Was die KI auf jeden Fall wissen muss, gehört nicht ans Ende.
- Code statt Prosa: Statt „benenne Dateien sauber“ lieber ein echtes Beispiel: „Komponenten heißen wie TaskList.tsx“. Ein Snippet sagt mehr als drei Absätze.
- Verbote immer mit Alternative: „Kein Raw SQL“ ist eine Sackgasse. „Kein Raw SQL – nutze
$wpdb->prepare()“ ist eine Anleitung. - Kurz halten: Unter 500 Zeilen bleiben. Codex kappt bei 32 KiB sowieso. Lange Erklärungen wandern nach
docs/und bekommen nur einen Link. - Als lebendes Dokument behandeln: Änderst du einen Befehl, änderst du die AGENTS.md – im selben Pull Request. Eine veraltete Datei ist schlimmer als gar keine, weil der Agent ihr blind vertraut.
- Mitwachsen lassen: Merkst du, dass die KI immer wieder denselben Fehler macht? Ergänze eine passende Regel.
Und jetzt zu den Fehlern, die ich am häufigsten sehe:
- Keine Persona: „Du bist ein erfahrener Senior-Entwickler …“ – bitte nicht. Das ist Prompt-Deko und frisst nur Kontext.
- README nicht kopieren: Die AGENTS.md ergänzt die README, sie dupliziert sie nicht.
- Kein Marketing: Der Agent muss nicht wissen, dass ihr „die führende Plattform für …“ seid.
- Keine Secrets: Die Datei liegt in der Versionsverwaltung. Für alle sichtbar. Immer.
- Nicht zu generisch: „Schreib sauberen Code“ hilft niemandem. Kurz und spezifisch schlägt lang und allgemein.
Bitte nicht von der KI schreiben lassen!
Das klingt erstmal verlockend: einfach den Agenten bitten, sich seine eigene AGENTS.md zu generieren. Bequem – aber kontraproduktiv. Eine Untersuchung der ETH Zürich hat genau das getestet: Handgeschriebene Instruktionsdateien verbesserten die Erfolgsquote um rund 4 Prozentpunkte. LLM-generierte senkten sie um etwa 3 Prozentpunkte – und trieben die Kosten um 20 Prozent nach oben. In fünf von acht getesteten Szenarien machte die generierte Datei die Sache schlechter statt besser.
Warum? Weil die KI zwar beschreiben kann, was da ist – aber nicht weiß, was dir wichtig ist. Sie kennt eure schmerzhafte Migration von letztem Jahr nicht. Sie weiß nicht, warum ihr diese eine Bibliothek niemals mehr anfasst. Genau dieses Wissen ist der Wert der Datei.
Nutz die KI also gerne als Startgerüst – aber schreib die entscheidenden Zeilen selbst.
Fazit
AGENTS.md ist ein kleiner Schritt mit großer Wirkung. Statt jedem KI-Tool den Projekt-Kontext einzeln beizubringen, schreibst du ihn einmal auf – tool-übergreifend, verständlich, an einem Ort. In weniger als einem Jahr ist aus einem internen OpenAI-Workaround ein Standard unter dem Dach der Linux Foundation geworden, den über 60.000 Projekte nutzen und praktisch jeder große KI-Agent nativ liest. Die einzige Ausnahme, Claude Code, löst du mit einer einzigen Zeile.
Merk dir vier Prinzipien: von Hand schreiben, kurz halten, Befehle und Grenzen zuerst, zusammen mit dem Code aktualisieren. Mehr braucht es nicht.
Egal ob du Solopreneur bist oder im Team arbeitest: Eine gepflegte AGENTS.md ist eine der einfachsten Investitionen in eine reibungslose Zusammenarbeit mit deinen KI-Helfern. Am besten legst du gleich heute eine an – fang klein an und lass sie mit deinem Projekt wachsen. Zehn Minuten. Nur die Befehle. Los geht’s!
Häufige Fragen zu AGENTS.md
Brauche ich AGENTS.md auch für kleine Projekte?
Ja, gerade dann lohnt es sich. Auch ein kleines Projekt profitiert davon, wenn der KI-Agent von Anfang an weiß, wie der Hase läuft. Du musst nicht alle Bereiche ausfüllen – schon ein kurzer Überblick und die wichtigsten Befehle helfen enorm. Und wenn das Projekt wächst, hast du bereits eine gute Grundlage. Zehn Minuten investieren, dauerhaft Nerven sparen.
Was, wenn mein KI-Tool AGENTS.md noch nicht unterstützt?
Dann schadet die Datei trotzdem nicht – im schlimmsten Fall wird sie schlicht ignoriert. Da AGENTS.md ein offener Standard unter dem Dach der Linux Foundation ist, ziehen immer mehr KI-Coding-Tools nach. Es lohnt sich also, die Datei früh anzulegen, damit du startklar bist, sobald dein Tool sie liest. Im Zweifel kombinierst du sie mit der tool-spezifischen Variante wie CLAUDE.md.
Kann ich AGENTS.md und CLAUDE.md gleichzeitig nutzen?
Absolut – das ist sogar das empfohlene Setup. Führe die AGENTS.md als gemeinsamen Standard für alle Tools und lass die CLAUDE.md sie per @AGENTS.md importieren. Darunter kommen nur noch die Claude-spezifischen Feinheiten. So können sich die Infos gar nicht erst widersprechen, weil es nur eine echte Quelle gibt.
Was passiert bei widersprüchlichen Anweisungen?
Es gibt eine klare Rangfolge. Ganz oben steht, was du direkt im Chat sagst – das übersteuert alles. Danach kommt die nächstgelegene AGENTS.md, dann die übergeordneten bis hinauf zum Projekt-Root, und ganz zuletzt deine globale Konfigurationsdatei im Benutzerordner. Kurz: Je näher an der Datei, desto stärker die Regel.
Hält sich die KI garantiert an meine AGENTS.md?
Ehrliche Antwort: nein. In Tests befolgte von fünf untersuchten Modellen nur eines die Regeln wirklich konsequent. AGENTS.md ist ein starker Vorschlag, keine erzwungene Regel – ein Leitplanken-System, kein Betonzaun. Aber genau deshalb gilt: kurz und spezifisch schlägt lang und generisch. Je knapper und konkreter deine Regeln, desto höher die Chance, dass sie ankommen.
Bringt AGENTS.md wirklich messbar was?
Ja. Neben den 100 Prozent Erfolgsquote im Vercel-Test und den rund 29 Prozent kürzerer Laufzeit gibt es noch eine schöne Zahl: In einer Auswertung wurden Pull Requests des Codex CLI zu 85,8 Prozent akzeptiert – bei menschlichen PRs waren es 82,6 Prozent. Als Hauptfaktor dafür gilt: verfügbarer Projekt-Kontext. Also genau das, was in deiner AGENTS.md steht.
