Eine AGENTS.md-Datei im Jahr 2026 schreiben (kurz, handgeschrieben, datenbasiert)

Eine AGENTS.md-Datei ist eine reine Markdown-"README für deinen Coding-Agenten", die im Wurzelverzeichnis deines Repositorys liegt und Tools wie Claude Code, Codex und Cursor sagt, wie sie in deinem Projekt bauen, testen und sich verhalten sollen. Die besten sind kurz, konkret und handgeschrieben: Sie listen deine exakten Befehle auf, benennen deinen Stack mit Versionen und ziehen klare Grenzen darum, was der Agent niemals anrühren darf. Die schlechtesten sind lang, vage und automatisch generiert — und inzwischen gibt es messbare Belege dafür, dass sie Agenten langsamer und ungenauer machen.

Wir bauen TechRiseUps mit Claude Code, und die einzelne Datei, die am meisten verändert hat, wie zuverlässig es korrekte Arbeit liefert, war die Datei mit den Agenten-Anweisungen. Dies ist der praktische Leitfaden, den wir uns gewünscht hätten: was man schreiben, was man streichen sollte und warum weniger mehr ist.

Was ist eine AGENTS.md-Datei?

AGENTS.md ist ein offenes, toolunabhängiges Format zur Steuerung von Coding-Agenten — "ein dedizierter, vorhersehbarer Ort, um den Kontext und die Anweisungen bereitzustellen, die KI-Coding-Agenten bei der Arbeit an deinem Projekt helfen." Betrachte es als das Gegenstück zu deiner für Menschen gedachten README: Build-Schritte, Test-Befehle und Konventionen, die die README überfrachten würden, die ein Agent aber tatsächlich braucht.

Das Format wurde von OpenAI für Codex initiiert und im Dezember 2025 an die Agentic AI Foundation unter der Linux Foundation übergeben, sodass es nicht länger die Konvention eines einzelnen Anbieters ist. Es wird inzwischen von über 60.000 Open-Source-Projekten anerkannt und von mehr als 28 Tools unterstützt, darunter Codex, Cursor, Aider, Devin, Google Jules und VS Code. Claude Code liest seine eigene CLAUDE.md und berücksichtigt zunehmend auch AGENTS.md; die folgenden inhaltlichen Ratschläge gelten für beide. Eine Datei, viele Agenten — das ist der ganze Sinn.

Was in eine AGENTS.md-Datei gehört

GitHub hat mehr als 2.500 echte agents.md-Dateien analysiert (veröffentlicht am 19. November 2025) und eine klare Trennlinie zwischen Dateien gefunden, die helfen, und solchen, die ignoriert werden. Die untauglichen teilen ein Merkmal: Sie sind zu vage. "Hilfreicher Coding-Assistent"-Personas brachten nichts; exakte Befehle und harte Grenzen erledigten die Arbeit.

Hier ist, was seinen Platz verdient — und was man weglassen sollte:

Aufnehmen (verdient seine Tokens)	Streichen (verschwendet sie)
Exakte Befehle mit Flags: pnpm test, pytest -v	"Führe die Tests aus" ohne Befehl
Stack mit Versionen: "React 18, TS 5, Vite, Tailwind"	"Moderner Web-Stack"
Ein echtes Code-Snippet, das deinen Stil zeigt	Absätze, die deinen Stil beschreiben
Dreistufige Grenzen: Immer / Vorher fragen / Niemals	Eine allgemeine "Sei vorsichtig"-Zeile
Nicht offensichtliche Fallstricke (Monorepo-Eigenheiten, Env-Setup)	Ein vollständiger Verzeichnisbaum, den der Agent selbst lesen kann
"Niemals Secrets committen" und geschützte Pfade	Wiederholen von Sprachdokumentation, die das Modell bereits kennt

Die am häufigsten wirklich nützliche Einschränkung über die 2.500 Repositories hinweg war unverblümt: "Niemals Secrets committen." Diese eine Zeile ist die günstigste Versicherung, die du schreiben kannst, und sie knüpft direkt an die umfassenderen Lehren zur Lieferkette aus der npm-Shai-Hulud-Krise an — Agenten mit Shell-Zugriff können Zugangsdaten genauso schnell durchsickern lassen wie ein kompromittiertes Paket.

Warum eine kürzere AGENTS.md eine längere schlägt

Das ist der Teil, den die meisten Leitfäden auslassen, und er ist der wichtigste. Jede Zeile in deiner AGENTS.md wird in jede Agenten-Sitzung eingespeist, sodass jede Zeile um das begrenzte Aufmerksamkeitsbudget des Modells konkurriert. Sie aufzublähen hilft dem Agenten nicht — es schadet aktiv.

