Claude Code und AGENTS.md: So funktionieren Anweisungsdateien für KI-Agenten 2026

Was AGENTS.md ist und warum es sie gibt

Eine Zeit lang erfand jedes Coding-Tool seine eigene Anweisungsdatei. Cursor hatte .cursorrules, Claude Code hatte CLAUDE.md, Aider hatte .aider.conf.yml, Gemini hatte GEMINI.md, und so weiter. Hattest du dein Repo für einen Agenten annotiert, durftest du alles für den nächsten noch einmal machen.

AGENTS.md ist die Lösung: ein offenes Format zur Anleitung von Coding-Agenten, eine einzige Markdown-Datei im Repo-Stamm, die viele Agenten lesen. Das Projekt nennt sie ein "README for agents", die klarste Kurzformel, die ich kenne. Deine README.md ist für Menschen (Schnellstart, Beitragsleitfaden); AGENTS.md enthält den zusätzlichen Kontext, den ein Agent braucht (Build-Schritte, Tests, Konventionen) und der ein README überladen würde.

Es gibt keine Pflichtfelder. Es ist einfach Markdown: Verwende beliebige Überschriften, der Agent liest den Text. Der Standard entstand in einer Zusammenarbeit im ganzen Ökosystem, unter anderem mit OpenAI Codex, Amp, Googles Jules, Cursor und Factory; der erste Commit landete am 19. August 2025. Inzwischen ist er in eine neutrale Heimat umgezogen und wird von der Agentic AI Foundation unter dem Dach der Linux Foundation betreut; das Repo liegt unter agentsmd/agents.md unter MIT-Lizenz.

Das ist kein Nischenexperiment. Das Repo hat 24,5k Sterne, eine GitHub-Codesuche findet über 60k Beispieldateien, und sogar OpenAIs eigenes Repo enthält 88 davon. Wenn du es bisher als Hype abgetan hast, wäre das der Punkt, an dem ich damit aufhören würde.

Welche Agenten sie tatsächlich lesen

Die Startseite listet 24 kompatible Tools, und die Liste umfasst einen großen Teil der Kategorie: Zed, OpenAI Codex, Gemini CLI, Cursor, Jules, Devin, Warp, Windsurf, VS Code, den Coding-Agenten von GitHub Copilot, Aider, goose, Amp und mehr. Und seit diesem Monat auch Claude Code. Wenn sich so viele konkurrierende Anbieter stillschweigend auf dieselbe einfache Datei einigen, hat sich das Format im Grunde durchgesetzt.

Liest Claude Code die AGENTS.md? Ja, jetzt nativ

Das ist die Frage, mit der die meisten kommen, also die direkte Antwort: Claude Code liest AGENTS.md nativ und setzt dafür v2.1.277 oder neuer voraus (veröffentlicht am 18. September 2026, als Anthropic die toolübergreifende Spezifikation übernahm). Ein Repo, das andere Agenten bereits verstehen, funktioniert mit Claude Code, ohne dass du eine CLAUDE.md, eine Import-Zeile oder eine Einstellung hinzufügen musst.

Der Haken ist, was passiert, wenn beide Dateien existieren. Das Standardverhalten:

Die Falle ist also eine veraltete CLAUDE.md, die stillschweigend über eine sorgfältig gepflegte AGENTS.md triumphiert. Wenn du beide willst, bietet die Einstellung „Project instructions“ (/config) die Werte claude-md-or-agents-md (Standard), claude-md-and-agents-md (beide, CLAUDE zuerst), claude-md (nur CLAUDE) und managed-only. Gut zu wissen: Eine CLAUDE.local.md zählt ebenfalls als Datei der CLAUDE-Familie. Wer eine hineinlegt, sorgt dafür, dass Claude die AGENTS.md nicht mehr liest, bis du diese Einstellung umstellst. Deine ~/.claude/CLAUDE.md, verwaltete Richtliniendateien und .claude/rules/ zählen nicht für die Prüfung „hat eine CLAUDE.md“ und werden deshalb weiterhin zusammen mit AGENTS.md geladen.

Eine weitere Eigenheit zum Merken: Eine direkt gelesene AGENTS.md erscheint nicht in /memory oder /context, und InstructionsLoaded-Hooks werden dafür nicht ausgelöst. Ob sie geladen wurde, erkennst du an der Zeile AGENTS.md loaded zu Beginn der Sitzung. Wenn du neu im Tool bist, decken unser Einstiegsleitfaden und die CLI-Referenz die Grundlagen ab.

