CLAUDE.md: wohin damit, was hineingehört und wie es mit AGENTS.md zusammenspielt

Was CLAUDE.md ist

Claude Code startet jede Session ohne Erinnerung an die letzte. Mit CLAUDE.md gibst du ihm den Kontext, den ein neuer Kollege bräuchte: Die Datei wird beim Start gelesen und nach dem System-Prompt als Nachricht an Claude gesendet. Sie ist damit Kontext, keine erzwungene Konfiguration. Claude hält sich meistens daran, doch was immer oder nie passieren muss, gehört in Hooks oder Berechtigungsregeln.

• Reines Markdown, keine Pflichtfelder: Überschriften und kurze Stichpunkte funktionieren am besten.
• Dateien werden kombiniert, nicht überschrieben: Jede zutreffende CLAUDE.md wird geladen, bei widersprüchlichen Zeilen wählt Claude eine aus.
• Prüfe mit /context all unter Memory files, was geladen wurde.

Wo CLAUDE.md-Dateien liegen und in welcher Reihenfolge sie laden

Claude Code lädt sie vom Allgemeinsten zum Spezifischsten, sodass die Datei, die dem Startort am nächsten liegt, zuletzt gelesen wird. Außerdem geht es von deinem Arbeitsverzeichnis aus nach oben und lädt die CLAUDE.md jedes übergeordneten Verzeichnisses.

So schreibst du eine CLAUDE.md, die funktioniert

1. Starte mit /init

   Führe /init in deinem Projekt aus. Claude Code liest die Codebasis und schreibt eine erste CLAUDE.md; gibt es schon eine, schlägt es Verbesserungen vor, statt sie zu überschreiben. Auch .cursorrules und Copilot-Anweisungen übernimmt es.

2. Beschränke dich auf das, was Claude nicht selbst findet

   Behalte die exakten Build-, Test- und Lint-Befehle (auch, wie man einen einzelnen Test ausführt), die Stellen, an denen der Code in die Irre führt, Entscheidungen, die nirgends aufgeschrieben sind, und alles, was du zweimal korrigieren musstest. Entferne Dateibäume und Architektur, die Claude aus dem Repository lesen kann. Anthropic empfiehlt, unter 200 Zeilen zu bleiben.

   # Befehle
   - Installieren: pnpm install
   - Eine einzelne Testdatei: pnpm vitest run path/to/file.test.ts
   - Typecheck: pnpm tsc --noEmit
   
   # Konventionen
   - Wirf Fehler mit den Helpern aus src/lib/errors.ts, nie mit rohen Strings.
   - src/legacy/ ist weiterhin im Einsatz, aber übernimm seine Muster nicht.
   
   # Stolperfallen
   - Integrationstests brauchen DATABASE_URL (siehe .env.example).

3. Sei konkret, ohne zu schreien

   Schreibe "Nutze 2 Leerzeichen Einrückung", nicht "Formatiere den Code ordentlich". Laut aktueller Dokumentation sind IMPORTANT und GROSSBUCHSTABEN überholte Ratschläge: Sie lassen Claude eine Regel übertrieben anwenden. Wird eine Zeile immer wieder übersehen, kürze die Datei oder mache aus der Regel einen Hook.

4. Teile sie mit Imports und Regeln auf

   @path/to/file importiert eine andere Datei (relativ zur importierenden Datei, bis zu vier Ebenen tief); ein @ in Backticks bleibt wörtlich. Regeln, die nur für einen Teil der Codebasis gelten, kommen mit einem paths-Glob nach .claude/rules/ und laden nur, wenn Claude passende Dateien anfasst.

   ---
   paths: ["src/api/**/*.ts"]
   ---
   - Jeder Handler validiert seine Eingabe mit dem Schema aus src/api/schemas/.

5. Verlagere Abläufe in Skills

   Mehrstufige Abläufe, etwa wie man ein Release schneidet, gehören in einen Skill (.claude/skills/<name>/SKILL.md), der nur lädt, wenn er relevant ist. CLAUDE.md wird bei jeder Aufgabe gelesen, jede Zeile kostet also Aufmerksamkeit.

