Claude Code liest jetzt AGENTS.md als Rückfalloption
Fehlt CLAUDE.md, übernimmt Claude Code nun Projektanweisungen aus AGENTS.md – und erspart damit in vielen Repositories eine zweite Regeldatei.
Anthropic hat Claude Code um eine kleine, aber praktische Kompatibilitätsfunktion erweitert: Findet das Werkzeug keine CLAUDE.md, sucht es nun nach AGENTS.md und liest die dort hinterlegten Projektanweisungen. Der Eintrag erschien am 18. September 2026 im offiziellen Claude-Code-Changelog; die Änderung ist auch über das Changelog im GitHub-Repository nachvollziehbar.
Damit kann Claude Code eine bereits vorhandene, allgemein benannte Anweisungsdatei verwenden. Das ist besonders dann nützlich, wenn ein Repository seine Konventionen nicht eigens für Claude Code, sondern als gemeinsame Arbeitsgrundlage für Coding-Agenten dokumentiert. Die entscheidende Logik ist einfach: CLAUDE.md hat Vorrang. Nur wenn sie nicht vorhanden ist, wird AGENTS.md zur Anlaufstelle.
Was sich mit dem Update ändert
Vor der Änderung brauchte Claude Code seine projektspezifischen Hinweise in CLAUDE.md. Ein Repository, das dieselben Regeln bereits in AGENTS.md pflegte, musste sie für Claude Code zusätzlich bereitstellen oder dem Werkzeug auf anderem Weg mitteilen. Nun erkennt Claude Code die vorhandene Datei automatisch, solange keine CLAUDE.md die spezifische Konfiguration übernimmt.
Neu ist also nicht das Konzept dauerhafter Projektanweisungen. Neu ist die zusätzliche Fundstelle. Das wirkt unspektakulär, trifft aber einen häufigen Reibungspunkt: Regeln gehören möglichst nahe an den Code, sollen versioniert werden und dürfen bei Änderungen nicht in mehreren fast identischen Dateien auseinanderlaufen.
Ein typisches Repository kann in AGENTS.md beispielsweise festhalten, welcher Befehl die Tests startet, welches Paketverwaltungswerkzeug vorgesehen ist, welche Verzeichnisse generiert werden oder welche Formatierungsregeln gelten. Fehlt CLAUDE.md, kann Claude Code diese Hinweise nun direkt berücksichtigen. Der Einstieg in ein bereits vorbereitetes Projekt wird dadurch kürzer, weil die grundlegenden Konventionen nicht bei jeder Sitzung erneut in einen Prompt kopiert werden müssen.
Eine klare Reihenfolge statt zweier konkurrierender Dateien
Die Formulierung im Changelog enthält eine wichtige Einschränkung: Claude Code liest AGENTS.md, wenn keine CLAUDE.md existiert. Die beiden Dateien bilden damit keine gleichrangigen, automatisch zusammengeführten Quellen. AGENTS.md ist die Rückfalloption, nicht ein zusätzlicher Regelstapel neben CLAUDE.md.
Diese Priorität verhindert eine naheliegende Mehrdeutigkeit. Würden beide Dateien ohne klar erkennbare Reihenfolge verarbeitet, könnten widersprüchliche Vorgaben entstehen: Die eine Datei verlangt einen vollständigen Testlauf, die andere nur einen gezielten Test; die eine nennt ein Formatierungswerkzeug, die andere ein abweichendes Kommando. Durch den Rückgriff bei fehlender CLAUDE.md bleibt erkennbar, welche Datei die maßgebliche Rolle übernimmt.
Für ein Repository ergibt sich daraus eine einfache Entscheidung. Allgemeine, werkzeugunabhängige Regeln können in AGENTS.md stehen. Benötigt Claude Code eigene Hinweise, kann das Projekt stattdessen eine CLAUDE.md bereitstellen. Wer bereits beide Dateien führt, sollte nicht davon ausgehen, dass Claude Code ihre Inhalte automatisch kombiniert: Nach der beschriebenen Changelog-Regel kommt AGENTS.md gerade dann zum Einsatz, wenn CLAUDE.md fehlt.
Gemeinsame Regeln ohne Kopie pflegen
Der unmittelbarste Nutzen liegt in Repositories, die AGENTS.md schon als gemeinsame Beschreibung ihrer Entwicklungsumgebung verwenden. Dort entfällt die Notwendigkeit, identische Hinweise zusätzlich in einer Claude-spezifischen Datei abzulegen. Das reduziert nicht nur eine Datei, sondern vor allem mögliche Abweichungen zwischen zwei Kopien.
Angenommen, ein Projekt wechselt den Befehl für seine Prüfungen. Bei zwei getrennten Regeldateien müsste diese Änderung an beiden Stellen korrekt nachgezogen werden. Bleibt eine Kopie veraltet, kann ein Agent den falschen Befehl ausführen. Mit einer gemeinsamen AGENTS.md gibt es für die übergreifenden Angaben nur noch eine gepflegte Stelle, die Claude Code nun ebenfalls findet.
Das eignet sich vor allem für stabile Repository-Fakten: die verwendeten Installations- und Testbefehle, feste Grenzen zwischen Quellcode und generierten Dateien, Namenskonventionen oder kurze Hinweise zur Verzeichnisstruktur. Solche Angaben beschreiben das Projekt und nicht die Eigenheiten eines bestimmten Assistenten. Genau deshalb profitieren sie von einer neutral benannten Datei.
Die Änderung macht CLAUDE.md allerdings nicht überflüssig. Sobald Anweisungen ausschließlich für Claude Code gedacht sind, bleibt die spezifische Datei sinnvoll. Dazu können besondere Hinweise für den Umgang mit einem Teil des Projekts oder bewusst abweichende Präferenzen gehören. Die neue Unterstützung eröffnet eine Wahl zwischen gemeinsamer und gezielter Konfiguration; sie zwingt Repositories nicht zu einer Umbenennung.
Beispiel: Ein Repository macht seine Konventionen auffindbar
Eine nützliche AGENTS.md muss kein langes Handbuch sein. Sie sollte vor allem Angaben enthalten, die Claude Code bei einer konkreten Codeänderung tatsächlich benötigt. Ein kompakter Inhalt könnte etwa so aussehen:
Technisches Detail: - Abhängigkeiten mit dem im Repository festgelegten Paketbefehl installieren.; - Vor Änderungen die Hinweise im betroffenen Unterverzeichnis lesen.; - Nach einer Änderung die passenden Tests und die Formatprüfung ausführen.; - Generierte Dateien nicht direkt bearbeiten..
Die Formulierungen zeigen das Prinzip, sollten in einem echten Projekt aber durch die tatsächlichen Befehle und Verzeichnisse ersetzt werden. Eine Anweisung wie „Tests ausführen“ ist weniger hilfreich als der konkrete, im Repository gültige Testbefehl. Ebenso sollte „generierte Dateien“ durch die betreffenden Pfade oder Dateimuster präzisiert werden, wenn diese Information feststeht.
Öffnet Claude Code ein solches Repository und findet keine CLAUDE.md, kann es nun auf diese Regeln zurückgreifen. Das ersetzt nicht die jeweilige Aufgabe im Prompt: Die gewünschte Änderung muss weiterhin beschrieben werden. Die Datei liefert vielmehr den beständigen Projektkontext, während der Prompt den aktuellen Auftrag enthält. So bleibt die einzelne Anfrage kurz, ohne dass wiederkehrende Konventionen verloren gehen.
Gute Anweisungen benennen überprüfbare Handlungen
Der neue Dateifund lohnt sich besonders, wenn die gespeicherten Hinweise konkret formuliert sind. „Schreibe guten Code“ gibt einem Coding-Agenten kaum Orientierung. „Führe nach Änderungen in diesem Modul den zugehörigen Testbefehl aus“ beschreibt dagegen eine erkennbare Handlung. Noch stärker wird der Hinweis, wenn er den tatsächlichen Befehl und den betroffenen Pfad nennt.
Hilfreich ist außerdem eine Trennung zwischen Projektfakten und dem jeweiligen Arbeitsauftrag. In AGENTS.md gehören wiederkehrende Informationen: Aufbau des Repositorys, Befehle, Konventionen und feste Einschränkungen. Die Aufforderung, heute eine bestimmte Funktion zu ändern, gehört in den aktuellen Prompt. Diese Aufteilung verhindert, dass die dauerhafte Datei zu einer Sammlung vergangener Einzelaufgaben anwächst.
Widersprüche sollten ebenfalls vermieden werden. Weil CLAUDE.md und AGENTS.md nach der beschriebenen Logik alternative Fundstellen sind, können zwei unterschiedlich gepflegte Fassungen zu überraschendem Verhalten führen, sobald eine Datei hinzugefügt oder entfernt wird. Wer von CLAUDE.md auf die gemeinsame Konvention wechseln möchte, sollte die weiterhin gültigen Angaben bewusst nach AGENTS.md übernehmen und die alte Datei nicht als unbemerkte Konkurrenz liegen lassen.
Auch knappe Erläuterungen zu Ausnahmen sind wertvoll. Ein pauschales Verbot wie „Dateien in diesem Ordner nie ändern“ kann korrekt sein, doch der Grund oder die zuständige Quelle macht die Regel robuster: etwa, dass der Ordner bei jedem Build neu erzeugt wird und Änderungen deshalb an der Vorlage erfolgen müssen. So lässt sich die Anweisung auf ähnliche Aufgaben übertragen, ohne unnötig breit zu werden.
- Claude Code erwartet Projektanweisungen in CLAUDE.md.
- Bereits vorhandene AGENTS.md-Regeln erfordern eine zusätzliche Fassung.
- Ohne CLAUDE.md sucht Claude Code nach AGENTS.md.
- Gemeinsame Repository-Regeln können ohne Claude-spezifische Kopie dienen.
Wo CLAUDE.md weiterhin die bessere Wahl ist
AGENTS.md bietet sich an, wenn dieselben Repository-Regeln für verschiedene Coding-Agenten gelten sollen. CLAUDE.md bleibt passend, wenn ein Projekt Claude Code bewusst anders anleiten möchte. Die Prioritätsregel erlaubt diese Spezialisierung, ohne die allgemeine Konvention abzuschaffen.
Ein Beispiel ist ein Repository mit einer neutralen AGENTS.md, deren Hinweise von mehreren Werkzeugen gelesen werden. Soll Claude Code für ein bestimmtes Projekt eine abweichende Anweisung erhalten, kann eine CLAUDE.md diese Rolle übernehmen. Nach dem Changelog ist dann nicht mit einem automatischen Ergänzen der allgemeinen Datei zu rechnen; die Claude-spezifische Datei ist die gefundene Vorgabe.
Deshalb sollte die Wahl nicht davon abhängen, welcher Dateiname moderner wirkt, sondern wem die Regeln gelten. Sind sie Bestandteil des Repositorys und unabhängig vom Werkzeug, spricht viel für AGENTS.md. Sind sie ausdrücklich auf Claude Code zugeschnitten, ist CLAUDE.md eindeutiger. Für viele Projekte dürfte die beste Lösung eine einzige, bewusst gewählte Datei sein statt zweier nahezu gleicher Fassungen.
Was das Update nicht verändert
Die Meldung beschreibt eine Änderung daran, wo Claude Code Projektanweisungen findet. Sie führt kein neues Modell, keine neue API und keinen eigenen kostenpflichtigen Dienst für AGENTS.md ein. Auch ein zusätzliches Integrationspaket ist für den beschriebenen Rückgriff nicht erforderlich. Entscheidend ist die Datei im Repository und das Fehlen einer CLAUDE.md.
Ebenso macht die Unterstützung aus allgemeinen Texten keine automatisch richtigen Projektregeln. Veraltete Befehle bleiben veraltet, unklare Formulierungen bleiben unklar und widersprüchliche Vorgaben bleiben problematisch. Der Gewinn entsteht dadurch, dass Claude Code die vorhandene Konvention erkennt; die Qualität des Inhalts bestimmt weiterhin, wie brauchbar der gelieferte Kontext ist.
Für die Anwendung ist daher keine neue Syntax nötig. Markdown eignet sich für kurze Überschriften, Listen und Codeblöcke mit Befehlen. Entscheidend sind konkrete Angaben, nicht eine besondere Formatvorlage. Projekte können ihre Datei so knapp halten, wie es ihre Struktur erlaubt, und nur jene Regeln aufnehmen, die bei wiederkehrenden Änderungen tatsächlich helfen.
Warum die kleine Änderung relevant ist
Coding-Agenten arbeiten zuverlässiger mit auffindbarem Projektkontext. Bisher konnte derselbe Inhalt je nach Werkzeug unter einem anderen Dateinamen erwartet werden. Anthropics Ergänzung reduziert diese Trennung zumindest für den Fall, dass ein Repository AGENTS.md verwendet und keine Claude-spezifische Datei angelegt hat.
Der praktische Fortschritt besteht deshalb weniger in einer neuen Fähigkeit des Agenten als in besserer Anschlussfähigkeit an bestehende Repositories. Eine bereits gepflegte Regeldatei wird für Claude Code nutzbar, doppelte Inhalte können entfallen und die bewusste Spezialisierung über CLAUDE.md bleibt erhalten.
Wer das Update nutzen möchte, braucht lediglich die Rollen der Dateien sauber zu wählen: AGENTS.md für gemeinsame Projektregeln oder CLAUDE.md für eine gezielte Claude-Code-Konfiguration. Fehlt Letztere, kann Claude Code seit dem dokumentierten Update automatisch auf die allgemeine Datei zurückgreifen. Genau diese überschaubare Änderung macht aus einer Dateinamensfrage eine klare Prioritätsregel.