So schreibst du eine AGENTS.md-Datei, damit jeder KI-Coding-Agent dein Projekt versteht

Wenn du jemals zugesehen hast, wie ein KI-Coding-Agent den falschen Testbefehl ausführt, Code in einem Stil formatiert, den dein Projekt verbietet, oder einen Helfer neu erfindet, der bereits existiert, dann ist die Lösung meist kein klügeres Modell — es ist Kontext. AGENTS.md ist die Standardmethode, um Agenten diesen Kontext zu geben, und sie funktioniert über nahezu jedes Werkzeug hinweg.

Was AGENTS.md eigentlich ist

AGENTS.md ist eine "README für Agenten": eine einfache Markdown-Datei, die du im Stammverzeichnis deines Repositorys ablegst, um KI-Coding-Werkzeugen mitzuteilen, wie dein Projekt funktioniert (agents.md). Es ist keine neue Konfigurationssprache — es gibt keine Pflichtfelder und keine spezielle Syntax. Verwende beliebige Markdown-Überschriften.

Das Format ist deshalb bedeutsam, weil es wirklich werkzeugübergreifend ist. Stand Mitte 2026 wird es nativ gelesen von OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Devin, Aider, Zed, VS Code, JetBrains Junie und Dutzenden weiteren — 28+ Werkzeuge und 60.000+ Open-Source-Repositories (agents.md; Codersera). Es wird inzwischen von der Agentic AI Foundation der Linux Foundation betreut, neben Anthropics Model Context Protocol. Auch Claude Code liest AGENTS.md, wobei sein reichhaltigeres natives Format weiterhin CLAUDE.md ist (DeployHQ).

Eine Datei, und die meisten deiner Werkzeuge verhalten sich einheitlich.

Warum eine Datei besser ist, als sich im Chat zu wiederholen

Wenn du Anweisungen in eine Chat-Nachricht einfügst, leben sie für genau eine Unterhaltung. Die nächste Sitzung — oder das nächste Teammitglied, oder ein Cloud-Agent, der deine Aufgabe über Nacht ausführt — beginnt bei null. Eine AGENTS.md wird zu Beginn jedes Laufs automatisch geladen, sodass deine Konventionen standardmäßig durchgesetzt werden, statt davon abzuhängen, ob du daran gedacht hast, sie zu erwähnen. Das ist der ganze Sinn: Projektwissen aus deinem Kopf und aus wegwerfbaren Chats herauszuholen und in eine Datei zu bringen, die die Werkzeuge jedes Mal lesen.

Was hineingehört

Denke daran, was ein kompetentes neues Teammitglied am ersten Tag brauchen würde — genau das braucht auch ein Agent. Die nützlichsten Abschnitte sind:

• Projektüberblick — ein Absatz darüber, was das hier ist und welcher Tech-Stack verwendet wird.
• Setup- und Build-Befehle — die genauen Befehle zum Installieren, Ausführen und Bauen.
• Testen — wie man Tests ausführt, und die Regel, dass Tests bestehen müssen, bevor eine Änderung als fertig gilt.
• Code-Stil — Formatierer, Linter, Namenskonventionen, zu bevorzugende oder zu vermeidende Muster.
• Commit- und PR-Richtlinien — Nachrichtenformat, Branch-Regeln, was nicht angefasst werden darf.
• Fallstricke — alles nicht Offensichtliche, worüber man stolpert.

Sei konkret. "Schreibe sauberen Code" sagt einem Agenten nichts. "Verwende pnpm, nicht npm; führe pnpm test vor dem Fertigstellen aus; bearbeite niemals Dateien in src/generated/" ist durchsetzbar.

Ein konkretes Beispiel

Hier ist eine kompakte AGENTS.md für eine typische Web-App:

# AGENTS.md

## Project
Next.js 15 + TypeScript storefront. Package manager is pnpm.

## Setup & commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`

## Testing
- Run all tests: `pnpm test`
- All tests must pass before a task is considered done.

## Code style
- TypeScript strict mode; no `any`.
- Format with Prettier (`pnpm format`) — do not hand-format.
- Prefer named exports. Reuse helpers in `src/lib/` before writing new ones.

## Do not touch
- `src/generated/**` is auto-generated. Never edit by hand.
- Never commit `.env` files.

Gib das an Claude Code, Cursor oder Copilot weiter, und jedes davon übernimmt dieselben Regeln.

Monorepos: verwende verschachtelte Dateien

In einem Monorepo kannst du eine AGENTS.md in jedem Paket sowie eine im Stammverzeichnis ablegen. Wenn ein Agent in einem Unterverzeichnis arbeitet, gewinnt die nächstgelegene Datei (agents.md). Halte gemeinsame Konventionen im Stammverzeichnis und paketspezifische Befehle in den verschachtelten Dateien, damit ein Agent, der packages/api/ bearbeitet, die Build- und Testbefehle dieses Pakets automatisch erhält.

AGENTS.md vs. CLAUDE.md vs. Cursor-Regeln

Möglicherweise hast du bereits werkzeugspezifische Dateien wie CLAUDE.md oder .cursor/rules. Du musst sie nicht wegwerfen. In der Praxis legen Teams die gemeinsamen, werkzeugunabhängigen Konventionen in AGENTS.md ab — das, was jeder Agent braucht — und behalten werkzeugspezifische Ergänzungen in der nativen Datei für das Werkzeug, das reichhaltigere Funktionen unterstützt (DeployHQ). Claude Code etwa liest beide, wobei CLAUDE.md sein ausdrucksstärkeres Format ist. Ein gängiges Muster ist, eine kanonische AGENTS.md zu pflegen und, wo ein Werkzeug seine eigene Datei benötigt, diese Datei auf AGENTS.md verweisen zu lassen, sodass es eine einzige Quelle der Wahrheit gibt. Beginne mit AGENTS.md; greife nur dann zur werkzeugspezifischen Datei, wenn du eine Funktion brauchst, die nur sie unterstützt.

Halte es kurz und spezifisch

Mehr ist nicht besser. Eine riesige AGENTS.md, die deinen gesamten Styleguide wiederholt, konkurriert um die Aufmerksamkeit des Modells und verschüttet die Regeln, die tatsächlich wichtig sind. Ziele auf die Handvoll Dinge ab, die ein Agent ohne Anleitung falsch machen wird — der nicht offensichtliche Befehl, das Verzeichnis, das nicht angefasst werden darf, das Muster, das deine Codebasis bevorzugt. Wenn eine Regel bereits aus dem Code offensichtlich ist, musst du sie wahrscheinlich nicht aufschreiben.

So bleibt sie nützlich

Eine AGENTS.md verdient sich ihren Platz nur, wenn sie wahr bleibt. Behandle sie wie Code: Wenn sich ein Befehl oder eine Konvention ändert, aktualisiere die Datei im selben Commit. Und wenn ein Agent denselben Fehler zweimal macht, korrigiere ihn nicht nur im Chat — schreibe die Regel auf. Diese eine Gewohnheit verwandelt jeden Fehltritt in eine dauerhafte Korrektur, und sie ist das Wirksamste, was du tun kannst, um KI-Agenten in deinem Projekt zuverlässig zu machen.