Warum Shopify Claude Code wegen AGENTS.md verbieten könnte

Shopify-Chef Tobi Lütke droht nicht wegen eines bloßen Dateinamens mit einem Verbot von Claude Code. Sein Vorwurf lautet: Wenn mehrere KI-Programmierwerkzeuge am selben Code arbeiten, aber jeweils eigene Anweisungssysteme verwenden, entsteht ein gefährliches Regelchaos – von Lütke als „Split Brain“ bezeichnet. 415

Für eine einzelne Entwicklerin oder einen einzelnen Entwickler mag es verkraftbar sein, zusätzlich eine CLAUDE.md zu pflegen. In einem Unternehmen mit großen Teams und einem umfangreichen Monorepo wird daraus jedoch laufender Verwaltungsaufwand – und ein potenzielles Sicherheits- und Qualitätsproblem.

Was Shopify an Claude Code kritisiert

AGENTS.md ist eine einfache Markdown-Datei im Repository. Sie kann festhalten, wie der Code gebaut und getestet wird, welche Stilregeln gelten, welche Verzeichnisse nicht verändert werden dürfen und welche Vorgaben für Beiträge oder Pull Requests gelten. Der entscheidende Vorteil: Die Anweisungen liegen zusammen mit dem Code in der Versionsverwaltung und sind nicht an ein bestimmtes Entwicklerwerkzeug gebunden. 192931

Claude Code setzt laut seiner Dokumentation dagegen auf CLAUDE.md, .claude/rules, projektspezifische Skills, Hooks und Einstellungen. Diese Dateien werden im aktuellen Verzeichnis und teilweise in übergeordneten Verzeichnissen gesucht – es gibt also ein eigenes, rekursiv aufgebautes Anweisungssystem. 2

Das funktioniert, solange ein Team ausschließlich Claude Code nutzt. Shopify verwendet jedoch – wie viele größere Entwicklungsorganisationen – mehrere KI-Coding-Tools, darunter Codex, Cursor, Gemini CLI oder GitHub Copilot. Liest ein Tool AGENTS.md, während Claude Code nur CLAUDE.md berücksichtigt, können zwei Agenten im selben Verzeichnis unterschiedliche Build-Befehle, Programmierregeln oder Grenzen für Änderungen sehen.

Warum doppelte Dokumentation im Monorepo teuer wird

Unternehmen haben dann im Wesentlichen vier Möglichkeiten:

• AGENTS.md und CLAUDE.md parallel im Repository pflegen;
• die Dateien in relevanten Unterverzeichnissen ebenfalls doppelt anlegen;
• beide Anweisungsketten bei jeder Änderung synchron halten; und
• Prüfungen oder eigene Werkzeuge entwickeln, die Abweichungen erkennen.

Eine vergessene Aktualisierung wäre nicht nur ein Dokumentationsfehler. Ein Agent könnte bereits den neuen Testbefehl kennen, während ein anderer noch einen veralteten verwendet. Ein Tool könnte eine geschützte Verzeichnisstruktur erkennen, ein anderes nicht. Das kann zu widersprüchlichen Codeänderungen, Reviews und Erwartungen im Team führen – genau das „Split-Brain“-Problem, auf das Lütke hingewiesen hat. 47

Ein öffentliches Feature-Request für Claude Code beschreibt die konkrete Reibung: Befindet sich in einem geklonten Repository eine AGENTS.md, kann Claude Code deren Kontext ignorieren. Entwicklerinnen und Entwickler müssen dann manuell eine CLAUDE.md anlegen und die Anweisungen duplizieren. 12

Wie AGENTS.md zum Interoperabilitäts-Symbol wurde

AGENTS.md entstand aus einer branchenübergreifenden Zusammenarbeit, an der unter anderem Google, OpenAI, Sourcegraph, Factory und Cursor beteiligt waren. 1931

Am 9. Dezember 2025 übertrugen OpenAI und Anthropic AGENTS.md sowie weitere Infrastruktur für KI-Agenten an die von der Linux Foundation unterstützte Agentic AI Foundation. Ziel dieser Stiftung ist eine neutrale Verwaltung offener und interoperabler Agent-Technologien – statt der Kontrolle durch einen einzelnen kommerziellen Anbieter. 2829

AGENTS.md ist damit zwar kein verpflichtender technischer Standard. Die Verbreitung verleiht der Konvention aber erhebliches Gewicht: Nach Angaben der Linux Foundation wurde sie bereits von mehr als 60.000 Open-Source-Projekten und Agent-Frameworks übernommen. Genannt werden unter anderem Codex, Cursor, Devin, Factory, Gemini CLI, GitHub Copilot, Jules und VS Code. 31

Für Unternehmen kann die Datei deshalb als gemeinsame Portabilitätsschicht dienen: Dauerhafte Projektregeln werden einmal im Repository abgelegt und können von mehreren Werkzeugen genutzt werden.

Welche Lösungen Anthropic derzeit anbietet

