Entwicklungsansatz

AGENTS.md vs. README.md (für KI-Agenten): Was soll Ihren Coding-Agent steuern?

AGENTS.md vs. README.md für KI-Coding-Agenten 2026. AGENTS.md ist jetzt der etablierte Standard (60k+ Repos, Codex, Cursor, Next.js 16.3) — README bleibt wichtig. So nutzen Sie beide.

Aktualisiert am 29. August 2026

Geprüft von Michael Kerkhoff, Stand 29. August 2026

Definition: Coding-Agenten wie Claude Code, Cursor und Codex lesen Ihr Repo, bevor sie es anfassen — aber wo gehören die Anweisungen hin? Jahrelang war README.md die einzige Option; AGENTS.md ist heute der eigens dafür gebaute Standard für Agenten-Anweisungen. Beide sind keine echten Rivalen: README ist die menschliche Eingangstür, AGENTS.md das Anweisungsblatt des Agenten. Dieser Vergleich betrachtet gezielt die Aufgabe „Agenten-Kontext“.
Kategorie: Entwicklungsansatz
Optionen: AGENTS.mdREADME.md (für KI-Agenten)

Detaillierter Vergleich

Eine Gegenüberstellung der wichtigsten Faktoren für Ihre Entscheidung.

AGENTS.md vs README.md (für KI-Agenten)
Faktor	AGENTS.md	README.md (für KI-Agenten)
Zweck & Zielgruppe	Eigens für KI-Agenten gebaut: ein dedizierter Ort für Build-/Test-Befehle, Konventionen und Leitplanken, die der Agent befolgen muss. Gewinner	Zuerst für Menschen geschrieben — Onboarding, Installation und Projektüberblick. Agenten können sie lesen, aber sie ist nicht als Anweisungsblatt gedacht.
Standardisierung & Tool-Unterstützung	Offener Standard, verwaltet von der Linux Foundation (Agentic AI Foundation); von 28+ Tools unterstützt (Codex, Cursor, GitHub Copilot, Aider, Zed, Sourcegraph Amp) und in 60.000+ Open-Source-Repositories vorhanden. Gewinner	Universelle Datei, aber ohne agent-spezifische Konvention — jedes Tool raten, welche Teile des README Anweisungen sind.
Signal statt Rauschen für den Agenten	Enthält nur agentenrelevante Regeln, sodass das Modell nicht von Badges, Lizenzen oder Marketing abgelenkt wird. Gewinner	Mischt Installationsschritte, CI-Badges, Contribution-Hinweise und Marketing — das verwässert die eigentlichen Anweisungen.
Menschliche Eingangstür	Wird von Menschen selten gelesen; GitHub/npm rendern sie nicht als Landing-Dokument.	Der Standard-Einstiegspunkt für Menschen, gerendert auf GitHub, npm und den meisten Registries — für Menschen unersetzlich. Gewinner
Monorepo & verschachteltes Scoping	Unterstützt verschachtelte AGENTS.md-Dateien, die Agenten pro Paket zusammenführen — sauberes Scoping in großen Repos. Gewinner	Ordnerweise READMEs existieren, sind aber kein konventioneller, von Agenten gelesener Scoping-Mechanismus.
Wartungsaufwand	Eine zusätzliche Datei, die synchron bleiben muss — hält Agentenregeln aber davor, in der menschlichen Doku zu verrotten.	Nur eine Datei zu pflegen — einfacher, aber hier vergrabene Agentenregeln veralten unbemerkt.
Universalität & Fallback	Neuerer Standard; einige ältere Agenten-Setups suchen noch nicht danach.	Wird praktisch von jedem Menschen und Tool gelesen und ist der übliche Fallback, wenn keine AGENTS.md vorhanden ist. Gewinner
Gesamtpunktzahl · 1 unentschieden	4 / 7	2 / 7

Wichtige Statistiken

Echte Daten aus verifizierten Branchenquellen zur Unterstützung Ihrer Entscheidung.