Eine ETH-Zürich-Studie aus dem Jahr 2026 hat das mit Zahlen belegt. Automatisch generierte, aufgeblähte Kontextdateien senkten den Aufgabenerfolg in 5 von 8 getesteten Konstellationen, ließen Agenten 2,45 bis 3,92 zusätzliche Schritte pro Aufgabe machen und trieben die Inferenzkosten um 20–23 % in die Höhe — und das alles ohne messbaren Qualitätsgewinn. Von Menschen kuratierte Dateien übertrafen dagegen LLM-generierte für jeden getesteten Agenten, und zwar um rund 4 Prozentpunkte im AGENTbench-Benchmark. Als die Forscher redundante Dokumentation vollständig löschten, verbesserte sich die Leistung der automatisch generierten Dateien sogar, was bestätigte, dass sie größtenteils nur Dinge duplizierten, die das Modell bereits kannte.

Die praktische Regel von Praktikern deckt sich mit den Daten: halte sie kurz. Der allgemeine Konsens liegt bei unter 300 Zeilen, und Teams wie HumanLayer halten ihre unter 60. Schreibe sie selbst, bewusst, denn "eine schlechte Zeile in AGENTS.md pflanzt sich über jede Sitzung hinweg zu schlechten Plänen, schlechtem Code und schlechten Ergebnissen fort."

So schreibst du deine AGENTS.md, Schritt für Schritt

Du kannst in zehn Minuten eine funktionierende Datei haben. Geh in dieser Reihenfolge vor:

1. Erstelle AGENTS.md im Repository-Wurzelverzeichnis. Beginne leer. Widerstehe dem Drang, einen "Generiere meine AGENTS.md"-Befehl auszuführen — du weißt jetzt, dass die Daten sagen: handgeschrieben gewinnt.
2. Schreibe zuerst die Befehle. Die exakten Zeilen, die du zum Installieren, Ausführen, Testen und Linten eintippen würdest. Nimm die Flags mit auf. Das ist der wertvollste Abschnitt, deshalb steht er ganz oben.
3. Benenne den Stack mit Versionen. Eine Zeile: Sprachen, Framework, Paketmanager, wichtige Bibliotheken und ihre Hauptversionen. Unklarheit hier verursacht die meisten verschwendeten Agenten-Schritte.
4. Füge ein echtes Code-Snippet hinzu, das deine Konventionen demonstriert — eine tatsächliche Funktion oder Komponente aus deinem Repository, keine Beschreibung davon.
5. Lege dreistufige Grenzen fest. Immer (z. B. "führe den Linter aus, bevor du fertig bist"), Vorher fragen (z. B. "bevor du das DB-Schema änderst"), Niemals (z. B. "niemals Secrets committen, niemals /vendor anrühren, niemals git push"). Hier codierst du das Urteilsvermögen, das das Modell nicht ableiten kann.
6. Notiere nur das Nicht-Offensichtliche. Die Paketstruktur im Monorepo, eine erforderliche Env-Variable, ein instabiler Test, den man ignorieren soll. Lass alles weg, was der Agent durch Lesen des Verzeichnisbaums selbst herausfinden kann.
7. Teste sie, dann kürze. Führe eine echte Aufgabe aus, beobachte, wo der Agent falsch rät, füge eine Zeile hinzu, um das zu beheben, und lösche jede Zeile, die sich nie bezahlt gemacht hat.

Ein kontraintuitiver Nutzen: Tools, die du in AGENTS.md benennst, werden etwa 160-mal häufiger verwendet als Tools, die du nicht benennst. Wenn du willst, dass der Agent dein eigenes Skript oder einen bestimmten MCP-Server nutzt, erwähne es ausdrücklich — sonst existiert es faktisch nicht. Wenn du noch überlegst, auf welchen Agenten du dich festlegen sollst, behandelt unser Vergleich Cursor vs Copilot vs Windsurf vs Claude Code, wie jeder den Projektkontext lädt.

AGENTS.md, CLAUDE.md und .cursorrules — brauchst du alle drei?

