AGENTS.md vs. CLAUDE.md: Welche Datei braucht dein KI-Coding-Projekt?

Du startest ein neues Projekt, öffnest OpenAI Codex und möchtest dem Coding-Agenten erklären, wie dein Repository aufgebaut ist. Also legst du eine AGENTS.md an.

Am nächsten Tag öffnet ein Kollege dasselbe Repository mit Claude Code.

Kennt Claude jetzt automatisch die Regeln aus deiner AGENTS.md?

Nein.

Genau hier entsteht derzeit eine der häufigsten Stolperfallen bei KI-gestützter Softwareentwicklung.

Codex arbeitet standardmäßig mit AGENTS.md. Claude Code verwendet dagegen CLAUDE.md. Beide Dateien erfüllen auf den ersten Blick einen sehr ähnlichen Zweck – technisch sind sie aber nicht identisch.

Und wer mehrere Coding-Agenten verwendet, sollte keinesfalls anfangen, dieselben Regeln manuell in fünf verschiedenen Dateien zu pflegen. Die bessere Lösung ist eine zentrale Quelle für gemeinsame Projektregeln.

Die Kurzantwort

Wenn du nur eine schnelle Entscheidung brauchst:

Empfohlene Instruktionsdatei je nach Coding-Agent

Dein Coding-Agent	Empfohlene Datei
OpenAI Codex	AGENTS.md
Claude Code	CLAUDE.md
Codex + Claude Code	AGENTS.md + kleine CLAUDE.md
Mehrere unterschiedliche Coding-Agenten	möglichst AGENTS.md als zentrale Basis
Nur Claude-Code-Projekt	CLAUDE.md reicht

Für Projekte, in denen Codex und Claude Code gemeinsam eingesetzt werden, ist derzeit besonders sinnvoll:

AGENTS.md
CLAUDE.md

Die eigentlichen gemeinsamen Projektregeln stehen in AGENTS.md. Die CLAUDE.md enthält anschließend beispielsweise nur:

@AGENTS.md

## Claude Code

Nutze für größere Änderungen zuerst den Plan Mode.

Damit pflegst du gemeinsame Regeln nur an einer Stelle. Anthropic beschreibt genau diesen Aufbau inzwischen auch in der offiziellen Claude-Code-Dokumentation: Claude Code liest CLAUDE.md, nicht automatisch AGENTS.md. Existiert bereits eine AGENTS.md, kann sie aus der CLAUDE.md importiert werden. Wer beide Agenten im selben Projekt einsetzt und noch unsicher ist, welcher davon insgesamt besser zum eigenen Workflow passt, findet einen ausführlichen Vergleich in Claude Code vs. OpenAI Codex: Welcher Coding-Agent ist besser? (Zum Artikel).

Was ist eine AGENTS.md?

Eine AGENTS.md ist vereinfacht gesagt eine README für KI-Coding-Agenten. Sie erklärt einem Agenten Dinge, die er nicht zuverlässig allein aus dem Quellcode ableiten kann.

Zum Beispiel:

• welche Architektur verwendet wird
• wie das Projekt gestartet wird
• welche Tests ausgeführt werden müssen
• welche Coding-Konventionen gelten
• welche Verzeichnisse verändert werden dürfen
• welche Komponenten besonders kritisch sind
• wie Git-Commits aussehen sollen
• welche Befehle vor einem Pull Request laufen müssen
• welche Änderungen ausdrücklich verboten sind

Eine typische Datei könnte so beginnen:

# AGENTS.md

## Projekt

Dieses Repository enthält eine React-Anwendung mit Flask-API
und MySQL-Datenbank.

## Installation

Frontend:

npm install
npm run dev

Backend:

python -m venv .venv
pip install -r requirements.txt

## Tests

Vor Abschluss jeder Änderung:

npm test
pytest

## Coding-Regeln

- Bestehende Architektur beibehalten.
- Keine neuen Dependencies ohne Begründung.
- Keine Secrets in das Repository schreiben.
- Bestehende Tests nicht entfernen.
- Fehler nicht durch leere catch-Blöcke unterdrücken.

Das offene AGENTS.md-Format beschreibt README.md und AGENTS.md bewusst als Ergänzung zueinander: README.md richtet sich an Menschen mit Quickstart, Projektbeschreibung und Beitragsrichtlinien, während AGENTS.md den zusätzlichen, teils detaillierten Kontext liefert, den Coding-Agenten brauchen.

