Ich arbeite inzwischen lieber mit Coding Agents als mit klassischen Chatfenstern. Der Unterschied ist nicht klein. Ein guter Agent kann ein Repository durchsuchen, Zusammenhänge erkennen, Änderungen vornehmen, Tests starten und sich entlang einer Architektur bewegen. Aber genau an dieser Stelle beginnt in älteren Projekten das eigentliche Problem: Der Agent sieht zwar den Code, aber nicht automatisch die Geschichte, die Fallstricke, die impliziten Regeln und die Stellen, an denen man besser nichts „mal eben“ umbaut. Genau dafür benötigt ein Projekt eine AGENTS.md. Das Format versteht sich ausdrücklich als eine Art „README für Agents“: ein klarer, vorhersehbarer Ort für den Kontext und die Anweisungen, die ein Coding Agent für verlässliche Arbeit braucht.

README für Agents

Der eigentliche Nutzen liegt nicht darin, einem Modell ein paar Stilregeln hinzulegen. Der Nutzen liegt darin, Projektwissen aus flüchtigen Chats herauszulösen und in die Codebasis zu verlagern. Codex liest AGENTS.md-Dateien vor der Arbeit ein und kombiniert dabei globale Vorgaben mit projektspezifischen und, wenn vorhanden, noch spezielleren Regeln in Unterverzeichnissen. Auch GitHub Copilot Agents unterstützen AGENTS.md; dort gilt ebenfalls, dass die nächstgelegene Datei im Verzeichnisbaum Vorrang hat.

Wer bisher nur mit Prompts gearbeitet hat, unterschätzt oft, wie viel Reibung dadurch entsteht. Alte Projekte haben fast immer blinde Flecken. Es gibt Einstiegspunkte, die nicht offensichtlich sind. Es gibt Services, die historisch gewachsen sind. Es gibt Build-Schritte, die in keiner README stehen. Es gibt Tests, die lokal nur unter bestimmten Voraussetzungen laufen. Es gibt Qualitätsregeln, die das Team selbstverständlich findet, die aber nirgends explizit notiert sind. Genau an solchen Stellen produzieren Agents Unsicherheit: nicht, weil sie zu wenig „Intelligenz“ hätten, sondern weil ihnen die Betriebsanleitung fehlt.

Was gehört hinein? Nicht alles. Gerade das ist wichtig. Eine AGENTS.md ist keine zweite Projektchronik, keine Ablage für diffuse Wunschlisten und kein Ersatz für saubere Architektur-Dokumentation. Sie sollte genau die Informationen enthalten, die ein Agent für sichere, konsistente Änderungen benötigt. OpenAI nennt dafür unter anderem Repo-Struktur, Start-, Build-, Test- und Lint-Kommandos, technische Konventionen, „Do-not“-Regeln sowie die Frage, woran eine Aufgabe als erledigt gilt. Auch das offene AGENTS.md-Format selbst nennt typische Bausteine wie Projektüberblick, Build- und Testbefehle, Code-Style, Testhinweise und Sicherheitsaspekte.

Das muss rein

In der Praxis sind für mich vor allem sieben Blöcke sinnvoll. Erstens der Zweck des Projekts und seine Grenzen: Was ist dieses Repository, und was ist es ausdrücklich nicht? Zweitens eine Architektur in Kurzform: Welche Verzeichnisse sind zentral, wie läuft der Datenfluss, welche Schichten gibt es? Drittens die unverzichtbaren Kommandos: Install, lokaler Start, Build, Tests, Linter, Typechecks, Migrations. Viertens verbindliche Konventionen: Typisierung, Naming, Logging, Dependency-Politik, Umgang mit Fehlern, Sicherheitsgrenzen. Fünftens Arbeitsregeln für den Agenten: Was muss vor Änderungen gelesen werden, was muss nach Änderungen geprüft werden, welche Refactorings sind ohne ausdrücklichen Auftrag tabu? Sechstens das Wissen, das nicht sauber aus dem Code hervorgeht: fragile Legacy-Bereiche, historische Workarounds, gefährliche Integrationen, externe Limits. Siebtens eine präzise Definition von „fertig“: Welche Checks müssen grün sein, welche Seiteneffekte dürfen nicht auftreten, welche Dokumentation muss bei Verhaltensänderungen mitgezogen werden.

Das muss raus

Genauso wichtig ist die Gegenfrage: Was gehört nicht hinein? Nicht jede Teammeinung muss in diese Datei. Nicht jede Geschmacksfrage ist relevant. Alles, was zu allgemein, zu vage oder zu umfangreich ist, macht die Datei schlechter statt besser. OpenAI empfiehlt ausdrücklich, AGENTS.md praktisch und knapp zu halten; eine kurze, präzise Datei sei nützlicher als ein langer Text voller diffuser Regeln. Anthropic formuliert denselben Gedanken für CLAUDE.md noch schärfer: Die Datei wird bei jeder Sitzung in den Kontext geladen, sollte spezifisch und gut strukturiert sein, und als Zielgröße nennt Anthropic weniger als 200 Zeilen pro Datei.

Gerade dieser Punkt wird oft falsch verstanden. Viele Entwickler neigen dazu, eine solche Datei sofort mit allem vollzuschreiben, was ihnen einfällt. Das ist verständlich, aber unklug. Eine gute AGENTS.md lebt nicht von Vollständigkeitsfantasien, sondern von Relevanz. Ein Agent braucht keine Unternehmensgeschichte. Er braucht die Information, dass src/LegacyBilling nur mit großer Vorsicht angefasst werden darf, dass Integrationstests Redis benötigen, dass Änderungen an einer API zwingend die OpenAPI-Dokumentation nachziehen müssen und dass ein grüner Linter allein noch nicht bedeutet, dass die Aufgabe erledigt ist.

