Ratgeber
AGENTS.md, CLAUDE.md und PROJECT_CONTEXT.md: welche Kontextdatei welche Aufgabe übernimmt
Mehrere Kontextdateien im Projekt, aber unklare Zuständigkeiten? Diese Seite trennt drei Rollen sauber: AGENTS.md und CLAUDE.md steuern Coding-Agenten, eine toolneutrale Kontextdatei hält den Projektstand. Keine vierte Datei, sondern klare Grenzen.
Die schnelle Antwort
Wer mit Coding-Agenten arbeitet, legt schnell mehrere Markdown-Dateien an — und verliert dann den Überblick, welche Datei wofür zuständig ist. Die saubere Trennung lautet: AGENTS.md und CLAUDE.md sind Anweisungen an die Werkzeuge (wie gearbeitet wird), eine toolneutrale Kontextdatei ist die Wahrheit über das Projekt (worum es geht und wo es steht). Die erste Sorte ändert sich selten, die zweite oft. Wer beides in eine Datei mischt, bekommt eine Datei, die halb veraltet und halb aktuell ist.
Wichtig ist auch, was nicht stimmt: AGENTS.md ist kein verbindlicher Standard, den jedes Tool erzwingt, sondern eine offene Konvention. Und kein Werkzeug erwartet zwingend den Dateinamen „PROJECT_CONTEXT.md" — der Name ist frei wählbar. Wer das einmal entwirrt, hört auf, in jeder Session dieselbe Erklärung zu wiederholen.
Vergleichstabelle: drei Dateien, drei Rollen
Die folgende Tabelle ordnet jeder Datei einen Zweck, einen Inhalt, eine Abgrenzung, eine Geltung und einen Pflegerhythmus zu. Sie ist eine Zuständigkeitsmatrix, keine Rangfolge — keine Datei ist „besser", sie haben unterschiedliche Aufgaben.
Tabelle horizontal scrollbar — auf dem Smartphone seitlich wischen.
| Datei | Zweck | Was gehört hinein | Was nicht | Geltung | Aktualität |
|---|---|---|---|---|---|
AGENTS.md | Agenten-Instruktionen für Coding-Agenten (Codex u. v. a.) | Build-/Testbefehle, Arbeits- und Qualitätsregeln, Scope, geschützte Bereiche | wechselnder Produktstatus, lange Entscheidungsprotokolle | toolübergreifend (offene Konvention, >20 Agenten) | stabil; bei neuen Befehlen/Regeln anpassen |
CLAUDE.md | Projektkontext speziell für Claude Code | lokale Arbeitsregeln, Plan-/Implementierungsprozess, Konventionen, Commands, geschützte Bereiche | langfristiger Produktstatus, Inhalte nur für andere Tools | Claude Code (liest CLAUDE.md, nicht AGENTS.md) | stabil; Versions-/Tool-abhängiges Verhalten kennzeichnen |
PROJECT_CONTEXT.md | toolneutrale Source of Truth zum Projekt | Ziel, aktueller Stand, Entscheidungen, Current/Next, Risiken, offene Fragen, Referenzpunkt | agentenspezifische Regeln, Tool-Befehle | frei benennbar, kein Tool-Pflichtname | ändert sich häufig — Prüfdatum/Referenzpunkt pflegen |
Welches Werkzeug du einsetzt, entscheidet, welche Regeldatei du brauchst. Die toolneutrale Kontextdatei lohnt sich unabhängig davon — sie ist die Grundlage, auf der jedes Werkzeug aufsetzt.
Was jede Datei leistet — und was nicht
AGENTS.md — toolübergreifende Agenten-Instruktionen
AGENTS.md ist „ein README für Agenten": ein vorhersehbarer Ort für Build-Schritte, Tests, Konventionen und Arbeitsregeln. Es ist eine offene, freiwillige Konvention, die von über 20 Coding-Agenten unterstützt wird — darunter OpenAI Codex, Cursor, Jules und weitere — und seit Dezember 2025 von der Agentic AI Foundation unter der Linux Foundation betreut wird. Das Format ist einfaches Markdown ohne Pflichtfelder. Hinein gehören: Repository- und Bereichsinstruktionen, Arbeits- und Qualitätsregeln, Build-/Testbefehle, Scope und Grenzen, geschützte Bereiche, optional eine Hierarchie zwischen Root und Unterordnern. Nicht hinein gehört der wechselnde Produktstatus.
Keine falsche Universalität: AGENTS.md ist breit adoptiert, aber kein von jedem Tool erzwungener Pflichtstandard. Ob ein bestimmtes Werkzeug die Datei liest, hängt vom Werkzeug ab.
CLAUDE.md — Projektkontext für Claude Code
CLAUDE.md gibt Claude Code dauerhafte Instruktionen, die zu Beginn jeder Session geladen werden. Laut der
Anthropic-Dokumentation liest Claude Code CLAUDE.md, nicht AGENTS.md. Nutzt dein Repository
bereits AGENTS.md für andere Agenten, bindest du sie in CLAUDE.md per Import (@AGENTS.md) ein oder
setzt einen Symlink — so lesen beide Werkzeuge dieselben Regeln ohne Doppelpflege, und Claude-spezifische
Ergänzungen stehen darunter. Hinein gehören: lokale Arbeitsregeln, der Plan-/
Implementierungsprozess, Projektkonventionen, relevante Commands, geschützte Bereiche.
Nicht hinein gehört der langfristige Produktstatus.
Versions- oder toolabhängiges Verhalten klar kennzeichnen: CLAUDE.md ist laut Doku Kontext, keine erzwungene Konfiguration. Was technisch garantiert greifen muss — etwa ein Verbot vor jedem Commit — gehört in einen Hook oder ein Setting, nicht nur in den Text. Empfohlen sind knappe Dateien (Richtwert unter 200 Zeilen), weil längere Dateien mehr Kontext verbrauchen und schlechter befolgt werden.
PROJECT_CONTEXT.md — toolneutrale Source of Truth
Diese Datei hält fest, worum es im Projekt geht — unabhängig von jedem Werkzeug. Hinein gehören: Produktziel, aktueller Stand, getroffene Entscheidungen, Current/Next, Risiken, offene Fragen und ein Referenzpunkt (Commit, Build oder Dokumentversion). Wichtig: Es ist eine frei benennbare Datei und kein offizieller Pflichtstandard — kein Tool erwartet exakt diesen Namen. Sie sollte nicht mit agentenspezifischen Regeln überladen werden; ihre Aufgabe ist der Stand, nicht die Arbeitsweise. Wie ein solcher portabler Projektkontext entsteht, zeigt der Guide KI-Projektkontext aufbauen.
Priorität, Konflikte und Root vs. Unterordner
Sowohl AGENTS.md (Codex / agents.md-Konvention) als auch CLAUDE.md werden vom Stammverzeichnis nach unten zur aktuellen Arbeitsdatei zusammengeführt. Die Regel ist in beiden Fällen dieselbe Logik: die Datei, die der bearbeiteten Stelle am nächsten liegt, hat Vorrang; eine ausdrückliche Anweisung im Chat steht über allem. Codex stoppt zudem ab einer Größengrenze (Standard 32 KiB) und berücksichtigt höchstens eine Datei pro Verzeichnis; Claude Code lädt übergeordnete CLAUDE.md beim Start vollständig und Unterordner-Dateien bei Bedarf.
Praktisch heißt das: Ins Stammverzeichnis kommt, was für das ganze Repository gilt. In einen Unterordner kommt nur, was wirklich nur dort gilt — eine abweichende Test- oder Stilregel für ein Teilsystem. So bleibt die Wurzeldatei klein und spezifische Regeln stehen, wo sie greifen.
Dauerhafter vs. temporärer Kontext
Die wichtigste Linie verläuft nicht zwischen den Tools, sondern zwischen dauerhaft und temporär. Dauerhafte Regeln (wie gearbeitet wird) gehören in AGENTS.md/CLAUDE.md. Zeitpunktbezogener Stand (was gerade gilt) gehört in die Kontextdatei — und für den Wechsel zwischen Sessions oder Werkzeugen in ein Übergabeartefakt. Wie ein solcher Wechsel sauber gelingt, beschreibt der Guide KI-Projektübergabe.
Kleines Context-Set statt Context Overload
- Lieber wenige, klare Regeln, die wirklich gelten, als eine lange Datei, die niemand mehr liest.
- Jede Regel sollte konkret und überprüfbar sein („2 Leerzeichen Einrückung" statt „sauber formatieren").
- Was nur ein Teilsystem betrifft, gehört in den Unterordner — nicht in die Wurzeldatei.
- Abgeschlossene Entscheidungen wandern ins Verlaufs-/Entscheidungsdokument, nicht in die Regeldatei.
Eine empfohlene Minimalstruktur
Für die meisten kleinen Projekte reicht ein schlankes Set. Die folgende Struktur ist eine Praxiseinschätzung, kein Tool-Vorgabewert — sie lässt sich frei anpassen:
@AGENTS.md importieren, darunter nur Claude-spezifische Ergänzungen Entscheidungsbaum: welche Information wohin
Im Zweifel hilft eine feste Fragenfolge. Sie führt eine einzelne Information zu ihrer richtigen Datei — und verhindert, dass alles in einer Datei landet.
-
Arbeitet nur ein Agent oder mehrere Tools?
Mehrere Tools → gemeinsame Regeln in AGENTS.md, von Claude per Import eingebunden. Nur Claude → CLAUDE.md genügt.
-
Geht es um Repository-Regeln oder Produktstatus?
Regeln → AGENTS.md / CLAUDE.md. Status, Entscheidungen, Current/Next → toolneutrale Kontextdatei.
-
Muss die Information dauerhaft gelten?
Dauerhaft → Regeldatei. Zeitpunktbezogen (aktueller Stand) → Kontextdatei oder Übergabe.
-
Gilt die Regel nur für Claude?
Nur Claude → CLAUDE.md (ggf. unterhalb des AGENTS.md-Imports). Toolübergreifend → AGENTS.md.
-
Gilt die Regel nur für einen Unterordner?
Nur dort → Datei in den Unterordner; die nächstgelegene Datei hat Vorrang. Sonst → Stammverzeichnis.
-
Ist die Information aktuell oder historisch?
Historisch (abgeschlossene Entscheidungen) → eigenes Entscheidungs-/Verlaufsdokument, nicht die Regeldatei aufblähen.
-
Kann die Information automatisiert verifiziert werden?
Harte Verbote besser als Hook/Setting erzwingen statt nur als Text — Regeldateien sind Kontext, keine technische Sperre.
Beispiele: kleines Projekt und komplexes Repository
Kleines Projekt (eine Person, ein Werkzeug)
Eine Solo-Gründerin nutzt nur Claude Code. Sie braucht keine AGENTS.md: Eine knappe CLAUDE.md im Stammverzeichnis (Build-/Testbefehle, „Plan-Mode vor größeren Änderungen", geschützte Bereiche) plus eine kurze Kontextdatei mit Ziel, Stand und nächster Aufgabe reichen. Zwei Dateien, beide unter einer Bildschirmseite.
Komplexeres Repository (mehrere Tools, Monorepo)
Ein kleines Team nutzt Codex und Claude Code in einem Monorepo. Im Stammverzeichnis liegt eine AGENTS.md mit den gemeinsamen Regeln; CLAUDE.md importiert sie und ergänzt Claude-spezifische Punkte. Einzelne Pakete haben eine eigene AGENTS.md mit lokal abweichenden Test- oder Stilregeln (die nächstgelegene Datei gewinnt). Eine toolneutrale Kontextdatei hält den projektweiten Stand. So lesen beide Werkzeuge dieselben Grundregeln, ohne dass etwas doppelt gepflegt wird.
Häufige Fehler
- Regeln und Produktstatus in eine Datei mischen — die Hälfte veraltet, ohne dass es auffällt.
- Für Claude Code eine AGENTS.md anlegen und erwarten, dass sie gelesen wird (Claude Code liest CLAUDE.md).
- Dieselben Regeln doppelt in AGENTS.md und CLAUDE.md pflegen, statt sie zu importieren.
- Annehmen, jedes Tool erwarte exakt „PROJECT_CONTEXT.md" — der Name ist frei.
- AGENTS.md/CLAUDE.md immer weiter wachsen lassen, bis die wichtigen Regeln untergehen.
- Ein hartes Verbot nur als Textregel schreiben, statt es per Hook/Setting technisch zu erzwingen.
Pflege und Freshness
Regeldateien überprüfst du, wenn sich Befehle, Konventionen oder geschützte Bereiche ändern — eher selten. Die toolneutrale Kontextdatei dagegen lebt vom Aktuellsein: Stand, Current/Next und der Referenzpunkt gehören nach jedem nennenswerten Schritt aktualisiert. Eine einfache Regel hilft: Wenn du im Chat zum zweiten Mal dieselbe Sache erklärst, gehört sie in eine der Dateien — als dauerhafte Regel oder als aktueller Stand.
Quellen & Methodik
Das beschriebene Tool-Verhalten (welche Datei welches Werkzeug liest, Priorität, Dateipfade, Größengrenzen) wurde am 13. Juni 2026 an den offiziellen Dokumentationen geprüft. Aussagen zu Struktur und Vorgehen sind als Praxiseinschätzung gekennzeichnet. Es werden keine Standards, Benchmarks oder Pflicht-Konventionen behauptet, die nicht belegt sind.
- agents.md — offene AGENTS.md-Konvention (Format, Adoption, Root/Unterordner-Priorität).
- Anthropic — Claude Code: Memory & CLAUDE.md (liest CLAUDE.md statt AGENTS.md, Import, Ladereihenfolge).
- OpenAI — Codex: AGENTS.md (Discovery-Hierarchie, Vorrang der nächstgelegenen Datei, Größengrenze).
Häufige Fragen
Brauche ich AGENTS.md und CLAUDE.md gleichzeitig?
Es hängt von deinen Werkzeugen ab. Claude Code liest laut Dokumentation CLAUDE.md, nicht AGENTS.md; Codex und viele andere Agenten lesen AGENTS.md. Wer beide Werkzeuge nutzt, hält die gemeinsamen Regeln an einer Stelle und verbindet sie — etwa indem CLAUDE.md die AGENTS.md per Import einbindet, statt beide Dateien doppelt zu pflegen.
Ist AGENTS.md ein offizieller Pflichtstandard?
Nein. AGENTS.md ist eine offene, freiwillige Konvention, die von über 20 Coding-Agenten unterstützt und seit Dezember 2025 von der Agentic AI Foundation unter der Linux Foundation betreut wird. Es ist einfaches Markdown ohne Pflichtfelder — kein verbindlicher Standard, den jedes Tool erzwingt.
Erwartet ein Tool den Dateinamen PROJECT_CONTEXT.md?
Nein. PROJECT_CONTEXT.md ist kein toolseitiger Standard, sondern eine frei benennbare, projektinterne Source-of-Truth-Datei. Du kannst sie beliebig nennen. Wichtig ist nicht der Name, sondern dass es einen toolneutralen Ort gibt, an dem Ziel, Stand und Entscheidungen stehen — getrennt von den agentenspezifischen Regeln.
Was gehört in CLAUDE.md und was nicht?
In CLAUDE.md gehören dauerhafte Arbeitsregeln, Build-/Test-Befehle, Konventionen und geschützte Bereiche — knapp gehalten, laut Anthropic-Doku idealerweise unter 200 Zeilen. Nicht hinein gehört der wechselnde Produktstatus oder lange Entscheidungsprotokolle; die liegen besser in einer projektinternen Kontextdatei, die sich häufiger ändert.
Welche Datei gewinnt bei einem Konflikt?
Bei den agentenspezifischen Dateien gilt in der Praxis: die Datei, die der bearbeiteten Stelle am nächsten liegt, hat Vorrang — sowohl AGENTS.md (Codex, agents.md-Konvention) als auch CLAUDE.md werden vom Stammverzeichnis nach unten zusammengeführt, und die nächstgelegene Anweisung überschreibt frühere. Eine ausdrückliche Anweisung im Chat steht über allem.
Sollte ich die Regeln in den Unterordner oder ins Stammverzeichnis schreiben?
Ins Stammverzeichnis kommt, was für das ganze Repository gilt. In einen Unterordner kommt nur, was wirklich nur dort gilt — etwa eine abweichende Test- oder Stilregel für ein Teilsystem. So bleibt die Wurzeldatei klein, und spezifische Regeln stehen dort, wo sie greifen.