AGENTS.md oder CLAUDE.md? Was enthalten die 592 führenden Repositories tatsächlich?

Anthropics auf KI ausgerichtete SDLC-Anleitung ordnet alle sechs Phasen der Softwarelieferung um die Coding-Agents herum an. In Phase 3 wird ein konkretes Dokument gefordert: CLAUDE.md, eine auf Repository-Ebene gespeicherte Wissensdatei, die jedes Mal aktualisiert wird, wenn ein Agent denselben Fehler wiederholt. Eine Umfrage unter den am meisten bewerteten öffentlichen Repositories untersuchte, inwieweit dieser Rat in der Praxis umgesetzt wird – das Ergebnis ist überraschend. CLAUDE.md führt in der Anzahl der Dateien, verliert aber beim Inhalt.

Die wichtigsten Zahlen

Am 8. September 2026 untersuchte ein Scanner die 592 am meisten bewerteten Repositories, die aus sechs Programmiersprachen-Rankings (TypeScript, Python, Go, Rust, Java und JavaScript, ohne Duplikate) ausgewählt wurden. Dabei wurde nach CLAUDE.md sowie mehreren damit verbundenen Dateien gesucht.

• 165 Repositories (27,9%) enthalten eine CLAUDE.md.
• Von diesen 165 enthalten 94 (57,0%) überhaupt kein Repository-Wissen. Es handelt sich dabei um Umleitungen.

Von diesen 165 verfügen 94 (57,0%) über keinerlei Kenntnisse bezüglich Repositorien. Es handelt sich dabei um Umleitungen.

209 Repositorien, das sind 35,3%, enthalten ein AGENTS.md, und 93,8% davon weisen echten Inhalt auf.

In den 132 Repositorien, in denen beide Dateien vorhanden sind, verweisen 89 auf AGENTS.md durch CLAUDE.md. Nur 10 verweisen in die andere Richtung.

Nur 5,9% haben eine .claude/settings.json-Datei, in der die Hooks für Stage 3 des Playbooks konfiguriert werden.

Substanzielle CLAUDE.md-Dateien haben eine mittlere Größe von 3.934 Bytes, wobei die größten 66.176 Bytes umfassen.

Wenn man die Umleitungen ausschließt, haben nur 12,0% der wichtigsten Repositorien ein CLAUDE.md mit Inhalt. Ein ausführliches AGENTS.md findet sich in 33,1% der Fälle.

Für alle, die das Playbook jetzt übernehmen, sind die Erkenntnisse gemischt. Die Agenten benötigen zwar eine zuverlässige, versionierte Wissensdatei, doch das Playbook bezeichnet die falsche Datei. In diesen Repositorien ist CLAUDE.md zu einer Kompatibilitätsbrücke geworden, die vor AGENTS.md liegt – einer herstellersneutralen Datei, die von jedem großen Programmieragenten gelesen wird. Die Projekte, die diese Frage bereits gelöst haben, haben ihr Wissen einmal in AGENTS.md geschrieben und einen einzeiligen Verweis hinterlassen.

Wie die Zählung erfolgte

Der Stichprobenrahmen bestand aus einem öffentlichen GitHub-Ranking-Snapshot – den 100 beliebtesten Repositorien nach Anzahl der Sterne in jeder der sechs Sprachen – die nach Entfernung doppelter Einträge auf 592 einzigartige Repositorien reduziert wurden. Von raw.githubusercontent.com wurden feste Pfadangaben unter Verwendung von HEAD abgerufen, ohne API-Schlüssel, ohne Authentifizierung und ohne Scraping. Es ging lediglich darum zu prüfen, ob eine Datei existiert und was sie enthält. Anschließend wurden alle CLAUDE.md- und AGENTS.md-Dateien heruntergeladen – insgesamt 374 Dateien aus 242 Repositorien – und von Hand gelesen.

Durch diese Lektüre zeigte sich, dass die Annahmen nicht zutrafen. Der Medianwert der CLAUDE.md-Dateien betrug lediglich zwei Zeilen Länge, sodass bereits dieser Wert für sich genommen fast nichts aussagt.

Was diese Dateien enthalten

Niemand der gängigen Muster stellt echtes Wissen dar:

• Ein Git-Symlink. Die Datei umfasst neun Bytes – lediglich den Text AGENTS.md ohne Zeilenumbruch am Ende – da Git einen Symlink als Blob speichert, der sein Ziel enthält. Beispiele hierfür sind openclaw, dify, ant-design, moby, home-assistant, superset, Stirling-PDF und nushell.
• Eine einzige Importzeile, @AGENTS.md, mit elf Bytes, die von Claude Code beim Laden verarbeitet wird. n8n, supabase, grafana, nuxt, storybook, prometheus, traefik, ruff und pdf.js funktionieren auf diese Weise.
• Ein Satz in Prosa. In lazygit handelt es sich dabei um eine Anweisung, zunächst AGENTS.md zu lesen und danach vorzugehen. Die CLI von Google Workspace formuliert dies in längeren Worten auf dieselbe Weise.