CLAUDE.md vs. AGENTS.md: der ehrliche Unterschied

Viele stellen das als Rivalität dar. Das ist es eigentlich nicht. AGENTS.md ist der toolübergreifende Standard; CLAUDE.md ist das umfangreichere Anweisungssystem von Claude Code. Beide sind reines Markdown, und Claude liest jetzt beide.

Praktisch gesehen: Wenn dein Team eine Mischung aus Coding-Agenten nutzt, halte die maßgebliche Quelle in AGENTS.md. Wenn du nur Claude Code nutzt und Imports oder Regeln pro Pfad willst, bietet CLAUDE.md mehr Mechanik. Und du kannst beide haben, wenn du sie bewusst statt zufällig verknüpfst.

Man muss es klar sagen: CLAUDE.md verschwindet nicht und ist auch nicht „schlechter“. Sie hat Funktionen, die AGENTS.md bewusst weglässt (die Spezifikation bleibt absichtlich minimal). Die Wahl zwischen beiden hängt davon ab, wie viele Tools du einsetzt, nicht davon, was besser gebaut ist.

Wie Claude Code Anweisungsdateien lädt

CLAUDE.md-Dateien werden vom breitesten zum spezifischsten Geltungsbereich geladen, und alles Gefundene wird aneinandergehängt statt überschrieben, sodass Anweisungen näher an deinem Startverzeichnis zuletzt gelesen werden. Es gibt vier Ebenen:

1. Verwaltete Richtlinie (organisationsweit, wird zuerst geladen, kann nicht ausgeschlossen werden). Liegt an betriebssystemspezifischen Pfaden wie /Library/Application Support/ClaudeCode/CLAUDE.md unter macOS.
2. Benutzer (~/.claude/CLAUDE.md), deine persönlichen Präferenzen für alle Projekte.
3. Projekt (./CLAUDE.md oder ./.claude/CLAUDE.md), über die Versionsverwaltung mit dem Team geteilt.
4. Lokal (./CLAUDE.local.md), deine privaten Notizen pro Projekt, die du in .gitignore einträgst.

Die Suche ist rekursiv: Claude lädt CLAUDE.md-Dateien aus deinem Arbeitsverzeichnis und aus jedem übergeordneten Verzeichnis. Dateien in Unterverzeichnissen unterhalb von dir werden beim Start nicht geladen; sie werden bei Bedarf nachgeladen, wenn Claude Dateien in diesen Ordnern liest. Genau dieses Verhalten hält Monorepos handhabbar, und es entspricht der Funktionsweise von AGENTS.md: Die nächstgelegene Datei gewinnt, und eine ausdrückliche Anweisung im Chat überstimmt alles. Zum Maßstab: OpenAIs Haupt-Repo enthält 88 einzelne AGENTS.md-Dateien, eine pro Paket.

Diese Aufteilung pro Paket ist wichtiger, als es aussieht, denn eine einzelne Stammdatei stößt bei einer großen Codebasis an eine Grenze. Es ist die häufigste Klage, die ich von Leuten höre, die diese Tools im großen Maßstab einsetzen:

"AGENTS dot md files don't scale beyond modest codebases. Lots of discussions on this lately. If you're building serious software with Claude Code or any agentic tool, a single AGENTS dot md will eventually fail you."

elvis (@omarsar0), X

Die Lösung ist keine größere Datei, sondern mehr davon: eine kurze Stammdatei plus eine verschachtelte pro Paket, damit der Agent immer Anweisungen liest, die auf das zugeschnitten sind, woran er gerade arbeitet.

Imports und das Limit von 4 Ebenen

CLAUDE.md kann andere Dateien mit der Syntax @path/to/import einbinden. Relative und absolute Pfade funktionieren beide, importierte Dateien können wiederum andere importieren, bis zu einer maximalen Tiefe von vier Ebenen, und ein Pfad in Backticks wird nicht importiert (praktisch, wenn du nur eine Datei erwähnen willst). Eine Falle für alle, die ihren Kontext verkleinern wollen: Das Aufteilen in Imports senkt den Token-Verbrauch nicht, weil importierte Dateien trotzdem beim Start geladen werden. Es hilft bei der Organisation, nicht bei der Größe.