AGENTS.md ist inzwischen mehr als eine reine Codex-Datei

Ursprünglich wurde AGENTS.md besonders durch Coding-Agenten wie Codex bekannt. Inzwischen entwickelt sich das Format jedoch zu einer deutlich allgemeineren Konvention für Coding-Agenten.

Die offizielle AGENTS.md-Seite beschreibt das Format als offenen, werkzeugunabhängigen Ansatz für Projektanweisungen und nennt inzwischen mehr als 60.000 Open-Source-Projekte, die das Konzept einsetzen. Die Weiterentwicklung wird von der Agentic AI Foundation innerhalb der Linux Foundation betreut.

Damit entsteht ein wichtiger Vorteil: AGENTS.md ist nicht ausschließlich an ein einzelnes KI-Modell oder einen einzelnen Hersteller gebunden. Genau deshalb eignet sich die Datei besonders gut als gemeinsame Basis eines modernen KI-Coding-Projekts.

Wie OpenAI Codex AGENTS.md verwendet

Codex liest AGENTS.md automatisch, bevor es mit einer Aufgabe beginnt – dafür ist kein manueller Aufruf nötig. Die Datei wird hierarchisch eingesammelt: eine globale Ebene unter ~/.codex/AGENTS.md beziehungsweise ~/.codex/AGENTS.override.md, darunter die projektbezogenen Dateien vom Git-Root bis zum aktuellen Arbeitsverzeichnis.

Vereinfacht kann ein Repository beispielsweise so aussehen:

projekt/
├── AGENTS.md
├── frontend/
│ ├── AGENTS.md
│ └── src/
└── backend/
├── AGENTS.md
└── src/

Die Datei im Projektstamm enthält allgemeine Regeln, zum Beispiel:

- Keine Secrets committen.
- Alle Änderungen müssen getestet werden.
- Keine direkten Änderungen auf Production.

Im Backend können zusätzliche, spezifischere Regeln gelten, im Frontend wiederum andere. Auf jeder Ebene prüft Codex zuerst, ob eine AGENTS.override.md vorhanden ist – existiert sie, hat sie Vorrang vor der regulären AGENTS.md derselben Ebene. Dateien, die näher am bearbeiteten Verzeichnis liegen, überschreiben dabei allgemeinere Vorgaben aus übergeordneten Ebenen.

Für diese Projektanweisungen gilt außerdem ein Kontextbudget: Standardmäßig sammelt Codex Dateien bis zu einer Gesamtgröße von 32 KiB (konfigurierbar über project_doc_max_bytes) und ignoriert leere Dateien. Wer die Codex CLI unter Linux einrichtet, findet eine ausführliche Schritt-für-Schritt-Anleitung inklusive AGENTS.md-Praxisbeispielen in Codex CLI unter Linux installieren und richtig nutzen (Zum Artikel).

Was ist eine CLAUDE.md?

CLAUDE.md erfüllt für Claude Code einen sehr ähnlichen Zweck. Sie enthält persistente Anweisungen, die Claude bei seiner Arbeit am Projekt berücksichtigen soll.

Dazu gehören beispielsweise:

# Projektregeln

## Architektur

Das Backend basiert auf Flask.
Die REST API befindet sich unter src/api/.

## Datenbank

MySQL verwenden.
Bestehende Migrationen niemals verändern.
Für Schemaänderungen neue Migration erstellen.

## Tests

Nach Backend-Änderungen:

pytest tests/

## Sicherheit

Keine Zugangsdaten aus .env ausgeben.
Keine Produktionssysteme verändern.
Keine Deployments ohne ausdrückliche Anweisung ausführen.

Claude Code lädt solche Informationen bei jeder neuen Session wieder in seinen Kontext. Anthropic empfiehlt, in CLAUDE.md vor allem Dinge abzulegen, die Claude ansonsten regelmäßig erneut erklärt werden müssten – etwa Build-Kommandos, Konventionen, Projektarchitektur oder feste Arbeitsregeln.

Claude Code kennt mehrere Ebenen von CLAUDE.md

Claude Code besitzt ein umfangreiches System rund um seine Instruktionsdateien. Anthropic unterscheidet dabei vier Ebenen:

