Analyse von 1.866 GitHub-Projekten deckt Lücken in den Anweisungen für KI-Agenten auf

Inzwischen enthält jedes dritte beliebte GitHub-Projekt spezifische Anweisungsdateien für KI-Coding-Agenten, wobei sich AGENTS.md als Standardformat etabliert hat. Eine aktuelle Analyse von 1.866 aktiven Repositories zeigt, dass die Adoption zwar weit verbreitet ist, insbesondere bei TypeScript-Projekten, die Qualität und Durchsetzbarkeit dieser Anweisungen jedoch stark variieren.

Was passiert ist

Forscher analysierten die am häufigsten mit Sternen markierten Repositories auf GitHub, um zu verstehen, wie Teams KI-Assistenten anleiten. Sie untersuchten 1.866 Projekte, die im laufenden Jahr Commits erhalten hatten, und suchten nach Dateien wie AGENTS.md, CLAUDE.md und anderen, die darauf ausgelegt sind, das Verhalten der Agenten zu steuern. Die Studie ergab, dass 627 dieser Projekte, also 34 %, mindestens eine solche Anweisungsdatei enthalten.

Die Daten zeigen eine klare Präferenz für AGENTS.md, das in 78 % der Projekte mit Agentenanweisungen vorkommt. Auch CLAUDE.md ist verbreitet und in 52 % dieser Projekte vorhanden, koexistiert aber meist neben AGENTS.md, statt es zu ersetzen. Die Adoptionsraten unterscheiden sich je nach Programmiersprache erheblich. TypeScript führt mit 73 % der Projekte, die Agentendateien enthalten, gefolgt von Go mit 58 % und Rust mit 52 %. Im Gegensatz dazu enthalten Perl-Projekte selten solche Dateien, mit einer Adoptionsrate von nur 4 %.

Die Studie hob auch Probleme mit der Dateilänge und Redundanz hervor. Die Hälfte der Hauptanweisungsdateien umfasst mehr als 100 Zeilen, mit einer Medianlänge von 106 Zeilen. Etwa 30 Projekte pflegen zwei separate Regelwerke, beispielsweise eine AGENTS.md und eine CLAUDE.md mit unterschiedlichem Inhalt, was potenzielle Konflikte für Agenten erzeugt, die verschiedene Tools nutzen.

Wie es funktioniert

Die Analyse kombinierte automatisierte Skripting mit menschlich wirkenden Bewertungen durch einen KI-Reviewer. Ein Skript sammelte zunächst Daten zur Existenz, Länge und zu Überschriften der Dateien. Anschließend klassifizierte ein separater KI-Reviewer zufällige Stichproben der Regeln, um festzustellen, ob es sich um echte Anweisungen handelte und ob sie durch Code durchgesetzt werden konnten.

Die Forscher stellten fest, dass drei von fünf Regeln zumindest teilweise durch ein Skript, einen Linter oder einen Test überprüft werden könnten. Weniger als eine von zwanzig Regeln benennt jedoch explizit die Überprüfung, die sie durchsetzt. Die meisten Regeln verlassen sich darauf, dass der Agent sich einfach an die Anweisung erinnert, was weniger zuverlässig ist als eine automatisierte Durchsetzung. Beispielsweise könnte eine Regel lauten: „Verwenden Sie keine leeren Destrukturierungsmuster“, was ein Linter leicht erfassen könnte, aber die Datei spezifiziert nicht, welche Linter-Regel angewendet wird.

Die Studie untersuchte auch, wo diese Dateien gespeichert sind. Während viele sich im Stammverzeichnis des Repositories befinden, bewahren 30 % der Projekte Anweisungsdateien in Unterordnern auf. Dies ermöglicht es, Regeln auf bestimmte Teile der Codebasis zu beschränken und zu verhindern, dass Agenten irrelevanten Kontext laden, wenn sie in anderen Bereichen arbeiten.

Wichtige Details

• Adoptionsrate: 34 % der beliebten aktiven Projekte haben Agentenanweisungsdateien, bei TypeScript steigt dieser Wert auf 73 %.
• Dateilänge: Die mediane Hauptdatei umfasst 106 Zeilen, 52 % überschreiten 100 Zeilen.
• Durchsetzbarkeit: 61 % der Regeln könnten teilweise oder vollständig durch ein Skript geprüft werden, aber nur 3,7 % benennen die spezifische Prüfung.
• Redundanz: Etwa 30 Projekte pflegen separate, nicht identische AGENTS.md- und CLAUDE.md-Dateien.
• Aktualität: Nur 2 % der Dateien verweisen auf Pfade oder Skripte, die nicht mehr existieren.
• Inhaltlicher Fokus: Code-Stil, Agentenverhalten und projektspezifische Korrektheit sind die häufigsten Themen, während Sicherheit und Leistung selten behandelt werden.

Warum das wichtig ist

Für Engineering-Teams verdeutlichen diese Daten eine Lücke zwischen dem Schreiben von Anweisungen und der Sicherstellung ihrer Befolgung. Lange Anweisungsdateien erhöhen die Token-Kosten und können den Fokus des Agenten verwässern. Die im Artikel zitierte ETH-Zürich-Studie weist darauf hin, dass虽然 von Entwicklern geschriebene Dateien marginal helfen, sie die Kosten für Agenten um bis zu 19 % erhöhen können. Es ist effizienter, Dateien kurz zu halten und auf externe Dokumentation zu verweisen.

Noch wichtiger ist, dass es riskant ist, sich bei kritischen Regeln auf das Gedächtnis eines Agenten zu verlassen. Wenn eine Regel ihren Durchsetzungsmechanismus benennt, wie etwa einen spezifischen Linter oder CI-Check, schafft dies ein Sicherheitsnetz. Falls der Agent die Regel vergisst, fängt das Tool den Fehler ab. Ohne diese Verknüpfung verlassen sich Teams auf die Konsistenz des Agenten, die nachlässt, wenn sich die Kontextfenster füllen. Die Verbreitung nicht durchgesetzter Regeln deutet darauf hin, dass viele Teams diese Dateien eher als Wunschlisten denn als operative Einschränkungen behandeln.

Was Sie tun können

• Dateilänge prüfen: Halten Sie Ihre Haupt-AGENTS.md unter 100 Zeilen, indem Sie detaillierte Erklärungen in verlinkte Dokumentation auslagern.
• Prüfungen benennen: Geben Sie für jede Regel den Linter, Test oder das Skript an, das sie durchsetzt, z. B. „Durchgesetzt durch Sorbet/ForbidTMust“.
• Pfade verifizieren: Überprüfen Sie regelmäßig, ob alle in Ihren Anweisungen referenzierten Befehle und Dateipfade noch existieren.
• Dateien konsolidieren: Wenn Sie mehrere Anweisungsdateien verwenden, stellen Sie sicher, dass sekundäre Dateien auf die primäre verweisen, um widersprüchliche Regeln zu vermeiden.
• Automatisierbare Regeln priorisieren: Konzentrieren Sie sich auf Regeln, die automatisiert werden können, und entfernen Sie solche, die sich ausschließlich auf das Gedächtnis des Agenten verlassen, es sei denn, sie sind kritisch.
• Unterordner-Regeln nutzen: Platzieren Sie spezifische Anweisungen in Unterverzeichnissen, um den Kontext relevant für den bearbeiteten Code zu halten.