AGENTS.md-Spezifikation – vollständiger Leitfaden
Gemeinschaftsvorschlag von OpenAI · Google · Cursor · Factory · CLAUDE.md-kompatibel · Beispiele aus echten Repositories · Stand 2026-10-07 liest Claude Code ab 2.1.277 AGENTS.md in Projekten ohne CLAUDE.md
Warum AGENTS.md notwendig war
Bis Anfang 2025 hatte jedes KI-Coding-Tool ein eigenes Projekt-Memory-Format – Cursor nutzte .cursorrules, Claude Code CLAUDE.md, Codex instructions.md, Aider .aider.conf.yml. Ein Toolwechsel bedeutete, das Projektwissen neu zu schreiben. Im August 2025 haben OpenAI, Google, Cursor, Factory und weitere AGENTS.md als anbieterübergreifenden Standard veröffentlicht, damit eine einzige Konfigurationsdatei mit jedem kompatiblen Agenten funktioniert.
Die fünf Kernabschnitte
AGENTS.md definiert fünf standardisierte Abschnitte, getrennt durch Markdown-H2-Überschriften, kompatibel mit jedem Markdown-Editor:
Identity: Identität des Agenten, Rolle, Antwortssprache
Capabilities: Fähigkeitsdeklarationen, Tool-Präferenzen, Modellversionen
Tools: verfügbare Tool-Liste, Berechtigungsumfang, externe API-Konfiguration
Memory: Projektkontext, Konventionen, Glossar, frühere Entscheidungen
Constraints: verbotene Verhaltensweisen, Sicherheitsregeln, Compliance
Interop mit CLAUDE.md und .cursorrules
AGENTS.md ist kein Ersatz – es ist der größte gemeinsame Nenner über alle Tools hinweg. Laut offizieller Doku (geprüft am 2026-10-07) gilt bei Claude Code standardmäßig Entweder-oder: Ohne CLAUDE.md liest es AGENTS.md, sind beide vorhanden, nur CLAUDE.md. Cursor liest AGENTS.md seit 1.2 nativ. Codex CLI sucht zuerst nach AGENTS.md und greift auf instructions.md zurück.
Toolchain-Unterstützung heute
CursorCursor 1.2+: native Unterstützung, AGENTS.md hat Vorrang vor .cursorrules
Claude CodeClaude Code: liest AGENTS.md seit 2.1.277 (veröffentlicht am 2026-09-18) nativ; der Changelog lautet „Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead“. Standard ist Entweder-oder: Liegt im Arbeitsverzeichnis oder darüber eine CLAUDE.md, wird nur diese gelesen; über Project instructions in /config lassen sich beide laden. Seit 2.1.281 (2026-09-23) gilt das auch hinter LLM-Gateways (geprüft am 2026-10-07).
Codex CLICodex CLI: sucht standardmäßig seit 2026-02 nach AGENTS.md, über alle OpenAI-Tools hinweg
AiderAider: experimentelle Unterstützung seit 0.65, aktiviert über --agents-md
Fünf häufige Anti-Patterns
1) Alle historischen Entscheidungen in Memory stopfen, bis die Datei über 10 KB anwächst; 2) Identity als Marketing-Text statt als ausführbare Direktiven formulieren; 3) Constraints listen abstrakte Prinzipien statt konkreter verbotener Verhaltensweisen; 4) Veraltete Tools-Listen, die niemand mehr bereinigt hat; 5) Verwechslung mit .gitignore – AGENTS.md muss in der Versionskontrolle liegen, damit das Team es teilt.
Claude Code mit AGENTS.md aus eingeschränkten Netzwerken betreiben
Eine häufige Frage: „Ich bin Entwickler in Festlandchina und Claude Code erhält bei meinem AGENTS.md-Projekt regelmäßig Timeout-Fehler – was nun?“ Dies ist ein Problem der Netzwerkerreichbarkeit, das nichts mit der Spezifikation selbst zu tun hat. Optionen: direkt bei Anthropic ein Abo abschließen (am besten bei stabilen Netzwerken im Ausland); einen Marken-API-Abodienst wie QCode.cc nutzen (für China optimierter Zugang + einheitliche Abrechnung + ein Key für vier Modelle); oder ein eigenes Unternehmens-Gateway aufbauen (lange Vorlaufzeit).
Ihr erstes AGENTS.md-Projekt auf QCode.cc ausführen
Claude Fable 5 · GPT-5.5 · Codex · Gemini 2.5 Pro – ein Abo, vier Tools
QCode-Konto erstellen
Ein API-Key für Claude, GPT und chinesische Modelle, Bezahlung pro Token — aktuelle Preise unter /models.