Ihr KI-Coding-Agent nutzt Dokumentation anders, als Sie denken

Eine Geschichte, wie man sie aus der Softwareentwicklung kennt: Ein Unternehmen will, dass seine KI-Coding-Agenten besser arbeiten. Also verbessert es das Entwicklerportal, erweitert die API-Referenz, ergänzt Beispiele und schreibt den Troubleshooting-Leitfaden neu. Die Dokumentation ist jetzt klarer, vollständiger und leichter zu navigieren. Dann legt der Agent los. Er öffnet AGENTS.md, liest einen Plan, den ein anderer Agent hinterlassen hat, legt eine neue Arbeitsnotiz an, sieht sich eine Konfigurationsdatei an, ändert den Code und aktualisiert seine eigenen Anweisungen. Die sorgfältig gepflegte API-Referenz bleibt unberührt.

Das Problem ist nicht unbedingt, dass die Dokumentation schlecht ist. Vielleicht verbessert die Organisation einfach die falsche Ebene der Dokumentation. Ein neuer Preprint, From Agent Behaviour to Agent-Friendly Documentation, bietet einen ungewöhnlich detaillierten Blick darauf, was Coding-Agenten tatsächlich mit technischer Dokumentation machen. Die Forscher analysierten 557 reale agentische Coding-Sessions mit 94.813 Entwicklungsereignissen, darunter 3.033 Interaktionen mit Dokumentation. Ergänzt wurden diese Traces durch 33.097 von Coding-Agenten erstellte Pull Requests mit 690.260 Änderungsdatensätzen auf Dateiebene.

Ihr zentrales Ergebnis stellt eine Grundannahme jeder Dokumentationsstrategie infrage: Coding-Agenten nutzen Dokumentation nicht wie etwas schnellere menschliche Entwickler. Sie haben ein eigenes Dokumentationssystem geschaffen.

Die Dokumentationshierarchie hat sich umgedreht

Die meisten Dokumentationsprogramme drehen sich um vertraute Artefakte: API-Referenzen, Architekturleitfäden, Installationsanleitungen, Beispiele, Troubleshooting-Seiten und READMEs. Für Menschen sind diese Dokumente nach wie vor wichtig. Im beobachteten Verhalten der Agenten dominierten aber andere.

Auf agentbezogene Artefakte entfielen 60,5 % aller erfassten Dokumentationsinteraktionen. Die größte Kategorie waren Anweisungsdateien für Agenten wie AGENTS.md, CLAUDE.md, SKILL.md sowie Regeln für Tools wie Cursor und Copilot. Sie machten 35,4 % der Interaktionen aus. Weitere 25,1 % betrafen Arbeitsnotizen der Agenten: Pläne, thoughts/-Verzeichnisse, Brainstormings, Review-Logs und andere Dateien, die Agenten anlegen, um ihre eigene Arbeit zu organisieren.

API-Referenzen kamen auf 1,3 %, Troubleshooting-Dokumentation auf 0,4 %. Anders gesagt: Anweisungsdateien tauchten rund 27-mal so oft auf wie API-Referenzen. Genau die Dokumente, in die klassische Dokumentationsteams am meisten investieren, spielten in diesen Repository-lokalen Traces nur am Rand eine Rolle. Im Zentrum standen die Dokumente, die das Verhalten der Agenten direkt steuern.

Das heißt nicht, dass Unternehmen ihre API-Dokumentation löschen sollten. Die Studie konnte weder Dokumentation sehen, die auf externen Websites gelesen wurde, noch Wissen, das bereits im Modell steckt, Inline-Kommentare, Docstrings oder Anweisungsdateien, die eine Agent-Runtime automatisch lädt. Ihre Zahlen beschreiben einen beobachtbaren Ausschnitt des Verhaltens, nicht die gesamte Informationsumgebung.

Das Ungleichgewicht ist aber zu groß, um es abzutun. Wenn eine Organisation verbessern will, wie Agenten in einer Codebasis arbeiten, ist das Entwicklerportal vielleicht nicht mehr der erste Ort, an dem sie ansetzen sollte. Eher eine Markdown-Datei im Stammverzeichnis des Repositorys.

