Instruktionsdateien für Agenten: AGENTS.md & CLAUDE.md

Ein Coding-Agent hat kein Gedächtnis über Sessions hinweg. Erklärt man ihm heute, wie das Projekt gebaut wird und welche Konventionen gelten, ist das morgen wieder weg. Die Lösung ist eine Instruktionsdatei im Repo: das schriftliche Langzeitgedächtnis, das der Agent zu Beginn jeder Session liest. Es haben sich zwei Namen etabliert, AGENTS.md und CLAUDE.md, und es lohnt sich zu wissen, welcher was ist. Dieser Guide klärt das und gibt eine Datei zum Kopieren.

1. 🎯 Warum überhaupt eine Datei

Ohne Instruktionsdatei wiederholt man sich. Jeder neue Agenten-Lauf braucht denselben Kontext: Wie baue ich das Projekt? Welche Tests laufen? Welche Konventionen gelten? Welche Fehler sind schon passiert? Schreibt man das einmal auf, liest der Agent es automatisch und startet informiert. Die Datei ist der wichtigste Baustein des Harness aus dem agentischen Flywheel: Sie ist der Ort, an dem aus jeder Korrektur eine dauerhafte Regel wird.

Der Vergleich, der sich durchgesetzt hat: Es ist das README, aber für Agenten statt für Menschen.

2. 📄 AGENTS.md: der werkzeugübergreifende Standard

AGENTS.md ist ein offenes, simples Format, das mehrere Werkzeuge gemeinsam nutzen. Die Idee: nicht jedes Tool seine eigene Datei (eine für Cursor, eine für Copilot, eine für den nächsten Agenten), sondern ein neutraler Standard, den alle lesen. Die offizielle Beschreibung:

“AGENTS.md is a simple, open format for guiding coding agents, used by over 60k open-source projects. Think of it as a README for agents.”

Es ist gewöhnliches Markdown, ohne Pflicht-Schema. Üblich sind Abschnitte zu Setup, Build, Tests und Konventionen. In Monorepos darf es mehrere geben (die dem bearbeiteten File am nächsten gelegene gewinnt). Getragen wird das Format inzwischen von der Agentic AI Foundation unter der Linux Foundation, also nicht von einem einzelnen Hersteller.

3. 🤖 CLAUDE.md: die native Datei von Claude Code

Claude Code, das CLI-Werkzeug, liest seine eigene Datei namens CLAUDE.md. Wichtig zu wissen, weil es ein häufiges Missverständnis ist: Claude Code liest AGENTS.md nicht automatisch, sondern nur CLAUDE.md. Drei Eigenschaften:

Sie lädt zu Session-Beginn. CLAUDE.md kommt beim Start in den Kontext und bleibt dort. Deshalb zählt jedes Token (siehe Context-Engineering).

Sie hat eine Rangfolge. Mehrere Ebenen greifen ineinander: eine projektweite ./CLAUDE.md im Repo, eine persönliche ~/.claude/CLAUDE.md für alle deine Projekte, und auf Unternehmensebene gesetzte Regeln stehen darüber.

Sie kann importieren. Mit der Zeile @pfad/zur/datei zieht CLAUDE.md andere Dateien herein, zum Beispiel @README.md oder eine ausgelagerte Konventionsdatei.

4. 🌉 Die Brücke: eine Wahrheit für beide

Was tun, wenn ein Repo von mehreren Agenten bearbeitet wird, die einen lesen AGENTS.md, Claude Code liest CLAUDE.md? Man will die Anweisungen nicht doppelt pflegen. Der offiziell dokumentierte Weg ist der Import: Man schreibt die Inhalte in AGENTS.md und legt eine winzige CLAUDE.md daneben, die nur darauf verweist.

# CLAUDE.md
@AGENTS.md

Damit ist AGENTS.md die einzige Quelle der Wahrheit, und Claude Code zieht sie über den Import herein. So bleibt eine Datei zu pflegen, und trotzdem lesen beide Welten dasselbe.

5. ✍️ Ein Beispiel zum Kopieren

So sieht eine knappe, brauchbare AGENTS.md für einen generischen Web-Service aus. Sie ist bewusst kurz: Setup, Konventionen, Definition of Done, und die wenigen Regeln, die sonst immer wieder vergessen werden.

# AGENTS.md

Projekt: REST-API für einen Webshop (Python, FastAPI).

## Setup & Befehle
- Abhängigkeiten installieren: `uv sync`
- Tests laufen lassen: `pytest`
- Linter und Formatierung: `ruff check .` und `ruff format .`
- Lokal starten: `uvicorn app.main:app --reload`

## Konventionen
- TDD: Erst der rote Test, dann die Implementierung.
- Jede neue Funktion braucht einen Test.
- Edge-Cases sind Pflicht, besonders "Artikel nicht auf Lager" und leerer Warenkorb.
- WICHTIG: Keine Secrets (Tokens, Passwörter) ins Log schreiben.
- Architektur-Entscheidungen als kurzes ADR unter `/docs/adrs/` festhalten.

## Definition of Done
- Tests grün, Linter sauber.
- Edge-Cases abgedeckt.
- Öffentliche Funktionen haben Docstrings.

Für Claude Code legst du daneben die Brücken-Datei aus Abschnitt 4. Fertig: ein gepflegter Ort, zwei Welten bedient.

6. ⚠️ Knapp halten, sonst wird sie ignoriert

Die häufigste Art, eine Instruktionsdatei kaputtzumachen, ist sie zu überladen. Je mehr Regeln drinstehen, desto eher übersieht das Modell die wichtigen. Anthropic formuliert die Faustregel scharf:

“Keep it concise. For each line, ask: ‘Would removing this cause Claude to make mistakes?’ If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!”

Praktisch heisst das: Wenige, wirksame Regeln in die Datei. Alles, was sich automatisch prüfen lässt (Formatierung, Style), gehört in einen Linter statt in Prosa. Und Anweisungen, die wirklich kritisch sind, darf man mit “WICHTIG” oder “IMMER” markieren, das verbessert die Befolgung.

📚 Weiterführende Links & Quellen

Intern:

Extern: