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

(vercel.com)

15 Punkte von GN⁺ 2026-01-31 | 4 Kommentare | Auf WhatsApp teilen

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

4 Kommentare

channprj 2026-01-31

KI-Coding-Agenten haben die Einschränkung, dass sie aufgrund von Trainingsdaten auf Basis veralteter APIs mit aktuellen Frameworks nicht präzise umgehen können.

Mit Context7 lässt sich das obige Problem bis zu einem gewissen Grad lösen.

https://context7.com

slowandsnow 2026-02-04

Der Grund, warum die beiden oben genannten Methoden verwendet werden, ist, dass context7 ineffizient ist...

channprj 2026-02-05

Ich verstehe, was Sie sagen möchten, aber ich denke trotzdem nicht, dass es eine besonders schlechte Wahl ist, context7 ergänzend zu nutzen, anstatt jedes Mal in AGENTS.md oder Skills einzeln die Links zur neuesten Dokumentation aller aktuell verwendeten Frameworks/Bibliotheken zu sammeln und einzutragen.

Außerdem wird context7 weder im GeekNews-Beitrag noch im Vercel-Originaltext erwähnt. Ich hinterlasse diese Antwort, weil es für mich so wirkt, als hätten Sie den Inhalt um einen halben Schritt voraus interpretiert.

(Nur der Vollständigkeit halber: Dass sich mit gut geschriebenen Skills und AGENTS.md Tokens einsparen lassen, ist eine weithin bekannte Tatsache, und auch ich weiß das sehr gut.)

GN⁺ 2026-01-31

Hacker-News-Kommentare

Das Modell ist keine AGI. Es ist nur ein Textgenerator, der darauf trainiert wurde, Effekte wie Dateibearbeitung oder Tool-Aufrufe auszulösen.
Das Modell nutzt Skills nicht, weil es sie „versteht“, sondern erzeugt solchen Text dank Reinforcement Learning (RL) auf Basis von von Menschen erstellten Beispielen und Nutzungsprotokollen.
Der Grund, warum es Skills nicht immer verwendet, ist, dass es solche Fälle noch nicht ausreichend gelernt hat. Wenn man das mit RL erzwingt, kann das Modell im Gegenteil sogar dümmer werden.
Im Moment sammeln wir Nutzungsprotokolle für Skill-Verwendung, damit zukünftige Modelle besser lernen, wann sie Skills einsetzen sollten.
AGENTS.md ist schlicht Kontext. Modelle wurden von Anfang an darauf trainiert, Kontext zu befolgen.
- Der Unterschied zwischen AGENTS.md und Skills ist letztlich eine Frage von wie sie in den Kontext eingefügt werden.
  Das Frontmatter von Skills landet am Ende ebenfalls im Kontext, daher würde ein besseres Funktionieren von AGENTS.md auf Unterschiede bei der Extraktion und Einbettung der Skill-Informationen hindeuten.
  Manche Agenten könnten kleine Modelle (z. B. Haiku) verwenden, um zu entscheiden, welche Skill-Informationen an große Modelle (z. B. Sonnet, Opus) weitergegeben werden sollen.
  Im Kern geht es also darum, welche Informationen im „rohen Prompt“ landen.
- Von AGI kann keine Rede sein. Es ist faktisch eher Autocomplete auf Steroiden.
  Nützlich, aber nicht perfekt. Die GPT-Technologie selbst scheint bereits in eine Leistungsstagnation eingetreten zu sein.
  Weitere Verbesserungen dürften eher aus Hilfssystemen wie Skills kommen. Die aktuell implementierte Skill-Funktion ist aber schlechter, als AGENTS.md direkt zu verwenden.