Agenten lesen Dokumentation, um zu denken

Das gängige Modell der Dokumentationsnutzung ist linear:

1. Ein Entwickler hat eine Frage.
2. Er findet das passende Dokument.
3. Er wendet an, was er gelernt hat.
4. Er testet das Ergebnis.
5. Bei Bedarf aktualisiert er die Dokumentation.

Das beobachtete Verhalten der Agenten sah anders aus. Nach dem Lesen eines Dokuments las ein Agent am wahrscheinlichsten ein weiteres Dokument oder dachte weiter nach. Auf 27 % der Lesevorgänge folgte ein weiterer Lesevorgang in der Dokumentation, auf 24,5 % ein Reasoning-Schritt. Eine unmittelbare Codeänderung folgte nur auf drei von 1.328 Lesevorgängen, eine Übergangswahrscheinlichkeit von 0,2 %. Die Zahl ist auffällig, verlangt aber Vorsicht. Dokumentation kann eine Änderung auch erst nach mehreren Reasoning-Schritten beeinflussen, und das statistische Ergebnis ändert sich je nachdem, wie man die Entwicklungsphase berücksichtigt. In der unbereinigten Analyse über drei Ereignisse lag die Codebearbeitung nach dem Nachschlagen praktisch auf dem Basiswert der Session. Im bereinigten Modell stieg der Zusammenhang über diesen Basiswert. Die Autoren betrachten die Verbindung zwischen dem Lesen von Dokumentation und dem Bearbeiten von Code daher als ungeklärt.

Belastbarer ist die Schlussfolgerung, dass das Nachschlagen in der Dokumentation keine einfache Transaktion nach dem Muster „lesen, dann handeln“ ist. Es ist ein wiederkehrender Prozess: Agenten holen Informationen, interpretieren sie, kehren zu anderen Dokumenten zurück und lagern Teile ihres Denkens aus. Dokumentation wird zu einer Mischung aus Nachschlagewerk, Notizblock und Kontextverwaltung. Das ist ein ganz anderes Designproblem, als eine Webseite leichter überfliegbar zu machen.

Dokumentation wird zum Arbeitsgedächtnis

Die Agenten in der Studie haben Dokumentation nicht bloß konsumiert. Sie haben sie fast genauso oft produziert. Die Forscher erfassten 1.615 Nachschlage-Ereignisse und 1.401 Ereignisse, in denen Dokumentation erstellt oder bearbeitet wurde. Auf jede Dokumentationsinteraktion, die aufs Lesen, Suchen oder Entdecken entfiel, kamen etwa 0,87 Schreibaktionen. Von den Sessions mit Dokumentationsaktivität enthielten 58,2 % sowohl Lesen als auch Schreiben.

Die Pull-Request-Daten erzählen in viel größerem Maßstab eine ähnliche Geschichte. In 41,5 % der 33.097 analysierten agentischen Pull Requests änderte sich Dokumentation. Dateien wie AGENTS.md, CLAUDE.md und copilot-instructions.md gehörten zu den am häufigsten geänderten Einzeldokumenten. Daraus entsteht ein Rückkopplungskreis, für den klassische Dokumentations-Governance nie gedacht war:

1. Eine Anweisungsdatei prägt das Verhalten eines Agenten.
2. Der Agent erledigt die Aufgabe.
3. Der Agent bearbeitet die Anweisungsdatei oder legt eine Arbeitsnotiz an.
4. Dieses neue Artefakt wird zum Kontext für einen künftigen Agenten.