Was in eine gute AGENTS.md (oder CLAUDE.md) gehört

Es gibt keine Pflichtabschnitte, aber die gängigen sind Projektübersicht, Build- und Test-Befehle, Code-Stil, Testanweisungen, Sicherheitshinweise und Regeln für PRs oder Commits. Das kanonische Beispiel der Spezifikation sieht so aus:

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package.
- Run `pnpm install --filter <project_name>` to add a package to your workspace.

## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check.
- Fix any test or type errors until the whole suite is green.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

Das Detail, das daraus mehr als Dokumentation macht: Die Test-Befehle, die du auflistest, werden automatisch ausgeführt. Der Agent versucht, die relevanten Prüfungen auszuführen und Fehler zu beheben, bevor er fertig ist. Eine präzise pnpm test-Zeile ist also keine Notiz, sondern eine Anweisung, nach der der Agent handelt.

Für das Schreiben selbst gilt Anthropics Leitfaden für CLAUDE.md genauso für AGENTS.md, denn beide werden ins Kontextfenster geladen und als Kontext behandelt, nicht als durchgesetzte Konfiguration:

• Halte sie kurz. Ziel: unter 200 Zeilen; längere Dateien fressen Kontext und verringern laut Docs sogar, wie gut der Agent ihnen folgt.
• Sei konkret. Laut dem Schreibleitfaden ist "Use 2-space indentation" besser als "Format code properly"; "Run npm test before committing" besser als "Test your changes." Schreibe Regeln so konkret, dass man sie prüfen kann.
• Strukturiere sie. Markdown-Überschriften und Aufzählungen, um zusammengehörige Anweisungen zu gruppieren.
• Bleibe konsistent. Wenn sich zwei Regeln widersprechen, wählt Claude möglicherweise willkürlich eine aus. Prüfe verschachtelte Dateien daher regelmäßig.

Richtig gemacht, zahlt sich das mehr aus, als die meisten erwarten. Wie es ein Entwickler in einem Ask-HN-Thread zur Pflege dieser Dateien formulierte:

"AGENTS.md is extremely important - it's probably the highest leverage thing you can give your agent. It's injected into every turn, and the agents are trained to follow instructions. If anything, I think people are under-investing into AGENTS.md and going purely based on vibes."

bisonbear, Hacker News

Der schnellste Weg zu einem ersten Entwurf ist /init: Es analysiert deine Codebasis auf Build-Befehle, Tests und Konventionen und schreibt eine Startdatei (es kann auch eine Cursor- oder Copilot-Datei migrieren). Bearbeite sie dann mit /memory und prüfe mit /context, was tatsächlich geladen wurde. Und weil eine CLAUDE.md nach dem System-Prompt als Benutzernachricht geliefert wird, gibt es keine Garantie für strikte Befolgung; wenn du eine Regel unter allen Umständen durchsetzen willst, verweisen die Docs statt auf die Anweisungsdatei auf einen PreToolUse-Hook.

So teilst du eine Datei mit allen Agenten

Wenn du Claude Code neben Codex, Cursor oder Gemini einsetzt, ist das Ziel eine einzige maßgebliche Quelle. Mit nativer Unterstützung ist das jetzt der Standard: Packe alles in AGENTS.md und lege keine CLAUDE.md an.

Wenn du eine ältere Version nutzt oder eine Umgebung, in der natives Lesen nicht verfügbar ist (Amazon Bedrock, andere Drittanbieter oder deaktivierte Telemetrie), besteht die Ausweichlösung darin, sie aus einer CLAUDE.md zu importieren:

# CLAUDE.md
@AGENTS.md

Es gibt auch den klassischen Symlink, den die Docs inzwischen aber nur noch als letzten Ausweg betrachten:

ln -s AGENTS.md CLAUDE.md

Der Symlink-Weg hat echte Nachteile: Claudes Edit- und Write-Tools weigern sich, durch den Symlink zu schreiben (sie leiten Änderungen auf die Ziel-AGENTS.md um), und unter Windows wird ein eingecheckter Symlink als reiner Text ausgecheckt, sofern core.symlinks nicht aktiviert ist. Deshalb ist der Import heute die sauberere Lösung. Der offizielle Einzeiler zur Migration einer alten Datei lautet:

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Häufige Fehler, die du vermeiden solltest

