AGENTS.md – ein offenes Format für AI-Coding-Agenten

 (agents.md)
35 Punkte von GN⁺ 2025-08-21 | 1 Kommentare | Auf WhatsApp teilen
  • AGENTS.md ergänzt die README und ist eine spezielle Datei mit Kontext und Anweisungen, die AI-Coding-Agenten für die Arbeit in einem Projekt benötigen
  • Wird bereits in mehr als 20.000 Open-Source-Projekten genutzt und bündelt Informationen wie Build/Test/Code-Stil, die für Menschen unnötig, für Agenten jedoch wichtig sind
  • Bietet agentenspezifische Anweisungen an einem klaren und vorhersehbaren Ort, hält die README schlank und verbessert zugleich die Effizienz der Zusammenarbeit
  • Eine einzige AGENTS.md ist mit verschiedenen Agenten und Tools kompatibel; in großen Monorepos sind auch separate AGENTS.md-Dateien pro Teilprojekt möglich
  • Ein offener Standard, entstanden durch die Zusammenarbeit mehrerer Ökosysteme wie OpenAI Codex, Cursor und Google Jules

Why AGENTS.md?

  • README.md ist Dokumentation für Menschen und bietet Schnellstart, Projektbeschreibung und Richtlinien für Beiträge
  • AGENTS.md ist ein ergänzendes Dokument für Agenten, das Detailkontext wie Build-/Test-/Code-Regeln enthält, ohne die README unnötig komplex zu machen
  • Warum eine separate Datei?
    • Sie bietet Agenten einen vorhersehbaren Ort für Anweisungen
    • Die README bleibt knapp und auf menschliche Beitragende ausgerichtet
    • Sie liefert präzise, agentenspezifische Anweisungen, die bestehende Dokumentation ergänzen
  • Statt eines proprietären Formats wurde die Bezeichnung eines offenen Standards gewählt, den jeder nutzen kann
  • Eine AGENTS.md ist mit mehreren AI-Coding-Agenten und Tools kompatibel

How to use AGENTS.md?

  • 1. AGENTS.md-Datei erstellen
    • Im Repository-Root ablegen (viele Agenten unterstützen die automatische Erstellung)
  • 2. Wichtige Punkte schreiben
    • Projektüberblick
    • Build- und Test-Befehle
    • Code-Style-Richtlinien
    • Testmethoden
    • Sicherheitsaspekte
  • 3. Zusätzliche Anweisungen aufnehmen
    • Alles, was dem Team mitgeteilt werden soll, z. B. Commit-/PR-Regeln, Sicherheitshinweise, große Datensätze oder Deployment-Schritte
  • 4. Monorepo-Unterstützung
    • Für jedes Paket kann eine eigene AGENTS.md abgelegt werden
    • Agenten lesen die nächstgelegene Datei und befolgen die Anweisungen für das jeweilige Teilprojekt
    • Beispiel: Im OpenAI-Repository gibt es 88 AGENTS.md-Dateien

FAQ

  • Pflichtfelder: keine, normales Markdown kann frei verwendet werden
  • Bei Konflikten: Die nächstgelegene AGENTS.md hat Vorrang, ein expliziter Prompt des Nutzers gilt zuletzt
  • Automatische Ausführung: Im Dokument angegebene Testbefehle werden vom Agenten ausgeführt, um Fehlerbehebungen zu versuchen
  • Aktualisierbarkeit: Kann jederzeit geändert werden und wird als lebendes Dokument gepflegt
  • Migration bestehender Dokumente: Kompatibilität bleibt durch Umbenennen der Datei und einen symbolischen Link erhalten
    • mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Verwandte Beiträge