Dokumentation ist nicht mehr nur ein von Menschen verfasster Input für die Softwareentwicklung. Sie ist auch ein von Agenten verfasster Output, der den nächsten Durchlauf beeinflussen kann. Das kann wertvoll sein. Ein Agent kann einen Plan hinterlassen, eine Einschränkung festhalten oder eine Repository-spezifische Vorgehensweise dokumentieren, die spätere Arbeit effizienter macht. Es entsteht aber auch etwas Neues, das gewartet werden muss. Temporäre Pläne können zu dauerhaftem Ballast werden. Falsche Annahmen können den Anschein von Repository-Richtlinien bekommen. Zwei Agenten können widersprüchliche Anweisungen hinterlassen. Eine Arbeitsnotiz für eine einzelne Aufgabe kann mit einer dauerhaften Architekturvorgabe verwechselt werden. Die Frage ist also nicht nur, ob der Agent die Dokumentation lesen kann, sondern ob die Organisation weiß, welche Dokumente den Agenten steuern und wer für sie verantwortlich ist.

Der Code geht voran, die Dokumentation folgt

Agenten schreiben vielleicht viel Dokumentation, aber sie fangen meist nicht damit an. Bei Pull Requests mit mehreren Commits, die sowohl Code als auch Dokumentation änderten, wurde in 47,3 % der Fälle zuerst der Code angefasst. Die Dokumentation kam in 10 % der Fälle zuerst. Die übrigen 42,6 % änderten beides im selben Commit, sodass sich die Reihenfolge nicht beobachten ließ. Über den gesamten Vergleich kam Code 4,7-mal so oft zuerst wie Dokumentation. Wenn beides in verschiedenen Commits auftauchte, lag der Code in 82,5 % der Fälle vorne.

Das erinnert an eine alte menschliche Gewohnheit: erst implementieren, dann dokumentieren. Für Organisationen, die hoffen, dass KI-Agenten Spezifikation und Implementierung automatisch laufend abgleichen, ist das eine Warnung. Viel Dokumentationsaktivität heißt nicht zwangsläufig, dass die Dokumentation die Arbeit steuert. Vielleicht hält sie nur fest, was der Agent schon getan hat. Es gibt einen entscheidenden Unterschied zwischen Dokumentation als Spezifikation und Dokumentation als Quittung. Die erste schränkt die Implementierung ein. Die zweite beschreibt sie im Nachhinein. Das beobachtete Verhalten der Agenten deutet überwiegend auf die Quittung hin.

Das eigentliche Problem ist die Verifikation

Das folgenreichste Ergebnis des Papers ist vielleicht das, was die Forscher nicht gefunden haben. Sie beobachteten keine explizite Abfolge, in der ein Agent Dokumentation nachschlug und sie dann als Orakel nutzte, um die Implementierung zu überprüfen. Nach der operationalen Definition der Studie kam dokumentationsbasierte Validierung kein einziges Mal vor.

Auch Tests und Builds waren unmittelbar nach dem Nachschlagen seltener. Innerhalb der nächsten drei Ereignisse traten Testläufe mit 23 % ihrer normalen Häufigkeit auf, Builds mit 15 %. Diese Zusammenhänge blieben unter dem Basiswert, auch nachdem die Forscher Entwicklungsphase und andere Faktoren herausgerechnet hatten.

Das beweist nicht, dass Agenten weniger testen, weil sie Dokumentation lesen. Die Studie ist rein beobachtend, und ein Teil der Verifikation könnte im Reasoning des Modells oder außerhalb des kurzen Ereignisfensters stattfinden. Sie zeigt aber eine Lücke zwischen gängigen Ratschlägen und tatsächlich erfasstem Verhalten. Wir sagen gern, agentfreundliche Dokumentation solle umsetzbar und überprüfbar sein. In diesen Traces war der Zusammenhang zwischen Lesen und Handeln statistisch unklar, und einen Verifikationsschritt hat man überhaupt nicht beobachtet.

Prosa kann einem Agenten sagen, was wahr sein sollte. Sie bringt ihn nicht automatisch dazu, zu prüfen, ob es stimmt. Deshalb ist „klarere Dokumentation“ keine vollständige Strategie für Zuverlässigkeit. Wenn eine Regel wichtig ist, braucht das System eine Möglichkeit, sie durchzusetzen oder zu testen. Ausführbare Beispiele, Schema-Verträge, Doctests, Policy-Checks, Akzeptanztests und explizite Validierungsbefehle machen aus einer Aussage eine beobachtbare Kontrolle. Die Studie beweist nicht, dass diese Maßnahmen das Problem lösen. Sie zeigt, warum Prosa allein nicht reicht.