Nein. AGENTS.md ist der aufkommende toolübergreifende Standard, mach es also zu deiner Single Source of Truth. Claude Code sucht weiterhin nach CLAUDE.md, und Cursor nutzte historisch .cursorrules; der aufwandsarme Weg ist, den echten Inhalt in AGENTS.md zu halten und dort, wo ein Tool auf seinem eigenen Dateinamen besteht, ihn per Symlink oder Import einzubinden, statt zwei auseinanderdriftende Kopien zu pflegen. In einem Monorepo kannst du Dateien auch verschachteln: Agenten lesen automatisch die nächstgelegene AGENTS.md im Verzeichnisbaum, sodass ein Paket das Wurzelverzeichnis überschreiben kann — OpenAIs eigenes Repository liefert 88 davon aus. Halte die Wurzeldatei allgemein und lass jedes Paket seine Besonderheiten enthalten. Welchen Agenten du damit kombinierst, ist weiterhin entscheidend; siehe unsere Übersicht über die besten KI-Coding-Tools 2026.

Häufige Fehler, die du vermeiden solltest

• Die ganze Datei automatisch generieren. Der schnellste Weg zu einem langsameren Agenten. Generiere höchstens ein Grundgerüst und schreibe es dann von Hand um.
• Deinen Verzeichnisbaum einfügen. Agenten listen Dateien selbst auf; ein statischer Baum veraltet nur und verbrennt Tokens.
• Das Offensichtliche wiederholen. Das Modell weiß, wie Python funktioniert. Sag ihm, was spezifisch für dein Repository ist.
• Eine einzige riesige Datei für alles. Nutze progressive Offenlegung: Halte aufgabenspezifische Notizen in separaten Dokumenten (z. B. agent_docs/running-tests.md) und verweise darauf, damit die Wurzeldatei schlank bleibt.
• Sie nie wieder anfassen. Die Datei driftet, während sich dein Projekt verändert. Kürze sie immer dann, wenn der Agent falsch rät.

Häufig gestellte Fragen

Wo gehört die AGENTS.md-Datei hin?

In das Wurzelverzeichnis deines Repositorys. Bei Monorepos füge zusätzliche AGENTS.md-Dateien innerhalb einzelner Pakete hinzu; der Agent liest die Datei, die der bearbeiteten Datei am nächsten liegt, und diese nächstgelegene Datei hat Vorrang.

Wie lang sollte eine AGENTS.md sein?

Kurz. Der geltende Konsens liegt bei unter 300 Zeilen, und viele starke Beispiele bleiben unter 100. Weil jede Zeile in jede Sitzung geladen wird, hat Länge einen realen Preis — bei Genauigkeit wie bei Tokens. Schreibe nur, was das Verhalten des Agenten verändert.

Sollte ich eine KI meine AGENTS.md generieren lassen?

Nutze eine, um ein grobes Grundgerüst zu entwerfen, falls es sein muss, aber liefere es nicht unverändert aus. Die ETH-Zürich-Forschung ergab, dass automatisch generierte Dateien den Aufgabenerfolg in den meisten Konstellationen senkten und die Kosten um 20–23 % erhöhten. Von Menschen kuratierte Dateien schlugen generierte auf ganzer Linie — die Datei ist es wert, von Hand geschrieben zu werden.

Nutzt Claude Code AGENTS.md?

Claude Code liest CLAUDE.md nativ und erkennt zunehmend AGENTS.md. Die inhaltlichen Prinzipien sind in beiden Fällen identisch: exakte Befehle, versionierter Stack, harte Grenzen und Kürze. Wenn du bereits eine gute CLAUDE.md pflegst, bist du zu 90 % auf dem Weg zu einer guten AGENTS.md.

Was ist die eine Sache, die jede AGENTS.md haben sollte?

Eine "Niemals"-Grenze, die "niemals Secrets committen" enthält. Sie war die mit Abstand häufigste nützliche Einschränkung über mehr als 2.500 echte Repositories hinweg, und sie ist die günstigste Zeile, um eine Codebasis zu schützen, die ein Agent nun bearbeiten und ausführen kann.

Quellen

• agents.md — das offene Format und die Spezifikation: Definition, unterstützte Tools, Monorepo-Verschachtelung sowie Trägerschaft durch die Agentic AI Foundation / Linux Foundation.
• GitHub Blog — How to write a great agents.md: lessons from over 2,500 repositories: die datenbasierten Abschnitte, die funktionieren, und der "zu vage"-Fehlermodus (19. Nov. 2025).
• Philipp Schmid — Writing a Good AGENTS.md: der "unter 300 Zeilen halten"-Konsens und der Befund zur 160-fach häufigeren Tool-Nennung.
• Augment Code — How to Build Your AGENTS.md: Zusammenfassung der ETH-Zürich-Studie, die zeigt, dass automatisch generierte Dateien den Aufgabenerfolg senken und die Kosten erhöhen.