Die Idee

Ein Coding-Agent ist nützlicher, wenn er die stabilen Fakten deines Repositories kennt: wie Tests laufen, wo ein Service liegt oder welche Konventionen gelten. Du könntest diese Fakten in jedem Chat erneut erklären. Eine CLAUDE.md ist ein besserer Ort für Fakten, die das gesamte Team bewusst festhalten möchte.

CLAUDE.md ist eine von Menschen gepflegte Markdown-Datei mit dauerhaften Projektanweisungen für Claude Code. Projektweite Dateien können über die Versionsverwaltung mit dem Team geteilt werden. Eine persönliche CLAUDE.local.md ist für projektspezifische Einstellungen gedacht, die nicht ins Repository gehören; laut Dokumentation solltest du sie zu .gitignore hinzufügen. Quelle: Claude-Code-Dokumentation

Einfach gesagt: Betrachte CLAUDE.md als kurze, versionierte Onboarding-Notiz für einen KI-Coding-Helfer. Sie gibt Orientierung; sie erteilt oder entzieht keine Berechtigungen.

Dieser Unterschied ist wichtig. Claude Code behandelt CLAUDE.md als Kontext, nicht als harte technische Durchsetzung. Halte gewünschtes Verhalten dort fest, aber verlasse dich nicht auf einen Satz wie „Ändere niemals Secrets“ als Schutzgrenze. Für Regeln, die technisch durchgesetzt werden müssen, nutze gegebenenfalls einen Hook oder eine verwaltete Einstellung. Hooks werden durch Lifecycle-Ereignisse ausgelöst und können zum Beispiel Befehle blockieren, bevor sie laufen. Quelle: Claude-Code-Dokumentation

Halte gemeinsame Anweisungen bewusst kurz und konkret. Geeignet sind Build- und Testbefehle, wichtige Verzeichnisse, Code-Konventionen und Prüfungen für eine häufige Änderung. Ein langes Regelwerk ist schwerer zu pflegen und liefert dem Agenten mehr konkurrierende Anweisungen, die er auslegen muss.

Verwechsle die Datei nicht mit Auto Memory. CLAUDE.md wird von Menschen geschrieben und geprüft. Auto Memory wird von Claude aus Korrekturen, Präferenzen und nützlichen projektspezifischen Erkenntnissen erstellt. Seine Dateien bleiben maschinenlokal, statt zwischen Maschinen oder Cloud-Umgebungen geteilt zu werden. Daher ist Auto Memory kein guter Ersatz für Teamstandards. Quelle: Claude-Code-Dokumentation

Ein kleines Beispiel

Beispiel: Dein Team pflegt einen Node-Service. Eine kompakte CLAUDE.md könnte Folgendes enthalten:

Führe vor einem Änderungsvorschlag `npm test` aus.
Führe bei TypeScript-Änderungen `npm run lint` aus.
API-Handler liegen in src/api/.
Neue Endpunkte brauchen Eingabevalidierung und Tests.

Jede Zeile beantwortet eine Frage, die der Agent sonst stellen oder erneut herausfinden müsste. Die Datei ersetzt weder Code Review noch Tests oder Zugriffskontrollen. Sie gibt dem Agenten einen gemeinsamen Ausgangspunkt.

Angenommen, dein lokaler Rechner hat zusätzlich eine Sandbox-URL und Daten für Wegwerf-Testkonten. Das sind persönliche Projekteinstellungen. Lege sie daher in CLAUDE.local.md ab und halte diese Datei aus der Versionsverwaltung heraus. So trennst du Teamkontext von der lokalen Einrichtung einer Entwicklerin oder eines Entwicklers. Quelle: Claude-Code-Dokumentation

Vielleicht begegnest du auch AGENTS.md. Es ist ein Markdown-Format für Anweisungen, die verschiedene Coding-Agenten teilen können, und hat keine Pflichtfelder. Claude Code kann es direkt lesen. Standardmäßig verwendet es AGENTS.md, wenn keine passende CLAUDE.md oder CLAUDE.local.md gefunden wird; per Konfiguration können beide Dateitypen gelesen werden. Unterstützung und Ladeverhalten anderer Tools können abweichen. Quellen: Claude-Code-Dokumentation AGENTS.md

Für einen ausführlichen wiederholbaren Ablauf, etwa die Release-Vorbereitung, ist stattdessen ein Skill sinnvoll. Skills verwenden SKILL.md-Dateien. Ihre Hauptanweisungen werden geladen, wenn du sie aufrufst oder Claude Code sie als relevant erkennt. So muss nicht jede Sitzung einen Ablauf mitführen, den sie nicht braucht. Quelle: Claude-Code-Dokumentation

Probier es aus

Stelle einen Timer auf fünf Minuten. Erstelle oder prüfe die CLAUDE.md deines Projekts und schreibe vier kurze Stichpunkte: einen Testbefehl, einen Lint- oder Build-Befehl, ein wichtiges Verzeichnis und eine Änderungsregel. Stelle dann zwei Fragen:

  1. Ist jeder Stichpunkt für alle Teammitglieder nützlich?
  2. Ist ein Stichpunkt in Wahrheit eine Sicherheits- oder Schutzanforderung?

Verschiebe private Rechnerdetails in CLAUDE.local.md und füge die Datei zu .gitignore hinzu. Prüfe für jede Anforderung, die nicht umgangen werden darf, eine verwaltete Einstellung oder einen PreToolUse-Hook, statt dich allein auf Text zu verlassen. Das ist eine Einordnungsübung, keine Aufforderung, ohne Prüfung einen Hook einzusetzen.

Darauf solltest du achten

CLAUDE.md kann missverstanden, durch andere Regeln widersprochen oder nicht befolgt werden. Sie ist Orientierung, keine Garantie. Prüfe sie im Code Review wie andere Projektdokumentation.

Prüfe außerdem, welche Instruktionsdateien deine installierte Claude-Code-Version und Konfiguration laden. AGENTS.md ist als gemeinsame Konvention für mehrere Agenten nützlich, aber die Unterstützung ist nicht universell. Prüfe Hooks zuletzt besonders sorgfältig: Sie bieten besser vorhersehbare Kontrolle als Anweisungen, führen aber konfigurierte Aktionen aus und erhöhen die Betriebsverantwortung. Quellen: Claude-Code-Dokumentation AGENTS.md