Zum Troubleshooting-Leitfaden greifen Agenten selten

Eine weitere verbreitete Annahme ist, dass Agenten dann in die Dokumentation schauen, wenn sie nicht weiterkommen. Von allen Dokumentationsinteraktionen gingen 70,2 % im normalen Arbeitsfortschritt von den Agenten selbst aus. Nur 7,5 % waren durch Fehler ausgelöst. Nach 2.034 Fehlerepisoden war das Lesen von Dokumentation in 5,4 % der Fälle der erste Schritt zur Behebung. Viel wahrscheinlicher war, dass Agenten Code lasen, die Aktion wiederholten, direkt etwas änderten oder die Codebasis durchsuchten. Troubleshooting-Dokumentation tauchte in den gesamten 3.033 Dokumentationsinteraktionen nur 11-mal auf.

Auch das heißt nicht, dass Troubleshooting-Leitfäden nutzlos sind. Die Studie erfasste Repository-lokale Dateien zuverlässiger als externe Webseiten, und die wenigen Fälle, in denen die Fehlerbehebung mit Dokumentation begann, reichten nicht aus, um Erfolgsquoten zu vergleichen. Es deutet aber darauf hin, dass bloße Verfügbarkeit nicht genügt. Ein Troubleshooting-Leitfaden, der hinter einem Link versteckt ist, wird nicht einfach deshalb Teil der Fehlerbehebung eines Agenten, weil es ihn gibt.

Die beobachteten Agenten öffneten immer wieder lokale Dateien, aber die Forscher fanden keinen einzigen Fall, in dem sie Verweisen zwischen Dokumenten folgten. Für die Nutzung durch Agenten sind Nähe und lokale Auffindbarkeit womöglich genauso wichtig wie eine elegante Informationsarchitektur.

Wie man Dokumentation für Agenten baut

Die Forschung spricht dafür, den Aufwand anders zu verteilen. Ein fertiges Playbook liefert sie nicht, aber sie weist auf einige praktische Änderungen hin.

1. Behandeln Sie Agent-Anweisungen als Produktionsinfrastruktur

Dateien wie AGENTS.md und CLAUDE.md sollten keine informellen Prompt-Ablagen sein. Sie prägen das operative Verhalten und verdienen eine verantwortliche Person, eine Versionshistorie, einen Review-Prozess und Tests. Änderungen daran können künftige Aktionen von Agenten verändern, auch wenn sich am Anwendungscode nichts ändert.

2. Trennen Sie dauerhafte Regeln von temporären Arbeitsnotizen

Eine architektonische Vorgabe und ein Notizblock für eine einzelne Aufgabe sollten nicht dieselbe scheinbare Autorität haben. Geben Sie Plänen, Reasoning-Logs und Verifikationsnotizen klare Ablageorte, Lebensdauern und Aufbewahrungsregeln. Arbeitsgedächtnis soll nützlich sein, ohne unbemerkt zur dauerhaften Richtlinie zu werden.

3. Legen Sie wichtige Vorgaben dorthin, wo der Agent arbeitet

Repository-lokale, in sich geschlossene Vorgaben sind für einen Agenten leichter abrufbar als eine Kette von Links quer durch ein Dokumentationsportal. Halten Sie wichtige Anweisungen nahe am betreffenden Code und machen Sie ihren Geltungsbereich explizit. Eine Regel im Stammverzeichnis sollte sagen, ob sie global gilt; eine komponentenspezifische Regel gehört in die Nähe dieser Komponente.

4. Machen Sie aus wichtiger Prosa ausführbare Checks

Wenn ein Agent einen API-Vertrag einhalten muss, bilden Sie ihn in einem Schema oder einem Contract-Test ab. Wenn ein Beispiel gültig bleiben muss, machen Sie es ausführbar. Wenn eine Richtlinie nie verletzt werden darf, fügen Sie einen automatisierten Check hinzu. Die Dokumentation kann die Regel erklären, prüfen sollte sie aber das System.

