Zum Hauptinhalt springen

AGENTS.md & Tool-übergreifende Interoperabilität

Fortgeschritten

Du kennst bereits CLAUDE.md — das Projekt-Briefing von Claude Code. Aber dein Repo wird wahrscheinlich von mehr als einem Agenten angefasst: ein Teamkollege nutzt Codex, die CI verwendet einen Coding-Bot, jemand öffnet das Repo in Cursor. AGENTS.md ist der offene Standard, den diese Tools übereinstimmend lesen, sodass du die Anweisungen deines Projekts einmal schreibst, statt eine andere Datei pro Tool zu pflegen.

What you'll learn
  • Was AGENTS.md ist und wer es betreut
  • Warum Claude Code CLAUDE.md liest und nicht AGENTS.md
  • Drei zuverlässige Wege, eine einzige Quelle der Wahrheit über alle Tools hinweg zu erhalten
  • Wie verschachtelte und globale AGENTS.md-Dateien zusammengeführt werden
  • Was in die Datei gehört — und was draußen bleiben sollte

Was AGENTS.md ist​

AGENTS.md ist eine einfache Markdown-Datei im Wurzelverzeichnis deines Repos — stell sie dir als ein README vor, das für Agenten statt für Menschen geschrieben ist. Sie sagt einem Coding-Agenten, wie das Projekt gebaut, getestet und dazu beigetragen wird. Das Format hat keine erforderlichen Felder: Agenten lesen einfach den Fließtext.

Es ist ein offener Standard, der von der Agentic AI Foundation (AAIF) unter der Linux Foundation betreut wird, und Mitte 2026 wird er von über 60.000 Open-Source-Projekten genutzt und von mehr als 30 Tools gelesen — darunter OpenAI Codex, Googles Jules und Gemini CLI, Cursor, Windsurf, Devin, Zed, Warp, Aider, goose, Amp und der Coding-Agent von GitHub Copilot.

What you'll learn
  • AGENTS.md ist eine Konvention, keine Laufzeitumgebung: jedes Tool entscheidet selbst, wie es die Datei findet, zusammenführt und einbindet.
  • Es wird kein Schema erzwungen — klarer Fließtext schlägt starre Struktur.
  • Es ergänzt dein README; es ersetzt es nicht.

Der Haken bei Claude Code​

Hier ist der Teil, über den die Leute stolpern: Claude Code liest CLAUDE.md, nicht AGENTS.md. Wenn dein Repo nur eine AGENTS.md hat, ignoriert Claude Code sie standardmäßig. Das ist kein Bug — es ist älter als der Standard — aber es bedeutet, dass ein Multi-Tool-Repo eine bewusste Sync-Strategie braucht, sonst driften deine Anweisungen unbemerkt auseinander.

Watch out
  • Geh nicht davon aus, dass Claude Code auf AGENTS.md zurückgreift — es liest sie nicht automatisch.
  • Zwei von Hand gepflegte Dateien (CLAUDE.md und AGENTS.md) werden auseinanderdriften. Wähle eine Quelle der Wahrheit.
  • Überprüfe das aktuelle Verhalten in der offiziellen Memory-Dokumentation, bevor du dich auf eine Fallback-Behauptung verlässt.

Eine einzige Quelle der Wahrheit erhalten​

Drei Muster halten CLAUDE.md und AGENTS.md synchron, ohne Inhalte zu duplizieren. Wähle nach der Plattform deines Teams.

Guided walkthrough1 of 3
  1. Mach CLAUDE.md zu einem Symlink auf AGENTS.md. Claude Code folgt Symlinks und liest das Ziel Byte für Byte — eine echte Datei, keine Merge-Logik. Vorbehalt: Unter Windows erfordert das Erstellen eines Symlinks den Entwicklermodus oder Adminrechte, daher bevorzugen plattformübergreifende Teams möglicherweise die Import-Methode.

