Das Handbuch vs. das Regelwerk: Ein kostspieliges Missverständnis
Dass viele Teams die Rolle einer AGENTS.md-Datei missverstehen, schafft einen kostspieligen operativen blinden Fleck. Aktuelle Untersuchungen von Ingenieuren bei Coldtea zeigen eine ernüchternde Realität: Nur 27 % der Top-1.000-GitHub-Repositories besitzen überhaupt eine AGENTS.md-Datei, und eine deutliche Mehrheit davon wird falsch genutzt. Dieses weit verbreitete Versäumnis hinterlässt eine kritische Lücke bei der Steuerung von KI-Beiträgen.
Das Kernproblem liegt in der Verwechslung eines Betriebshandbuchs mit einem 'Regelwerk'. Die meisten existierenden AGENTS.md-Dateien fungieren als Handbücher, die sich auf Beschreibungen der Projektarchitektur konzentrieren oder exakte Befehle zum Bauen und Testen auflisten. Sie sagen einer KI, wie sie arbeiten soll, versäumen es aber entscheidend, festzulegen, was sie tun darf und was nicht.
Eine echte AGENTS.md fungiert als Regelwerk, das strenge Leitplanken und explizite negative Einschränkungen für KI-Agenten festlegt. Ohne dieses Regelwerk agieren Agenten ohne Grenzen, was zu inkonsistenten Beiträgen, unerwartetem Verhalten und der Einführung potenzieller Fehler führt. Größere Repositories widmen beispielsweise fast doppelt so viel Platz den „Nicht“-Regeln – ein klares Signal für ihr Verständnis dieser Notwendigkeit. Das Fehlen klarer „muss“, „immer“ und „niemals“-Anweisungen macht aus einem potenziell mächtigen Werkzeug eine unvorhersehbare Haftungsquelle.
Die Macht des „Nicht“: Lektionen von Vercel und Bun
Die Forschung von Coldtea enthüllt ein kritisches Muster bei führenden Repositories: Die effektivsten AGENTS.md-Dateien priorisieren explizite negative Einschränkungen. Top-100-Repositories widmen im Vergleich zu kleineren Projekten fast doppelt so viel Platz Regeln darüber, was nicht zu tun ist, wobei 784 Instanzen von impliziten „Nicht“-Sätzen gefunden wurden.
Beeindruckende 90 % dieser leistungsstarken Dateien nutzen definitive Begriffe wie „muss“, „immer“ oder „niemals“, um KI-Agenten zu leiten. Dies ist kein Zufall; es ist eine bewusste Strategie, um unbeabsichtigte Aktionen zu verhindern und die Code-Integrität zu wahren – ein Markenzeichen robuster Systeme.
Spezifische Beispiele unterstreichen diese Präzision. Das Next.js-Repository von Vercel verbietet beispielsweise explizit Fußzeilen wie „generated with Claude code“ in Commits. Dieser Detailgrad stellt sicher, dass KI-Beiträge perfekt mit den Projektstandards und menschlichen Erwartungen übereinstimmen.
Das Repository von Bun bietet mit seiner Warnung in Großbuchstaben ein weiteres starkes Beispiel: 'NEVER run bun test directly - it won't include your changes.' Solche direkten Verbote beseitigen Mehrdeutigkeiten und verhindern, dass Agenten schädliche Befehle ausführen, die die Build- oder Testumgebung gefährden könnten.
Explizite Grenzen sind unerlässlich, da KI-Agenten ohne menschlichen Kontext oder Intuition agieren. Ihnen fehlt das implizite Verständnis für die Projekthistorie, Teamnormen oder potenzielle Nebenwirkungen. Daher müssen Sie ihnen präzise mitteilen, welche Dateien, Funktionen oder Muster sie akribisch vermeiden sollen, indem Sie als digitale Leitplanke fungieren. Dieser proaktive Ansatz verhindert subtile Fehler und schützt die Codebasis.
Von 33 bis 14.000 Wörtern: Die richtige Größe für Ihre Datei finden
Die enorme Variabilität in der Länge von AGENTS.md-Dateien zeigt eine aufkommende Best Practice. Betrachten Sie die Extreme: Die gesamte Datei von VS Code umfasst nur 33 Wörter und fungiert als einfache Weiterleitung. Die von Neovim ist mit 35 Wörtern kaum länger und konzentriert sich auf eine einzige Offenlegungsregel für KI-generierte Commits. Das OpenHands-Repository hingegen präsentiert ein beeindruckendes Regelwerk von 14.000 Wörtern. Dieses breite Spektrum verdeutlicht die Herausforderung, einen optimalen Bauplan zu definieren.
Die Forschung von Coldtea bietet jedoch einen praktischen Orientierungspunkt: eine mittlere Länge von etwa 1.200 Wörtern. Diese Zahl deutet auf einen pragmatischen Idealwert für die meisten Projekte hin, der genügend Details für KI-Mitwirkende mit der für menschliche Aufsicht und schnelle Iterationen erforderlichen Klarheit in Einklang bringt. Es ist ein realistischer Maßstab, um effektive Agenten-Grenzen zu setzen, ohne durch übermäßige Ausführlichkeit zu überfordern.
Letztendlich muss die Komplexität Ihrer AGENTS.md-Datei direkt auf den Umfang Ihres Projekts und die spezifischen Risiken abgestimmt sein, die Sie mit KI-Unterstützung mindern möchten. Ein kleineres, fokussiertes Hilfsprogramm benötigt möglicherweise nur minimale Leitplanken, aber ein komplexes System mit mehreren Mitwirkenden erfordert ein robustes Regelwerk. Für tiefere Einblicke, wie Kontextdateien Coding-Agenten wirklich helfen, erkunden Sie Arbeiten wie Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?.
Gefällt Ihnen der Artikel? Erhalten Sie jeden Morgen einen wie diesen per E-Mail.
eine E-Mail pro Tag · Abmeldung mit zwei Klicks · kein Tracking durch Dritte
Ihre 3-Punkte-Checkliste für ein Agenten-sicheres Repository
Nach der Analyse der 1.000 besten GitHub-Repositories haben die Ingenieure von Coldtea die Essenz effektiver AGENTS.md-Dateien in einer entscheidenden Drei-Punkte-Checkliste zusammengefasst. Hier geht es nicht um Vorschläge, sondern darum, präzise Befehle für Ihre KI-Agenten bereitzustellen und Ihre Datei in ein robustes Regelwerk zu verwandeln.
Stellen Sie für ein Agenten-sicheres Repository sicher, dass Ihre AGENTS.md Folgendes enthält:
- Mindestens eine explizite 'Nicht'-Regel. Diese kritische Richtlinie, die in 86 % der effektiven Dateien vorhanden ist, legt klare Grenzen für das Verhalten von Agenten fest. Ohne diese negativen Einschränkungen verlassen sich Agenten oft auf Annahmen, was potenziell unerwünschte Änderungen oder "generierte" Fußzeilen einführen kann, wie bei Vercel's Next.js zu sehen. Dies beinhaltet die klare Definition dessen, was der Agent niemals anfassen darf.
- Detaillierte Angaben dazu, wie Commits und Pull Requests formatiert werden müssen. Diese finden sich in 79 % der erfolgreichen Dateien und stellen sicher, dass die Projekthistorie und die Standards konsistent bleiben, unabhängig davon, ob ein Mensch oder ein KI-Agent den Code einreicht. Eine präskriptive Formatierung verhindert Chaos im Versionskontrollsystem.
- Genau, wie Tests ausgeführt und Code gelint werden soll. Etwa drei Viertel (75 %) der effektiven Dateien enthalten diese präzisen Anweisungen. Dies sind keine optionalen Schritte; es sind direkte Befehle, die der Agent ausführen muss, um sicherzustellen, dass jeder Beitrag vor der Integration die Qualitätskontrollen erfüllt.
Häufig gestellte Fragen
Was ist der Hauptfehler, den Projekte bei AGENTS.md-Dateien machen?
Der häufigste Fehler besteht darin, AGENTS.md als Betriebshandbuch (Auflistung von Befehlen) zu behandeln, anstatt als strenges Regelwerk, das einem KI-Agenten sagt, was er tun muss und, was noch wichtiger ist, was er nicht tun darf.
Was sind die Schlüsselelemente einer guten AGENTS.md-Datei?
Eine effektive Datei enthält explizite negative Einschränkungen ('Nicht'-Regeln), klare Anweisungen für die Formatierung von Commits und PRs sowie präzise Richtlinien zur Ausführung von Tests und zum Linting des Codes.
Benötigen große Projekte andere AGENTS.md-Dateien als kleine?
Ja. Die Forschung zeigt, dass größere, komplexere Projekte viel strengere AGENTS.md-Dateien haben und fast doppelt so viel Platz für negative Einschränkungen ('Nicht'-Regeln) aufwenden, um die Codebasis zu schützen.
Wie verbreitet sind AGENTS.md-Dateien in Top-GitHub-Repos?
Sie sind immer noch relativ selten. Eine Studie der 1.000 besten GitHub-Repos ergab, dass nur 27 % eine AGENTS.md-Datei hatten, was auf eine große Verbesserungsmöglichkeit bei der Anleitung von KI-Agenten hinweist.