CLAUDE.md vs AGENTS.md:welcher Agent welche Datei liest.

Was jede Datei ist

Beide sind einfaches Markdown, das ein Agent zu Beginn einer Sitzung in seinen Kontext lädt. Du schreibst Build- und Testbefehle, Code-Stil, Projektaufbau und Regeln wie „generierte Dateien nie bearbeiten“ hinein. Es sind Anweisungen, keine erzwungenen Einstellungen: Der Agent behandelt sie als Richtschnur.

• CLAUDE.md gehört zu Claude Code. Sie kann im Projektstamm liegen (./CLAUDE.md oder ./.claude/CLAUDE.md), in ~/.claude/CLAUDE.md für alle deine Projekte und in Unterordnern. Eine CLAUDE.local.md enthält private Notizen für ein Projekt.
• AGENTS.md ist ein offenes Format, beschrieben auf agents.md, eine README für Agenten. Codex, Cursor, der Coding-Agent von GitHub Copilot, Gemini CLI, Zed und viele andere lesen sie. In einem Monorepo gilt eine AGENTS.md in einem Unterordner für diesen Teil, und die nächstgelegene Datei gewinnt.

Der Inhalt ist von derselben Art. Der Unterschied ist, welches Werkzeug die Datei aufnimmt.

Was Claude Code mit AGENTS.md macht

Die Dokumentation von Claude Code beschreibt drei Fälle, ab Version 2.1.277:

• Nur eine AGENTS.md in deinem Projekt, keine CLAUDE.md: Claude Code liest die AGENTS.md.
• Beide Dateien in deinem Projekt: Claude Code liest nur die CLAUDE.md-Dateien.
• Eine CLAUDE.md, die AGENTS.md mit @AGENTS.md importiert: Claude liest die CLAUDE.md samt AGENTS.md.

Der zweite Fall überrascht die Leute. Legst du in einem Repository mit AGENTS.md eine CLAUDE.md an, auch eine winzige, liest Claude die AGENTS.md nicht mehr, es sei denn, die CLAUDE.md importiert sie. Dasselbe gilt für eine CLAUDE.local.md. Ältere Versionen von Claude Code lasen nur CLAUDE.md, deshalb bleibt der Import die sichere Wahl. Die Doku beschreibt auch eine Einstellung Project instructions in /config, damit Claude beide Dateien zusammen liest.

Nur einen Satz Anweisungen pflegen

Wähle eine Datei als maßgebliche Quelle. Zwei Wege sind dokumentiert:

1. AGENTS.md aus CLAUDE.md importieren

   Lege neben AGENTS.md eine CLAUDE.md an, deren erste Zeile @AGENTS.md ist, und ergänze darunter Claude-spezifische Anweisungen. Importe nutzen die Syntax @path, relative Pfade werden von der Datei aus aufgelöst, die sie enthält, und importierte Dateien können weitere bis zu vier Ebenen tief importieren.

2. CLAUDE.md per Symlink mit AGENTS.md verknüpfen

   Führe ln -s AGENTS.md CLAUDE.md aus, wenn du nichts Claude-Spezifisches ergänzen willst. Die Doku warnt, dass die Bearbeitungswerkzeuge von Claude nicht durch einen Symlink schreiben und dass ein eingecheckter Symlink unter Windows als einzeilige Textdatei ausgecheckt werden kann. Für ein gemeinsames Repository ist der Import daher die sicherere Wahl.

Vermeide einen dritten Ansatz: eine CLAUDE.md, die in Worten sagt „lies AGENTS.md“. Claude sieht die Datei nur, wenn es sich entscheidet, sie zu öffnen, während ein Import sie jedes Mal lädt.

Eine gemeinsame AGENTS.md

Lege in AGENTS.md ab, was jeder Agent braucht:

# AGENTS.md

## Commands
- Install: `npm ci`
- Test: `npm test`
- Lint: `npm run lint`

## Conventions
- TypeScript, strict mode. No default exports.
- Update the tests with every change.

## Do not
- Edit files under `generated/`.
- Commit without running the tests.

Halte sie kurz und konkret. Die Doku von Claude Code empfiehlt, unter etwa 200 Zeilen pro CLAUDE.md zu bleiben, weil längere Dateien Kontext kosten und weniger zuverlässig befolgt werden.

Häufige Fehler

• Zwei Dateien, die auseinanderlaufen. Eine Kopie wird aktualisiert, die andere nicht. Nimm den Import.
• Eine CLAUDE.md anlegen und die AGENTS.md verlieren. Siehe oben: Importiere sie.
• Geheimnisse in einer der Dateien. Sie werden eingecheckt und in jede Sitzung geladen.
• Vage Regeln. „Schreibe sauberen Code“ bewirkt nichts. „Führe npm test aus, bevor du sagst, dass du fertig bist“ schon.
• Widersprüchliche Regeln in der Datei eines übergeordneten Ordners und der eines Unterordners.

Diese Dateien lesen und prüfen

Beide sind normales Markdown, daher öffnet DotMD CLAUDE.md und AGENTS.md wie jede .md-Datei, mit Gliederung und einem Verlauf jeder Änderung, und zeigt, was ein Agent darin geändert hat. Lesen ist kostenlos. Siehe auch Claude Code und Codex mit DotMD.

Fragen zu CLAUDE.md und AGENTS.md

Weitere Fragen