1 Kommentare

 
GN⁺ 2025-08-21
Hacker-News-Kommentare

  • Bei kleinen Projekten reicht oft schon eine einzelne .md-Datei, aber bei komplexen Projekten habe ich die Erfahrung gemacht, dass eine hierarchische Ordnerstruktur mit index.md deutlich effektiver ist.
    Eine Struktur mit index.md und darunter Dateien wie auth.md oder performance.md ist leicht zu pflegen, und ein LLM oder Agent kann den relevanten Kontext herausziehen, ohne unnötig Tokens zu verbrauchen.
    Die .docs-Dateien werden dadurch sowohl für Menschen als auch für LLMs geeignet, und in index.md kann man auch eine kurze Einführung zu jeder Datei sowie Richtlinien zur Organisation unterbringen.
    Allerdings fände ich einen Namen wie .codebots oder .context intuitiver als .agents.

    • Ich denke nicht, dass wichtige Dateien und Verzeichnisse unbedingt versteckt werden müssen.
      Gerade Dokumentation wird durch das Verstecken eher intransparent; vielleicht ist das Tradition, aber es ist kein gutes Muster.
      Ich habe über einen Namen wie robot_docs nachgedacht.

    • Eigentlich überschneiden sich solche Informationen mit dem, was Beitragende wissen wollen, daher denke ich, dass sie ursprünglich in CONTRIBUTING.md gehören.

    • Diese Struktur wirkt wie ein Leitfaden für Software-Design und Coding-Stil, der sowohl für Menschen als auch für Roboter gedacht ist.
      Ich lege solche .md-Dateien in den Ordner docs/, Claude Code schreibt sie direkt.
      AGENTS.md und CLAUDE.md sollten nur für Roboter gedacht sein, und ob man einen großen Block mit h2-Überschriften aufteilt oder mehrere Dateien verwendet, hat jeweils Vor- und Nachteile.
      Es gibt auch Architektur-Dokumentationsformate wie Arc42, die beides unterstützen.
      Statt in einem großen Markdown-Dokument auf bestimmte Abschnitte zu verweisen, ist es einfacher und fehlerärmer, dafür separate Dateien anzulegen und sie per @-Mention zu referenzieren.
      Wenn man sich auf einen bestimmten Teil konzentrieren muss, sind kleinere Dateien auch für Code-Agenten besser.
      Kleine Dateien sind außerdem praktischer bei Diff-/PR-Reviews.

    • Man kann auch mehrere AGENTS.md-Dateien innerhalb einer Codebasis haben.
      Wenn das Tooling sowohl die AGENTS.md im aktuellen Verzeichnis als auch die im Root-Verzeichnis liest, können die Informationen nah am Code bleiben und trotzdem mit dem gewünschten Ansatz koexistieren.

    • Ich nutze ebenfalls eine ähnliche Struktur und habe gute Ergebnisse erzielt, indem ich in index.md kurze Hinweise zu jeder Datei ergänzt habe.
      Ich experimentiere auch mit verzeichnisspezifischen Regeldateien wie rules.md, die gewünschtes Verhalten festlegen.
      Zum Beispiel kann in einem Verzeichnis mit verschiedenen Services wie realtime-service.ts und queue-service.ts daneben eine rules.md liegen.
      Wenn man diese Regeldatei im Prompt angibt, lassen sich neue Dinge leicht erzeugen; über den Namen muss aber noch mehr nachgedacht werden.

  • Derzeit befinden wir uns in einer Übergangsphase, in der Menschen zusätzliche Spezialanleitungen schreiben müssen, damit Agenten die Codebasis verstehen, also mehr, als Menschen eigentlich benötigen.
    Ich glaube, bald wird das nicht mehr nötig sein.
    Wenn unsere Projektdokumentation von Anfang an ausreichend gründlich wäre, könnte sie auch alles enthalten, was heute in AGENTS.md steht.
    Wir sollten Dokumentation immer für Menschen schreiben, und die Stärke von LLMs besteht darin, dass sie von Menschen geschriebene Texte lesen können.
    Ich denke, aus dieser Perspektive sollte man das entwerfen.

    • Es ist nicht nur zum Verständnis der Codebasis nützlich, sondern auch, um bestimmte Stilvorgaben festzuhalten, etwa welche Assert-Bibliothek für Tests verwendet werden soll, dass Kommentare verboten sind oder dass strukturiertes Logging genutzt werden soll.
      Für neue Projekte mit kaum vorhandenem Code kann es sogar noch nützlicher sein.

    • Ich erwarte, dass maschinenlesbare Regeln in vielen Bereichen der Gesellschaft stärker eingeführt werden.
      Ein Beispiel sind autonomes Fahren und Verkehrsregeln; Schilder, deren Kontext selbst für Menschen schwer zu erfassen ist, etwa „Bei Rot rechts abbiegen verboten, an Schultagen 7–9 Uhr“, sind für Maschinen noch schwieriger.
      Letztlich werden Behörden Signale wohl so ändern müssen, dass weniger Kontext nötig ist oder dass sie maschinenlesbar sind, etwa per QR-Code.
      Ohne solche Veränderungen werden Maschinen häufig gegen Regeln verstoßen.

    • Ich denke, in Bereichen wie Business-Logik wird man auch künftig spezielle Anleitungen für Agenten brauchen.
      Was gebaut wird, welche Absicht dahintersteht und was das endgültige Ziel des Projekts ist, kann eine Maschine nicht verstehen, wenn ein Mensch es ihr nicht konkret erklärt.
      Auch bei Architekturfragen hat jeder andere Maßstäbe; wenn man ein Modell im Kopf hat, hilft das beim Verständnis realer Änderungen, und genau das ist letztlich der eigentliche Engpass.

    • Insgesamt stimme ich zu, aber bei bestimmten Informationen, also Dingen, die man jedes Mal unbedingt im Kontext haben will, entsteht schon der Wunsch, sie in einer separaten Datei zwangsweise einzubinden.

    • Wenn wir die Regeln und Annahmen, die wir implizit voraussetzen, nicht dokumentieren, kann ein LLM sie nicht kennen.
      Es kann zwar einiges aus dem Code ableiten, aber niemals zu 100 %, deshalb ist es wichtig, Anforderungen explizit aufzuschreiben.

  • AGENTS.md erfüllt am Ende eine ähnliche Rolle wie README.md, zieht aber mehr Hype an, und es ist erstaunlich, dass die Leute den Inhalt tatsächlich ausfüllen.
    Menschen tun sich oft schwer damit, Dokumentation für andere Menschen zu schreiben, aber für Roboter schreiben sie plötzlich eifrig; das ist interessant.
    Das erinnert an ergonomisches Design, das eigentlich nur für eine Minderheit gedacht war, am Ende aber für alle besser funktioniert, etwa bei einem Griffdesign.

    • Eher umgekehrt: Niemand hatte Motivation, Dokumentation zu schreiben, weil Menschen sie ohnehin nicht lesen.
      Eine CLAUDE.md für Agenten schreibt man einmal, und danach wird sie potenziell von 1000 Agenten gelesen, das motiviert eher.

    • Reicht es nicht ohnehin, einfach nur das Nötigste in README.md zu schreiben?

    • In der Praxis lesen selbst Agenten diese Dokumente oft nicht, oder sie vergessen alles wieder, wenn man ihnen noch ein paar weitere Anweisungen gibt.

    • Die aktuelle Lage ist letztlich dadurch entstanden, dass Menschen versuchen, menschliche Entwickler — einschließlich sich selbst — aktiv aus dem Entwicklungsprozess herauszunehmen, wodurch Agenten unbedingt passende Anleitungen brauchen.
      Der Wunsch, jede menschliche Beteiligung an der Softwareentwicklung zu eliminieren, ist stärker geworden.