Verwaltete Regeln (Managed Policy) – von IT oder DevOps zentral verteilt, unter Linux und WSL beispielsweise unter /etc/claude-code/CLAUDE.md, unter macOS unter /Library/Application Support/ClaudeCode/CLAUDE.md. Dort stehen üblicherweise Unternehmensrichtlinien, die für alle Nutzer eines Rechners gelten und sich nicht durch einzelne Projekt- oder Nutzereinstellungen ausschließen lassen.

Persönliche Regeln – ~/.claude/CLAUDE.md, zum Beispiel: „Bevorzuge ausführliche Commit-Messages.“, „Verwende pnpm statt npm.“

Projektregeln – ./CLAUDE.md oder ./.claude/CLAUDE.md. Diese Datei gehört normalerweise ins Repository und gilt für das ganze Team.

Lokale persönliche Regeln – ./CLAUDE.local.md. Dort können projektspezifische persönliche Einstellungen abgelegt werden, die nicht mit dem Team geteilt werden sollen. CLAUDE.local.md sollte deshalb normalerweise über .gitignore ausgeschlossen werden.

Claude Code lädt CLAUDE.md und CLAUDE.local.md aus dem aktuellen Arbeitsverzeichnis und aus jedem übergeordneten Verzeichnis darüber; Dateien in Unterverzeichnissen werden bei Bedarf nachgeladen, sobald Claude dort Dateien liest. Für größere Projekte lassen sich Instruktionen zusätzlich in .claude/rules/ aufteilen – dort können einzelne Regeldateien sogar auf bestimmte Dateipfade beschränkt werden, sodass sie nur dann geladen werden, wenn Claude tatsächlich an passenden Dateien arbeitet.

Der wichtigste Unterschied: Claude Code liest AGENTS.md nicht automatisch

Hier entsteht die entscheidende Falle.

Du hast eine AGENTS.md perfekt gepflegt. Darin stehen Architektur, Tests, Sicherheitsregeln, Git-Konventionen und Deployment-Regeln.

Du startest anschließend claude und gehst davon aus, dass Claude diese Datei ebenfalls berücksichtigt.

Das solltest du nicht voraussetzen.

Anthropics Dokumentation formuliert es eindeutig: Claude Code liest CLAUDE.md, nicht AGENTS.md. Genau deshalb empfiehlt Anthropic bei bestehenden AGENTS.md-Projekten eine kleine Importdatei:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Damit bekommt Claude Code denselben gemeinsamen Kontext. Claude lädt die importierte Datei beim Sitzungsstart und hängt die restlichen, Claude-spezifischen Anweisungen anschließend an.

Die beste Struktur für Codex und Claude Code gemeinsam

Für ein modernes Multi-Agent-Projekt würde ich folgende Struktur bevorzugen:

projekt/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── docs/
├── frontend/
├── backend/
└── tests/

Die Rollen sind klar getrennt:

README.md – für Menschen. Enthält zum Beispiel: Was macht das Projekt? Wie installiere ich es? Wie starte ich es? Wie kann ich beitragen?

AGENTS.md – gemeinsame Arbeitsregeln für Coding-Agenten. Beispielsweise: Architekturprinzipien, Build-Kommandos, Test-Kommandos, Sicherheitsregeln, Git-Regeln, Definition of Done, wichtige Einschränkungen.

CLAUDE.md – nur Claude-spezifische Ergänzungen, zum Beispiel:

@AGENTS.md

## Claude Code

- Verwende Plan Mode bei Architekturänderungen.
- Nutze Subagents für unabhängige Analyseaufgaben.

Damit existiert genau eine gemeinsame Wahrheit.

Warum du AGENTS.md und CLAUDE.md nicht kopieren solltest

Eine schlechte Lösung wäre: AGENTS.md und CLAUDE.md mit jeweils 300 nahezu identischen Zeilen.

Am Montag änderst du die Testregel in AGENTS.md. Am Mittwoch ergänzt jemand eine Sicherheitsregel in CLAUDE.md. Vier Wochen später widersprechen sich beide Dateien.

Codex bekommt npm test. Claude bekommt npm run test:ci. Codex darf ein bestimmtes Verzeichnis verändern. Claude darf es laut seiner Datei nicht.

Damit hast du genau das Problem geschaffen, das die Dateien eigentlich verhindern sollten: Duplikation von Agentenregeln erzeugt Konfigurations-Drift.