Die dokumentierten Ausweichlösungen binden die gemeinsame Datei an die native Konfiguration von Claude Code. Eine Möglichkeit besteht darin, AGENTS.md aus einer CLAUDE.md heraus zu importieren. Daneben werden je nach Umgebung symbolische Links oder andere Konfigurationsbrücken genannt. 69

Diese Ansätze können das unmittelbare Problem reduzieren, sind aber keine gleichwertige native Unterstützung. Sie erfordern zusätzliche Einrichtung in jedem Repository und überlassen den Teams Fragen zu Importen, Prioritäten, Geltungsbereichen und Aktualisierungen. Symbolische Links können außerdem je nach Betriebssystem, Git-Konfiguration, Entwicklungsumgebung, Container oder Unternehmensrichtlinie unterschiedlich funktionieren.

Anthropics Mitarbeiter Thariq erklärte in der öffentlichen Diskussion, Claude Code solle stärker konfigurierbar werden. Dazu gehöre auch, die Nutzung von AGENTS.md oder Änderungen an anderen System-Prompt-Einstellungen zu erleichtern. 15 Das vorliegende Material belegt jedoch keinen eindeutigen technischen oder geschäftlichen Grund dafür, warum Claude Code die Datei bislang nicht nativ erkennt. Aussagen über ein bestimmtes Motiv wären daher Spekulation.

Der scheinbare Widerspruch bei Anthropic

Der Streit wirkt auch deshalb bemerkenswert, weil Anthropic Teil des weiteren Agentic-AI-Foundation-Ökosystems ist, während Claude Code bei seinen dokumentierten Projektkonventionen weiterhin auf Anthropic-eigene Dateien setzt. 22829

Das bedeutet nicht automatisch, dass Anthropic offene Standards ablehnt. Ein Anbieter kann einen offenen Grundstandard unterstützen und zugleich proprietäre Erweiterungen für Funktionen behalten, die speziell zu seinen Modellen oder Produkten gehören. Für Unternehmenskunden zählt allerdings vor allem die Praxis: Müssen zentrale Projektanweisungen vor der Nutzung durch ein bestimmtes Tool umgeschrieben oder überbrückt werden, bleibt die Interoperabilität eingeschränkt.

Was der Konflikt für KI-Entwicklerwerkzeuge bedeuten könnte

Eine wiederkehrende Konfigurationssteuer

Jede anbieterspezifische Anweisungsstruktur verursacht zusätzliche Arbeit: doppelte Dateien, Synchronisationsprüfungen, Migrationsskripte und Tests. Je mehr Coding-Agenten ein Unternehmen parallel einsetzt, desto größer wird dieser laufende Aufwand.

Mehr Druck gegen Vendor Lock-in

In Repository-Anweisungen steckt oft wertvolles Wissen über Arbeitsabläufe, Sicherheitsgrenzen und Teamkonventionen. Ist dieses Wissen am besten im Format eines einzelnen Anbieters nutzbar, wird der Wechsel zu einem anderen Tool oder der parallele Einsatz mehrerer Werkzeuge teurer. Ein gemeinsames Format senkt diese Wechselkosten.

Wahrscheinlich ein Modell mit zwei Ebenen

Die praktikabelste Lösung muss nicht darin bestehen, jede proprietäre Konvention abzuschaffen. Denkbar ist ein gemeinsamer Kern wie AGENTS.md für portable Projektregeln, ergänzt durch CLAUDE.md oder andere Dateien mit optionalen, anbieterspezifischen Funktionen. So könnten Anbieter ihre Produkte differenzieren, ohne den grundlegenden Projektkontext einzuschließen.

Großkunden werden zu Standardsetzern

Lütkes Reaktion zeigt, wie aus einer kleinen Kompatibilitätsforderung eine zentrale Produktanforderung werden kann. Wenn Unternehmen wie Shopify die Unterstützung mehrerer Anweisungsformate zur Voraussetzung für den Einsatz machen, müssen Anbieter Interoperabilität möglicherweise als Teil ihrer Enterprise-Tauglichkeit behandeln – und nicht mehr als freiwilliges Community-Extra.

Fazit

Shopify stellt Claude Code nicht deshalb infrage, weil CLAUDE.md grundsätzlich schlechter wäre als AGENTS.md. Das Problem ist der proprietäre Standard in einer Umgebung, in der viele Entwicklerinnen und Entwickler mehrere Agenten an derselben Codebasis einsetzen.

Die breite Verbreitung von AGENTS.md, die Verwaltung unter dem Dach der Linux Foundation und die Unterstützung durch zahlreiche Coding-Tools machen die Datei zu einer glaubwürdigen gemeinsamen Grundlage. 2931 Imports und symbolische Links können als Übergangslösung dienen, verlagern den Integrationsaufwand aber auf jedes einzelne Unternehmen.

Hinter dem Streit um zwei Markdown-Dateien steht daher eine größere Marktfrage: Werden KI-Coding-Agenten zu interoperabler Entwicklungsinfrastruktur – oder zu geschlossenen Plattformen, deren Projektwissen für jedes Werkzeug neu angepasst werden muss?