Ihre AGENTS.md ist jetzt Ihr Wettbewerbsvorteil: Was in Produktionsdateien gehört

Als create-next-app vor drei Tagen AGENTS.md als Standard-Scaffolding einführte, hörte die Framework-Wahl auf, zu differenzieren. Der Inhalt dieser Datei ist jetzt das Einzige, was einen funktionierenden Agent-Stack von einem defekten trennt.

Sechs Monate lang signalisierte eine vorhandene AGENTS.md, dass das Team einen Vorsprung hatte. Seit dem 2026-04-28 liefert jedes neue Next.js-Projekt eine mit. Das Signal ist weggefallen. Was in der Datei steht, ist das neue Signal.

Viele Engineering-Führungskräfte behandeln AGENTS.md wie Dokumentation. Tatsächlich ist es eine Laufzeit-Konfigurationsdatei, die das Modell bei jedem Aufruf lädt. Dieser Artikel geht durch die empirische Studie von Augment Code, die 100-bis-150-Zeilen-Regel, die darüber entscheidet, ob die Datei hilft oder schadet, sowie das Template-Muster, das in Produktions-Client-Repositories verwendet wird.

Was sich am File-Contract geändert hat

• Next.js 16.2 liefert AGENTS.md als Standard-Scaffolding (veröffentlicht am 2026-04-28). Jedes neue Starter-Projekt auf Vercel erbt sie.
• Die AuggieBench-Studie von Augment Code (2026-04-23): Dateien zwischen 100 und 150 Zeilen erzielen die besten Ergebnisse. Über 150 Zeilen kehren sich die Gewinne um.
• Dieselbe Datei kann die Bugfix-Genauigkeit um 25 % verbessern und die Feature-Vollständigkeit um 30 % senken, je nach Aufgabe. Das Abschnittsdesign ist wichtiger als die Gesamtlänge.
• AGENTS.md ist die einzige Dokumentationsoberfläche mit 100 % Discovery-Rate. Verwaiste _docs/-Ordner liegen unter 10 %.
• Der neue Vorteil liegt in prozeduralen Workflows, Entscheidungstabellen und einzeiligen reaktiven Regeln. Nicht in Architektur-Überblicken oder gestapelten Warnungen.

Vor drei Tagen hörte AGENTS.md auf, zu differenzieren

Next.js 16.2 erschien am 2026-04-28 mit AGENTS.md als Standarddatei im create-next-app-Template. Vercel verteilt das Scaffolding an jedes neue Starter-Projekt. Die Datei, die früher zeigte, dass ein Team voraus war, liegt jetzt im leeren Paket.

Die Verschiebung in der Debatte ist der eigentliche Punkt. Vor sechs Monaten lautete die Frage, ob ein Team überhaupt eine AGENTS.md hatte. Diese Woche lautet sie: Was steht drin? Einkäufer, die Entwicklungspartner bewerten, brauchen ein neues Scoring-Kriterium, denn das binäre Signal ist verschwunden.

Zwei parallele Signale verstärken diesen Wandel. Matt Pococks Repository mattpocock/skills erreichte in 85 Tagen 41.000 Sterne, und das Repo ist sein .claude-Ordner, verbatim gepusht. Menschen starten andere Leute's Agent-Configs, so wie sie früher Frameworks gestartet haben. So sieht Kommodifizierung aus.

Garry Tans gstack-Repository, in derselben Woche veröffentlicht, überschritt 23.000 Sterne in sieben Tagen. Tan hat damit 600.000 Zeilen Produktionscode in 60 Tagen ausgeliefert. Das Repo enthält 31 Markdown-Skill-Dateien. Ein Framework liegt nicht darunter.

Wenn Ihr Einkaufsteam eine Methode sucht, KI-Readiness in Vendor-Evaluierungen zu bewerten, erklärt webvise das Scoring-Schema aus Client-Projekten.

Die 100-bis-150-Zeilen-Regel, empirisch belegt

Augment Code veröffentlichte am 2026-04-23 die erste empirische Studie zur Inhaltsqualität von AGENTS.md-Dateien. Autor Slava Zhenylenko zog Dutzende AGENTS.md-Dateien aus Augments Monorepo. Jede Datei durchlief die AuggieBench-Eval-Suite zweimal: einmal mit und einmal ohne die Datei. Die Ausgabe wurde gegen den Golden PR bewertet, den Menschen gemergt hatten.

Das Kernergebnis: Die besten Dateien erzeugten einen Qualitätssprung, der einem Upgrade von Haiku auf Opus entspricht. Die schlechtesten produzierten Ausgaben schlechter als gar keine AGENTS.md. Dasselbe Engineering-Team, dasselbe Modell, dieselbe Aufgabe. Die Datei entschied den Unterschied.

