Agents.md: Anweisungen für die Projektarbeit
Autor: Redaktion Domeny.ForSale Veröffentlicht
Kurz erklärt: AGENTS.md ist eine Textdatei mit Anweisungen für AI-Agenten, die an einem Projekt arbeiten, meist am Code. Sie beschreibt unter anderem, wie Tests ausgeführt werden, wie das Projekt aufgebaut ist und welche Regeln für Änderungen gelten. Die Datei selbst führt nichts aus: Ihre Wirkung hängt davon ab, ob das verwendete Werkzeug sie liest und wie es die enthaltenen Hinweise interpretiert.
Wozu die Datei AGENTS.md dient
Ein AI-Agent ist ein Werkzeug, das nicht nur Fragen beantwortet, sondern auch Aufgaben ausführen kann, etwa Dateien durchsuchen, Code bearbeiten und Befehle ausführen. Dazu braucht er Informationen zum jeweiligen Projekt. Ohne diesen Kontext kann er eine ungeeignete Methode zur Installation von Abhängigkeiten wählen oder Dateien verändern, die das Team nicht von Hand bearbeitet.
Mit AGENTS.md lässt sich dieser Kontext im Repository festhalten, also dort, wo der Code und seine Änderungshistorie gespeichert werden. Die Datei nutzt Markdown, ein einfaches Textformat mit Überschriften, Listen und Codeblöcken. Sie lässt sich in einem gewöhnlichen Editor bearbeiten und zusammen mit den übrigen Projektänderungen prüfen.
Es handelt sich um eine Konvention zur Weitergabe von Anweisungen, nicht um ein Programm, ein AI-Modell oder einen Mechanismus zur Vergabe von Berechtigungen. Die Anweisung „Ändere die Produktionskonfiguration nicht“ ist ein Hinweis für den Agenten, verhindert aber technisch keinen Zugriff auf diese Konfiguration.
AGENTS.md und README – unterschiedliche Aufgaben der Dokumentation
README.md stellt das Projekt üblicherweise Menschen vor: Die Datei erklärt seinen Zweck, die Installation und die grundlegende Nutzung. AGENTS.md konzentriert sich darauf, wie ein Agent in diesem Repository arbeiten soll. Die beiden Dateien können sich ergänzen, statt dieselbe Dokumentation zu wiederholen.
Die README einer Bibliothek kann beispielsweise zeigen, wie man diese in der eigenen Anwendung verwendet. Die Anweisungen für den Agenten können dagegen festlegen, dass nach einer Änderung der öffentlichen Schnittstelle die Beispiele aktualisiert und bestimmte Tests ausgeführt werden müssen.
AGENTS.md darf auch nicht mit llms.txt verwechselt werden. Letztere Datei wurde als Möglichkeit vorgeschlagen, Sprachmodellen Informationen über die Inhalte einer Website bereitzustellen. AGENTS.md betrifft vor allem die Arbeit am Projekt, nicht die Darstellung der Website-Inhalte. Die bloße Existenz dieser Datei sagt nichts über die Sichtbarkeit der Website in Suchmaschinen oder AI-Diensten aus.
Wo die Datei hingehört und ob jedes Werkzeug sie liest
Der übliche Speicherort ist das Hauptverzeichnis des Repositorys. Verwende beim Erstellen der Datei den Namen AGENTS.md mit Großbuchstaben: Auf Systemen, die zwischen Groß- und Kleinschreibung unterscheiden, kann Agents.md eine andere Datei sein. Gehe nicht davon aus, dass das Werkzeug jede Schreibweise des Namens erkennt.
In größeren Projekten finden sich mitunter zusätzliche AGENTS.md-Dateien in Unterverzeichnissen, beispielsweise getrennt für die Benutzeroberfläche und die serverseitige Komponente. So lassen sich Regeln für unterschiedliche Technologien voneinander trennen. Der Geltungsbereich der Anweisungen und der Umgang mit Widersprüchen hängen jedoch vom Werkzeug ab. Deshalb sollte man nicht für alle Agenten dieselbe Rangfolge der Anweisungen voraussetzen.
Prüfe vor dem Einsatz in der offiziellen Dokumentation des verwendeten Agenten:
- ob er
AGENTS.mdunterstützt und ob zusätzliche Konfiguration nötig ist; - in welchen Verzeichnissen er nach Anweisungen sucht;
- ob er Dateien aus Unterverzeichnissen liest;
- wie er sie mit dem Auftrag des Nutzers und anderen Anweisungen zusammenführt.
Eine Datei zum Repository hinzuzufügen bedeutet nicht, dass jede AI-Funktion im Editor sie automatisch verwendet.
Was in die Anweisungen für den Agenten gehört
Am hilfreichsten sind Informationen, die Rätselraten vermeiden: tatsächlich verwendete Befehle, die Speicherorte wichtiger Dateien und die Grenzen der beauftragten Änderung. Eine allgemeine Aufforderung wie „Schreibe guten Code“ sagt dem Agenten nicht, wie er das Ergebnis überprüfen soll.
Eine Beispieldatei für ein JavaScript-Projekt mit npm kann so aussehen. Die Befehle sind nur dann sinnvoll, wenn sie zur Konfiguration des jeweiligen Repositorys passen:
## Arbeit am Projekt
## Ausführen und Überprüfen
- Installiere Abhängigkeiten mit dem Befehl `npm ci`.
- Führe Tests mit dem Befehl `npm test`.
- Prüfe die Einhaltung der Code-Regeln mit dem Befehl `npm run lint`.
- Wenn du eine Prüfung nicht ausführen kannst, gib den Grund an.
## Dateiorganisation
- Der Anwendungscode liegt in `src/`.
- Bearbeite dieses Verzeichnis nicht von Hand: `generated/`.
## Umfang der Änderungen
- Füge ohne Zustimmung des Nutzers keine Abhängigkeiten hinzu.
- Füge bei einer Fehlerbehebung einen Test hinzu, der den Fehler reproduziert.
- Verbinde die Fehlerbehebung nicht mit davon unabhängigen Aufräumarbeiten am Code.
Gib bei einem Projekt mit mehreren Anwendungen für jeden Befehl an, aus welchem Verzeichnis er ausgeführt werden muss. Wenn Tests einen zusätzlichen Dienst benötigen, beschreibe diese Voraussetzung und wie sich die Umgebung sicher vorbereiten lässt. Schreibe keine Passwörter, Token oder sonstigen Geheimnisse in die Anweisungen.
Wirksamkeit prüfen und die Datei aktuell halten
Eine kleine Aufgabe eignet sich gut zur Überprüfung, etwa die Korrektur der Validierung eines einzelnen Formularfelds. Beobachte, ob der Agent die richtigen Befehle verwendet, automatisch erzeugte Dateien unverändert lässt und auf nicht ausgeführte Tests hinweist. Falls das Werkzeug die eingelesenen Anweisungen anzeigt, prüfe auch diese Anzeige.
Wenn der Agent einen Fehler macht, kläre zunächst, ob er die Datei gelesen hat. Weitere Verbote hinzuzufügen hilft nicht, wenn das Werkzeug die Datei nicht unterstützt oder sie am falschen Ort liegt. Wurde die Anweisung gelesen, ersetze eine unklare Formulierung durch eine konkrete Handlung oder Bedingung.
Behandle AGENTS.md als Teil der laufend gepflegten Dokumentation: Aktualisiere die Datei, wenn sich Befehle, Verzeichnisstruktur oder Testabläufe ändern. Setze Zugriffsbeschränkungen durch Berechtigungen und die Konfiguration der Umgebung durch, nicht allein durch Sätze in der Datei. Halte zunächst funktionierende Prüfbefehle und die wichtigsten Einschränkungen fest und überprüfe sie anschließend anhand einer kleinen Aufgabe.
Siehe auch: Was ist GitHub?
Lesen Sie auch
