Blog

AGENTS.md Dateien erstellen: Anleitung für API-Entwicklungsteams

Ashley Innocent

Ashley Innocent

29 April 2026

AGENTS.md Dateien erstellen: Anleitung für API-Entwicklungsteams

Code-Agenten lesen Ihr Repository, bevor sie Code schreiben, und die erste Datei, die sie lesen, ist AGENTS.md. Dies ist die offene Konvention, auf die sich Codex CLI, Cursor, Aider, OpenHands und eine wachsende Liste anderer Tools geeinigt haben, damit eine einzige Kontextdatei in jedem Agenten funktioniert. Für API-Entwicklungsteams ist diese Datei der Unterschied zwischen einem Agenten, der die richtigen Tests gegen einen echten lokalen Server ausführt, und einem, der Endpunkte halluziniert und einen fehlerhaften Client ausliefert.

Dieser Leitfaden behandelt, was AGENTS.md ist, warum API-Teams sie als Produktionscode behandeln sollten, die wichtigen Abschnitte für OpenAPI-First-Repos, konkrete Beispiele und wie man sie aktuell hält, wenn sich die API weiterentwickelt. Am Ende kombinieren wir sie mit Apidog, damit der Vertragstest-Workflow des Agenten auf einer echten Spezifikation basiert.

Schaltfläche

TL;DR

Was AGENTS.md wirklich ist

AGENTS.md ist eine Markdown-Datei, die Sie im Root-Verzeichnis eines Repositories ablegen. Code-Agenten suchen beim ersten Kontakt mit der Codebasis danach und behandeln ihren Inhalt als die maßgebliche Anweisung, wie das Projekt funktioniert. Die Konvention entstand innerhalb der Codex CLI von OpenAI und wurde als offener Standard veröffentlicht, damit andere Tools dieselbe Datei lesen konnten. Ab diesem Jahr lesen Codex CLI, Cursor, Aider, Claude Code, OpenHands, Sourcegraph Cody und mehrere kleinere Agenten diese Datei.

Drei Dinge machen sie nützlich:

  1. Eine Datei, jeder Agent. Sie schreiben den Kontext einmal und jeder Agent im Werkzeugkasten des Teams nimmt ihn auf. Keine Konfigurationsabweichung pro Tool.
  2. Einfaches Markdown. Keine DSL, kein Schema, kein Build-Schritt. Ingenieure bearbeiten sie wie jedes andere Dokument.
  3. Lebt neben dem Code, den sie beschreibt. Wenn sich das Build-Skript ändert, ändert sich die Datei im selben Pull Request. Der Diff macht die Änderung für Reviewer und den Agenten sichtbar.

Der engste Verwandte ist CLAUDE.md, den Anthropic's Claude Code liest. Die beiden Formate überschneiden sich stark; viele Projekte halten eine AGENTS.md, die symbolisch mit CLAUDE.md verknüpft ist, damit beide Tools ohne zusätzliche Konfiguration funktionieren. Das Codex-Team und Anthropic haben sich öffentlich darauf geeinigt, die Formate in Zukunft kompatibel zu halten.

Warum API-Entwicklungsteams sie dringender benötigen als die meisten anderen

API-Teams befinden sich an einer heiklen Schnittstelle: Der Code ist klein, die Verträge sind groß, und die Folgen, wenn man beides falsch macht, sind für jeden nachgeschalteten Client sichtbar. Ein Agent, der nicht weiß, dass die Spezifikation in openapi.yaml liegt, wird Typen aus der Antwortform umschreiben, die er aus Trainingsdaten erinnert. Ein Agent, der den Vertragstestbefehl nicht kennt, wird Code committen, der zwar kompiliert, aber die Client-SDK-Pipeline unterbricht.

Eine gut geschriebene AGENTS.md für ein API-Repository leistet vier Dinge:

Wenn die Datei diese vier Dinge tut, sieht die Agenten-Ausgabe nicht mehr wie die eines Junior-Entwicklers aus, der die README übersprungen hat, sondern wie die eines Teamkollegen.

Die Struktur, die für API-Repos funktioniert

AGENTS.md hat kein vorgeschriebenes Schema. Die Community hat sich auf einige Abschnitte geeinigt, die in fast jeder gut abgestimmten Datei auftauchen. Für ein API-Team ist die folgende Reihenfolge ein guter Standard.

1. Projektzusammenfassung (3-5 Zeilen)

Geben Sie an, was die API tut, wer die Konsumenten sind und welche Sprache und welches Framework der Server verwendet. Bleiben Sie sachlich.

# Projekt: Zahlungs-API

