CLAUDE.md: Das Projektwissen, das Claude Code immer dabei hat

Lektion 7: CLAUDE.md, wie Claude Code dein Projekt kennenlernt

Das Problem: Claude Code kennt kein Projekt

Wenn du Claude Code in einem Verzeichnis startest, sieht es zwar alle Dateien, aber es weiß zunächst nichts darüber, wie das Projekt aufgebaut ist, welche Konventionen gelten oder welche Befehle verwendet werden. Ohne weitere Einweisung muss Claude Code bei jeder Session von vorne erkunden, was das Projekt eigentlich macht.

Für ein einzelnes Skript ist das kein Problem. Bei größeren oder regelmäßig genutzten Projekten kostet diese Erkennungsphase Zeit und führt zu Fehlern: Claude Code schlägt Befehle aus dem falschen Framework vor, ignoriert den Code-Stil des Teams oder baut Tests nach dem falschen Muster.

CLAUDE.md löst dieses Problem, dauerhaft und für alle Sessions.

Was ist CLAUDE.md?

CLAUDE.md ist eine Markdown-Datei, die du im Root-Verzeichnis (dem obersten Ordner eines Projekts, der Ausgangspunkt der gesamten Verzeichnisstruktur) deines Projekts anlegst. Claude Code liest sie automatisch bei jedem Start und behandelt ihren Inhalt als unsichtbare Hintergrundinstruktion, ähnlich wie Custom Instructions in einem Claude.ai-Project, aber spezifisch für dieses Projektverzeichnis.

Drei wichtige Eigenschaften:

1. Automatisch geladen, du musst nichts aktivieren oder einen Befehl ausführen. Sobald die Datei existiert, gilt sie für jede Session in diesem Verzeichnis.
2. Persistente Anweisung, jede Claude-Code-Session startet mit diesem Wissen, ohne dass du es jedes Mal eingeben musst.
3. Hierarchisch, CLAUDE.md-Dateien in Unterordnern ergänzen die Root-Datei. Das ist nützlich, wenn verschiedene Teile eines Monorepos (ein einzelnes Git-Repository, das mehrere Projekte oder Pakete enthält) unterschiedliche Konventionen haben.

Was gehört in eine CLAUDE.md?

Eine gute CLAUDE.md beantwortet die Fragen, die sich Claude Code beim Start stellt:

1. Projektbeschreibung Was macht das Projekt? Was ist das Ziel? Das gibt Claude Code den Überblick, um Fragen im richtigen Rahmen zu beantworten, ohne die Codebasis zuerst vollständig zu durchsuchen.

2. Tech-Stack Welche Programmiersprachen, Frameworks (vorgefertigte Softwarerahmenwerke, die grundlegende Architekturentscheidungen festlegen, z. B. React, FastAPI oder Spring) und wichtige Bibliotheken werden verwendet? Ohne diese Info schlägt Claude Code eventuell falsche Imports oder die falsche Syntax vor.

3. Häufige Befehle Welche Kommandozeilenbefehle werden für Bauen, Testen und Ausführen des Projekts verwendet? Claude Code kann diese dann direkt aufrufen, ohne sie zu erraten.

4. Code-Konventionen Naming-Regeln, Formatierungsstandards, Kommentarpolitik, alles, was im Team oder im Projekt als verbindlich gilt.

5. Verzeichnisstruktur Wo liegt was? Welche Ordner haben welchen Zweck? Das hilft Claude Code, Dateien an der richtigen Stelle zu erstellen und zu lesen.

6. Was Claude NICHT tun soll Explizite Ausschlüsse sind oft genauso wichtig wie Anweisungen: „Ändere nie direkt die Datenbankschicht“ oder „Schreibe keine Tests für generierte Dateien.“

Ein reales Beispiel

Hier eine CLAUDE.md für ein kleines Python-Webprojekt:

# CLAUDE.md

## Projektbeschreibung
Eine REST-API für ein internes Buchungssystem. Backend in Python, Datenbank PostgreSQL.

## Tech-Stack
- Python 3.12
- Framework: FastAPI
- Datenbank: PostgreSQL (via SQLAlchemy ORM)
- Tests: pytest
- Paketmanager: uv

## Häufige Befehle
- Server starten:       uv run uvicorn app.main:app --reload
- Tests ausführen:      uv run pytest
- Linter ausführen:     uv run ruff check .
- DB-Migrationen:       uv run alembic upgrade head

## Verzeichnisstruktur
- app/         Hauptcode (Routes, Services, Models)
- tests/       pytest-Tests (spiegeln die app/-Struktur)
- migrations/  Alembic-Migrationsdateien (nicht manuell bearbeiten)

## Konventionen
- Funktionen und Variablen in snake_case
- API-Routen unter app/routers/, ein Router pro Ressource
- Alle Datenbankzugriffe über SQLAlchemy, kein rohes SQL
- Docstrings nur für öffentliche Funktionen, einzeilig

## Ausschlüsse
- Niemals migrations/ direkt bearbeiten, nur via "alembic revision"
- Keine print()-Statements im Produktionscode; stattdessen logging

Nach dem Anlegen dieser Datei startet Claude Code jede Session mit genau diesem Wissen. Du kannst direkt sagen: „Füge eine neue Route für die Benutzeranmeldung hinzu“, ohne Vorerklärung.

CLAUDE.md anlegen: zwei Wege

Weg 1, Selbst schreiben:

# Leere Datei im Projektordner erstellen
touch CLAUDE.md