5. Beobachten Sie den Dokumentationskreislauf

Dass die Aufgabe am Ende erledigt ist, reicht nicht. Teams sollten diese Fragen beantworten können:

• Welche Anweisungsdateien hat der Agent geladen?
• Welche Arbeitsnotizen hat er angelegt?
• Hat er Dokumente geändert, die künftige Agenten anleiten werden?
• Welche Regeln haben die Implementierung beeinflusst?
• Welche Validierung folgte auf das Nachschlagen?
• Ist temporärer Kontext zu dauerhaftem Repository-Inhalt geworden?

Ohne diese Transparenz kann ein Agent einen brauchbaren Patch liefern und dabei unbemerkt die Steuerungsebene für künftige Arbeit verändern.

6. Gestalten Sie für zwei Zielgruppen

Menschliche Entwickler brauchen weiterhin Erklärungen, Beispiele, konzeptionelle Modelle und gut navigierbares Referenzmaterial. Agenten brauchen kompakte lokale Anweisungen, einen eindeutigen Geltungsbereich, maschinell prüfbare Vorgaben und saubere Kontextgrenzen. Diese Bedürfnisse überschneiden sich, sind aber nicht identisch. Eine Dokumentationsstrategie muss heute beiden gerecht werden.

Ein bedeutendes Ergebnis mit bedeutenden Einschränkungen

Das Paper ist ein Preprint, keine begutachtete finale Veröffentlichung. Die Session-Daten stammen aus Opt-in-Telemetrie, wobei 87 % des breiteren Korpus einer einzigen Agent-Familie zugeordnet sind. Die Pull Requests stammen aus öffentlichen Repositorys, die Coding-Agenten früh eingesetzt haben, und ähneln privaten Unternehmens-Codebasen womöglich nicht. Die Studie erkennt Dokumentation außerdem am Dateipfad. Sie kann nicht alles sehen, was ein Agent weiß oder liest, und der Kontakt mit Anweisungsdateien wird zu niedrig erfasst, wenn eine Runtime diese Dateien automatisch lädt. Die Kategorie „Arbeitsnotizen von Agenten“ (eines der zentralen Ergebnisse des Papers) wurde mit einem Sprachmodell klassifiziert und noch nicht von menschlichen Codierern validiert. Der genaue Anteil von 60,5 % ist daher als vorläufig zu betrachten, nicht als universelle Konstante.

Vor allem beschreibt die Forschung Verhalten. Sie beweist nicht, dass das beobachtete Verhalten optimal ist oder dass eine bestimmte Maßnahme an der Dokumentation die Ergebnisse verbessert. Trotzdem ist das Gesamtmuster schwer zu ignorieren. Coding-Agenten konsumieren nicht bloß das Dokumentationssystem, das für Entwickler gebaut wurde. Sie schaffen eine parallele Ebene aus Anweisungen, Plänen, Notizen und Verifikationslogs. Diese Ebene lesen sie häufig, schreiben fast genauso oft hinein und ändern manchmal genau die Dateien, die ihr künftiges Verhalten steuern werden. Die nächste Generation technischer Dokumentation wird daher mehr sein als eine Website oder ein Handbuch. Sie wird Teil der operativen Umgebung des Agenten: lokal abrufbar, sorgfältig verwaltet, teilweise ausführbar und in ihren Änderungen beobachtbar.

Die wichtige Frage lautet nicht mehr „Ist unsere Dokumentation agentfreundlich?“, sondern „Welche Dokumentation hat den Agenten gesteuert, wer pflegt sie, und woher wissen wir, dass der Agent seine Arbeit überprüft hat?“. Das ist kein Schreibproblem. Das ist Systemdesign.

Quelle

Zhijun Gao und Jing Chen, From Agent Behaviour to Agent-Friendly Documentation: An Empirical Study of How Coding Agents Discover, Read, and Write Technical Documentation, arXiv-Preprint, 2026.

Aus dem Englischen übersetzt: zum Originalbeitrag