Interner Zahlungsdienst für die Acme-Produktlinie. Konsumenten sind
mobile, Web- und Partner-Backends. Server ist Go 1.23 auf Echo, Postgres
17 für den Speicher und eine Redis-basierte Idempotenzschicht.

Dieser Block sagt dem Agenten, welche Sprache standardmäßig verwendet werden soll, welche Idiome zu befolgen sind und welche Clients kaputt gehen, wenn Sie die falsche Antwortform ausliefern.

2. Schnellstartbefehle

Fünf bis zehn Befehle, die der Agent ständig ausführen wird. Fügen Sie immer den Befehl ein, verlinken Sie niemals auf ein Wiki.

## Befehle

| Absicht | Befehl |
|--------|---------|
| Abhängigkeiten installieren | `make deps` |
| Server lokal starten | `make dev` (bindet 127.0.0.1:8080) |
| Unit-Tests ausführen | `make test` |
| Vertragstests gegen den lokalen Mock ausführen | `make contract` |
| Lint | `make lint` |
| Clients aus Spezifikation neu generieren | `make codegen` |
| Migrationen anwenden | `make migrate` |

Wenn ein Befehl eine Umgebungsvariable benötigt, um zu funktionieren, platzieren Sie den Namen der Umgebungsvariablen daneben. Agenten sind gut darin, Variablen zu exportieren; sie sind schlecht im Raten.

3. Der OpenAPI / GraphQL-Spezifikationsabschnitt

Dies ist der wertvollste Abschnitt in einem API-Repository. Sagen Sie dem Agenten, wo sich die Spezifikation befindet, wie die Spezifikation mit generiertem Code zusammenhängt und in welche Richtung Änderungen fließen.

## Single Source of Truth

- Die Spezifikation befindet sich unter `apis/payments/openapi.yaml`.
- Generierte Clients leben in `gen/clients/{go,ts,python}` und DÜRFEN NICHT manuell bearbeitet werden.
- Die Generierungspipeline ist `make codegen`. Führen Sie diese nach jeder Spezifikationsänderung aus
  und committen Sie die neu generierten Clients im selben PR.
- Spezifikationsänderungen fließen: Spezifikation -> `make codegen` -> Server-Handler-Updates ->
  Vertragstests -> Auslieferung.

Dieser Block allein beseitigt eine Klasse von Fehlern, bei denen Agenten den generierten Client bearbeiten, um eine Typeninkongruenz zu "beheben", der nächste Codegenerierungslauf die Änderung löscht und der Build zwei Tage später auf mysteriöse Weise fehlschlägt.

4. Mock-Server und Apidog-Anbindung

Wenn Sie Mock-Server betreiben (und das sollten Sie), benennen Sie sie. Listen Sie die URLs, die Spezifikation, aus der sie lesen, und wie man sie startet auf.

## Lokale Server

- Echter Server: `make dev` -> `http://127.0.0.1:8080`
- Apidog Mock-Server: `make mock` -> `http://127.0.0.1:4010`
- Der Mock liest aus derselben `openapi.yaml` und spielt gespeicherte Beispiele
  aus der Apidog-Sammlung unter `apis/payments/apidog/` ab.

Hier verdient Apidog seinen Platz in der Datei. Der Mock-Server, die Spezifikation und die gespeicherten Anforderungsbeispiele bilden einen Vertrag, den der Agent ausführen kann, ohne Aufrufe auf dem echten Backend zu verbrennen. Kombinieren Sie dies mit dem API-Testing ohne Postman-Leitfaden für den zugrunde liegenden Workflow.

5. Authentifizierung und Secrets

Sagen Sie dem Agenten, wie die API authentifiziert und welche Umgebungsvariablen was enthalten. Legen Sie niemals echte Geheimnisse in der Datei ab.

## Authentifizierung

- Produktion verwendet OAuth 2 Client-Zugangsdaten, ausgestellt von Auth0.
- Lokale Entwicklung verwendet einen statischen Entwicklungs-Token; exportieren Sie `DEV_TOKEN` aus `.env.local`.
- Die Apidog-Sammlung verwendet dieselben Umgebungsvariablennamen, sodass sich der Mock und der
  echte Client identisch verhalten.
- Tokens DÜRFEN NICHT committet werden; `.env.local` ist in `.gitignore`.

6. Teststrategie

Ordnen Sie die Testebenen. Agenten werden sie in der von Ihnen angegebenen Reihenfolge ausführen.

## Testen

1. `make test` für Unit-Tests. Schnell, wird bei jeder Änderung ausgeführt.
2. `make contract` für OpenAPI-Vertragstests gegen den Mock. Vor dem
   Zusammenführen jeder Spezifikationsänderung ausführen.