Die sinnvollere Architektur lautet:

AGENTS.md = gemeinsame Wahrheit
CLAUDE.md = Import + Claude-spezifische Ergänzungen

Alternative: CLAUDE.md als Symlink

Anthropic nennt noch eine zweite Möglichkeit. Unter Linux oder macOS kannst du beispielsweise verwenden:

ln -s AGENTS.md CLAUDE.md

Dann zeigen beide Dateinamen auf denselben Inhalt. Das funktioniert gut, wenn überhaupt keine Claude-spezifischen Ergänzungen benötigt werden.

Der Nachteil: Sobald du Claude-spezifische Regeln brauchst, wird der einfache Symlink unpraktisch. Außerdem ist das Erstellen symbolischer Links unter Windows je nach Konfiguration an Administratorrechte oder den Developer Mode gebunden – dort ist der Import mit @AGENTS.md deshalb häufig die praktischere Lösung.

Kann Codex auch CLAUDE.md lesen?

Technisch lässt sich Codex flexibler konfigurieren, als es zunächst aussieht. OpenAI unterstützt in der Codex-Konfiguration alternative Projektdateinamen über die Option project_doc_fallback_filenames. Damit könnte ein Benutzer Codex beispielsweise so konfigurieren, dass zusätzliche Instruktionsdateien berücksichtigt werden.

Für ein Teamprojekt würde ich mich darauf allerdings nicht verlassen. Diese Einstellung existiert möglicherweise nur auf deinem eigenen Rechner. Ein anderer Entwickler klont das Repository und verwendet die Standardkonfiguration – dann fehlt plötzlich der Projektkontext.

Für portable Repositories ist deshalb besser:

Codex → AGENTS.md
Claude → CLAUDE.md
Gemeinsam → AGENTS.md + CLAUDE.md-Import

Was gehört wirklich in AGENTS.md oder CLAUDE.md?

Die Dateien sollten keine Enzyklopädie deines gesamten Projekts werden. Sinnvolle Inhalte sind beispielsweise:

Projektstruktur

Frontend: /frontend
Backend: /backend
Tests: /tests
Dokumentation: /docs

Technologie

Frontend: React + TypeScript
Backend: Flask
Database: MySQL
CSS: Tailwind CSS

Build-Befehle

npm install
npm run build

Test-Befehle

npm test
pytest

Coding-Regeln

- Bestehende Patterns wiederverwenden.
- Keine unnötigen Abhängigkeiten hinzufügen.
- Kleine, nachvollziehbare Änderungen bevorzugen.

Sicherheitsregeln

- Niemals .env-Dateien committen.
- Keine Secrets ausgeben.
- Keine Produktionssysteme verändern.
- Keine Datenbanken löschen.

Definition of Done – eine Aufgabe ist erst abgeschlossen, wenn:

1. die Änderung implementiert wurde,
2. vorhandene Tests erfolgreich laufen,
3. neue Funktionen getestet wurden,
4. keine Secrets committed wurden,
5. git diff geprüft wurde.

Gerade eine solche Definition of Done verbessert Coding-Agent-Workflows erheblich.

Was sollte nicht hinein?

Mindestens genauso wichtig ist, was du weglässt.

Keine Zugangsdaten

Niemals:

DATABASE_PASSWORD=...
API_KEY=...
SSH_PASSWORD=...

Eine Instruktionsdatei gehört häufig ins Git-Repository. Secrets gehören dort nicht hinein.

Keine 1000-Zeilen-Projektdokumentation

In der Praxis zeigt sich häufig: Eine sehr umfangreiche AGENTS.md funktioniert schlechter als eine kompakte Datei, die den Agenten gezielt zu weiterführender Dokumentation führt. Die offizielle AGENTS.md-Seite beschreibt die Datei entsprechend eher als Karte beziehungsweise Inhaltsverzeichnis des Repositories – ausführlichere Informationen gehören in eine strukturierte Dokumentation unter docs/.

Beispielsweise:

AGENTS.md
ARCHITECTURE.md
docs/
├── security.md
├── database.md
├── deployment.md
└── api.md