Der optimale Bereich war eng. Dateien zwischen 100 und 150 Zeilen, ergänzt durch eine kleine Menge fokussierter Referenzdokumente, die bei Bedarf geladen werden, erzielten in mittelgroßen Modulen mit etwa 100 Core-Dateien Verbesserungen von 10 bis 15 % über alle Metriken. Jenseits von 150 Zeilen kehrten sich die Gewinne um.

Tans eigenes Eingeständnis deckte sich mit dem Befund. Seine CLAUDE.md hatte 20.000 Zeilen, mit jeder Eigenheit, jedem Muster, jeder Erkenntnis in einer einzigen Datei. Claude Code selbst meldete den Ballast. Die Lösung waren rund 200 Zeilen Verweise, mit dem eigentlichen Inhalt in Skills, die bei Bedarf geladen werden.

Das Template für webvise-Client-Repos liegt innerhalb von Augments empfohlenem Bereich. Client-Repository-Namen werden nicht veröffentlicht, aber das Betriebsmuster zählt: eine kompakte Einstiegsdatei, projektspezifische Platzhalter und Skills, die erst extrahiert werden, wenn das Team ein wiederkehrendes Problem gelöst hat.

Discovery-Raten aus Augments Traces über Hunderte von Sessions erklären, warum die Platzierung genauso wichtig ist wie der Inhalt:

AGENTS.md ist die einzige Oberfläche mit zuverlässiger Discovery. Was gesehen werden muss, gehört dorthin oder wird von dort referenziert. Inhalte in eine referenzierte Position zu verlagern bringt mehr als weitere Dokumentation zu schreiben.

Was die Datei stärkt, und was sie zerstört

Augments Traces wurden nach Inhaltstyp aufgeschlüsselt. Die Muster, die die Ausgabe verbesserten, und jene, die sie ruinierten, sind nicht symmetrisch.

Was funktioniert

• Prozedurale Workflows. Nummerierte Mehrschrittabläufe waren das stärkste Einzelmuster. Ein sechsstufiger Deploy-Workflow für neue Integrationen senkte PRs mit fehlenden Wiring-Dateien von 40 % auf 10 %, hob die Korrektheit um 25 % und die Vollständigkeit um 20 %.
• Entscheidungstabellen, wenn 2 oder 3 sinnvolle Optionen existieren. Eine React Query vs. Zustand-Entscheidungstabelle erzielte 25 % mehr best_practices-Bewertungen bei PRs in diesem Bereich. Die Tabelle löst Ambiguität, bevor der Agent Code schreibt.
• Echte Codebase-Beispiele, je 3 bis 10 Zeilen. Verbessert Wiederverwendung und Muster-Adhärenz. Längeres verleitet den Agent zum Pattern-Matching am falschen Objekt.
• Jedem Verbot ein Gebot beifügen. Reine Warnungsdokumentation schneidet schlechter ab. Ein bloßes Verbot macht den Agent vorsichtig und explorationsorientiert. Wird es mit einer positiven Direktive gepaart, die die richtige Call-Site nennt, macht der Agent weiter.
• Dateien auf Modulebene statt einer riesigen Root-Datei. Das 100-bis-150-Zeilen-Band passt zu einem mittelgroßen Modul mit etwa 100 Dateien. Übergreifende Root-Dateien jenseits dieser Größe verloren auf jeder Metrik.

Was die Ausgabe zerstört

• Architektur-Überblicke. Der Agent liest den Überblick, öffnet dann Dutzende umgebende Dokumente, um seinen Ansatz zu verifizieren, lädt 10.000 bis 100.000 Token irrelevanten Kontext, und die Ausgabe verschlechtert sich. Augment nennt das die Overexploration-Falle.
• Gestapelte Warnungen ohne begleitende Anleitung. Bei 30 bis 50 Verboten ohne ein einziges Gebot prüft der Agent seine Lösung gegen jede Warnung einzeln, auch wenn keine davon zutrifft.
• Muster, die in der Codebase noch nicht existieren. Beschreibt die AGENTS.md eine Architektur, die der Code nicht implementiert, steuert die Datei den Agent aktiv in die falsche Richtung.
• Dokumentations-Sprawl um die Datei herum. Augments schlechteste Performer waren AGENTS.md-Dateien, die auf 500K bis 2MB Architekturdokumentation aufsaßen. Das Entfernen der AGENTS.md veränderte das Verhalten kaum. Der Agent las den Sprawl ohnehin.

