So schreibst du eine AGENTS.md, die deinem KI-Coding-Agenten wirklich hilft

Wenn du einen KI-Coding-Agenten an einem echten Projekt genutzt hast, hast du wahrscheinlich den Moment erlebt, in dem er den falschen Test-Befehl ausführt, deinen Formatter ignoriert oder einen Helfer neu erfindet, den du schon hast. Die Lösung ist meist kein klügeres Modell — es ist, dem Agenten den projektspezifischen Kontext zu geben, den er nicht erschließen kann. Dafür ist eine AGENTS.md-Datei da.

Was AGENTS.md ist

AGENTS.md ist ein einfaches, offenes Markdown-Format, das Coding-Agenten einen vorhersehbaren Ort gibt, um Projektkontext und Anweisungen zu finden. Es begann als Zusammenarbeit zwischen OpenAI Codex, Amp, Google Jules, Cursor und Factory und wird nun von der Agentic AI Foundation unter der Linux Foundation betreut. Über 25 Tools lesen es — darunter Codex, Cursor, VS Code, GitHub Copilot, Aider, Windsurf, JetBrains Junie, Zed und goose — und es taucht in mehr als 60.000 Open-Source-Repositories auf.

Stell es dir als eine README vor, die für den Agenten statt für einen Menschen geschrieben ist: Die README erklärt dein Projekt einem neuen Mitwirkenden; AGENTS.md sagt dem Agenten die Dinge, die er sonst falsch raten würde. (Claude-Code-Nutzer werden CLAUDE.md als das Äquivalent wiedererkennen; viele Teams pflegen beide oder verlinken eine symbolisch auf die andere.)

Wohin sie gehört

Leg AGENTS.md ins Wurzelverzeichnis des Repositories. In einem Monorepo füge verschachtelte Dateien in jedes Paket ein — Agenten lesen die nächstgelegene Datei im Verzeichnisbaum, sodass eine packages/api/AGENTS.md Vorrang vor der Wurzel-Datei hat, wenn der Agent in diesem Ordner arbeitet. So bekommen ein Python-Service und ein TypeScript-Frontend jeweils maßgeschneiderte Anweisungen.

Was hineingehört

Das Format ist einfach Markdown — nutze beliebige Überschriften. Häufig nützliche Abschnitte sind:

• Build- und Test-Befehle — die exakten Befehle, keine Näherungen
• Codestil — Formatter, Linter und jede Konvention, die ein Linter nicht abfängt
• Testanweisungen — wie man einen einzelnen Test ausführt, was vor einer abgeschlossenen Änderung bestehen muss
• Sicherheitsüberlegungen — Dateien oder Operationen, die nie angefasst werden dürfen
• Commit- / PR-Konventionen — Nachrichtenformat, Branch-Benennung
• Deployment-Schritte — nur wenn der Agent sie anfassen soll

Hier ein minimales, signalstarkes Beispiel:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (do NOT run in CI)
- Test a single file: `pnpm vitest run path/to/file.test.ts`
- Lint + typecheck before any commit: `pnpm check`

## Conventions
- Use the existing `db()` helper in `src/lib/db.ts`; never open a raw client.
- Dates are stored as UTC ISO strings. Never use `Date.now()` in tests.

## Do not touch
- `src/generated/**` is codegen output. Edit the schema, then run `pnpm gen`.

Beachte, was nicht drinsteht: keine Architektur-Vorlesung, keine Wiederholung der Ordnerstruktur, kein "dies ist eine moderne Web-App, gebaut mit Best Practices". Das ist Absicht.

Kürzer ist meist besser

Es gibt die Versuchung, den Agenten zu bitten, dir eine riesige AGENTS.md zu generieren. Widersteh ihr. Eine ETH-Zürich-Studie von 2026, berichtet von InfoQ, maß die tatsächliche Wirkung dieser Dateien und fand, dass der Effekt marginal und gemischt ist. LLM-generierte Kontextdateien senkten die Aufgabenerfolgsraten im Schnitt um etwa 3 %, während sie die Inferenzkosten um über 20 % erhöhten. Von Menschen geschriebene Dateien halfen bescheiden — rund 4 % Zuwachs beim Erfolg — drängten Agenten aber dennoch zu mehr Schritten und erhöhten die Kosten um bis zu ~19 %.

Der Mechanismus ist aufschlussreich: Agenten befolgen pflichtbewusst, was immer die Datei sagt, sodass ein ausuferndes Dokument ihnen aufträgt, zusätzliche Tests auszuführen, mehr Dateien zu lesen und Qualitätsprüfungen durchzuführen, die für die anstehende Aufgabe nicht nötig waren. Die Empfehlung der Forscher: Verzichte ganz auf automatisch generierte Kontextdateien und beschränke von Menschen geschriebene Anweisungen auf nicht erschließbare Details — das spezifische Tooling und die maßgeschneiderten Befehle, die der Agent wirklich nicht selbst entdecken kann.

Mit anderen Worten: Jede Zeile sollte sich ihren Platz verdienen, indem sie einen konkreten Fehler verhindert, den du den Agenten tatsächlich hast machen sehen.

Ein Workflow, der funktioniert

1. Starte leer. Schreibe keine AGENTS.md, bis du den Agenten etwas falsch machen gesehen hast.
2. Füge die Behebung hinzu, nicht die Theorie. Wenn er den falschen Test-Befehl ausführt, füge den richtigen hinzu. Wenn er eine Datei auf deine Art neu formatiert und der Linter sich beschwert, füge die Regel hinzu.
3. Halte es knapp. Wenn eine Zeile nur wiederholt, was der Agent aus der package.json oder den Ordnernamen lesen könnte, lösche sie.
4. Nutze Verschachtelung für Monorepos, damit jede Paket-Datei klein bleibt.
5. Lies sie monatlich erneut. Veraltete Anweisungen sind schlimmer als keine — ein Agent, der einen überholten Build-Befehl befolgt, scheitert selbstbewusst.

Die besten AGENTS.md-Dateien lesen sich wie ein knapper Onboarding-Spickzettel für den einen Teamkollegen, der nie vergisst, aber auch nie erschließt. Schreib die Dinge auf, die er nicht erraten kann, und nichts sonst.