CLAUDE.md und AGENTS.md: was sie sind, was man hineinschreibt und warum der Agent Regeln ignoriert

Was CLAUDE.md und AGENTS.md sind

Es handelt sich um gewöhnliche Markdown-Dateien im Wurzelverzeichnis des Repositorys, die der Agent zu Beginn einer Sitzung automatisch in seinen Kontext lädt. Mit ihnen teilen Sie dem Agenten mit, was er aus dem Code selbst nicht erfahren kann: wie die Umgebung aufgesetzt wird, mit welchen Befehlen die Arbeit zu prüfen ist, welche Projektregeln nicht zur Diskussion stehen und wo die ausführliche Dokumentation liegt.

CLAUDE.md ist die Datei, die Claude Code liest. AGENTS.md ist ein offenes Format mit derselben Idee, das viele Coding-Agenten unterstützen. Wenn im Team verschiedene Agenten eingesetzt werden, ist es praktisch, den Hauptinhalt in AGENTS.md zu halten und in CLAUDE.md darauf zu verweisen. Claude Code unterstützt das Einbinden einer anderen Datei über eine Zeile mit @:

# CLAUDE.md
@AGENTS.md

So leben die Regeln an einem Ort und laufen nicht zwischen zwei Dateien auseinander.

Wie der Agent diese Dateien liest

Der Inhalt der Anweisungsdatei gelangt zusammen mit dem Systemprompt in das Kontextfenster des Modells und bleibt dort die ganze Sitzung. Daraus folgen drei wichtige Konsequenzen.

• Jede Zeile kostet Platz im Kontext. Die Datei wird bei jedem Start vollständig gelesen, auch wenn für die aktuelle Aufgabe ein Zehntel davon genügt.
• Das sind keine ausführbaren Regeln, sondern Text. Das Modell berücksichtigt sie zusammen mit dem übrigen Kontext, eine hundertprozentige Einhaltung ist nicht garantiert. Harte Verbote müssen durch Mechanismen abgesichert werden: Prüfungen, Hooks, Zugriffsrechte.
• Dateien lassen sich verschachteln. Claude Code lädt CLAUDE.md aus dem Projektwurzelverzeichnis und aus dem Benutzerordner ~/.claude/, Dateien in Unterverzeichnissen werden geladen, wenn der Agent mit Dateien dieser Verzeichnisse arbeitet. So können Sie die Regeln eines Moduls direkt neben dem Modul halten.

Was in CLAUDE.md und AGENTS.md gehört

Eine gute Anweisungsdatei ist eine Landkarte, kein Lehrbuch. Sie beantwortet die Fragen, die ein Agent einem erfahrenen Kollegen am ersten Tag stellen würde.

1. Wie das Projekt gebaut und geprüft wird

Der wertvollste Abschnitt. Konkrete Befehle, die der Agent ausführen muss, bevor er „fertig“ sagt: Tests, Linter, Typprüfung, Start der Umgebung. Ohne sie prüft der Agent seine Arbeit „nach Gefühl“.

2. Harte Vorgaben

Eine kurze Liste von Dingen, die unter keinen Umständen verletzt werden dürfen: Sicherheits- und Dateninvarianten. Formulieren Sie als Invarianten, nicht als Umsetzungsanweisungen: „Alle SQL-Abfragen sind parametrisiert“, nicht „nutze diese Funktion in jener Datei“.

3. Eine Karte des Projekts

Wo was liegt: einige Zeilen zur Verzeichnisstruktur und dazu, wo die Details stehen. Zu jedem großen Thema ein Verweis auf ein eigenes Dokument, das der Agent erst öffnet, wenn er sich mit diesem Thema beschäftigt.

4. Wo der Stand der Arbeit festgehalten wird

Wo man nachsieht, um dort weiterzumachen, wo die letzte Sitzung aufgehört hat: Planungsdatei, Fortschrittsprotokoll, Backlog. Das behebt die „Amnesie“ des Agenten zwischen Sitzungen.

Was nicht hinein gehört

