Glossareintrag
Wir denken. KI tippt mit.
AGENTS.md ist eine Textdatei im Markdown-Format, die im Projektordner liegt und einem KI-Agenten sagt, wie er in diesem Projekt arbeiten soll. Die Anweisungsdatei für KI-Agenten enthält das, was ein neuer Kollege am ersten Tag erfährt: Befehle zum Bauen und Testen des Programms, Regeln für den Code-Stil, Abläufe und Verbote. Die Projektseite agents.md nennt sie ein „README for agents“, also ein README für Agenten. Die README.md bleibt für Menschen. In die AGENTS.md kommen die Details, die nur der Agent benötigt.
Das Format entstand im August 2025 aus einer Absprache mehrerer Hersteller von Programmier-Agenten (Coding-Agenten), laut Projektseite OpenAI Codex, Amp, Jules von Google, Cursor und Factory. Seit dem 9. Dezember 2025 liegt es bei der Agentic AI Foundation (AAIF) unter dem Dach der Linux Foundation, zusammen mit dem Model Context Protocol von Anthropic und dem Agenten goose von Block. Pflichtfelder und Versionsnummer gibt es nicht. Jede Überschrift ist erlaubt. Der Agent liest den Text so, wie er dasteht.
Eine eigene deutsche Bezeichnung hat sich nicht gebildet, der Dateiname bleibt unübersetzt. Die deutsche GitHub-Dokumentation führt die Datei unter „benutzerdefinierte Anweisungen“ als „AGENTS.md-Agent-Anweisungen“. Anbietereigene Gegenstücke sind CLAUDE.md (Claude Code von Anthropic), GEMINI.md (Gemini CLI von Google) und copilot-instructions.md (GitHub Copilot). In der Fachliteratur heißen alle zusammen Kontextdateien (englisch: Context Files).
Der Agent liest die Datei beim Start jeder Sitzung und legt ihren Text in sein Kontextfenster. Die Regeln gelten damit ab der ersten Anfrage. Niemand muss sie im Chat wiederholen. Der Preis dafür sind Token, denn der Agent liest jede Zeile in jeder Sitzung mit. Große Projekte verteilen die Anweisungen auf mehrere Dateien. In jedem Unterordner darf eine eigene AGENTS.md liegen. Bei Widersprüchen gewinnt laut Projektseite die Datei, die der bearbeiteten Stelle am nächsten liegt. Ausdrückliche Anweisungen im Chat schlagen alle Dateien. Beim Verfassen der Projektseite enthielt das Haupt-Repository (die Code-Ablage) von OpenAI 88 solcher Dateien.
Was hineingehört, hat GitHub an über 2.500 Dateien aus öffentlichen Projekten untersucht. Kernbereiche laut der Analyse erfolgreicher AGENTS.md-Dateien:
Eine Studie über 2.303 Kontextdateien aus 1.925 Repositories hat Testabläufe in 75,9 Prozent der Dateien gefunden. Sicherheitsvorgaben standen nur in 14,8 Prozent. Die Autoren beschreiben die Dateien als schwer lesbare Gebilde, die wie Konfigurationscode durch viele kleine Nachträge wachsen.
Die Projektseite listete am 19. September 2026 insgesamt 23 kompatible Werkzeuge auf, darunter Codex, Jules, Cursor, GitHub Copilot, Zed, Devin, Junie von JetBrains und Visual Studio Code. Kompatibel heißt nicht überall dasselbe:
Trotz Linux Foundation fehlt bis heute eine förmliche Spezifikation, also ein Dokument, das festlegt, wie ein Tool die Datei zu lesen hat. Das offene Repository des Formats (MIT-Lizenz) enthält die Website und seit September 2026 eine Satzung für die Projektführung (Technical Charter). Mehrere offene Anträge aus der Community fordern eine Spezifikation. Bis dahin unterscheiden sich Ladereihenfolge, Größengrenzen und der Umgang mit Unterordnern von Tool zu Tool. Die AAIF nennt als Gründungsmitglieder der höchsten Stufe Amazon Web Services, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft und OpenAI.
Vercel hat im Januar 2026 Aufgaben mit neuen Schnittstellen des Web-Frameworks Next.js geprüft, die in keinem Trainingsstand der KI-Modelle vorkamen. Ohne Dokumentation bestand der Agent 53 Prozent der Prüfungen, mit einem Skill ebenfalls 53 Prozent, mit Skill und ausdrücklicher Anweisung 79 Prozent. Ein 8 KB großes Inhaltsverzeichnis der Dokumentation direkt in der AGENTS.md brachte 100 Prozent. Vercel erklärt den Abstand in seinem Bericht über AGENTS.md und Skills im Vergleich damit, dass der Agent bei einer immer geladenen Datei nie entscheiden muss, ob er nachschlägt.
Eine Untersuchung an 124 Pull Requests aus zehn Repositories hat mit AGENTS.md eine um 28,64 Prozent kürzere mittlere Laufzeit (Median) gemessen, dazu 16,58 Prozent weniger Ausgabe-Token bei vergleichbarem Erledigungsverhalten.
Ein Team der ETH Zürich um Martin Vechev kommt zu einem anderen Ergebnis. Gemeinsam mit der Firma LogicStar.ai hat die Gruppe Claude Code, Codex und Qwen Code mit und ohne Kontextdatei getestet. Laut der ETH-Studie „Evaluating AGENTS.md“ steigt die Erfolgsquote durch Kontextdateien im Allgemeinen nicht. Die Kosten pro Aufgabe wachsen dagegen im Schnitt um mehr als 20 Prozent. Das gilt für automatisch erzeugte wie für von Entwicklern geschriebene Dateien. Die Agenten befolgen die Anweisungen zuverlässig. Die beliebten Projektübersichten bleiben aber wirkungslos, weil sie dem Agenten beim Finden der richtigen Dateien nicht helfen. Nach dem Schluss der Autoren lohnen sich Kontextdateien für Arbeitsweisen, die vom Üblichen abweichen. Vercels Testfall gehört in diese Gruppe, denn die geprüften Schnittstellen kannte kein KI-Modell aus dem Training.
Eine Auswertung von 100 populären Repositories hat in 62 Prozent der Dateien Regeln gefunden, die im Projekt bereits ein Prüfprogramm für Code-Form und Schreibweise abdeckt (Linter oder Formatter). 42 Prozent der Dateien hatten 200 Zeilen oder mehr, was die Autoren als aufgeblähten Kontext („Context Bloat“) werten. Anthropic empfiehlt aus Sicht des Context Engineering für seine CLAUDE.md weniger als 200 Zeilen, weil längere Dateien mehr Kontext verbrauchen und schlechter befolgt werden. OpenAI rät, Format- und Lint-Prüfungen der automatischen Kontrolle zu überlassen.
AGENTS.md unterscheidet sich von verwandten Dateien durch Ort und Ladezeitpunkt. Eine llms.txt liegt auf einer Website und weist KI-Systemen den Weg zu deren Inhalten. AGENTS.md liegt dagegen im Projektordner und regelt die Arbeit darin. Eine SKILL.md hat Pflichtfelder, und der Agent lädt sie erst, wenn ihre Beschreibung zur Anfrage passt. AGENTS.md ist immer geladen und formfrei. Die ältere .cursorrules gilt nur in Cursor und ist dort als Altformat markiert.
Weil der Agent die Datei als Anweisung behandelt, ist sie ein Angriffsziel. Die Cloud Security Alliance nennt SKILL.md, CLAUDE.md und AGENTS.md in einer Research Note zu Agent Context Poisoning (Vergiften des Agenten-Kontexts) vom 6. Mai 2026 den wichtigsten Übertragungsweg dieser Angriffsklasse. Die Schadlast ist gewöhnlicher Text, den das KI-Modell als Verhaltensregel liest. Im schlimmsten Fall steckt er in unsichtbaren Unicode-Zeichen. Das Red Team von NVIDIA (die hauseigene Angriffs-Testgruppe) hat am 20. April 2026 eine solche indirekte Prompt Injection vollständig vorgeführt. Im Versuch erkennt eine manipulierte Programmbibliothek die Codex-Umgebung und schreibt beim Übersetzen des Programms (Build) eine eigene AGENTS.md ins Projekt. Der Agent baut daraufhin eine Verzögerung von fünf Minuten in das Programm ein und verschweigt sie in der Zusammenfassung seines Pull Requests. NVIDIA empfiehlt in der Analyse indirekter AGENTS.md-Angriffe unter anderem feste Versionen für Abhängigkeiten, eingeschränkte Schreibrechte auf Konfigurationsdateien und eine Überwachung unerwarteter Dateiänderungen.
Eine AGENTS.md benötigt nur, wer einen KI-Agenten in einem Ordner mit Dateien arbeiten lässt. Wer ChatGPT oder Claude im Browser nutzt, hat dafür die benutzerdefinierten Anweisungen in den Einstellungen.
Die eigene Website oder ein eigenes Tool. Terminformulare, Angebotsrechner oder kleine Kundenportale lassen sich heute mit Codex, Claude Code oder Cursor bauen, selbst per Vibe Coding oder über eine Agentur. Die AGENTS.md im Projektordner hält fest, was man sonst in jedem Chat neu sagen müsste. Beispiel für einen Sanitärbetrieb mit Angebotsrechner:
Wichtig: Passwörter und API-Schlüssel gehören nie in die AGENTS.md. Die Datei liegt offen im Projekt und geht in jeder Sitzung an den Anbieter des KI-Modells.
Der Wechsel von Werkzeug oder Dienstleister. Weil Codex, Copilot, Cursor, Jules und seit September 2026 auch Claude Code dieselbe Datei lesen, bleiben die Projektregeln beim Wechsel erhalten. Wer eine Agentur mit KI-gestützter Entwicklung beauftragt, fragt nach, ob das Projekt eine AGENTS.md hat und ob sie mit übergeben wird. Die Datei dokumentiert nebenbei, nach welchen Regeln die Agentur am eigenen Projekt gearbeitet hat.
Büroarbeit mit Agenten. Die Website agents.md spricht durchgehend von Coding-Agenten. Für reine Büro-Ordner ist AGENTS.md nicht dokumentiert. Claude Cowork arbeitet laut der Einstiegsanleitung von Anthropic für Cowork mit derselben Agenten-Architektur wie Claude Code und kennt Ordner-Anweisungen für ausgewählte lokale Ordner. Darin steht dann kein Build-Befehl, sondern z. B. der Aufbau der Angebotsnummern, der Ablageort für Rechnungen und die Regel, dass nichts gelöscht wird.
Die Datei bleibt in allen drei Fällen kurz und enthält nur, was der Agent nicht selbst aus den Dateien erkennen kann. Von Hand geschriebene Regeln sind einer automatisch erzeugten Projektübersicht vorzuziehen. Solche Übersichten erhöhen nach den Messungen der ETH Zürich primär die Kosten. Wer eine AGENTS.md aus einer fremden Vorlage oder einem heruntergeladenen Projekt übernimmt, liest sie vor dem ersten Start komplett. Der Agent führt aus, was darin steht.