- Ich habe selbst ähnliche Experimente gemacht. Im System-Prompt lasse ich relevante Skills vorab laden, im User-Prompt teste ich, sie bei Bedarf laden zu lassen.
- Es gab auch eine Frage dazu, was RL eigentlich ist.
- Auf die Aussage „Das Modell ist keine AGI“ gab es einen scherzhaften Kommentar mit einer Analogie zur GNU/Linux-Namensdebatte.
In der Auswertung wurde festgestellt, dass in 56 % der Fälle Skills kein einziges Mal aufgerufen wurden. Das heißt: Die Dokumentation war vorhanden, wurde aber nicht genutzt. Dazu kam der Witz: „Den Turing-Test hat es also bestanden …“
- Darauf gab es die schlagfertige Reaktion: „Auch AI RTFM nicht.“
- Ich musste ebenfalls lachen, aber ernsthaft gesagt sind auch Menschen oft nicht zuverlässig.
  Der Unterschied ist, dass AI Korrekturanweisungen ohne Ego akzeptiert.
  Noch nicht auf Senior-Entwickler-Niveau, aber beim Befolgen von Anweisungen besser als ein Junior.
Die zentrale Erkenntnis ist, dass Kompression (compression) von Dokumentzeigern effektiv ist.
Für Menschen schwer lesbar, für LLMs aber eine direkte und effiziente Referenzstruktur.
Künftig könnten statt Heuristiken wie agents.md/claude.md/skills.md standardisierte komprimierte Indexformate üblich werden, die immer geladen werden.
API-Testsuiten könnten außerdem zur Validierung der LLM-Codeleistung wiederverwendet werden.
Je stärker LLMs eingeführt werden, desto mehr müssen sich auch Bibliotheken und APIs daran anpassen.
- Eine weitere Lehre ist, dass „erst das Projekt erkunden, dann Skills aufrufen“ besser funktioniert als „immer Skills verwenden“.
  In Antigravity (= auf GEMINI.md basierend) wurde vorgegeben, den AGENTS.md-Regeln zu folgen, doch das wurde ignoriert.
  Der Prompt „Prüfe, ob es im Projekt eine AGENTS.md gibt“ funktionierte dagegen immer.
  Es ist ein merkwürdiges Phänomen, ähnlich wie früher „let’s think step by step“ Chain of Thought ausgelöst hat.
- Es gab auch die Reaktion, dass „Kompression“ hier nicht eher schlicht Minify sei.
- Jemand meinte, mit Zeilenumbrüchen statt Pipes wäre es leichter lesbar gewesen.
Wenn man AGENTS.md direkt in den System-Prompt aufnimmt, ist es immer im Kontext.
Aber alle Skills jedes Mal einzubinden wäre Verschwendung. Deshalb braucht man einen Ansatz wie Anthropics advanced tool use, bei dem nur im benötigten Moment geladen wird.
Letztlich ist das eine Frage des Gleichgewichts zwischen Kontext und Kosten. Wenn man Spielraum hat, ist eine komprimierte Einbettung in AGENTS.md effizient.
- Skills werden am Ende ebenfalls im Kontext deklariert. Es scheint einfach besser zu funktionieren, sie direkt komprimiert in AGENTS.md unterzubringen.
- Vercel scheint Skills und Kontextkonfiguration verwechselt zu haben. Die beiden verfolgen völlig unterschiedliche Ziele, daher sollte man beides zusammen verwenden.
- Deshalb funktioniert auch der RLM-Ansatz gut. Nur die nötigen Informationen kommen in den Kontext, der Rest bleibt in der Umgebung.
  Solche Agenten mit selbstverwaltetem Kontext dürften sich dieses Jahr stark weiterentwickeln.
- Am Ende braucht man beides. Einiges sollte fest in den Kontext gezwungen werden (index/sparknotes), anderes muss dynamisch per Exploration oder Suche ergänzt werden.
- Einzelne Nutzer können einfach den System-Prompt anpassen, aber im Team braucht man Skills für Standards wie Code-Stil.
  Claudes Skill-Compliance ist niedrig.