Dann füllst du sie manuell aus. Du kennst dein Projekt am besten, ein ehrlicher, knapper Text ist besser als ein langer, unscharfer.

Weg 2, Claude Code befüllen lassen: Starte Claude Code im Projektverzeichnis und gib diesen Prompt ein:

Analysiere das aktuelle Verzeichnis und erstelle eine CLAUDE.md-Datei mit:
- Kurzer Projektbeschreibung (was du erkennst)
- Tech-Stack (Sprachen, Frameworks, Bibliotheken)
- Den wichtigsten Build- und Test-Befehlen (aus package.json, Makefile o. Ä.)
- Verzeichnisstruktur (nur die wichtigsten Ordner)
- 2-3 Code-Konventionen, die du im Code erkennst

Falls du wenig erkennst: Schreib eine Vorlage, die ich ausfüllen kann.

Claude Code liest das Projektverzeichnis, erkennt den Tech-Stack und schreibt einen ersten Entwurf. Den korrigierst und ergänzt du anschließend, du kennst Details, die Claude Code nicht aus dem Code ablesen kann.

@-Imports: Andere Dateien einbinden

Ab einer gewissen Projektgröße kann CLAUDE.md lang werden. Claude Code unterstützt @-Imports (eine Syntax, mit der du Inhalte anderer Dateien in CLAUDE.md einbettest, Claude Code liest sie beim Start automatisch mit):

# CLAUDE.md

## Architektur
@docs/architecture.md

## API-Konventionen
@docs/api-guidelines.md

So kannst du bestehende Dokumentation einbinden, ohne sie zu duplizieren.

CLAUDE.md im Team: in Git einchecken

Ein entscheidender Vorteil gegenüber Custom Instructions in Claude.ai: CLAUDE.md kann ins Git-Repository (das Versionskontrollsystem, das alle Codeänderungen nachverfolgt) eingecheckt werden. Dann hat jede Person im Team automatisch dieselbe Claude-Code-Konfiguration, sobald sie das Repository klont, kein manuelles Setup, keine veralteten Kopien.

Wann CLAUDE.md besonders viel bringt

CLAUDE.md lohnt sich besonders, wenn:

• du regelmäßig in Claude Code mit demselben Projekt arbeitest
• ein Team Claude Code im gleichen Repository verwendet
• das Projekt klare Konventionen hat, die Claude sonst ignorieren würde
• du häufige Befehle nicht jedes Mal tippen willst

Für ein einmaliges Experiment oder ein frisches Projekt brauchst du sie nicht sofort, lege sie an, sobald du merkst, dass du Claude Code dieselben Dinge zweimal erklärst.

Selbst ausprobieren (ca. 10-15 min)

Du brauchst: Claude Code, ein Projektverzeichnis (eigener Code, ein Beispielprojekt oder ein leeres Verzeichnis reicht).

1. Starte Claude Code im Projektverzeichnis:

cd /pfad/zu/deinem/projekt
claude

2. Bitte Claude Code, eine CLAUDE.md zu erstellen:

Analysiere dieses Verzeichnis und erstelle eine CLAUDE.md mit:
- Kurzer Projektbeschreibung (was du erkennst)
- Tech-Stack (Sprachen, Frameworks, Bibliotheken)
- Den wichtigsten Build- und Test-Befehlen
- Verzeichnisstruktur (nur die wichtigsten Ordner)
- 2-3 Konventionen, die du im Code siehst

Falls du wenig erkennst: Schreib eine ausfüllbare Vorlage.

3. Lies den Entwurf und ergänze, was nicht stimmt oder fehlt.

4. Beende Claude Code mit /exit, starte es neu und teste:

Was macht dieses Projekt und wie führe ich die Tests aus?

Erfolg erkennst du daran: Claude Code gibt eine korrekte, projektspezifische Antwort, ohne dass du etwas erklärt hast.

Neu bei Claude

• Claude Code --safe-mode, Was ist neu: Claude Code hat einen neuen Startmodus: claude --safe-mode (alternativ Umgebungsvariable CLAUDE_CODE_SAFE_MODE=1) startet Claude Code mit deaktivierten Anpassungen, CLAUDE.md wird dabei nicht geladen, ebenso keine Plugins, Skills, Hooks oder MCP-Server. Was bringt es dir: Wenn Claude Code sich nach einer Konfigurationsänderung unerwartet verhält, kannst du mit --safe-mode sofort testen, ob das Problem in deiner CLAUDE.md oder einer anderen Anpassung liegt, ohne Debugging-Aufwand. Quelle

Glossar

• CLAUDE.md, Projektspezifische Konfigurationsdatei für Claude Code; wird beim Start automatisch geladen und vermittelt Claude Code das nötige Projektwissen, ohne dass du es im Chat erklären musst.
• Root-Verzeichnis, Der oberste Ordner eines Projekts, der Ausgangspunkt der Verzeichnisstruktur; hier liegt CLAUDE.md typischerweise.
• @-Import, Syntax in CLAUDE.md, um den Inhalt anderer Dateien einzubetten (@docs/datei.md); Claude Code liest diese Dateien beim Start automatisch mit.
• Framework, Vorgefertigte Softwarestruktur, die grundlegende Architekturentscheidungen für ein Projekt festlegt (z. B. FastAPI, React, Django).
• Monorepo, Ein einzelnes Git-Repository, das mehrere Projekte oder Pakete enthält; CLAUDE.md-Dateien in Unterordnern erlauben dort projektspezifische Konfiguration.