6. Halte sie aktuell

   Ergänze eine Zeile, wenn Claude einen Fehler wiederholt oder ein Review etwas findet, und bearbeite die Datei mit /memory oder lass Claude sie aktualisieren. /doctor schlägt Kürzungen vor, wenn die Datei zu lang wird.

Quelle: Claude-Code-Dokumentation, How Claude remembers your project

CLAUDE.md vs. AGENTS.md

AGENTS.md ist ein offenes Format für Anweisungen an Coding-Agenten, das Codex, Cursor, Gemini CLI, der Coding-Agent von GitHub Copilot, opencode und viele andere nutzen. Claude Code liest es inzwischen auch, standardmäßig aber nur, wenn das Projekt keine CLAUDE.md hat.

Eine Datei für Claude Code und Codex

Wenn dein Team beide Agenten nutzt, lege die gemeinsamen Anweisungen in AGENTS.md ab und lass CLAUDE.md sie importieren, mit den Claude-spezifischen Notizen darunter. Sie lädt nie doppelt. Ein Symlink (ln -s AGENTS.md CLAUDE.md) funktioniert auch, aber nicht für Kollegen unter Windows, und eine CLAUDE.md, die nur in Worten "lies AGENTS.md" sagt, ist nicht zuverlässig.

• Das Repository dieser Website macht genau das: Seine CLAUDE.md besteht aus der einen Zeile @AGENTS.md.
• Codex liest AGENTS.md-Dateien vom Repository-Root bis zu deinem Arbeitsverzeichnis und begrenzt ihre Gesamtgröße standardmäßig auf 32 KiB.

Grenzen und Stolperfallen

• Eine CLAUDE.md, die beim Start lädt, wird bis 4 MiB komplett gelesen; eine größere Datei wird übersprungen.
• Dateien, die bei Bedarf laden, etwa CLAUDE.md-Dateien in Unterverzeichnissen und pfadbezogene Regeln, werden ab einem Limit pro Datei abgeschnitten (40.000 Zeichen bei einem Kontextfenster von 200K).
• Imports ordnen eine Datei, sparen aber keinen Kontext: Der importierte Text wird trotzdem geladen.
• Imports von außerhalb des Projekts fragen einmal nach Freigabe; HTML-Kommentare <!-- --> werden entfernt und kosten nichts.
• Die CLAUDE.md im Projekt-Root wird nach /compact erneut gelesen.
• "Merk dir das" landet im Auto Memory (~/.claude/projects/<project>/memory/), nicht in CLAUDE.md.

CLAUDE.md sagt, wie gearbeitet wird. Crewmark sagt, woran und wann.

Eine gute CLAUDE.md lässt jede Claude-Code-Session informiert starten, aber die Session wartet trotzdem auf deine nächste Nachricht. Crewmark macht aus einer Session von Claude Code, Codex, DeepSeek Harness oder OpenCode einen KI-Mitarbeiter mit Rolle, Ziel und Arbeitszeiten und weckt ihn per Heartbeat, damit er das nächste Issue von einem Board übernimmt.

1. Mach aus einer Session einen Mitarbeiter

   Wähle eine Rolle wie Softwareentwickler oder SEO-Spezialist, schreibe sein Ziel als Zahl und führe den Setup-Befehl in deinem Projekt aus, wo deine CLAUDE.md schon liegt.

2. Lass den Heartbeat die Arbeit starten

   Während seiner Arbeitszeiten wacht der Mitarbeiter alle 15, 30 oder 60 Minuten in derselben Konversation auf; siehe Claude Code proaktiv machen. Mehrere können sich ein Repository teilen, wie bei mehreren Claude-Code-Agenten.

3. Weise Issues zu und beantworte seine Nachrichten

   Lege Arbeit auf das Board; der Mitarbeiter übernimmt sie, kommentiert unterwegs und schreibt dir, wenn er eine Entscheidung braucht. Lies, was ein KI-Mitarbeiter ist.

FAQ zu CLAUDE.md