Einige Randfälle sind für jeden wichtig, der einen Klassifikator entwickelt. Docusaurus weist einen Überschriftsabschnitt auf, gefolgt von einer Import-Anweisung, und nichts weiter. Jest verweist hingegen auf .github/copilot-instructions.md. Ansible besteht aus drei Importzeilen ohne jeglichen Text. Zed verlinkt auf eine Datei mit dem Namen .rules.

Nach Ausschluss aller Dateien, deren einziger Inhalt eine Umleitung ist, weisen 71 der 592 Repositorien ein CLAUDE.md auf, das Kenntnisse über das jeweilige Repository enthält – das sind 12,0 %. Diese 71 Dateien sind echt, einige davon sogar recht umfangreich: Median 3.934 Bytes, 90. Perzentil 19.506 Bytes, Maximum 66.176 Bytes. Projekte wie bun, pytorch, swc, gstack und 3x-ui pflegen echte Betriebsanleitungen, die Build-Befehle, Repository-Karten, Testphilosophien sowie regelbasierte Vorgaben für bestimmte Verzeichnisse enthalten.

Wo die Kenntnisse tatsächlich gespeichert sind

In AGENTS.md – und mit großem Abstand. Sein Inhaltanteil beträgt 93,8 %, also 196 von 209 Dateien, im Vergleich zu 43,0 % bei CLAUDE.md. Diese Asymmetrie ist das Entscheidende. Ein Repository, das ein AGENTS.md erstellt, füllt es fast immer mit Inhalt. Ein Repository, das eher ein CLAUDE.md erstellt, baut in den meisten Fällen eine Verbindung zu einer anderen Stelle auf.

Die 132 Repositories, die beide Dateien enthalten, machen diese Richtung klar:

• In 89 davon ist CLAUDE.md der Verweis und AGENTS.md enthält den Inhalt.
• In 10 ist die Rolle umgekehrt: AGENTS.md leitet weiter und CLAUDE.md ist die eigentliche Datei. Dazu gehören Pytorch, bun, milvus, anki und litellm.
• 31 Repositories enthalten in beiden Dateien Inhalt, was bedeutet, dass derselbe institutionelle Wissenstext zweimal aufbewahrt wird.
• 2 Repositories enthalten in beiden Dateien Verweise, was auf eine dritte Datei irgendwo hinweist.

Daher fließen die Umleitungen in etwa im Verhältnis von neun zu eins zum vendor-neutralen Format. Ein einseitiges Ergebnis ist oft ein Messfehler, weshalb absichtlich nach dem gegenteiligen Fall gesucht wurde. Er existiert zwar, aber nur in geringem Maße.

Verbreitung nach Sprache

Der Unterschied zwischen den Sprachen ist groß genug, um entsprechend planen zu können. Zuerst CLAUDE.md, dann AGENTS.md:

• TypeScript: 46,5 % und 53,5 %.
• Rust: 33,3 % und 43,4 %.
• Go: 32,3 % und 37,4 %.
• Python: 25,5 % und 31,6 %.
• JavaScript: 19,0 % und 23,0 %.
• Java: 10,3 % und 22,7 %.

AGENTS.md führt in jeder Sprache. Java weist den größten Unterschied auf – Repositorys mit AGENTS.md sind mehr als doppelt so wahrscheinlich wie solche mit CLAUDE.md – und TypeScript-Projekte haben mehr als viermal so hohe Chancen auf ein CLAUDE.md wie Java-Projekte. In allen sechs Sprachen verfügen 43,2 % der führenden Repositorys über eine Datei mit Agent-Anweisungen, sei es AGENTS.md, CLAUDE.md, .cursorrules oder Copilots Anweisungsdatei. Copilots Datei ist in 9,3 % der Fälle vorhanden. Die .cursorrules-Konvention ist in dieser Gruppe fast verschwunden und kommt nur noch in 0,5 % vor – ein gutes Beispiel dafür, wie schnell ein herstellerspezifischer Brauch verschwinden kann.

Der Rest des Stage-3-Stacks

Plattformteams sollten diesen Teil sorgfältig lesen. Das Playbook verlangt mehr als nur eine Wissensdatei: Es kombiniert Wissensdateien, Fähigkeiten und Hooks, wobei Hooks die Überwachungsschicht darstellen, die während der Kompilierung gefährliche Aktionen verhindert.

Nur 35 von 592 Repositorien (5,9%) enthalten eine .claude/settings.json-Datei, und nur 32 davon (5,4%) besitzen zusätzlich eine CLAUDE.md-Datei. Die Dokumentationsdatei, die jeder schreiben kann, ist es, die von den Nutzern übernommen wurde. Die Durchsetzungsmechanismen, die tatsächlich bestimmen, was ein Agent tun darf, finden sich in etwa einem von achtzehn Repositorien. Ein Playbook, dessen Sicherheitskonzept auf Hooks beruht, beschreibt etwas, das bisher fast niemand entwickelt hat.

Beschränkungen der Daten

