CLAUDE.md und AGENTS.md: Was ich nach 42 Projekten eintrage

Aktualisierung (9. November 2026): Claude Fable 5.2 und Mythos 5.2 sind erschienen - Preise, Zugang und Benchmarks im Überblick zu Claude Fable 5.2.

👁 114 Aufrufe

Auf meiner Festplatte liegen 42 Dateien mit Anweisungen für KI-Agenten: 16 CLAUDE.md- und 26 AGENTS.md-Dateien, jeweils im Ordner eines anderen Projekts. Die kürzeste hat eine Zeile, die längste 402. Diese längste Datei ist doppelt so lang, wie Anthropic empfiehlt. Mit ihr fange ich an, denn sie zeigt gut, was tatsächlich in so einer Datei steht.

Was ist eine CLAUDE.md-Datei?

Sie ist eine gewöhnliche Markdown-Datei, die Claude Code zu Beginn jeder Sitzung liest. Jedes Gespräch mit einem Agenten beginnt mit leerem Gedächtnis. Alles, was sich nicht aus dem Code ablesen lässt, müssen Sie ihm deshalb erneut mitteilen. CLAUDE.md übernimmt das: Befehle für Tests, Projektregeln, Dinge, die der Agent nicht tun darf, und Stolperfallen, auf die Sie bereits gestoßen sind.

Die Dokumentation zu Claude Code stellt klar: Die Datei liefert Kontext, ist aber keine verbindliche Konfiguration. Der Agent hält sich meistens daran, muss es aber nicht. Was immer gesperrt sein soll - zum Beispiel das Löschen von Dateien oder ein Deployment auf einen Server -, sollte über Hooks und Berechtigungen in den Einstellungen geregelt werden, nicht über einen Satz in CLAUDE.md.

Wo die Datei liegt und welche Inhalte geladen werden

Es können mehrere Dateien gleichzeitig vorhanden sein. Claude Code wählt nicht eine davon aus, sondern führt alle gefundenen Dateien zusammen - von den allgemeinsten bis zu denen, die dem aktuellen Arbeitsordner am nächsten sind.

Dateien aus Ordnern oberhalb des Ordners, in dem Sie den Agenten starten, werden sofort geladen. Dateien aus Unterordnern erst dann, wenn der Agent dort Dateien liest oder ändert. So belegen Anweisungen für das Frontend in einem großen Repository keinen Platz, wenn der Agent gerade an der Datenbank arbeitet.

Eine erste Version können Sie mit dem Befehl /init erstellen. Claude untersucht den Code und hält Befehle sowie Konventionen fest, die es selbst erkennt. Das ist ein guter Anfang. Ich ergänze den Rest aber immer von Hand, denn die wertvollsten Zeilen sind gerade jene, die sich nicht aus dem Code ablesen lassen.

Meine längste Datei: 402 Zeilen

Die Dokumentation empfiehlt, eine CLAUDE.md-Datei auf weniger als 200 Zeilen zu beschränken. Eine längere Datei verbraucht Kontext, und der Agent hält sich schlechter an ihre Vorgaben. Meine Datei im Projekt Jantaris hat 402 Zeilen und umfasst 46.095 Byte. Von meinen 16 CLAUDE.md-Dateien überschreitet nur diese den Richtwert; der Median liegt bei 35 Zeilen.

Sie ist nicht auf einmal entstanden. Nach jedem Fehler kamen neue Stolperfallen hinzu: wie der Server Bilder zwischenspeichert und warum eine Datei, die unter demselben Namen ersetzt wird, die Nutzer erst eine Woche später erreicht; wie viele Registrierungen pro Stunde die Schutzfunktion zulässt und wie Tests sie zurücksetzen müssen; wo der Server steht und wie der E-Mail-Versand funktioniert. Jede Zeile ist die Spur eines konkreten Problems. Zusammen wurde es zu viel.

Meine Einschätzung: CLAUDE.md ist keine Projektdokumentation, sondern eine Minenkarte. Wie die Anwendung funktioniert, findet der Agent im Code und in der README. In CLAUDE.md gehört, was im Code nicht sichtbar ist, aber schon einmal schiefgegangen ist. Wenn die Datei mehr als 200 Zeilen hat, teile ich sie in thematische Dateien unter .claude/rules/ auf. Der Import über @datei.md hilft nur bei der Ordnung, denn auch die importierte Datei wird vollständig geladen.

Die Datei aus meinem Kurs: 34 Zeilen