AGENTS.md is reported across 60,000+ open-source repositories by mid-2026, supported by OpenAI Codex, Cursor and GitHub Copilot. — Tech With Ibrahim (Medium) — Top AI Agent Standards 2026 (2026)
In Vercel's own agent evals, a compressed 8KB docs index embedded in AGENTS.md hit a 100% pass rate, while modular skills maxed out at 79%. — Vercel — AGENTS.md outperforms skills in our agent evals (2026)
Next.js 16.3 ships first-party AGENTS.md docs so agents like Claude Code, Cursor and Codex get framework context by default. — Next.js 16.3: AI Improvements (2026)
AGENTS.md is a single standardized markdown file at the repository root that gives coding agents project-specific conventions — replacing fragmented per-tool config files. — AGENTS.md Guide 2026 (vibecoding.app) (2026)
By 2026 AGENTS.md has become the default way engineering teams give AI coding agents the context they need — including monorepo and nested-package patterns. — BuildBetter — AGENTS.md Complete Guide for Engineering Teams 2026 (2026)
Kontrollierte Studie an 10 Repositories und 124 GitHub-Pull-Requests: Die Anwesenheit einer AGENTS.md-Datei ist mit ca. 28,6 % niedrigerer medianer Laufzeit und ca. 16,6 % reduzierten Output-Token-Verbrauch verbunden, bei vergleichbarer Task-Abschlussrate. — arXiv 2601.20404 — Mohsenimofidi et al. (Jan 2026, v2 Mrz 2026) (2026)

Alle Statistiken stammen aus verifizierten Drittquellen. Quelle, Jahr und Original-Link werden direkt bei jeder Kennzahl angezeigt.

Wann Sie welche Option wählen sollten

Klare Orientierung basierend auf Ihrer spezifischen Situation und Ihren Bedürfnissen.

Unsere Empfehlung

Um einem KI-Coding-Agenten zu sagen, wie er in Ihrem Repo arbeiten soll, ist AGENTS.md 2026 der klare Standard — verbreitet über 60.000+ Repositories, unterstützt von Codex, Cursor und Copilot und in Next.js 16.3 ab Werk enthalten. README.md bleibt für das menschliche Onboarding zuständig und ist der universelle Fallback, den viele Agenten lesen, wenn keine AGENTS.md existiert. Best Practice: Behalten Sie beide. Menschliche Doku, Installationsschritte und Badges in die README; Build-/Test-Befehle, Konventionen, Nicht-anfassen-Pfade und Agentenregeln in die AGENTS.md. Pressen Sie Agenten-Anweisungen nicht in die README — dort verwässern sie die menschliche Doku und werden übersehen.

Wählen Sie AGENTS.md, wenn...: KI-Agenten sollen bestimmte Build-, Test- und Style-Konventionen befolgen
Sie arbeiten in einem Monorepo und brauchen verschachtelte, paketweise Agentenregeln
Ihr Team nutzt täglich Codex, Cursor, Copilot oder Claude Code
Sie wollen Agenten-Anweisungen von menschlicher Marketing-/Doku trennen
Wählen Sie README.md (für KI-Agenten), wenn...: Das Projekt ist winzig und eine einzige lesbare Datei genügt
Sie brauchen die universelle Datei, die jeder Mensch und jedes Tool auf GitHub/npm liest
Ihre Agenten/Tools sind älter als AGENTS.md und suchen nur nach README
Sie dokumentieren zuerst für Menschen, dann für Agenten

Häufige Fragen zu diesem Vergleich beantwortet.

Häufig gestellte Fragen

(01)Ersetzt AGENTS.md die README.md?

Nein. Sie bedienen unterschiedliche Zielgruppen. README.md bleibt die menschliche Eingangstür für Onboarding und Installation; AGENTS.md ist die maschinenlesbare Anweisungsdatei für Coding-Agenten. Behalten Sie beide.

(02)Ist AGENTS.md jetzt wirklich ein Standard?

Ja — bis Mitte 2026 ist sie über 60.000+ Repositories verbreitet und wird von OpenAI Codex, Cursor und GitHub Copilot unterstützt; Next.js 16.3 liefert AGENTS.md-Doku ab Werk mit.

(03)Was gehört in AGENTS.md vs. README.md?

AGENTS.md: Build-/Test-Befehle, Code-Konventionen, Nicht-anfassen-Pfade, PR- und Review-Regeln. README.md: Projektüberblick, Installation, Nutzung, Badges und menschliche Contribution-Hinweise.

(04)Funktioniert ein Agent auch mit nur einer README?

Meist ja — viele Agenten greifen auf die README zurück, wenn keine AGENTS.md existiert. Bessere, konsistentere Ergebnisse bekommen Sie aber mit einer dedizierten AGENTS.md und sauberen, rein agentenbezogenen Anweisungen.

Brauchen Sie Hilfe bei der Entscheidung?

Buchen Sie ein kostenloses 30-minütiges Beratungsgespräch und wir helfen Ihnen, den besten Ansatz für Ihr Projekt zu bestimmen.

Kostenloses BeratungsgesprächE-Mail senden

Kostenlose Beratung · Unverbindlich · Persönliche Antwort