build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors. Die Idee, solche Dinge auszulagern, fühlt sich wirklich so an, als wüsste man nicht mehr, wie die Welt gerade funktioniert.

  • Halb im Scherz wurde erwähnt, dass die aktuelle Stimmung eben vibe coding sei.
    Ich meine, ich habe früher schon ähnliche Meinungen gesehen, dass Dokumentation für Bots letztlich nicht viel anders ist als gute Dokumentation allgemein.

  • Am Ende wirkt es so, als würde man nur sagen: „Erstelle eine AGENTS.md und fülle sie mit Magie“, und dann auf die eigentliche Website verlinken.

  • In meinem Fall entwickle ich einen Coding-Agenten, der mehr als 5.000 Repositories verwaltet.
    Der Zustand des Agenten wird in einem versteckten .agent-Verzeichnis gespeichert, das Konfigurationsordner für jede Agentenrolle und klare rollenspezifische Anweisungen enthält.
    Im Projektordner gibt es einen Ordner agents, in dem mehrere Dateien nach Rollen aufgeteilt und im Stil <Role> <instruction> verwaltet werden.
    Der Agent liest nur die Dateien, für die eine Rolle definiert ist, und speichert den Zustand in einem dot<coding agent name>-Ordner.
    Die Initialisierung erfolgt mit /init; statt einfach das gesamte Repository zu indizieren, wird eine High-Level-Zusammenfassung der gesamten Architektur und Logik erzeugt.
    Diese Zusammenfassung wird im Editor als umschaltbare „ghost comments“ bereitgestellt und als Metadaten nicht in den eigentlichen Code committet.
    Durch ein ausgefeiltes Mapping-System ist jede Zusammenfassung präzise mit Codezeilen verknüpft.
    Als ich anfangs RAG direkt auf den Code angewandt habe, bekam ich nicht die gewünschten Ergebnisse, deshalb habe ich die jetzige Struktur eingeführt.
    Aktuell nutze ich ein hybrides Suchmodell, das schnelle AST-basierte syntaktische Suche mit semantischer Exploration auf Basis der Zusammenfassungen kombiniert.
    Wenn man zum Beispiel fragt: „Wie funktioniert die Authentifizierung in dieser App?“, findet die syntaktische Suche nur Funktionen mit Wörtern wie login, während die semantische Suche über die Zusammenfassungen den gesamten Authentifizierungsfluss narrativ erfasst und verteilte Inhalte über mehrere Dateien hinweg verbindet — das wirkt fast wie Magie.

    • Ergänzend dazu könnte man eine Hierarchie von Zusammenfassungen aufbauen, also in Form eines B-Baums oder eines normalen Baums.
      Dann gäbe es Zusammenfassungen auf Ebene von Methode/Klasse/Modul, wobei jede Ebene auf die darunterliegende verweist.
      RAG könnte dann je nach semantischer Anfrage so tief hinabsteigen wie nötig, und jede Stufe fasst die darunterliegenden Inhalte zusammen, reduziert also die Informationsmenge und bewahrt zugleich die entscheidende Bedeutung.
      Besonders gut funktioniert das, wenn der Code sauber abstrahiert ist.
      Ein Beispiel: Bei einer Funktion wie add(n1, n2) reicht der Name aus, um die Bedeutung zu verstehen, sodass man die Implementierung nicht kennen muss. In realen Funktionen gibt es aber oft zusätzlich Logging, Caching und andere Aufgaben, sodass man je nach Situation doch den tatsächlichen Code in den Kontext aufnehmen muss.

    • Ich würde gern eine ausführlichere Erklärung dazu hören.

  • Es fühlt sich an, als würden Menschen langsam dazu gedrängt, Projektdokumentation endlich ordentlich zu schreiben.

    • Das ist zwar scherzhaft gemeint, aber genau damit werbe ich tatsächlich im Team.
      Selbst wenn LLMs die Produktivität nicht massiv steigern, sorgen sie am Ende immerhin dafür, dass die Dokumentation deutlich besser wird.

    • „Mission. Fucking. Accomplished.“ xkcd 810

  • Ich bin noch nicht überzeugt, dass man README.md und AGENTS.md wirklich trennen muss.

  1. Unterschiede im Schreibstil (in Agentendokumenten ist GROSSSCHREIBUNG zur Hervorhebung okay, in Dokumenten für Menschen störend)
  2. Knappheit versus Vollständigkeit (Agentendokumente sollten nur Kerninformationen enthalten, menschengerechte Dokumente möglichst alles)
  3. Unterschiedlicher Informationsbedarf (LLMs brauchen andere Informationen als Menschen)
    Gründe gegen eine Trennung sind:
  4. Doppelter Pflegeaufwand (im Kern dieselben Dinge an zwei Orten separat pflegen zu müssen).

  • README.md wirkt inzwischen eher wie eine Art Marketing- oder Landingpage, während AGENTS.md und CLAUDE.md die Orte sind, an denen man die eigentlichen Inhalte zu Code, Architektur und Verwendung findet.

  • Beim Lesen der Beispiele dachte ich dasselbe; eigentlich müsste doch ein einziges gutes README.md genügen, wenn dort alles enthalten ist.

  • README ist für Menschen, AGENTS.md und Ähnliches sind für LLMs.
    Nutzung und Installation gehören ins README, Kompilierung und Tests, Architekturentscheidungen, Coding-Standards und die Repository-Struktur in die Agentendokumente.

  • Man muss auch die Größenbeschränkungen des Kontexts bei LLMs bedenken.
    README.md ist oft sehr umfangreich und lässt sich nicht komplett in den Kontext packen.
    In AGENT.md stehen dann kompakt nur die Befehle, die ein LLM unbedingt braucht, etwa Tests oder Build-Kommandos.
    Es kann Überschneidungen mit dem README geben, aber man will vermeiden, unnötige Inhalte immer wieder in den Kontext zu schicken.

  • War das Versprechen von AI nicht gerade, dass wir gar nicht auf exakte Formate bestehen müssen, weil die Maschine schon zurechtkommt, solange wir es nur so aufschreiben, wie wir möchten?

    • Tatsächlich wurde nur der Dateiname standardisiert, und es war die richtige Entscheidung, beim Inhalt kein bestimmtes Format zu erzwingen, sodass jeder schreiben kann, wie er möchte.
      AGENTS.md ist normales Markdown, man kann also beliebige Überschriften verwenden, und der Agent parst den Text.

    • Trotzdem behalten Struktur und Format bis zu einem gewissen Grad ihre Bedeutung.
      Nicht auf dem Niveau exakter Programmiersyntax, aber dennoch.

    • Am Ende läuft es darauf hinaus, den Inhalt klar zu formulieren.
      Je länger Dokumentation wird, desto vorteilhafter ist aus menschlicher Sicht ein strukturierter Ansatz für die Wartbarkeit.

  • Jeder verwendete Agent — Claude Code, Gemini, Aider — hat einen anderen Dateinamen.
    Eine Standardisierung wäre gut, aber aktuell nehme ich den Aufwand in Kauf, mit ruler mehrere Formate automatisch zu erzeugen.
    Vor allem verbraucht jeder Agent seine MCP-Konfigurationsdateien anders, daher erwarte ich kurzfristig keine echte Standardisierung.
    ruler

    • Etwas zynisch betrachtet, liegt das wohl an Bemühungen, Vendor Lock-in zu schaffen.
      Standardisierung könnte zur Austauschbarkeit führen, und genau das scheinen Anbieter vermeiden zu wollen.

    • Jules verwendet AGENTS.md, was zeigt, dass Google diesen Standard mitträgt.
      Wenn Gemini Code Assist bestehen bleibt, wird es AGENTS.md voraussichtlich ebenfalls unterstützen.
      In der Aider-Dokumentation wird kein bestimmter Dateiname erwähnt; falls es dazu einen Link gibt, würde ich ihn gern sehen.
      Anthropic scheint derzeit der einzige Anbieter zu sein, der noch keinen standardisierten Dateinamen unterstützt.

    • Es ist etwas schade, dass ein Tool wie ruler tatsächlich nötig ist.

  • Es ist eine seltsam wirkende Website.
    Da sie von OpenAI erstellt wurde, fragt man sich, ob es um Besuchergewinnung und Marketing-Positionierung geht.
    Tatsächlich wird aber gar kein Format festgelegt, sondern nur ein Dateiname.
    Auffällig ist auch, dass Anthropic/Claude fehlt; per symbolischem Link könnte man CLAUDE.md aber auf AGENTS.md zeigen lassen.

    • Tatsächlich wurde sie von Sourcegraph erstellt und existiert schon seit Mai.
      Früher war es agent.md, inzwischen wird per 301 auf agents.md weitergeleitet.
      Siehe alter Link.
      Es gibt auch eine offizielle Ankündigung.
      Anscheinend gab es kürzlich eine Partnerschaft mit OpenAI.
      Interessanterweise hieß es anfangs agent.md, jetzt aber agents.md.

    • Dass Claude nicht auf der Liste steht, liegt daran, dass nur Claude die standardisierte Dateinamenskonvention bislang noch nicht unterstützt.