AGENTS.md zeigt bei Agenten-Evaluierungen eine bessere Leistung als Skills

• In einer Evaluierung für die Next.js 16 API erzielte ein Dokumentindex in AGENTS.md im Projekt-Root eine höhere Genauigkeit als ein Skill-basierter Ansatz
• Skills sind Pakete für Domänenwissen, die Agenten bei Bedarf aufrufen, doch der Aufruf war instabil, sodass sie in der Standardkonfiguration nur 53 % Erfolgsquote erreichten
• Dagegen erreichte ein auf 8 KB komprimierter AGENTS.md-Index in allen Tests (Build, Lint, Test) eine Erfolgsquote von 100 %
• Dieser Ansatz liefert durch den Wegfall von Entscheidungspunkten, ständige Verfügbarkeit und die Beseitigung von Reihenfolgeproblemen stabilere Ergebnisse als ein proaktiver Aufruf
• Framework-Maintainer können die Genauigkeit der Codegenerierung erhöhen, indem sie einen versionspassenden Dokumentindex in AGENTS.md aufnehmen

---

Problemhintergrund

• KI-Coding-Agenten haben die Einschränkung, dass ihre Trainingsdaten auf älteren APIs basieren und sie deshalb aktuelle Frameworks nicht präzise handhaben können
  • Next.js-16-Funktionen wie 'use cache', connection() und forbidden() sind in den bestehenden Modelldaten nicht enthalten
• Umgekehrt kommt es in Projekten mit älteren Versionen auch dazu, dass Modelle neuere, gar nicht vorhandene APIs vorschlagen
• Zur Lösung wurde ein Zugriffsansatz mit versionspassender Dokumentation erprobt

Zwei Ansätze

• Skills: ein offenes Standardpaket, das Prompts, Tools und Dokumentation bündelt und bei Bedarf vom Agenten aufgerufen wird
• AGENTS.md: eine persistente Kontextdatei im Projekt-Root, auf die in jedem Gesprächszug jederzeit verwiesen werden kann
• Beide Ansätze wurden auf Basis derselben Next.js-Dokumentation vergleichend evaluiert

Grenzen des Skill-Ansatzes

• Die Evaluierung zeigte, dass in 56 % der Tests der Skill nicht aufgerufen wurde; die grundlegende Erfolgsquote blieb bei 53 % ohne Verbesserung
• In einigen Punkten wurden sogar schlechtere Werte als die Baseline (z. B. Test 58 % vs. 63 %) erreicht
• Das wird als Hinweis darauf gewertet, dass aktuelle Modelle Tool-Nutzung nicht zuverlässig stabil ausführen

Zusätzlicher Versuch mit expliziten Anweisungen

• Als in AGENTS.md eine explizite Anweisung ergänzt wurde, „vor dem Schreiben von Code den Skill aufzurufen“, stieg die Erfolgsquote auf 79 %
• Allerdings hatten feine Unterschiede in der Formulierung großen Einfluss auf das Ergebnis
  • „Zuerst den Skill aufrufen“ → Fixierung auf Dokumentmuster, Projektkontext fehlt
  • „Nach Erkundung des Projekts den Skill aufrufen“ → bessere Ergebnisse
• Wegen dieser sprachlichen Fragilität ist die Zuverlässigkeit im Praxiseinsatz gering

Aufbau einer verlässlichen Evaluierung

• Die frühen Tests waren wegen uneindeutiger Prompts und doppelter Validierungsprobleme nur begrenzt verlässlich
• Das wurde verbessert und durch verhaltensbasierte Validierung sowie Tests mit nicht antrainierten Next.js-16-APIs verstärkt
• Wichtige Test-APIs: connection(), 'use cache', cacheLife(), forbidden(), proxy.ts, cookies(), headers(), after(), refresh() usw.

Experiment mit dem AGENTS.md-Ansatz

• Der Auswahlprozess des Agenten wurde entfernt, und stattdessen wurde der Dokumentindex direkt in AGENTS.md eingefügt
• Der Index bestand nicht aus der vollständigen Dokumentation, sondern aus einer Liste versionsspezifischer Dokumentpfade
• Zusätzliche Anweisung:
  IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks.
  • Damit soll das Modell dokumentbasierte Schlussfolgerung gegenüber vorhandenem Trainingswissen bevorzugen

Evaluierungsergebnisse

• Mit eingefügtem AGENTS.md-Index wurde eine Erfolgsquote von 100 % erreicht
  • Build, Lint und Test waren durchweg perfekt
• Vergleichswerte:
  • Baseline 53 %, Skill Standard 53 %, Skill + Anweisung 79 %, AGENTS.md 100 %
• Gründe, warum der passive Kontextansatz dem aktiven Aufruf überlegen ist
  1. Keine Entscheidungspunkte — die Information ist immer vorhanden
  2. Konsistente Verfügbarkeit — in jedem Turn im System-Prompt enthalten
  3. Wegfall von Reihenfolgeproblemen — nicht abhängig von der Suchreihenfolge in der Dokumentation

Lösung des Kontextkapazitätsproblems

• Der ursprüngliche Index war 40 KB groß, wurde aber durch Komprimierung auf 8 KB reduziert (80 % weniger)
• Mit einer durch Pipes (|) getrennten Struktur werden Dokumentpfade und Dateinamen mit minimalem Platzbedarf gespeichert
• Der Agent liest nur die benötigten Dateien im Verzeichnis .next-docs/ und nutzt so präzise Versionsinformationen

Vorgehensweise zur Nutzung

• Die Einrichtung ist mit einem einzigen Befehl möglich

  npx @next/codemod@canary agents-md
  

• Dieser Befehl führt Folgendes aus:
  1. Next.js-Version erkennen
  2. Die passende Versionsdokumentation nach .next-docs/ herunterladen
  3. Den komprimierten Index in AGENTS.md einfügen
• Das funktioniert ebenso mit Agenten, die AGENTS.md erkennen, etwa Cursor

Implikationen für Framework-Entwickler

• Skills bleiben weiterhin nützlich, doch zur generellen Verbesserung der Genauigkeit bei der Codegenerierung ist der AGENTS.md-Ansatz effektiver
• Skills eignen sich für spezifische aufgabenorientierte Workflows wie „Versions-Upgrade“ oder „App-Router-Migration“
• Empfehlungen:
  • Nicht auf Verbesserungen bei Skills warten, sondern sofort AGENTS.md nutzen
  • Nur den Dokumentindex einfügen, um den Kontext klein zu halten
  • Mit API-zentrierten Evaluierungen, die nicht in den Trainingsdaten enthalten sind, validieren
  • Dokumentation als feingranulare Suchstruktur gestalten
• Das Ziel ist der Wechsel von vortrainierungszentrierter zu retrieval-basierter Schlussfolgerung;
  AGENTS.md ist der stabilste Weg, dies umzusetzen