Reaktiv statt vorgefertigt

Elie Steinbock veröffentlichte am 2026-04-20 einen separaten Beitrag mit einer Disziplin, die die meisten Enterprise-AGENTS.md-Dateien repariert: Keine Regeln im Voraus schreiben, bevor etwas schiefgelaufen ist. Präventives Überstrukturieren erzeugt Ballast, den das Modell bei jedem Durchlauf parst.

Regeln kommen reaktiv hinzu, wenn eine echte Korrektur stattgefunden hat, und Ergänzungen bleiben einzeilig. Für alles Schwergewichtigere kommt der Inhalt in einen progressiv geladenen Skill. Die AGENTS.md bleibt kompakt. Die Skill-Ebene absorbiert das Gewicht.

Tans parallele Regel, die Twice-You-Failed-Disziplin, sagt dasselbe von der anderen Seite. Muss man den Agent zweimal nach derselben Sache fragen, sollte die zweite Anfrage nicht existieren. Das Muster kommt in die Skill-Ebene oder als Einzeiler in AGENTS.md. Das System wächst mit.

In einem webvise-Build sieht das so aus: AGENTS.md wird als kompakte, platzhaltergesteuerte Einstiegsdatei ausgeliefert. Das .claude/skills-Verzeichnis enthält eine kleine Menge lieferspezifischer Skill-Dateien, jede ein Prozess, den das Team während des Builds tatsächlich durchgeführt hat. Die Datei antizipiert keine Probleme. Sie dokumentiert gelöste.

Fünf Fragen, die Einkäufer jedem Anbieter stellen sollten

Die Inhaltsqualität einer AGENTS.md ist jetzt ein messbarer Proxy für KI-native Ausführung. Die fünf Fragen unten geben einem nicht-technischen Einkaufsteam einen schnellen Eindruck davon, ob ein Anbieter für den 2026-Stack oder den 2024-Stack entwickelt.

Kann ein Anbieter drei der fünf nicht beantworten, liefert er noch das 2024-Template aus. Die meisten Enterprise-Teams stoßen an dieser Stelle auf der Dokumentationsebene gegen die Wand. Dieses Audit ist die erste Phase jedes webvise-Migrationsprojekts.

Der tiefere Befund: Die Umgebung reparieren, nicht nur den Einstiegspunkt

Augments unbequemster Befund stammte aus den schlechtesten AGENTS.md-Dateien. Sie saßen auf 500K bis 2MB umgebender Architekturdokumentation. Wurde nur die AGENTS.md aus dem Run entfernt, änderte sich das Verhalten kaum. Der Agent las den Sprawl, egal was die Einstiegsdatei sagte.

Für Legacy-Enterprise-Teams ist diese Konsequenz schwer zu verdauen. Die meisten vor 2024 aufgebauten Dokumentationsumgebungen tragen jahrelange Architecture Decision Records, Design-Dokumente und Runbooks. Der Agent lädt davon genug, um eine saubere AGENTS.md zu übertönen. Eine bessere Einstiegsdatei zu schreiben ist notwendig, aber nicht hinreichend.

Die Arbeit ist unangenehm: Prüfen, welche Dokumente der Agent tatsächlich lädt, tote Dokumente zur Archivierung markieren, lebende in modulscoped Referenzen aufteilen und die AGENTS.md so ausrichten, dass sie nur auf das zeigt, was der Agent auf dem Weg zur Änderung lesen soll. Tans Formulierung trifft es: Das Gehirn ist ein Git-Repo, der Orchestrator ein schlanker Dirigent, der Dateien liest. Ist das Git-Repo voller toter Seiten, repariert keine Einstiegsdatei das.

Checkliste für die Build-Inbetriebnahme

Der Framework-Krieg ist vorbei. Next.js, Astro, SvelteKit und Nuxt liefern alle AGENTS.md-Scaffolding standardmäßig aus oder werden es innerhalb des Quartals tun. Der Differenzierungspunkt hat sich eine Ebene nach oben verschoben. Der Inhalt der Datei, die Struktur des Skill-Verzeichnisses und die dahinterstehende Disziplin entscheiden, ob der Agent-Stack hilft oder schadet.

Moderne Web-Builds 2026 werden von Tag eins an agent-lesbar ausgeliefert. Das ist der Contract, den webvise standardmäßig in jedem Projekt schreibt, von der einseitigen Landing Page bis zum mandantenfähigen SaaS. Das kompakte Template, die .claude/skills-Ebene und die Reactive-Rules-Disziplin gehören zum Lieferumfang.