Das ist wesentlich skalierbarer. Auch Anthropic warnt davor, CLAUDE.md unnötig groß werden zu lassen, und empfiehlt als Richtgröße unter 200 Zeilen pro Datei – längere Dateien verbrauchen mehr Kontext und werden weniger zuverlässig befolgt. Für Regeln, die nur für bestimmte Dateitypen gelten, bietet sich stattdessen ein pfadbezogenes Regel-Set unter .claude/rules/ an, das nur bei Bedarf geladen wird.

AGENTS.md sollte eine Karte sein – kein Roman

Eine gute Regel lautet: Schreibe in AGENTS.md, was der Agent immer wissen muss. Verlinke für alles andere auf die passende Dokumentation.

Zum Beispiel:

# Architektur

Siehe docs/architecture.md.

# Datenbank

Schema und Migrationsregeln:
docs/database.md

# Security

Sicherheitsanforderungen:
docs/security.md

So muss der Agent nicht bei jeder kleinen Aufgabe die komplette Architekturgeschichte des Projekts in seinen Kontext laden. Das spart Kontext und reduziert widersprüchliche Informationen.

CLAUDE.md besitzt zusätzlich Auto Memory

Claude Code unterscheidet inzwischen ausdrücklich zwischen den von dir geschriebenen Instruktionen und automatisch aufgebautem Projektwissen.

CLAUDE.md enthält bewusst definierte Regeln, die du selbst formulierst.

Daneben kann Claude Code Erkenntnisse eigenständig in einem separaten Auto-Memory-Verzeichnis ablegen, typischerweise unter:

~/.claude/projects/<projekt>/memory/
├── MEMORY.md
├── user_role.md
├── feedback_testing.md
└── ...

Dort unterscheidet Claude Code vier Arten von Notizen: Informationen zu deiner Rolle und deinen Vorlieben, Feedback und Korrekturen, laufenden Projektkontext, den Claude nicht allein aus Code oder Git-Historie ableiten kann, sowie Verweise auf externe Systeme. Dinge, die bereits aus dem Code ableitbar sind oder ohnehin in der CLAUDE.md stehen, speichert Claude bewusst nicht zusätzlich.

Das ist ein wichtiger Unterschied: CLAUDE.md sagt Claude, wie gearbeitet werden soll. Auto Memory speichert Dinge, die Claude während der Arbeit gelernt hat. Beides sollte nicht miteinander verwechselt werden.

AGENTS.md und CLAUDE.md sind keine Sicherheitsmechanismen

Dieser Punkt ist besonders wichtig.

Eine Zeile wie „Niemals Produktionsdaten löschen.“ ist sinnvoll. Sie ist aber keine technische Zugriffskontrolle.

Claude Code behandelt CLAUDE.md ausdrücklich als Kontext und nicht als technisch erzwungene Konfiguration: Die Inhalte werden Claude als Nachricht nach dem System-Prompt übergeben, es gibt keine Garantie, dass jede formulierte Regel in jeder Situation strikt befolgt wird. Wer eine Aktion unabhängig von der Entscheidung des Agenten zuverlässig blockieren möchte, braucht dafür einen technisch erzwungenen Hook statt einer reinen Textregel. Dasselbe Grundprinzip gilt für Coding-Agent-Instruktionen allgemein.

Wenn ein Agent eine Produktionsdatenbank technisch erreichen und löschen kann, sollte deine Sicherheitsstrategie nicht ausschließlich aus dem Satz „Bitte nicht löschen.“ bestehen.

Stattdessen brauchst du technische Grenzen: Sandbox, Dateisystemrechte, getrennte Benutzer, minimale API-Berechtigungen, eingeschränkte SSH-Rechte, Git, Backups, CI/CD, Reviews, Freigaben, isolierte Entwicklungsumgebungen. Wie du genau diese Freigaben und Sicherheitsgrenzen für Codex in der Praxis einrichtest, zeigt Codex sicher verwenden: Git, Sandbox, Backups und Freigaben (Zum Artikel). Bindest du zusätzlich MCP-Server ein, gilt dasselbe Least-Privilege-Prinzip auch dort – konkrete Absicherungsschritte zeigt MCP Server sicher betreiben: Rechte, Tools und Risiken erklärt (Zum Artikel).

Instruktionsdateien ergänzen diese Mechanismen – sie ersetzen sie nicht.

Beispiel für eine gute AGENTS.md

Eine kompakte Datei könnte so aussehen:

# AGENTS.md