CLAUDE.md auf den gemeinsamen Standard symlinken (macOS / Linux)

ln -s AGENTS.md CLAUDE.md

Oder halte eine einzeilige CLAUDE.md, die ihn importiert

@AGENTS.md
Pro tip
  • Symlink, wenn dein gesamtes Team auf macOS/Linux ist — das ist am wenigsten zu pflegen.
  • Verwende @import, wenn Windows-Mitwirkende dabei sind.
  • Committe, was auch immer du wählst, damit das gesamte Team dasselbe Verhalten erhält.

Wie verschachtelte und globale Dateien zusammengeführt werden​

Die mächtigeren Agenten behandeln AGENTS.md hierarchisch — dasselbe mentale Modell wie die CLAUDE.md-Memory-Hierarchie. Codex zum Beispiel läuft von einer globalen Datei in deinem Home-Verzeichnis hinunter durch die Git-Wurzel bis zu deinem aktuellen Ordner und konkateniert dabei:

Dateien, die näher an der Arbeit sind, gewinnen, weil sie zuletzt konkateniert werden und frühere Vorgaben überschreiben. So erbt eine services/payments/AGENTS.md die Anweisungen aus der Repo-Wurzel und fügt Regeln hinzu, die nur innerhalb dieses Service gelten — platziere spezialisierte Vorgaben so nah wie möglich am spezialisierten Code.

Interoperabilität auf einen Blick
Drücke Enter oder die Leertaste, um die Karte umzudrehen. Nutze die Pfeiltasten links und rechts, um zwischen den Karten zu wechseln.Begriff angezeigt.
1 / 5

Was hineingehört​

Dieselbe Disziplin wie bei einer guten CLAUDE.md — der Standard schlägt lediglich ein paar gängige Abschnitte vor:

  • Projektübersicht — was das ist, in zwei Sätzen.
  • Build- & Test-Befehle — wie man ausführt, testet und lintet.
  • Code-Stil — Konventionen, die ein Agent nicht ableiten kann.
  • Testanweisungen — was "fertig" bedeutet.
  • Sicherheitsüberlegungen — was niemals angefasst oder committet werden darf.
  • Commit- / PR-Richtlinien — Nachrichtenformat, Branch-Regeln.
Watch out
  • Agenten folgen der Datei wörtlich — veraltete oder visionäre Anweisungen schaden aktiv, genau wie bei CLAUDE.md.
  • Halte es kurz und wahr; beschreibe, wie das Projekt heute funktioniert.
  • Committe niemals Secrets; verweise auf große Dokumente, statt sie einzufügen.

Überprüfe dich selbst​

Überprüfe dich selbst

0/3
  1. Liest Claude Code AGENTS.md automatisch?
  2. Dein Team ist vollständig auf macOS und Linux. Was ist der wartungsärmste Weg, eine einzige Anweisungsdatei über Claude Code und Codex hinweg zu teilen?
  3. Wenn Agenten eine globale, eine Repo-Wurzel- und eine Unterverzeichnis-AGENTS.md zusammenführen, welche gewinnt bei Konflikten?
Key takeaways
  • AGENTS.md ist der offene, von der Linux Foundation betreute Standard, den über 30 Coding-Agenten lesen — ein README für Agenten.
  • Claude Code liest CLAUDE.md, nicht AGENTS.md, daher müssen Multi-Tool-Repos sie synchron halten.
  • Symlinke CLAUDE.md → AGENTS.md unter Mac/Linux, oder verwende einen einzeiligen @AGENTS.md-Import für plattformübergreifende Teams.
  • Verschachtelte Dateien werden global → Wurzel → Unterverzeichnis zusammengeführt, wobei die nächstgelegene Datei gewinnt.
  • Fülle sie wie eine großartige CLAUDE.md: Übersicht, Build-/Test-Befehle, Konventionen, Sicherheit und Leitplanken — kurz und wahr.

Weiter​

Quellen & weiterführende Literatur​