AGENTS.md & CLAUDE.md: Die neue README für KI-Coding-Agenten

Wer in letzter Zeit einen KI-Coding-Assistenten benutzt hat, dem ist wahrscheinlich etwas aufgefallen: Sie alle wollen eine Markdown-Datei.

GitHub Copilot liest .github/copilot-instructions.md. Cursor liest .cursor/rules/. Claude Code liest CLAUDE.md. Windsurf liest .windsurf/rules. Googles Jules liest JULES.md. Und der universelle Standard? AGENTS.md — mittlerweile in über 60.000 Open-Source-Repositories genutzt und von der Agentic AI Foundation der Linux Foundation gepflegt.

Markdown hat sich von einem Dokumentationsformat zum Betriebssystem für KI-Coding-Agenten entwickelt.

Was ist AGENTS.md?

AGENTS.md ist eine einfache, offene Markdown-Datei, die in Ihrem Repository liegt und als Briefing-Paket für KI-Coding-Agenten fungiert. Stellen Sie es sich als das Gegenstück zu README.md vor:

• README.md ist für Menschen: Quick Starts, Projektbeschreibungen, Badges
• AGENTS.md ist für KI-Agenten: Build-Schritte, Test-Befehle, Coding-Konventionen, Architekturentscheidungen

Der Agent liest die nächstgelegene Datei im Verzeichnisbaum, sodass die näherliegende Vorrang hat. Jedes Teilprojekt kann maßgeschneiderte Anweisungen mitliefern.

Was ist CLAUDE.md?

CLAUDE.md ist speziell für Anthropics Claude Code gedacht. Es wird zu Beginn jeder Sitzung automatisch eingelesen und enthält projektspezifische Anweisungen, die Sie andernfalls in jedem Prompt wiederholen müssten.

Eine gute CLAUDE.md enthält typischerweise:

• Projektkontext: Ein Satz, der Claude über das Projekt orientiert
• Code-Stil: Formatierungspräferenzen, Namenskonventionen, zu befolgende Muster
• Befehle: Wie man Tests ausführt, baut, lintet und deployt
• Architekturhinweise: Schlüsselentscheidungen, die Claude respektieren sollte

Der empfohlene Ansatz: Gemeinsame Anweisungen in AGENTS.md (damit alle KI-Tools davon profitieren), dann Claude-spezifische Ergänzungen in CLAUDE.md.

Die vollständige Landschaft der KI-Instruktionsdateien

Hier sind alle wichtigen KI-Coding-Tools und ihre Markdown-Konventionen:

Tool	Datei	Format
GitHub Copilot	.github/copilot-instructions.md	Markdown
Cursor	.cursor/rules/*.md	Markdown
Claude Code	CLAUDE.md	Markdown
Windsurf	.windsurf/rules	Markdown
Google Jules	JULES.md	Markdown
Universal	AGENTS.md	Markdown

Sehen Sie das Muster? Es ist alles Markdown. Ausnahmslos.

Warum Markdown gewonnen hat

Markdown ist das perfekte Format für Agenten-Instruktionsdateien, weil:

1. LLMs es nativ verstehen — es ist das häufigste Format in ihren Trainingsdaten
2. Es für Menschen lesbar ist — Entwickler können Anweisungen leicht überprüfen und bearbeiten
3. Es versionierbar ist — lebt in git neben Ihrem Code
4. Es leichtgewichtig ist — kein Parsing-Overhead, kein spezielles Tooling nötig
5. Es universal ist — funktioniert mit jedem KI-Tool, Editor und jeder Plattform

Wie das Visual Studio Magazine formulierte: In der agentischen KI dreht sich alles um Markdown.

Best Practices für das Schreiben von Agenten-Instruktionen

Basierend auf der Analyse tausender Repositories:

Klein anfangen. Fügen Sie Regeln nur hinzu, wenn Sie bemerken, dass der Agent denselben Fehler wiederholt. Zu detaillierte Anweisungen können mehr verwirren als helfen.

Konkret bei Befehlen sein. Nicht „führe die Tests aus” — sondern pnpm test oder pytest -x tests/.

Ihre Architektur dokumentieren. Wenn Ihr Projekt ein spezifisches Muster verwendet (wie Message Passing zwischen einem Content Script und einem Service Worker), erklären Sie es. Der Agent kann Architekturentscheidungen nicht allein aus dem Code ableiten.

Auch einbeziehen, was NICHT getan werden soll. Negative Anweisungen sind überraschend effektiv: „Datenbankschema niemals direkt ändern” oder „Keine Class Components verwenden, immer Hooks verwenden.”

Saves Rolle in dieser Welt

Wenn Sie Agenten-Instruktionsdateien erstellen, speichern Sie wahrscheinlich auch Referenzmaterial aus dem Web: Dokumentationsseiten, Stack Overflow-Antworten, GitHub READMEs, API-Referenzen.

Save wandelt jede dieser Webquellen mit einem Klick in sauberes Markdown um — ideal zum Aufbau des Kontexts, den Ihre KI-Agenten benötigen. Eine Dokumentationsseite speichern, das Markdown in Ihre AGENTS.md oder Referenzdokumente einfügen, und Ihr KI-Coding-Assistent hat sofort den nötigen Kontext.

Der Workflow:

1. Nützliche Dokumentation oder Code-Beispiele im Web finden
2. Save klicken, um in Markdown zu konvertieren
3. In Agenten-Instruktionsdateien referenzieren oder einfügen
4. Ihr KI-Coding-Assistent wird mit jedem Speichern besser

Die Zukunft: Markdown als Kontrolloberfläche für KI

Microsoft und GitHub behandeln Markdown jetzt als stabile, prüfbare Kontrolloberfläche für KI-Verhalten. Es ist nicht mehr nur Dokumentation — es ist die Schnittstelle zwischen menschlicher Absicht und KI-Ausführung.

Wir sehen, dass Markdown-Dateien drei unterschiedliche Rollen erfüllen:

1. Dokumentation: Erklärt ein System für Menschen
2. Instruktion: Schränkt KI-Verhalten ein und lenkt es
3. Skill: Bündelt Anweisungen mit Ressourcen, damit Agenten Workflows wiederholen können

Dieser Trend beschleunigt sich nur noch. Je fähiger KI-Coding-Assistenten werden, desto wichtiger werden die Markdown-Dateien, die sie steuern.

---

Save wandelt jede Webseite mit einem Klick in sauberes Markdown um. Ideal zum Aufbau von Referenzbibliotheken, zur Erfassung von Dokumentation und zur Erstellung von Kontext für KI-Coding-Workflows. Save kostenlos testen.