Ein gutes Beispiel ist die CLAUDE.md-Datei des Projekts „Reparaturdatenbank“: eine Anwendung für eine Autowerkstatt, die wir in meinem Kurs SaaS am Wochenende mit Claude Code von Grund auf entwickeln. Hier ist die vollständige Datei, ohne Kürzungen:

# Reparaturdatenbank - Notizen für den Agenten

Produkt, Ansichten und Regeln: @SPEC.md
Baue nur den Abschnitt MUSS SEIN aus UMFANG.md. Ergänze Ideen außerhalb davon
unter SPÄTER, mit einer Bedingung für die Wiederaufnahme, und frag mich.

## Technologie-Stack
- Node 22.13+, keine npm-Abhängigkeiten: node:http, node:sqlite, node:test, fetch.
- SQLite in data/app.db, Migrationen in migrations/NNN_name.sql.
- HTML wird auf dem Server gerendert, im Browser läuft reines JavaScript.

## Befehle
- npm run dev                 Server auf Port 8080, Neustart nach Dateiänderungen
- npm test                    node --test "test/*.test.js" (Glob in Anführungszeichen)
- npm run reset               Datenbank neu erstellen + Testdaten + Testkonten
- python tools/zrzuty.py URL  Aufnahmen mit 1440 px und 390 px in data/shots/

## Regeln
- Beträge als INTEGER in kleinsten Währungseinheiten. Niemals Gleitkommazahlen.
- Tariflimits (R1-R3) prüft der Server. Der Browser zeigt sie nur an.
- Jede R-Regel aus SPEC.md hat einen Test mit ihrer Nummer im Namen.
- Textdateien mit LF-Zeilenumbrüchen speichern.
- In Texten nur den einfachen Bindestrich "-". Der Test prüft alle Vorlagen.

## Verbote
- .env nicht lesen. Kein Deployment. Kein git push, git reset oder git clean.
- Tests nicht mit data/app.db ausführen (Tests verwenden eine Datenbank im Arbeitsspeicher).
- Keine Werksdaten importieren (Autodata, HaynesPro, Herstellerportale):
  Herstellerlizenzen und Datenbankschutz in der EU.

## Stolperfallen
- Git Bash verändert Pfade: Vor Befehlen mit /... MSYS_NO_PATHCONV=1 setzen.
- Dateien mit regulären Ausdrücken mit dem Dateitool speichern,
  nicht mit einem Bash-Heredoc (dabei gehen Backslashes verloren).

Jeder Abschnitt hat seinen Grund:

• Verweis auf die Spezifikation. Die Produktbeschreibung steht in SPEC.md; CLAUDE.md importiert sie nur. Die Zeile zum Abschnitt MUSS SEIN hält den Agenten im vorgegebenen Umfang. Ohne sie bekommen Sie nach einer Stunde Funktionen, um die niemand gebeten hat.
• Befehle mit genauer Syntax. Das in Anführungszeichen gesetzte Glob-Muster für die Tests ist ein leicht zu übersehendes Syntaxdetail. Davon hängt ab, ob alle Testdateien ausgeführt werden.
• Überprüfbare Regeln. Beträge in kleinsten Währungseinheiten, serverseitige Limits, ein Test für jede Regel. Keine Vorgaben wie „Schreib sauberen Code“, denn das lässt sich nicht überprüfen.
• Verbote. Die wichtigsten davon hinterlege ich zusätzlich in den Berechtigungseinstellungen, denn die Datei ist nur eine Bitte.
• Stolperfallen der Umgebung. Windows und Git Bash verändern Pfade, die mit einem Schrägstrich beginnen. Der Agent weiß das erst, wenn ein Befehl fehlschlägt.

Die Zeile, die mich einen Redaktionsdurchgang kostete

Am deutlichsten zeigt sich das an einem Beispiel. Am 30. Oktober wurde bei der Redaktion von Texten für das Magazin DYGOT ein Skript ausgeführt, das den aktuellen Stand vom Server abruft. Es lief zwischen den Änderungen und dem Hochladen, überschrieb die lokalen Änderungen und machte den ersten Redaktionsdurchgang zunichte. Seitdem steht in der Anweisungsdatei dieses Projekts: „Nur VOR der Arbeit ausführen - zwischen Bearbeitung und Hochladen werden Ihre Änderungen überschrieben.“ Kein Generator hätte diesen Hinweis formuliert, denn aus dem Skriptcode geht nicht hervor, wann es ausgeführt werden darf.

AGENTS.md: dieselbe Idee für andere Agenten

AGENTS.md ist ebenfalls eine Anweisungsdatei, nur unter einem Namen, den verschiedene Tools verwenden: Codex von OpenAI, Cursor, Gemini CLI, der GitHub-Copilot-Agent und ein Dutzend weitere. Die Agentic AI Foundation bei der Linux Foundation betreut das Format. Ich habe 26 solcher Dateien. Sie sind kurz, der Median liegt bei 8 Zeilen, denn die meisten beschreiben einzelne Grafikaufgaben für Codex.

Auch Claude Code kann AGENTS.md lesen, und zwar ab Version 2.1.277. Standardmäßig geschieht das nur, wenn es im Projekt keine CLAUDE.md-Datei gibt. Sind beide vorhanden, liest Claude seine eigene Datei und lässt AGENTS.md aus. Sollen beide Tools dieselben Regeln erhalten, ist es am einfachsten, sie in AGENTS.md abzulegen und in CLAUDE.md eine Zeile mit dem Import @AGENTS.md hinzuzufügen. Wie Sie das gesamte Setup einschließlich Skills und MCP-Server übertragen, beschreibe ich im Artikel Claude Code zu Codex übertragen.

Für Projekte, an denen Claude und Codex abwechselnd arbeiten, habe ich noch eine Regel am Ende der Datei: Nach der Arbeit soll ein Eintrag ins gemeinsame Agentenprotokoll, mit Datum, Agentenname und einer Liste der Änderungen. Der nächste Agent liest das Protokoll vor dem Start und weiß, was sein Vorgänger geändert hat. Das ist einfacher, als das Gedächtnis beider Tools miteinander abzugleichen.

Was ich nicht eintrage

• Schlüssel und Passwörter. Die Projektdatei landet oft im Repository. In meinen Dateien steht eher, dass .env nicht gelesen werden darf, als dass ihr Inhalt dort auftaucht.
• Ordnerstrukturen. Der Agent erkennt sie innerhalb weniger Sekunden selbst, und eine Beschreibung in der Datei wäre schon nach der ersten Änderung veraltet.
• Allgemeinplätze. „Achten Sie auf Qualität“ ändert nichts. „Jede Regel hat einen Test mit ihrer Nummer“ schon.
• Widersprüchliche Regeln. Die Dokumentation warnt, dass Claude bei zwei widersprüchlichen Anweisungen eine davon beliebig auswählen kann. Ich lese meine Dateien deshalb von Zeit zu Zeit durch und entferne, was nicht mehr gilt.
• Notizen für Menschen. Falls sie bleiben müssen, setze ich sie in einen HTML-Kommentar <!-- -->. Claude Code entfernt solche Kommentare vor dem Laden der Datei, sie verbrauchen also keinen Kontext.

So fangen Sie an

Wenn Sie mit Claude Code beginnen, schreiben Sie nicht vorsorglich eine CLAUDE.md-Datei. Führen Sie /init aus, behalten Sie, was sinnvoll ist, und ergänzen Sie jeweils eine Zeile, wenn der Agent denselben Fehler zum zweiten Mal macht. Nach einer Woche haben Sie eine Datei, die Ihr Projekt beschreibt - und nicht das Projekt aus irgendeinem Ratgeber. Die Installation und die ersten Schritte beschreibe ich in der Anleitung Claude Code installieren; um die Kosten der Tarife geht es im Artikel Was Claude Code kostet.

Die Spezifikation und CLAUDE.md erarbeiten wir Schritt für Schritt im Kurs SaaS am Wochenende mit Claude Code: 30 Lektionen, von der Prüfung der Nachfrage nach einer Idee über Datenbank, Anmeldung und Zahlungen bis zum Deployment auf einem eigenen Server. Der Kurs ist auch im Paket kombAIn enthalten, zusammen mit 27 weiteren Kursen.

Quellen und Stand

Stand: 6.11.2026.

• CLAUDE.md- und AGENTS.md-Dateien aus meinen Projekten: 42 Dateien, nach dem Ausschluss von Kopien und fremden Repositories, gezählt am 6.11.2026
• Claude Code - Dokumentation: How Claude remembers your project (CLAUDE.md, AGENTS.md, Importe, Richtwert von 200 Zeilen)
• AGENTS.md - Beschreibung des Formats

// weiterlesenBlack Friday KI-Abo 2026: ChatGPT, Gemini und Claude im CheckAnleitungenClaude Duet in Deutschland: Stand und AlternativenAnleitungenClaude Sonnet 5.5 kostenlos: Gibt es einen Free-TierAnleitungen

Kinetyra