Lass die KI ihre Anleitung erstellen

Die nächste naheliegende Frage lautet: Kann die KI so eine Datei selbst erzeugen? Ja, und das ist sogar sinnvoll. OpenAI empfiehlt für Codex den Slash-Befehl /init, um eine erste AGENTS.md im aktuellen Verzeichnis zu erzeugen. Anthropic bietet für Claude Code ebenfalls ein /init, das eine erste CLAUDE.md generiert beziehungsweise bestehende Dateien verbessert. Beide Werkzeuge können also sehr gut den ersten Rohbau liefern: Repo-Struktur, Befehle, Tests, offensichtliche Konventionen, vielleicht schon wiederkehrende Muster.

Lass den Maintainer die Anleitung prüfen

Der entscheidende Mehrwert entsteht aber erst in der Nachbearbeitung durch einen Menschen. Denn was der Agent aus dem Repo extrahieren kann, ist nur der sichtbare Teil. Die wichtigen Informationen liegen oft außerhalb des Codes: Welche Abkürzungen im Team tabu sind, welche Schicht bewusst unberührt bleiben soll, welche „temporäre“ Lösung seit drei Jahren in Wahrheit geschäftskritisch ist, welche Tests man lokal ignorieren darf und welche niemals. Genau diese Dinge müssen nach dem automatischen Entwurf ergänzt werden. Anders gesagt: Die KI kann die Datei erzeugen, aber die eigentliche Qualität entsteht durch das, was nur Maintainer wissen.

Für diesen ersten Entwurf funktioniert ein einfacher Arbeitsauftrag erstaunlich gut:

Analysiere dieses Repository und erstelle eine erste AGENTS.md-Datei.
Berücksichtige:
- Projektzweck und Systemgrenzen
- Repo-Struktur und wichtige Einstiegspunkte
- Setup-, Build-, Test-, Lint- und Migrationskommandos
- erkannte Coding-Konventionen
- Risiken, heikle Bereiche und bekannte Fallstricke
- Definition of Done für Änderungen
Schreibe knapp, konkret und nur projektbezogen.
Keine Wiederholung der README.
Markiere alles, was du nur vermutest, als offene Annahme.

Danach beginnt die eigentliche Arbeit. Ich würde die Datei Zeile für Zeile so überarbeiten, als müsste morgen ein fremder Agent darin allein zurechtkommen. Das bedeutet: Vermutungen entfernen, implizite Regeln explizit machen, Verallgemeinerungen streichen, konkrete Kommandos eintragen, riskante Bereiche benennen. OpenAI empfiehlt sinngemäß genau dieses iterative Vorgehen: kurz anfangen, praktisch bleiben und neue Regeln erst dann ergänzen, wenn sich echte Fehler wiederholen. Besonders treffend ist der Hinweis, dass man nach wiederholten Fehlgriffen des Agents eine kleine Retrospektive machen und AGENTS.md aktualisieren soll.

AGENTS.md ist fließend

Das ist ohnehin der vielleicht wichtigste Gedanke an der ganzen Sache: AGENTS.md ist kein statisches Dokument, sondern ein Fehlergedächtnis. Immer wenn ein Agent an derselben Stelle zweimal scheitert, fehlt nicht „mehr Modell“, sondern meistens bessere Projektführung. Wenn etwa wiederholt der falsche Einstiegspunkt geändert wird, gehört der richtige Einstiegspunkt explizit in die Datei. Wenn ständig relevante Tests vergessen werden, gehören sie in die Datei. Wenn Agents gern zu breit refaktorieren, gehört eine klare Scope-Regel in die Datei.

Wer mit mehreren Tools arbeitet, sollte sich früh für eine kanonische Quelle entscheiden. Ich halte es für sinnvoll, AGENTS.md im Repository zur zentralen Datei zu machen und toolspezifische Varianten nur als dünne Adapter zu führen. Das ist besonders praktisch, weil Claude Code offiziell CLAUDE.md statt AGENTS.md liest, aber ausdrücklich empfiehlt, in CLAUDE.md einfach @AGENTS.md zu importieren und darunter nur noch Claude-spezifische Zusätze zu notieren. So entsteht keine Doppelpflege. GitHub Copilot Agents unterstützen AGENTS.md direkt, und auch dort gilt das Prinzip der nächstgelegenen Datei im Verzeichnisbaum.

Für größere Repositories oder Monorepos lohnt sich zusätzlich eine hierarchische Struktur. Das offene AGENTS.md-Format sieht ausdrücklich vor, in Teilprojekten weitere AGENTS.md-Dateien abzulegen; Agents lesen automatisch die nächstgelegene Datei, und die spezifischere Regel gewinnt. Dasselbe Prinzip beschreibt OpenAI für Codex. Praktisch bedeutet das: eine zentrale Datei im Repo-Root für globale Standards und kleinere, lokale Dateien in riskanten oder stark spezialisierten Teilbereichen. So bleibt die Hauptdatei kurz, während Sonderregeln genau dort liegen, wo sie gebraucht werden.

Am Ende ist AGENTS.md für mich eine sehr nüchterne Idee: ein Versuch, Projektkontext aus temporären Chats in versionierte Infrastruktur zu überführen. Nicht der Agent soll sich alles merken. Das Repository selbst muss sprechfähig werden. Gerade in alten Projekten ist das der Unterschied zwischen blindem Herumstochern und kontrollierter Arbeit. Wer Coding Agents ernsthaft einsetzen will, braucht deshalb nicht nur bessere Modelle, sondern bessere Projektgedächtnisse. AGENTS.md ist dafür derzeit die schlichteste und wahrscheinlich nützlichste Form.