• Was der Agent aus dem Code erfährt. Die Abhängigkeiten stehen in package.json oder pyproject.toml, die Struktur der Klassen im Code selbst.
• Allgemeine Ratschläge. „Schreibe sauberen Code“ oder „sei aufmerksam“ ändern das Verhalten nicht und belegen nur Platz.
• Projektgeschichte und einmalige Notizen. „Im März sind wir von MySQL 5.7 umgezogen“ hilft der aktuellen Aufgabe nicht.
• Ausführliche Anleitungen für seltene Aufgaben. Ein Deployment oder eine Datenmigration braucht man einmal pro Woche — verlagern Sie das in ein eigenes Dokument oder einen Skill.
• Geheimnisse. Die Datei liegt im Repository und geht vollständig an das Modell. Tokens und Passwörter gehören nur in Umgebungsvariablen.

Warum der Agent eine Regel ignoriert, die in der Datei steht

Eine typische Geschichte: Der Agent hat einen Fehler gemacht, also wurde eine Regel ergänzt. Er machte einen weiteren Fehler, es kam noch eine Regel hinzu. Einige Monate später hat die Datei Hunderte Zeilen, und die kritische Sicherheitsregel wird verletzt, als gäbe es sie nicht. Es gibt meist vier Ursachen, die gleichzeitig wirken.

Eine aufgeblähte Datei

Eine Datei mit 600 Zeilen entspricht etwa 10.000 bis 20.000 Tokens. Das Kontextfenster wirkt riesig, aber es teilt sich Code, Befehlsausgaben und den Gesprächsverlauf. Je mehr die Anweisungen belegen, desto weniger Aufmerksamkeit erhält jede Regel und desto mehr Platz fehlt der Aufgabe selbst.

Die Regel steht in der Mitte

Sprachmodelle nutzen Informationen aus der Mitte eines langen Textes deutlich schlechter als aus Anfang und Ende. Eine Regel in Zeile dreihundert von sechshundert liegt an der schwächsten Stelle.

Keine Prioritäten

Ein unverhandelbares Verbot und eine beiläufige Bemerkung zum Stil sind gleich formatiert — als eine Zeile in einer Liste. Dem Agenten fehlt die Möglichkeit zu erkennen, was wichtiger ist. Und wenn die Datei drei widersprüchliche Stilregeln enthält, wird das Verhalten von Lauf zu Lauf zufällig.

Verrottung

Eine Regel hinzuzufügen kostet nichts, eine zu löschen ist riskant: „Vielleicht hängt doch etwas davon ab.“ Also wächst die Datei stetig, während der Anteil nützlicher Zeilen sinkt. Praktisch lässt sich das als Signal-Rausch-Verhältnis messen: Wie viele Zeilen braucht eine typische Aufgabe tatsächlich, und wie viele nicht?

Die Lösung: ein Router statt einer Textwand

Eine einzelne Ursache zu beheben nützt wenig: Kürzen Sie die Datei, aber lassen Sie sie unstrukturiert, sind die Regeln weiterhin vermischt. Wirksam ist ein Bündel von Maßnahmen.

1. Machen Sie die Einstiegsdatei zum Router. 50 bis 150 Zeilen: Prüfbefehle, harte Vorgaben, Projektkarte und Verweise auf Themendokumente.
2. Lagern Sie Themen in eigene Dateien aus. Zum Beispiel docs/agents/deploy.md und docs/agents/database.md. Der Agent öffnet sie bei Bedarf. In Claude Code eignen sich für wiederkehrende Abläufe Skills, die nur bei Bedarf geladen werden.
3. Stellen Sie das Kritische nach oben. Harte Vorgaben gehören an den Anfang der Datei, in einen kurzen eigenen Block mit der klaren Kennzeichnung MUST.
4. Beseitigen Sie Widersprüche. Eine Regel pro Thema. Gibt es eine Ausnahme, schreiben Sie sie direkt neben die Regel.
5. Stützen Sie die Regel durch einen Mechanismus. Ist eine Verletzung inakzeptabel, reicht Text nicht. Nötig ist eine Prüfung, die sie abfängt: Linter, Test, Pre-Commit-Hook oder Agenten-Hook, oder eine Einschränkung auf der Ebene der Zugriffsrechte.
6. Überprüfen Sie regelmäßig. Setzen Sie eine Zeilengrenze, und fragen Sie bei jeder Ergänzung, was entfernt oder ausgelagert werden kann.