3. `make integration` für End-to-End-Tests gegen einen lokalen Server mit einer
   echten Postgres-Datenbank. Vor dem Zusammenführen in den Hauptzweig ausführen.
4. Staging-Dauerläufe finden nächtlich über GitHub Actions statt; kein lokaler Befehl.

7. Liste der nicht zu berührenden Elemente

Generierter Code, vendored Abhängigkeiten und Migrationen gehören fast immer hierher.

## Nicht manuell bearbeiten

- `gen/**` (neu generiert durch `make codegen`)
- `vendor/**` (verwaltet durch `go mod vendor`)
- `migrations/*.up.sql` nach der ersten nicht angewendeten Migration
- `apis/payments/openapi.yaml` Schemasfeldnamen ohne Eigentümerfreigabe

8. Hausstil

Drei bis fünf Regeln. Bei mehr wird der Agent die falsche auswählen.

## Konventionen

- Fehler geben RFC 7807 Problem-JSON zurück; niemals reine Strings.
- Verwenden Sie snake_case in JSON, camelCase in Go, PascalCase in TS-Clients.
  Die Codegenerierung übernimmt die Zuordnung.
- Idempotenzschlüssel sind für alle POST-Endpunkte erforderlich, die Ressourcen erstellen.
- Neue Endpunkte erfordern einen Vertragstest, der sowohl 200- als auch 4xx-Pfade abdeckt.

Konkretes Beispiel: Eine 90-zeilige Datei, die ihren Zweck erfüllt

Die Versuchung ist groß, 800 Zeilen zu schreiben. Widerstehen Sie ihr. Die folgende Datei deckt einen echten API-Dienst in 90 Zeilen Markdown ab und ist ausreichend, damit jeder größere Agent produktiv arbeiten kann.

# Projekt: Zahlungs-API

Interner Zahlungsdienst für die Acme-Produktlinie. Go 1.23, Echo,
Postgres 17, Redis für Idempotenz. Konsumenten sind mobil, Web,
und Partner-Backends.

## Befehle

| Absicht | Befehl |
|--------|---------|
| Installieren | `make deps` |
| Server starten | `make dev` |
| Unit-Tests | `make test` |
| Vertragstests | `make contract` |
| Lint | `make lint` |
| Clients neu generieren | `make codegen` |
| DB migrieren | `make migrate` |

## Single Source of Truth

- Spezifikation: `apis/payments/openapi.yaml`
- Generierte Clients: `gen/clients/{go,ts,python}` (nicht bearbeiten)
- Bearbeitungsfluss: Spezifikation -> `make codegen` -> Handler -> Vertragstests -> Auslieferung

## Lokale Server

- Echter Server: `make dev` (`http://127.0.0.1:8080`)
- Apidog Mock: `make mock` (`http://127.0.0.1:4010`)
- Apidog-Sammlung: `apis/payments/apidog/`

## Authentifizierung

- Produktion: Auth0 OAuth 2 Client-Zugangsdaten.
- Lokale Entwicklung: statischer `DEV_TOKEN` aus `.env.local`.

## Testreihenfolge

1. `make test`
2. `make contract`
3. `make integration`

## Nicht manuell bearbeiten

- `gen/**`, `vendor/**`
- Angewendete Migrationen in `migrations/`
- Spezifikationsfeldnamen ohne Eigentümergenehmigung

## Konventionen

- RFC 7807 Problem-JSON für Fehler
- snake_case JSON, Codegenerierung handhabt Sprachzuordnung
- Idempotenzschlüssel erforderlich bei POST-Erstellungen
- Jeder neue Endpunkt wird mit einem Vertragstest ausgeliefert

Das ist ausreichend. Fügen Sie Abschnitte nur hinzu, wenn ein Agent zweimal die gleiche falsche Wahl trifft.

Die Datei aktuell halten

Eine veraltete AGENTS.md ist schlimmer als gar keine Datei. Der Agent wird ihr vertrauen und Code auf der Grundlage eines Build-Befehls ausliefern, der nicht mehr funktioniert.

Drei Gewohnheiten halten sie frisch:

  1. Behandeln Sie sie als Produktionscode. Änderungen durchlaufen dieselbe Überprüfung wie jeder andere PR. Prüfer überprüfen, ob Befehlslisten mit dem tatsächlichen Makefile übereinstimmen.
  2. Binden Sie sie in CI ein. Ein kurzes Skript, das die Befehlstabelle parst und jeden Befehl bei einem frischen Checkout ausführt, erkennt Abweichungen schnell. Die meisten Teams schreiben dies in 30 Zeilen Bash.
  3. Aktualisieren Sie sie im selben PR. Wenn Sie einen neuen Testbefehl hinzufügen, versprechen Sie nicht, AGENTS.md später zu aktualisieren. Aktualisieren Sie sie jetzt. Die Kosten betragen zwei Minuten; die Kosten für das Überspringen betragen zwei Wochen Agenten-Verwirrung.

Apidog als Laufzeitvertrag für Ihre AGENTS.md

AGENTS.md gibt dem Agenten Kontext. Die OpenAPI-Spezifikation gibt ihm den Vertrag. Apidog überbrückt die beiden: Es liest die Spezifikation, führt einen lokalen Mock unter der in AGENTS.md aufgeführten URL aus, spielt gespeicherte Anforderungsbeispiele für Tests ab und ermöglicht dem Agenten, echte Antworten zu sehen, ohne Credits für das Live-Backend zu verbrennen.

Das funktionierende Muster:

Für eine tiefere Erklärung des Apidog-Mock-Workflows mit einer echten API deckt der DeepSeek V4 API-Leitfaden dasselbe Muster ab, angewendet auf eine Modell-API anstatt einer Dienst-API.

Häufige Fehler, die API-Teams machen

Nach der Überprüfung dutzender solcher Dateien tauchen immer wieder die gleichen fünf Probleme auf:

  1. Verlinken statt Auflisten. „Siehe Wiki für Build-Befehle.“ Der Agent browsed nicht im Wiki. Fügen Sie die Befehle direkt ein.
  2. Marketingorientierte Prosa. „Unsere erstklassige API-Plattform ermöglicht…“ Der Agent braucht keine Werbepitch. Geben Sie Fakten an.
  3. Veraltete Befehle. Ein Befehl, der im März defekt war, ist im April immer noch in der Datei. Binden Sie CI ein, um dies zu erkennen.
  4. Fehlender Spezifikationsabschnitt. Der nützlichste Block überhaupt. Fügen Sie ihn immer ein.
  5. Keine Do-not-touch-Liste. Der Agent bearbeitet generierten Code. Der nächste Codegenerierungslauf löscht die Bearbeitung. Der Build bricht. Wiederholen.

Wenn Sie eine Ausgangsbasis benötigen, kopieren Sie das obige Beispiel in Ihr Repository, bearbeiten Sie die Projektzusammenfassung und passen Sie die Befehlstabelle an. Sie können eine brauchbare Datei in 20 Minuten ausliefern.

FAQ

Ist AGENTS.md dasselbe wie CLAUDE.md?Die Formate sind kompatibel. Die meisten Teams halten eines von ihnen als Single Source of Truth und verknüpfen das andere symbolisch. Anthropic und OpenAI haben sich öffentlich darauf geeinigt, die Konventionen interoperabel zu halten.

Wo sollte ich die Datei ablegen?Immer im Repository-Root. Einige Agenten lesen auch verschachtelte AGENTS.md-Dateien in Unterverzeichnissen, was für Monorepos nützlich ist. Beginnen Sie mit einer Datei auf Root-Ebene und fügen Sie Unterverzeichnisdateien nur hinzu, wenn eine einzelne Root-Datei zu lang wird.

Wie lang sollte sie sein?200 bis 400 Zeilen sind der Sweet Spot. Darüber hinaus beginnen Agenten, Abschnitte zu überspringen. Wenn Sie mehr Tiefe benötigen, verlinken Sie auf ein separates Dokument mit einer einzeiligen Zusammenfassung.

Sollte ich Codebeispiele hinzufügen?Kurze ja. Lange nein. Bewahren Sie vollständige Beispiele für Tests auf; Agenten lesen auch Tests. Der GPT-5.5 free Codex-Leitfaden erklärt, wie Codex speziell Beispieltests als zusätzliches Signal verwendet.

Liest der Agent die Datei bei jeder Runde neu?Die meisten Agenten lesen sie beim Start der Sitzung und cachen sie. Einige lesen nach großen Dateiänderungen neu. Wenn Sie eine größere Bearbeitung vornehmen, ist das Neustarten der Agentensitzung der sicherste Schritt.

Wie teste ich, ob meine Datei funktioniert?Führen Sie eine neue Agentensitzung ohne weiteren Kontext aus, geben Sie ihr eine kleine Aufgabe („eine 422-Antwort zu POST /payments hinzufügen“) und beobachten Sie, was sie tut. Wenn sie die Spezifikation liest, make codegen ausführt und einen Vertragstest schreibt, erfüllt die Datei ihren Zweck.

Praktizieren Sie API Design-First in Apidog

Entdecken Sie eine einfachere Möglichkeit, APIs zu erstellen und zu nutzen

Kostenlos registrierenDownload