• Die Stichprobe umfasst öffentliche Repositorien, die nach Anzahl der Sterne sortiert sind. Solche Playbooks werden in privaten Unternehmens-Repositorien eingesetzt, die nicht sichtbar sind. Die Übernahme dort könnte höher und disziplinierter sein.
• Es handelt sich um einen einzigen Zeitpunkt, genauer gesagt vom HEAD-Standort am 8. September 2026. Die Übernahme neuer Lösungen geschieht schnell, sodass die Prozentsätze bereits nach einem Monat nicht mehr korrekt sind – dabei ist die Richtung wichtiger als das genaue Ausmaß.

Ein Datei existiert noch nicht gleichbedeutend mit praktischer Anwendung. Ein inhaltlich vollständiger CLAUDE.md zeigt lediglich an, dass jemand eine solche Datei erstellt hat. Er liefert jedoch keinerlei Beweis dafür, dass jemand sie weiterhin pflegt oder dass die Leistung der Agenten dadurch verbessert wird. Veröffentlichte Arbeiten stellen in Frage, ob solche Dateien überhaupt hilfreich für Coding-Agenten sind, und diese Messung sagt dazu nichts aus.

Die Datei settings.json ist lediglich ein Ersatz für Hooks und keine vollständige Übersicht. Alle in anderen Orten definierten Hooks bleiben unentdeckt, wodurch 5,9 % als Mindestwert angesehen wird.

Die Abgrenzung zwischen Pfeilern und inhaltlichen Elementen ist eine subjektive Entscheidung. Nach Entfernung der Überschriften, Importe und Umleitungsanweisungen blieben 120 Zeichen an überschüssigem Text übrig. Die vierzehn Dateien, die dieser Grenze am nächsten lagen, wurden manuell überprüft; die nächstliegende inhaltliche Datei, lazydocker, enthält 172 Zeichen mit echten Build-Flags. Eine Änderung der Schwellenwert führt zu einer entsprechenden Anpassung dieser Zahl. Eine weitere manuelle Überprüfung von 25 Repositorien gegen die tatsächlichen Dateien zeigte, dass Fehler in eine Richtung auftreten: Der Klassifikator gibt gelegentlich eine Umleitungsanweisung fälschlicherweise als inhaltliches Element aus, wenn diese eher wie eine Anweisung an den Agenten formuliert ist statt als Angabe darüber, wo die Dokumentation zu finden ist – wie bei zeroclaw. Daher stellt 57,0 % einen Mindestwert dar, und der tatsächliche Anteil an Pfeilern ist etwas höher.

Auch ein knapper Ausrutscher, den man zugeben sollte. Der erste Bericht besagte, dass 27,9 Prozent der führenden Repositorien CLAUDE.md übernommen hatten, und dieser Satz wäre veröffentlicht worden. Die Zwei-Sätze-Mediane verhinderte das.

Praktische Lösungen

Welches Datei sollte den Inhalt enthalten? Die Beweise sprechen für AGENTS.md, wobei CLAUDE.md auf einen Verweis reduziert wird. Die meisten Repositorien mit zwei Dateien (89 von 132) handhaben es genau so. Eine Kopie des Wissens bleibt erhalten, und Agenten, die niemals nach einem für Claude spezifischen Dateinamen suchen, können sie dennoch lesen.

Liest Claude Code AGENTS.md direkt? Nicht nach der Namenskonvention, im Gegensatz zu CLAUDE.md – und genau dieses Defizit ist der Grund für das Pointer-Muster. In der Praxis funktionieren zwei Ansätze: ein git-Link namens CLAUDE.md, der auf AGENTS.md verweist, oder die @AGENTS.md-Import-Methode. Das neue-api-Projekt warnt sogar in seinem eigenen CLAUDE.md davor, dass der Import nicht immer zuverlässig funktioniert, und empfiehlt den Agenten, die Datei selbst zu öffnen.

Ist eine Adoptionsrate von 27,9 % gut oder schlecht? Besser als erwartet für eine so junge Konvention – aber schlechter, als es das Playbook nahelegt. Zwei weitere Zahlen sagen mehr aus: 12,0 % der Repositorien enthalten CLAUDE.md-Dateien mit echtem Inhalt, und nur 5,4 % kombinieren eine solche Datei mit Durchsetzungs-Hooks.

Warum sollten 31 Repositorien beide Dateien inhaltlich beibehalten? Der Unterschied zwischen den Kopien wurde nie gemessen, was die klare nächste Forschungsfrage darstellt. Doppelte institutionelle Kenntnisse werden zu einem Risiko, sobald sich die Kopien unterscheiden, und die Tools geben keine Warnung.

Können andere das wiederholen? Ja. Die Stichprobe stammt aus einer öffentlichen Sternen-Rangliste, die Abfragen sind einfache, nicht authentifizierte HTTP-Anfragen an raw.githubusercontent.com, und der Klassifikator passt in etwa 40 Zeilen.

Eine abschließende Überprüfung für alle, die ein Repository mit einem angehängten Programmieragenten betreiben: Wurde beim letzten Mal, als ein Build-Befehl geändert wurde, auch die Wissensdatei des Agenten im selben Commit geändert, oder tauchte der veraltete Befehl erst drei Sitzungen später wieder auf?