AGENTS.md: Der forschungsbasierte Guide, der KI-Agenten 29 % schneller macht
Eine neue arxiv-Studie hat es schwarz auf weiß bewiesen: AGENTS.md-Dateien machen KI-Coding-Agenten 28,6 % schneller und sparen 16,6 % an Tokens. Während die meisten Entwickler noch darüber diskutieren, ob sie eine solche Datei brauchen, nutzen wir bei Context Studios AGENTS.md seit dem ersten Tag — und die Forschung bestätigt jetzt, was wir in der Praxis längst wussten.
In diesem Guide zeigen wir, was die Forschung sagt, wie du AGENTS.md optimal strukturierst und welche konkreten Inhalte den größten Impact haben. Mit realen Beispielen aus unserem eigenen Workspace.
Was ist AGENTS.md?
AGENTS.md ist ein offenes Format für die Anleitung von KI-Coding-Agenten. Entwickelt als README für Agenten, wird die Datei mittlerweile von über 60.000 Open-Source-Projekten auf GitHub genutzt und von einem wachsenden Ökosystem unterstützt — darunter OpenAI Codex, Google Jules, Cursor, Amp und Factory.
Das Konzept ist simpel: Während README.md für Menschen gedacht ist (Projektbeschreibung, Quickstart, Contribution Guidelines), liefert AGENTS.md den Kontext, den KI-Agenten brauchen — Build-Schritte, Test-Befehle, Coding-Konventionen und Projektstruktur.
Seit Januar 2026 wird AGENTS.md von der Agentic AI Foundation unter dem Dach der Linux Foundation betreut. Das Format ist damit kein proprietäres Tool, sondern ein offener Standard.
Die Forschung: 28,6 % schneller, 16,6 % weniger Tokens
Die Studie "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents" (Lulla et al., arxiv 2601.20404, Januar 2026) liefert die ersten empirischen Belege für den Impact von AGENTS.md:
Studiendesign
- 10 Repositories, 124 Pull Requests analysiert
- Agent: GPT-5.2-Codex (OpenAI)
- Paired Design: Jede Aufgabe wurde mit und ohne AGENTS.md ausgeführt
- Isolierte Docker-Umgebungen für Reproduzierbarkeit
- Metriken: Wall-Clock-Zeit und Token-Verbrauch
Die Ergebnisse
| Metrik | Ohne AGENTS.md | Mit AGENTS.md | Verbesserung |
|---|---|---|---|
| Median Laufzeit | 98,57s | 70,34s | −28,64 % |
| Mean Laufzeit | 162,94s | 129,91s | −20,27 % |
| Median Output Tokens | 2.925 | 2.440 | −16,58 % |
| Mean Output Tokens | 5.744 | 4.591 | −20,08 % |
| Mean Input Tokens | 353.010 | 318.651 | −9,73 % |
Die Statistik ist signifikant (Wilcoxon Signed-Rank-Test, p < 0,05).
Warum funktioniert das?
Die Forscher vermuten, dass AGENTS.md die Effizienz steigert, weil Agenten weniger Zeit mit explorativer Navigation verbringen. Statt die Projektstruktur und Konventionen selbst herauszufinden, erhalten sie diese Informationen direkt — weniger Planungsiterationen, weniger wiederholte Anfragen an das Modell.
In der Hacker-News-Diskussion zur Studie bringt es ein Kommentator auf den Punkt: "AGENTS.md is context. Models have been trained to follow context since the dawn of the thing." Im Gegensatz zu Skills, die der Agent aktiv aufrufen muss, ist AGENTS.md passiver Kontext — immer verfügbar, keine Entscheidung nötig.
Was gehört in eine gute AGENTS.md?
GitHub hat 2.500+ Repositories analysiert und die Muster erfolgreicher AGENTS.md-Dateien identifiziert. Die sechs Kernbereiche, die du abdecken solltest:
1. Befehle (Commands)
Setze ausführbare Befehle an den Anfang — mit Flags und Optionen, nicht nur Tool-Namen:
## Setup & Build
- Install: \`pnpm install\`
- Dev Server: \`pnpm dev\`
- Build: \`pnpm build\`
- Lint: \`pnpm lint --fix\`
2. Test-Anweisungen
## Testing
- Unit Tests: \`pnpm test\`
- Single Test: \`pnpm vitest run -t "test name"\`
- E2E Tests: \`pnpm playwright test\`
- Alle Tests müssen grün sein vor dem Commit
3. Projektstruktur
## Architecture
- \`src/app/\` — Next.js 16.1 App Router Pages
- \`src/components/\` — React 19 Components (Shadcn UI)
- \`convex/\` — Convex Backend (Queries, Mutations, Actions)
- \`public/\` — Static Assets
4. Code-Stil
Ein echtes Code-Beispiel schlägt drei Absätze Beschreibung:
## Code Style
- TypeScript strict mode
- Tailwind v4.1 für Styling (CSS-First Config)
- Funktionale Patterns bevorzugen
- Keine \`any\` Types — immer explizite Typen
5. Git-Workflow
## Git
- Branch Naming: \`feat/\`, \`fix/\`, \`refactor/\`
- Commit Messages: Conventional Commits
- Immer \`pnpm lint && pnpm test\` vor dem Commit
6. Grenzen (Boundaries)
Sag dem Agenten, was er niemals anfassen soll:
## Boundaries
- ✅ Immer: Tests schreiben für neuen Code
- ⚠️ Erst fragen: Datenbankschema-Änderungen
- 🚫 Niemals: Secrets committen, .env-Dateien ändern, Produktions-Configs anfassen
Praxis: Unsere AGENTS.md bei Context Studios
Wir betreiben unsere KI-Workflows mit Claude Opus 4.5 und Claude Code 2.1. Unsere eigene AGENTS.md-Datei ist ein lebendes Dokument, das über Monate hinweg gewachsen ist. Hier sind die Kernelemente:
Session-Bootstrapping
Unsere AGENTS.md definiert, was der Agent bei jedem Session-Start lesen soll — Identität (SOUL.md), User-Kontext (USER.md), Tagesnotizen und Langzeitgedächtnis. Das eliminiert die "Wer bin ich?"-Phase komplett.
Memory-System
Statt "mentaler Notizen" (die bei Session-Neustarts verloren gehen) schreiben wir alles in Dateien:
- Tagesnotizen:
memory/YYYY-MM-DD.md— rohe Logs - Langzeitgedächtnis:
MEMORY.md— kuratierte Erinnerungen
Die Regel: "Text > Brain." Was nicht in einer Datei steht, existiert nicht.
Sicherheitsrichtlinien
Klare Grenzen zwischen "sicher ohne Rückfrage" und "erst fragen":
- Frei: Dateien lesen, Web durchsuchen, innerhalb des Workspace arbeiten
- Erst fragen: E-Mails senden, Tweets posten, alles was die Maschine verlässt
Proaktive Heartbeats
Unser Agent wartet nicht nur auf Befehle — er nutzt regelmäßige Heartbeats, um E-Mails zu checken, Kalender zu prüfen und Hintergrundarbeit zu erledigen.
Fortgeschritten: Nested AGENTS.md für Monorepos
Für große Monorepos unterstützt AGENTS.md verschachtelte Dateien. Der Agent liest automatisch die nächstliegende Datei im Verzeichnisbaum. OpenAIs eigenes Repository hat 88 AGENTS.md-Dateien für verschiedene Teilprojekte.
my-monorepo/
├── AGENTS.md ← Globale Anweisungen
├── packages/
│ ├── frontend/
│ │ └── AGENTS.md ← Frontend-spezifisch
│ ├── backend/
│ │ └── AGENTS.md ← Backend-spezifisch
│ └── shared/
│ └── AGENTS.md ← Shared Libraries
Agenten-Kompatibilität
AGENTS.md funktioniert mit allen großen Coding-Agenten:
| Agent | Unterstützung |
|---|---|
| OpenAI Codex | Native — AGENTS.md entstand hier |
| Claude Code 2.1 | Liest AGENTS.md automatisch |
| GitHub Copilot | Volle Unterstützung + Custom Agents |
| Google Jules | Native Unterstützung |
| Cursor | Kompatibel via Rules |
| Amp | Native Unterstützung |
| Aider | Konfigurierbar via .aider.conf.yml |
| Gemini CLI | Konfigurierbar via settings.json |
Die sechs wichtigsten Regeln für deine AGENTS.md
Basierend auf der Forschung, GitHubs Analyse und unserer eigenen Erfahrung:
- Befehle zuerst — Setup, Build, Test, Lint an den Anfang
- Code-Beispiele statt Prosa — Ein Snippet schlägt drei Absätze
- Klare Grenzen setzen — Was der Agent niemals anfassen darf
- Stack spezifisch benennen — "Next.js 16.1 mit TypeScript und Tailwind v4.1", nicht "React-Projekt"
- Lebendiges Dokument — Regelmäßig aktualisieren, wenn sich Konventionen ändern
- Keep it focused — Keine Roman-Länge; Agenten haben Kontextfenster
ROI-Rechnung: Warum sich AGENTS.md sofort lohnt
Nehmen wir ein typisches Entwicklungsteam mit 5 Entwicklern, die jeweils 20 Agent-Tasks pro Tag ausführen:
- Ohne AGENTS.md: 100 Tasks × 98,57s = ~2,7 Stunden Agent-Laufzeit/Tag
- Mit AGENTS.md: 100 Tasks × 70,34s = ~1,95 Stunden Agent-Laufzeit/Tag
- Ersparnis: ~45 Minuten Agent-Laufzeit pro Tag + 16,6 % weniger Token-Kosten
Bei aktuellen API-Preisen und über ein Jahr gerechnet summiert sich das auf tausende Dollar an gesparten Compute-Kosten — ganz abgesehen von der Zeitersparnis für die Entwickler.
Frequently Asked Questions (FAQ)
Was ist der Unterschied zwischen AGENTS.md und README.md?
README.md ist für Menschen — Projektbeschreibung, Installationsanleitung, Contribution Guidelines. AGENTS.md ist für KI-Agenten — Build-Befehle, Test-Anweisungen, Coding-Konventionen und Projektstruktur. Beide Dateien ergänzen sich: Die README erklärt was das Projekt macht, AGENTS.md erklärt wie ein Agent daran arbeiten soll.
Brauche ich für jeden KI-Agenten eine separate Konfigurationsdatei?
Nein. AGENTS.md ist ein offener Standard, der von allen großen Coding-Agenten unterstützt wird — OpenAI Codex, Claude Code 2.1, GitHub Copilot, Google Jules, Cursor und mehr. Eine AGENTS.md-Datei funktioniert überall. Einige Agenten (wie Aider oder Gemini CLI) brauchen eine kurze Konfigurationszeile, um AGENTS.md zu lesen.
Wie lang sollte eine AGENTS.md-Datei sein?
So kurz wie möglich, so lang wie nötig. KI-Agenten haben Kontextfenster (Claude Opus 4.5: 200K Tokens, GPT-5.2: 400K Tokens, Gemini 3 Pro: 2M Tokens), und jede unnötige Anweisung verbraucht wertvolle Kapazität. Die besten AGENTS.md-Dateien konzentrieren sich auf die sechs Kernbereiche: Commands, Testing, Projektstruktur, Code-Stil, Git-Workflow und Boundaries.
Können AGENTS.md-Dateien Sicherheitsrisiken darstellen?
AGENTS.md-Dateien selbst sind reines Markdown ohne ausführbaren Code. Allerdings solltest du keine Secrets, API-Keys oder sensible Konfigurationen in der Datei hinterlegen — diese gehören in Environment-Variablen. Nutze stattdessen die Boundaries-Sektion, um explizit zu definieren, welche Dateien und Verzeichnisse der Agent nicht anfassen darf.
Lohnt sich AGENTS.md auch für kleine Projekte?
Ja. Die Studie zeigt signifikante Verbesserungen bereits bei kleinen Pull Requests (≤ 100 LoC). Selbst eine minimale AGENTS.md mit Setup-Befehlen und Test-Anweisungen kann die Effizienz deiner Agenten messbar steigern. Der Aufwand für die Erstellung beträgt 10–15 Minuten — die Zeitersparnis amortisiert sich nach wenigen Agent-Tasks.
Du nutzt KI-Agenten in deinem Entwicklungsworkflow? Context Studios hilft dir, AGENTS.md-Dateien zu erstellen und deine Agenten-Workflows zu optimieren. Kontaktiere uns für eine kostenlose Beratung.