Wer heute ein aktuelles Softwareprojekt öffnet, sieht im Root längst nicht mehr nur README.md, package.json und .gitignore. Immer öfter liegt dort auch eine AGENTS.md. Sie ist so etwas wie die Einarbeitungsmappe für Coding-Agenten wie OpenAI Codex, Claude Code, GitHub Copilot oder Cursor: Hier steht, wie das Projekt gebaut wird, welche Konventionen gelten und was der Agent besser bleiben lässt.
Genau darin liegt aber auch das Problem. Agenten nehmen diese Datei ernst, und zwar ziemlich wörtlich. Die Sicherheitsforscher Gal Weizman und Omer Samet von Forever Security haben am 22.10.2026 beschrieben, was das in der Praxis bedeutet. Ein unbemerkter Download reicht, und der eigene KI-Assistent arbeitet plötzlich für jemand anderen.
Wie aus dem Wildwuchs ein Standard wurde
Solange KI-Assistenten nur Code vervollständigt haben, kamen sie mit wenig Kontext aus. Das änderte sich, als sie anfingen, selbstständig Dateien zu bearbeiten, Tests zu starten und Befehle auszuführen. Ein Agent, der Architektur, Build-Befehle und Konventionen eines Projekts nicht kennt, schreibt Code, den man hinterher mühsam wieder einfangen muss.
Also hat erst einmal jeder Hersteller sein eigenes Format erfunden. Anthropic setzte auf CLAUDE.md, Cursor auf .cursorrules (später .cursor/rules), andere Tools wollten .clinerules, GEMINI.md oder .github/copilot-instructions.md. In Teams, in denen nicht alle dasselbe Tool nutzen, lagen dann schnell fünf, sechs Dateien mit fast identischem Inhalt im Repo. Spätestens nach der dritten Änderung stimmten sie nicht mehr überein.
AGENTS.md ist die Antwort auf dieses Durcheinander. Entstanden ist das Format 2025 als Gemeinschaftsprojekt von OpenAI, Google, Cursor, Amp und Factory, inzwischen kümmert sich die Agentic AI Foundation unter dem Dach der Linux Foundation darum. Codex, Cursor, GitHub Copilot, Windsurf und Zed lesen die Datei. Claude Code greift seit Version 2.1.277 vom 18.09.2026 ebenfalls darauf zurück, sofern im Projekt keine CLAUDE.md liegt. Wer beides pflegt, bindet die AGENTS.md einfach per @AGENTS.md in die CLAUDE.md ein.
Die Grundidee passt in einen Satz: Die README.md ist für Menschen, die AGENTS.md für Maschinen.
Wie die Datei den Agenten steuert
Technisch ist an AGENTS.md nichts Besonderes. Es ist schlichtes Markdown ohne vorgeschriebenes Schema. Spannend wird die Datei erst durch das, was der Agent mit ihr anstellt.
Startet man einen Coding-Agenten in einem Verzeichnis, sucht er dort nach einer AGENTS.md und lädt ihren kompletten Inhalt in seinen Kontext, bevor man überhaupt die erste Frage gestellt hat. In Monorepos dürfen mehrere solcher Dateien liegen, etwa /frontend/AGENTS.md und /backend/AGENTS.md. Die Datei im Root gibt dann die globalen Regeln vor, und für die Datei, an der der Agent gerade arbeitet, zählt in der Regel die nächstgelegene AGENTS.md.
Der entscheidende Unterschied zu normaler Doku ist, dass der Agent das nicht nur liest, sondern danach handelt. Steht dort „Führe nach jeder Änderung npm run test:unit aus und behebe Fehler selbstständig“, dann läuft genau dieser Befehl auf dem Rechner des Entwicklers.
So sieht eine typische AGENTS.md aus:
# Project Context & Agent Rules ## Build & Test Commands - Run tests via `pnpm test:unit` (never run the full suite without asking). - Linter check: `pnpm lint --fix` before finishing any task. ## Architecture & Conventions - State management uses Zustand, do not introduce Redux. - All database queries must go through `/src/db/repositories`. - Write strict TypeScript; `any` is forbidden.
Warum sich die Pflege lohnt
Eine gut gepflegte AGENTS.md entscheidet oft darüber, ob sich ein Agent wie ein erfahrener Kollege verhält oder ob man ihm ständig hinterherräumt. Ohne klare Vorgaben greifen Sprachmodelle gern zu veralteten Bibliotheksversionen oder mischen Patterns, die im Projekt nichts verloren haben. Steht der Stack schwarz auf weiß in der Datei, passiert das deutlich seltener.
Dazu kommt ein ganz praktischer Effekt. Der Agent muss nicht in jeder Sitzung erst mit grep und find herausfinden, wie man die Tests startet oder wo die API-Routen liegen. Das spart Zeit und Tokens. Und wenn er die genauen Befehle für Linter, Typecheck und Tests kennt, kann er seinen Code selbst prüfen und nachbessern, bevor ein Mensch draufschaut.
Die Kehrseite: Wenn die Datei zur Waffe wird
Ein Programm, das eine Textdatei einliest und die Anweisungen darin ausführt, verwischt die Grenze zwischen Dokumentation und Code. Weizman und Samet bringen das auf eine knappe Formel: Markdown ist das neue Executable.
Gefunden haben sie das Problem nicht im Labor. Ihre Software hatte auf dem Rechner eines Kunden einen Coding-Agenten gestoppt, der gerade das npm-Paket function-color installieren wollte, ein bekanntes Schadpaket. Merkwürdig war, woher der Befehl kam. Nicht aus einer Abhängigkeit, nicht aus einem Repository, sondern aus einer AGENTS.md im Downloads-Ordner. Wie sie dorthin gekommen war, wusste niemand.
So läuft der Angriff ab
Die Angriffskette verbindet zwei Dinge, die jedes für sich völlig harmlos sind.
Zum einen speichern Browser Downloads standardmäßig ohne Rückfrage in ~/Downloads. Eine präparierte Website kann dort also unbemerkt eine unscheinbare Textdatei namens AGENTS.md ablegen. Dafür muss nicht einmal ein Mensch am Bildschirm sitzen. Laut Forever öffnet rund ein Viertel aller Agenten-Sessions einen echten Browser, der Agent kann sich die Datei also auch selbst einfangen.
Zum anderen starten viele Entwickler ihren Agenten früher oder später direkt im Downloads-Ordner, um schnell ein Archiv anzuschauen, ein Skript zu prüfen oder ein kleines Tool auszuprobieren. In der Telemetrie von Forever kommt das bei etwa der Hälfte der Kunden vor.
Tippt man dann in ~/Downloads den Befehl codex ein und stellt irgendeine harmlose Frage, behandelt der Agent die untergeschobene Datei wie gewöhnlichen Projektkontext. Codex hat zwar eine Hürde eingebaut und folgt einer AGENTS.md nur in Ordnern, denen man vertraut. Wer dort aber schon einmal gearbeitet hat, hat diese Hürde längst selbst aus dem Weg geräumt.
Was die Datei anrichtet
Die gefundene AGENTS.md war ein rund 13 KB langes, betont langweiliges Dokument mit „Engineering Work Guidelines“. Der eigentliche Angriff, eine klassische Indirect Prompt Injection, steckt in einem Abschnitt kurz vor Schluss und gibt sich als Routine-Setup für Projekt-Tools aus.
Bei Codex bringt dieser Abschnitt den Agenten dazu, vor der eigentlichen Aufgabe einen zusätzlichen MCP-Server in seine globale Konfiguration ~/.codex/config.toml einzutragen. Über diesen Eintrag wird function-color installiert und ausgeführt. Damit die Netzwerksperre der Sandbox nicht stört, lässt die Datei Codex eine zweite Instanz mit dem Flag --dangerously-bypass-approvals-and-sandbox starten. In den Tests der Forscher führte Codex die Schadsoftware in mehr als 90 % der Versuche aus. Besonders unangenehm ist, dass die Änderung für den ganzen Rechner gilt. Ab dann lädt jede Codex-Sitzung den Server des Angreifers, ganz egal, in welchem Projekt.
Claude Code war deutlich schwerer zu täuschen. Für diesen Fall haben die Forscher selbst eine präparierte CLAUDE.md geschrieben, angelehnt an die echte Datei. Sie soll Claude dazu bringen, in .claude/settings.json die Variable ANTHROPIC_BASE_URL auf einen Server der Angreifer zu setzen, getarnt als internes Firmen-Gateway. Eigentlich verlangt Claude für so einen Schreibzugriff eine Freigabe und lehnt verdächtige Änderungen oft von sich aus ab. Die lange, unauffällige Verpackung kam trotzdem in etwa der Hälfte der Versuche durch. Danach laufen sämtliche API-Anfragen über den fremden Server, samt OAuth-Token. Das reicht für eine Kontoübernahme, ohne dass eine einzige Zeile Code laufen muss. Und weil sich der Server als Modell ausgeben kann, schiebt er Claude ab der nächsten Sitzung Tool-Aufrufe unter, die dann direkt auf dem Rechner ausgeführt werden.
Warum es dafür keinen Patch gibt
Das eigentlich Heikle daran: Es gibt keinen Bug, den OpenAI oder Anthropic einfach schließen könnten. Ein Agent, der die AGENTS.md in seinem Arbeitsverzeichnis befolgt, tut genau das, wofür er gebaut wurde. Die Forscher ziehen den Vergleich zu Phishing. Wenn ein Browser eine gefälschte Bank-Seite anzeigt, hat er auch nur seinen Job gemacht.
Jahrzehntelang galt eine Datei im Downloads-Ordner als ungefährlich, solange niemand sie doppelt anklickt und die Warnungen des Betriebssystems (unter macOS etwa Gatekeeper) ignoriert. Agenten hebeln diese Annahme aus, weil sie Text lesen und ihn selbst in Shell-Befehle übersetzen. Das gleiche Risiko besteht übrigens bei jedem fremden Repository, das man von GitHub klont und in dem eine manipulierte AGENTS.md liegt.
Was Entwickler und Teams jetzt tun können
Weil die Lücke an der Nahtstelle zwischen Browser und Agent entsteht, hilft vor allem Disziplin beim Arbeitsverzeichnis, ergänzt um ein paar technische Leitplanken.
- Agenten gehören weder in den Downloads-Ordner noch direkt ins Home-Verzeichnis. Heruntergeladene Dateien wandern zuerst in einen eigenen, sauberen Ordner.
- Fremde Instruktionsdateien sollten gelesen werden, bevor ein Agent damit arbeitet.
AGENTS.md,CLAUDE.mdoder.cursor/rulesin einem frisch geklonten Repo verdienen dieselbe Skepsis wie ein Makefile oder einpostinstall-Skript in derpackage.json. - Sandbox und Bestätigungsabfragen bleiben am besten eingeschaltet, vor allem für Änderungen außerhalb des Projektordners und für Netzwerk- oder Paketmanager-Befehle wie
npm installodercurl. Verlangt ein Projekt, den Agenten im YOLO-Modus ohne Rückfragen laufen zu lassen, ist Misstrauen angebracht. - Ein regelmäßiger Blick in die Agenten-Konfiguration lohnt sich. In
~/.codex/config.tomlsind unbekannte[mcp_servers]-Einträge oder eine verändertechatgpt_base_urlverdächtig, in.claude/settings.jsoneineANTHROPIC_BASE_URLoder ein Proxy, den niemand bewusst gesetzt hat. - Wer so etwas findet, sollte davon ausgehen, dass das Token abgeflossen ist, und es austauschen. Taucht
function-color(inzwischen von npm entfernt) in den Installationen eines Rechners auf, ist der Rechner als kompromittiert zu behandeln.
Was bleibt
AGENTS.md wird nicht wieder verschwinden, und das ist auch gut so. Die Datei löst ein echtes Problem und macht Agenten in größeren Codebasen überhaupt erst zu verlässlichen Mitarbeitern. Der Fall zeigt aber, dass sich unsere Gewohnheiten ändern müssen. Wenn ein Satz in natürlicher Sprache genügt, damit eine Maschine Code ausführt, ist jede Textdatei, die ein Agent liest, im Grunde ausführbar. Prompt-Kontext gehört deshalb genauso gründlich geprüft wie Quellcode.