## Projekt

Webanwendung mit React-Frontend, Flask-Backend und MySQL.

## Struktur

/frontend React
/backend Flask API
/tests automatisierte Tests
/docs technische Dokumentation

## Arbeitsweise

- Bestehende Architektur zuerst analysieren.
- Kleine Änderungen bevorzugen.
- Keine unnötigen Refactorings durchführen.
- Keine neuen Dependencies ohne technischen Grund hinzufügen.

## Tests

Frontend:

npm test

Backend:

pytest

Nach Änderungen müssen relevante Tests ausgeführt werden.

## Git

- Keine Änderungen direkt auf main.
- Keine bestehenden Commits verändern.
- Vor Abschluss git diff prüfen.

## Sicherheit

- Keine Secrets committen.
- Keine .env-Dateien ausgeben.
- Keine Produktionssysteme verändern.
- Keine Datenbanken löschen.
- Keine Deployments ohne ausdrückliche Anweisung.

## Dokumentation

Architektur:
docs/architecture.md

Security:
docs/security.md

Deployment:
docs/deployment.md

## Definition of Done

Eine Aufgabe gilt als abgeschlossen, wenn:

- Implementierung vollständig ist
- Tests erfolgreich sind
- keine bekannten Regressionen vorhanden sind
- Dokumentation bei Bedarf aktualisiert wurde
- git diff geprüft wurde

Eine solche Datei ist für einen Coding-Agenten wesentlich hilfreicher als allgemeine Sätze wie „Schreibe guten Code.“, „Arbeite professionell.“ oder „Vermeide Fehler.“ Diese Aussagen liefern kaum zusätzlichen Kontext.

Welche Datei solltest du 2026 verwenden?

Damit kommen wir zur eigentlichen Entscheidung.

Du verwendest ausschließlich OpenAI Codex

Nutze AGENTS.md. Das ist die natürliche Wahl für Codex. Über /init kann Codex sogar ein entsprechendes Grundgerüst für das aktuelle Projekt erzeugen.

Du verwendest ausschließlich Claude Code

Nutze CLAUDE.md. Ergänze bei größeren Projekten gegebenenfalls .claude/rules/ sowie normale technische Dokumentation.

Du verwendest Claude Code und Codex

Nutze AGENTS.md und CLAUDE.md – aber pflege die Regeln nicht doppelt. Stattdessen: @AGENTS.md in deiner CLAUDE.md.

Dein Team verwendet verschiedene Coding-Agenten

Dann würde ich AGENTS.md als gemeinsame, möglichst werkzeugunabhängige Basis verwenden. Tool-spezifische Dateien sollten anschließend lediglich als Adapter beziehungsweise Erweiterung dienen. Das reduziert Wartungsaufwand und verhindert widersprüchliche Regeln.

Die eigentliche Zukunft heißt nicht AGENTS.md oder CLAUDE.md

Die entscheidende Frage lautet langfristig vermutlich gar nicht: Welche Datei ist besser?

Sondern: Wo liegt die zentrale Wahrheit über die Arbeitsweise meines Projekts?

Ein professionelles Repository sollte seine Architektur, Sicherheitsanforderungen, Tests und Workflows nicht vollständig an ein einzelnes KI-Produkt koppeln.

Eine sinnvolle Struktur könnte deshalb so aussehen:

README.md
AGENTS.md
CLAUDE.md
ARCHITECTURE.md

docs/
├── development.md
├── testing.md
├── security.md
├── database.md
└── deployment.md

Dabei hat jede Datei eine klare Aufgabe. README.md hilft Menschen beim Einstieg. AGENTS.md liefert gemeinsame Agentenregeln. CLAUDE.md adaptiert diese Regeln für Claude Code. Die ausführliche technische Wahrheit liegt in /docs.

Damit bleibt dein Projekt verständlich – unabhängig davon, ob morgen Codex, Claude Code oder ein völlig anderer Coding-Agent daran arbeitet.

Fazit: AGENTS.md oder CLAUDE.md?

Die Antwort ist überraschend eindeutig: Für Codex brauchst du AGENTS.md. Für Claude Code brauchst du CLAUDE.md.

Wenn du beide verwendest, solltest du trotzdem nicht zwei getrennte Regelwerke pflegen. Die derzeit sauberste Lösung lautet: AGENTS.md und CLAUDE.md mit @AGENTS.md als Import in der CLAUDE.md.