Ein paar Fallen, die ich immer wieder sehe und die meist direkt aus den Vorrangregeln stammen:

• Eine vergessene CLAUDE.md, die deine AGENTS.md stillschweigend überstimmt. Wenn beide existieren, liest Claude die CLAUDE.md. Lösche die veraltete oder importiere die andere.
• Imports als Diät behandeln. Das Aufteilen einer riesigen Datei in @-Imports senkt den Kontext nicht; alles wird trotzdem geladen. Kürze stattdessen den Inhalt.
• Vage Regeln. "Write clean code" bringt nichts. Gib den genauen Befehl, die genaue Einrückung, das genaue Titelformat für PRs an.
• Eine Datei mit 600 Zeilen. Ab etwa 200 Zeilen sinkt die Befolgung. Verschiebe mehrstufige Abläufe in Skills oder Subagenten und Regeln für Teile der Codebasis in pfadbezogene .claude/rules/-Dateien.
• Annehmen, dass sie durchgesetzt wird. Anweisungsdateien sind Kontext, keine harte Sperre. Für eine echte Blockade greife zu einem Hook.

Für das Umfeld deiner Anweisungsdateien lohnt sich ein Blick in den settings.json-Leitfaden und die Berechtigungen, da beide beeinflussen, wie Regeln tatsächlich angewendet werden.

eesel ausprobieren: dieselbe Idee für die Agenten in deinem Support

Hier ist die Verbindung. AGENTS.md und CLAUDE.md sind der Weg, einem Coding-Agenten seine dauerhaften Anweisungen in einer Datei zu übergeben. Dieser Coding-Agent ist Infrastruktur, die du konfigurierst. eesel ist die andere Hälfte des Bildes: Statt eines Tools, das du anweist, ist es ein einsatzbereiter KI-Teammate, den du für eine klar umrissene Aufgabe einstellst, heute ein KI-Helpdesk-Agent, der deine Support-Warteschlange abarbeitet, und ein KI-Blog-Autor.

Und er folgt derselben Philosophie, dass „Anweisungen an einem Ort liegen“. Die dauerhaften Regeln eines eesel-Agenten sind nicht über Einstellungsseiten verstreut, sondern ein einziger bearbeitbarer Satz Anweisungen, plus dein echtes Wissen (frühere Tickets, Help Center, Docs). Es ist das mentale Modell von AGENTS.md, angewandt auf einen Support-Teammate.

Wenn du ohnehin im Terminal zu Hause bist, wird sich das vertraut anfühlen. eesel liefert eine echte CLI (@eesel/cli), und die Docs sind deutlich in ihrer Absicht: Alles, was du im Dashboard tun kannst, kannst du auch im Terminal tun, einschließlich der Möglichkeit, die Einrichtung von einem KI-Coding-Agenten erledigen zu lassen. Du kannst sie ohne Installation ausführen (npx @eesel/cli init), mit dem Agenten chatten (eesel chat), seine dauerhaften Regeln bearbeiten (eesel instructions) und nachsehen, was er getan hat (eesel activity). Jeder Befehl gibt JSON aus und unterstützt --dry-run, was genau dafür sorgt, dass er sich von einem Skript oder einem Agenten statt von einem klickenden Menschen steuern lässt.

Noch besser: Jeder eesel-Workspace ist auch ein MCP-Server. Führe eesel mcp token aus, und es gibt eine einfügefertige Zeile für claude mcp add aus, sodass Claude Code (oder Cursor oder Codex) die Anweisungen deines Support-Agenten verwalten, seine Aktivität prüfen und zurückgehaltene Aktionen freigeben kann, ohne deinen Editor zu verlassen. Derselbe Agent, drei Oberflächen: Terminal, Skripte und Coding-Agenten über MCP.

Die Preise sind ein fester Monatspreis ab $299/Monat für 500 Credits (1 Credit pro Ticket oder Chat), Dashboard-Fragen sind größtenteils kostenlos, und es gibt einen kostenlosen Plan mit 100 Credits ohne Karte. Wenn du ohnehin AGENTS.md-Dateien schreibst, wirst du dich sofort zurechtfinden. Probiere eesel aus oder richte Claude Code darauf aus und lass es die Verkabelung erledigen.