Regel oder Prüfung?

Beispiel für eine kompakte AGENTS.md

# AGENTS.md — Zahlungs-Backend (FastAPI, PostgreSQL)

## MUST — nicht verletzen
- Geldbeträge sind int in Cent, niemals float
- SQL nur parametrisiert, keine f-Strings
- Angewendete Migrationen nicht ändern, nur neue hinzufügen
- Geheimnisse nur aus Umgebungsvariablen

## Prüfung vor dem Wort „fertig“
docker compose up -d     # Umgebung
make lint                # ruff + mypy
make test                # pytest
make e2e                 # Bestellszenario
Grüne Unit-Tests ohne E2E sind nicht „fertig“.

## Karte
- app/payments/   — Betragsberechnung, Rabatte, Provider-Webhooks
- app/api/        — HTTP-Handler
- tests/e2e/      — Nutzerszenarien
Details: docs/agents/architecture.md, docs/agents/database.md

## Stand der Arbeit
- PLAN.md      — aktuelles Ziel, Abnahmekriterien, nächster Schritt
- PROGRESS.md  — was erledigt wurde und wie geprüft, Sackgassen
- BACKLOG.md   — Dinge, die „nebenbei“ auffallen: hier notieren, jetzt nicht reparieren

Am Ende der Sitzung PROGRESS.md und den nächsten Schritt in PLAN.md aktualisieren.

Beachten Sie, was fehlt: keine Liste von Bibliotheken, keine Stilratschläge, keine Projektgeschichte. Alles davon ist entweder im Code sichtbar, durch Prüfungen abgesichert oder steht in Themendokumenten.

Amnesie zwischen Sitzungen: eine Anweisungsdatei plus eine Planungsdatei

Die Anweisungsdatei beschreibt, wie im Projekt zu arbeiten ist, aber nicht, was gerade geschieht. Dafür braucht es eine eigene Zustandsdatei, die der Agent zu Beginn liest und am Ende der Sitzung aktualisiert. Sie enthält das Ziel, das Erledigte mit dem Hinweis, wie es geprüft wurde, getroffene Entscheidungen mit ihren Gründen, verworfene Varianten und eine Formulierung des nächsten Schritts. Eine einfache Qualitätsprüfung: Öffnen Sie eine neue Sitzung, schreiben Sie „mach weiter“ und sehen Sie, ob der Agent ohne Rückfragen sinnvoll arbeitet.

Verwechseln Sie die beiden Dateien nicht. Anweisungen ändern sich selten und betreffen alle Aufgaben. Ein Plan ändert sich in jeder Sitzung und betrifft die aktuelle Aufgabe. Vermischt man beides, füllt sich die Anweisungsdatei schnell mit veralteten Notizen.

Wie Sie prüfen, dass die Datei funktioniert

Auch die Anweisungsdatei muss getestet werden. Nehmen Sie einige typische Aufgaben — eine Fehlerbehebung, ein kleines Feature, ein Refactoring — und beobachten Sie, was der Agent ohne Hinweise tut: führt er die richtigen Befehle aus, öffnet er das passende Themendokument, hält er die harten Vorgaben ein. Wird eine Regel verletzt, fragen Sie zuerst, ob sie sichtbar ist, ob sie einer anderen widerspricht und ob sie durch eine automatische Prüfung ersetzt werden kann. Eine neue Zeile hinzuzufügen ist das letzte Mittel.

Fazit

CLAUDE.md und AGENTS.md sind der Einstiegspunkt des Agenten in das Projekt. Sie funktionieren, wenn sie eine kurze Landkarte bleiben: Prüfbefehle, harte Vorgaben oben, Verweise auf Details und auf die Planungsdatei. Wird eine Regel ignoriert, liegt die Ursache fast immer an einer aufgeblähten, unstrukturierten Datei, und wirklich kritische Regeln müssen durch Prüfungen und Hooks abgesichert werden. Der Aufbau von Anweisungen und Zustand des Agenten wird im Kurs zum Harness Engineering praktisch behandelt.