Dadurch wird AGENTS.md zur gemeinsamen Quelle für Architekturregeln, Tests, Sicherheitsanforderungen und Arbeitsabläufe. Claude-spezifische Besonderheiten bleiben in CLAUDE.md. So vermeidest du doppelte Pflege, widersprüchliche Agentenanweisungen und unnötigen Kontext.

Und genau darum geht es bei guten KI-Coding-Projekten letztlich: nicht möglichst viele Regeln zu schreiben, sondern dafür zu sorgen, dass jeder Agent zur richtigen Zeit die richtigen Regeln bekommt.

Häufige Fragen zu AGENTS.md und CLAUDE.md

Liest Claude Code eine AGENTS.md automatisch?

Nein. Anthropic dokumentiert ausdrücklich, dass Claude Code CLAUDE.md verwendet, nicht AGENTS.md. Eine bestehende AGENTS.md kann jedoch per @AGENTS.md-Import in eine CLAUDE.md eingebunden werden.

Liest OpenAI Codex CLAUDE.md?

Standardmäßig nicht. Codex liest automatisch AGENTS.md beziehungsweise AGENTS.override.md, sowohl global unter ~/.codex/ als auch hierarchisch vom Git-Root bis zum Arbeitsverzeichnis. Über die Konfigurationsoption project_doc_fallback_filenames lassen sich zusätzliche Dateinamen ergänzen; eine ausdrückliche Unterstützung für CLAUDE.md dokumentiert OpenAI dabei nicht.

Kann ich AGENTS.md und CLAUDE.md gleichzeitig verwenden?

Ja. Für Projekte mit Codex und Claude Code ist das sogar sinnvoll. Die gemeinsame Konfiguration sollte jedoch möglichst nur einmal gepflegt werden.

Kann CLAUDE.md einfach AGENTS.md importieren?

Ja. Anthropic dokumentiert dafür die Zeile @AGENTS.md am Anfang der CLAUDE.md. Darunter können zusätzliche Claude-spezifische Regeln stehen.

Kann ich CLAUDE.md als Symlink auf AGENTS.md anlegen?

Ja. Unter Linux oder macOS beispielsweise mit ln -s AGENTS.md CLAUDE.md. Wenn Claude-spezifische Ergänzungen benötigt werden, ist der Import meist flexibler.

Sollte AGENTS.md ins Git-Repository?

Projektweite Regeln normalerweise ja. Dadurch erhalten alle Entwickler und Agenten dieselben Instruktionen. Persönliche Einstellungen oder vertrauliche Informationen gehören dagegen nicht hinein.

Gehören Passwörter oder API-Keys in AGENTS.md?

Nein. Niemals Secrets, Passwörter, Tokens, private Schlüssel oder Zugangsdaten in AGENTS.md, CLAUDE.md oder andere versionierte Instruktionsdateien schreiben.

Ersetzt AGENTS.md die README.md?

Nein. README.md richtet sich primär an Menschen. AGENTS.md enthält zusätzlichen Kontext und Arbeitsanweisungen für Coding-Agenten. Beide Dateien ergänzen sich.

Wie groß sollte eine AGENTS.md oder CLAUDE.md sein?

So kompakt wie möglich. Anthropic empfiehlt für CLAUDE.md unter 200 Zeilen pro Datei. Für AGENTS.md gilt sinngemäß dasselbe: eher eine Karte des Repositories als eine ausführliche Dokumentation, die besser in strukturierte Dateien unter docs/ ausgelagert wird.

Quellen und Faktencheck

Für diesen Artikel wurden insbesondere die aktuelle OpenAI-Dokumentation zu Codex und AGENTS.md, die offizielle Claude-Code-Dokumentation von Anthropic sowie die Dokumentation des offenen AGENTS.md-Formats herangezogen.

Stand: September 2026.

Weiterführende Themen

Claude Code vs. OpenAI Codex: Welcher Coding-Agent ist besser? (Zum Artikel)

Codex sicher verwenden: Git, Sandbox, Backups und Freigaben richtig einrichten (Zum Artikel)

Codex CLI unter Linux installieren und richtig nutzen (Zum Artikel)

MCP Server sicher betreiben: Rechte, Tools und Risiken erklärt (Zum Artikel)