Ich arbeite ebenfalls in einem ähnlichen Bereich. Ich möchte bewerten, wie sich die Projekt-Scaffolding-Struktur auf Ergebnisse von Claude Code/Opencode auswirkt.
Allerdings ist Vercels Testmethode nicht klar genug, sodass Vergleiche schwierig sind.
AGENTS.md ist nicht völlig etwas anderes als Skills, sondern eine vereinfachte Form von Skills.
Entscheidend ist die Qualität des Skill-Designs, also die Minimierung der Anzahl von Schritten, die die AI braucht, um die richtigen Informationen zu finden.
Je weniger Schritte, desto geringer die Fehlerakkumulation.
- Ich selbst verwalte es ebenfalls in zwei Kategorien.
  1. Dinge, die regelbasiert zwangsweise in den System-Prompt eingefügt werden
  2. Dinge, die der Agent bei Bedarf erkundet
    Und um Tokenverschwendung zu reduzieren, füge ich große Dateien nur einmal in den System-Prompt ein.
Wenn in Blogs Prompt-Engineering verglichen wird, frage ich mich jedes Mal, ob nur einmal ausgeführt wurde oder mehrfach wiederholt.
LLMs liefern selbst bei gleicher Eingabe keine konsistenten Ergebnisse.
- Es ist frustrierend, dass solche nichtdeterministischen Ergebnisse als Wissenschaft präsentiert werden.
  Meist wirkt es so, als würden anekdotische Daten als Wissenschaft verpackt.
- Ich führe es ebenfalls immer mehrfach aus und berechne Konfidenzintervalle.
  Aber wenn man sorgfältig benchmarkt, gibt es wenige Aufrufe; macht man es schlampig, steigt der Blog-Traffic um das Neunfache.
  Das Problem ist eine verzerrte Anreizstruktur.
Es gibt sogar noch bessere Methoden als AGENTS.md.
Man kann einen Ordner .context anlegen und projektrelevante Dokumente (README, Abhängigkeitsdokumentation usw.) per symbolischem Link hineinlegen, sodass sie immer in den Kontext geladen werden.
So hat das LLM von Anfang an alle nötigen Informationen, was bessere Leistung und geringere Kosten ermöglichen kann.
- Dokumentation zu Abhängigkeiten macht allerdings keinen großen Unterschied. Stattdessen ist es viel nützlicher, den Quellcode selbst in einen Ordner _vendor zu legen.
  Das LLM kann den Code direkt analysieren und verstehen, wie er funktioniert.
- Alle Dokumente jedes Mal zu laden ist ineffizient. Eine andere Meinung war, lieber nur die Positionen in Claude.md oder Agents.md anzugeben und sie bei Bedarf lesen zu lassen.
- Man sollte den Kontext nicht unnötig aufblähen. Stattdessen ist ein Ansatz effizienter, bei dem nur ein Dokumentindex komprimiert eingebettet wird.
- Große Dateien jedes Mal einzubinden ist Tokenverschwendung. Im Claude-Code-Blog gab es dieselbe Warnung.
Das sind Erfahrungen aus der Entwicklung meines eigenen Custom-Agenten.
1. Ich habe mich an den Extraktionsanweisungen von Claude Code orientiert.
2. Ich lade AGENTS.md automatisch für Inhaltsverzeichnis und Zusammenfassung (sparknotes).
3. Thematische Markdown-Dateien verwalte ich als Skills.
4. MCP und Skills sind konzeptionell ähnlich, daher ist es entscheidend, gute Tools zu bauen.
5. Ich experimentiere weiter, habe Spaß dabei und verbessere es laufend.
  Nachdem ich read/write_file in den Zustand aufgenommen und im System-Prompt sichtbar gemacht habe, funktionierte es deutlich besser.
  Jetzt versuche ich das mit quantitativen Bewertungen (evals) zu belegen. Subjektiv fühlt sich die Leistung sehr gut an.