CLAUDE.md erstellen und richtig aufbauen: Anleitung für Claude Code

Im Claude Code Cheat Sheet habe ich die CLAUDE.md bereits kurz angerissen. Aber diese Datei verdient einen eigenen, tiefgehenden Artikel. Denn sie ist der Dreh- und Angelpunkt, wenn es darum geht, Claude Code wirklich effektiv in Ihrem Projekt einzusetzen. Ohne sie fängt Claude bei jeder neuen Session wieder bei null an. Mit einer gut gepflegten CLAUDE.md weiß Claude sofort, wie Ihr Projekt aufgebaut ist, welche Standards gelten und wie es sich verhalten soll.

Was ist die CLAUDE.md?

Die CLAUDE.md ist eine Markdown-Datei, die Claude Code zu Beginn jeder Session automatisch einliest. Sie enthält alles, was Claude wissen muss, um in Ihrem Projekt sofort produktiv zu arbeiten: Build-Befehle, Code-Standards, Architekturentscheidungen und Workflow-Regeln. Stellen Sie es sich vor wie ein Onboarding-Dokument für einen neuen Entwickler, nur eben für eine KI.

Wichtig: Die CLAUDE.md ist Kontext und keine erzwungene Konfiguration. Claude liest die Datei und versucht, sich daran zu halten. Je spezifischer und knapper Sie formulieren, desto zuverlässiger hält sich Claude an Ihre Vorgaben.

Speicherorte und Geltungsbereiche

Die CLAUDE.md kann an verschiedenen Stellen liegen, die jeweils einen anderen Geltungsbereich haben. Alle gefundenen Dateien werden aneinandergehängt, nicht überschrieben; die projektnächste Datei steht zuletzt im Kontext.

# Projekt-Ebene: wird über Git mit dem Team geteilt
./CLAUDE.md
# oder im .claude-Verzeichnis
./.claude/CLAUDE.md
# Persönliche Notizen im Projekt, nicht im Repository (siehe unten)
./CLAUDE.local.md

# Persönliche Ebene: gilt für alle Ihre Projekte
~/.claude/CLAUDE.md

# Organisations-Ebene: durch IT/DevOps zentral verwaltet
# macOS:  /Library/Application Support/ClaudeCode/CLAUDE.md
# Linux:  /etc/claude-code/CLAUDE.md
# Windows: C:\Program Files\ClaudeCode\CLAUDE.md

# Unterverzeichnisse: werden on-demand geladen,
# wenn Claude mit Dateien in diesen Verzeichnissen arbeitet
packages/frontend/CLAUDE.md
packages/backend/CLAUDE.md

Claude lädt die CLAUDE.md-Dateien, indem es vom aktuellen Arbeitsverzeichnis nach oben wandert. Arbeiten Sie also in foo/bar/, werden sowohl foo/bar/CLAUDE.md als auch foo/CLAUDE.md geladen. CLAUDE.md-Dateien in Unterverzeichnissen werden erst geladen, wenn Claude dort tatsächlich mit Dateien arbeitet.

Die erste CLAUDE.md erstellen

Der schnellste Weg zu einer CLAUDE.md ist der /init-Befehl direkt in Claude Code. Claude analysiert dann Ihre Codebase und erstellt automatisch eine Startdatei mit Build-Befehlen, Test-Anweisungen und Konventionen, die es entdeckt.

# Im Projektverzeichnis Claude Code starten
cd mein-projekt
claude

# CLAUDE.md automatisch generieren lassen
/init

# Claude analysiert Ihre Codebase und schlägt eine CLAUDE.md vor.
# Existiert bereits eine, werden Verbesserungen vorgeschlagen,
# statt sie zu überschreiben.

Die generierte Datei ist ein Startpunkt. Von dort aus verfeinern Sie sie mit Anweisungen, die Claude nicht von selbst aus dem Code ablesen kann.

Was hineingehört, und was nicht

Die CLAUDE.md wird bei jeder Session in das Context Window geladen und verbraucht dabei Tokens. Das heißt: Jede Zeile, die Sie hinzufügen, reduziert den Platz für Ihre eigentliche Konversation. Deshalb ist weniger hier definitiv mehr.

Das gehört rein

# Rein: Bash-Befehle, die Claude nicht erraten kann
## Build & Test
- Build: `npm run build`
- Tests: `npm test`
- Einzelner Test: `npm test -- --grep "Testname"`
- Linting: `npm run lint`

# Rein: Code-Standards, die von Defaults abweichen
## Code-Standards
- 2-Space-Indentation (kein Tab)
- Immer ES Modules (import/export), kein CommonJS (require)
- Destrukturierung bei Imports bevorzugen

# Rein: Architekturentscheidungen, die projektspezifisch sind
## Architektur
- Monorepo mit Turborepo
- API-Handler liegen in src/api/handlers/
- Shared Packages in packages/shared/

# Rein: Repository-Etiquette
## Git-Workflow
- Feature-Branches von main erstellen
- Conventional Commits auf Englisch
- Vor jedem Commit: npm test ausführen

# Rein: Nicht-offensichtliches Verhalten und Gotchas
## Gotchas
- Der Dev-Server braucht die .env.local Datei
- Tests laufen nur mit lokaler Redis-Instanz
- Die CI-Pipeline erwartet Node 20

Das gehört NICHT rein

# Nicht rein: Dinge, die Claude durch Lesen des Codes selbst herausfinden kann
# z.B. welche Frameworks verwendet werden, wenn sie in package.json stehen

# Nicht rein: Standard-Sprachkonventionen, die Claude bereits kennt
# z.B. "Verwende camelCase in JavaScript": das macht Claude ohnehin

# Nicht rein: Detaillierte API-Dokumentation (lieber verlinken)
# Stattdessen: "API-Docs: @docs/api-reference.md"

# Nicht rein: Informationen, die sich häufig ändern
# z.B. aktuelle Versionsnummern oder Sprint-Ziele

# Nicht rein: Datei-für-Datei-Beschreibungen der Codebase
# Das kann Claude selbst lesen

# Nicht rein: Selbstverständlichkeiten
# z.B. "Schreibe sauberen Code": das bringt nichts

Meine Faustregel: Fragen Sie sich bei jeder Zeile, ob Claude ohne diese Anweisung Fehler machen würde. Wenn nein, streichen Sie sie raus. Eine aufgeblähte CLAUDE.md führt dazu, dass Claude die wirklich wichtigen Regeln übersieht.

Größe und Struktur optimieren

Halten Sie die CLAUDE.md unter 200 Zeilen. Nutzen Sie Markdown-Überschriften und Aufzählungen, um zusammengehörige Anweisungen zu gruppieren. Claude scannt die Struktur genauso wie ein menschlicher Leser: Gut organisierte Abschnitte werden besser befolgt als dichte Textblöcke.

# Gute Struktur: klar, scanbar, spezifisch

## Build & Test
- Build: `npm run build`
- Tests: `npm test`
- Type-Check: `npx tsc --noEmit`

## Code-Standards
- TypeScript strict mode
- Funktionale React-Komponenten mit Hooks
- Keine Class-Components

## Git
- Conventional Commits
- Branch-Prefix: feature/, bugfix/, hotfix/

## Architektur
- src/api/ → API-Handler
- src/components/ → React-Komponenten
- src/lib/ → Shared Utilities

Wenn Claude trotz einer Regel in der CLAUDE.md etwas falsch macht, ist die Datei wahrscheinlich zu lang und die Regel geht im Rauschen unter. Sie können wichtige Anweisungen auch betonen, z.B. mit „WICHTIG:“ oder „PFLICHT:“, um die Einhaltung zu verbessern.

Externe Dateien importieren

Damit die CLAUDE.md schlank bleibt, können Sie externe Dateien mit der @pfad/zur/datei-Syntax importieren. Importierte Dateien werden beim Start zusammen mit der CLAUDE.md in den Kontext geladen.

# In der CLAUDE.md:

# Projekt-Übersicht und verfügbare npm-Befehle aus bestehenden Dateien laden
@README.md
@package.json

# Zusätzliche Anweisungen aus separaten Dateien
## Git-Workflow
@docs/git-instructions.md

## Deployment
@docs/deployment-guide.md

# Persönliche Präferenzen, die nicht ins Repo sollen
# (Die Datei liegt lokal, der Import steht in der geteilten CLAUDE.md)
@~/.claude/meine-projekt-prefs.md

Sowohl relative als auch absolute Pfade funktionieren. Relative Pfade werden relativ zur Datei aufgelöst, die den Import enthält. Importierte Dateien können wiederum weitere Dateien importieren, mit einer maximalen Tiefe von vier Ebenen.

Falls Ihr Repository bereits eine AGENTS.md für andere Coding-Agenten verwendet, erstellen Sie einfach eine CLAUDE.md, die sie importiert:

# CLAUDE.md: importiert die bestehende AGENTS.md
# und ergänzt Claude-spezifische Anweisungen

@AGENTS.md

## Claude Code spezifisch
- Nutze Plan-Modus für Änderungen unter src/billing/
- Bevorzuge Subagents für Code Reviews

Regeln modular aufteilen mit .claude/rules/

Für größere Projekte können Sie Anweisungen in mehrere Dateien aufteilen. Das .claude/rules/-Verzeichnis hält Regeln modular und pflegbar. Jede Datei sollte ein Thema abdecken.

# Verzeichnisstruktur für modulare Regeln
mein-projekt/
├── .claude/
│   ├── CLAUDE.md              # Hauptanweisungen
│   └── rules/
│       ├── code-style.md      # Code-Standards
│       ├── testing.md         # Test-Konventionen
│       ├── security.md        # Sicherheitsregeln
│       ├── frontend/
│       │   └── react.md       # Frontend-spezifische Regeln
│       └── backend/
│           └── api-design.md  # API-Design-Standards

Regeln ohne paths-Frontmatter werden bedingungslos bei jedem Session-Start geladen. Das eigentlich Mächtige sind aber die pfad-spezifischen Regeln, die nur dann greifen, wenn Claude mit bestimmten Dateien arbeitet.

Pfad-spezifische Regeln

# Datei: .claude/rules/api-standards.md
# Diese Regeln laden nur, wenn Claude an Dateien arbeitet,
# die dem Pfad-Muster entsprechen

---
paths:
  - "src/api/**/*.ts"
---

# API Entwicklungsregeln
- Alle Endpoints brauchen Input-Validierung
- Standard-Error-Response-Format verwenden
- OpenAPI-Dokumentationskommentare hinzufügen
- Rate Limiting für alle öffentlichen Endpoints

# Datei: .claude/rules/react-components.md
# Greift nur bei React-Dateien

---
paths:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
---

# React-Komponentenregeln
- Funktionale Komponenten mit Hooks
- Props immer als Interface definieren
- Keine inline Styles, Tailwind CSS nutzen
- Tests mit React Testing Library

# Datei: .claude/rules/database.md
# Greift bei Migrations- und Datenbankdateien

---
paths:
  - "src/db/**/*.ts"
  - "prisma/**/*.prisma"
  - "migrations/**/*.sql"
---

# Datenbank-Regeln
- WICHTIG: Niemals Daten löschen in Migrationen, nur Spalten hinzufügen
- Immer Rollback-Migrationen bereitstellen
- Indizes für Foreign Keys nicht vergessen
- snake_case für Tabellen- und Spaltennamen

Sie können in paths Glob-Patterns verwenden und auch mehrere Muster mit geschweiften Klammern kombinieren:

# Glob-Pattern Beispiele
---
paths:
  - "**/*.ts"                    # Alle TypeScript-Dateien
  - "src/**/*"                   # Alles unter src/
  - "*.md"                       # Markdown im Projekt-Root
  - "src/components/*.tsx"       # Nur eine Ebene tief
  - "src/**/*.{ts,tsx}"          # TypeScript UND TSX
  - "tests/**/*.test.ts"        # Nur Test-Dateien
---

Regeln per Symlink teamübergreifend teilen

Das .claude/rules/-Verzeichnis unterstützt Symlinks. Damit können Sie einen gemeinsamen Regelsatz pflegen und in mehrere Projekte verlinken.

# Gemeinsames Regelverzeichnis verlinken
ln -s ~/shared-claude-rules .claude/rules/shared

# Einzelne Regeldatei verlinken
ln -s ~/company-standards/security.md .claude/rules/security.md

Persönliche Regeln

Neben den Projekt-Regeln gibt es persönliche Regeln, die in ~/.claude/rules/ liegen und für alle Ihre Projekte gelten. Perfekt für Vorlieben, die nicht projektspezifisch sind.

# Persönliche Regeln (gelten überall)
~/.claude/rules/
├── preferences.md     # Ihre persönlichen Coding-Vorlieben
└── workflows.md       # Ihre bevorzugten Workflows

# Beispiel: ~/.claude/rules/preferences.md
# Persönliche Vorlieben
- Commit Messages immer auf Englisch
- Bevorzuge funktionale Programmierung wo möglich
- Kommentare im Code auf Deutsch
- Nutze pnpm statt npm

Persönliche Regeln werden vor Projekt-Regeln geladen, Projekt-Regeln haben also höhere Priorität.

CLAUDE.local.md: persönliche Einstellungen im Projekt

Manche Angaben gehören weder in die geteilte CLAUDE.md noch in Ihre globalen Regeln: die URL Ihrer lokalen Sandbox, bevorzugte Testdaten, ein Pfad auf Ihrem Rechner. Dafür gibt es die CLAUDE.local.md. Sie liegt im Projektstamm neben der CLAUDE.md, wird zusammen mit ihr geladen und genauso behandelt. Der Unterschied ist die Reichweite: sie gilt nur für Sie und nur in diesem Projekt.

# Projektstamm
./CLAUDE.md          # geteilt, im Repository
./CLAUDE.local.md    # nur Sie, nur dieses Projekt

# In .gitignore aufnehmen, damit sie nicht eingecheckt wird
echo "CLAUDE.local.md" >> .gitignore

# Beispiel: ./CLAUDE.local.md
# Lokale Umgebung
- Staging läuft unter http://shop.localhost:8081
- Testkonto: kunde-test@example.com (Passwort im Passwortmanager)
- Vor dem Push immer gegen die lokale Datenbank testen

Beim Laden hängt Claude Code in jedem Verzeichnis die CLAUDE.local.md hinter die CLAUDE.md. Ihre persönlichen Notizen sind damit das Letzte, was Claude auf dieser Ebene liest. Eine Falle gibt es bei Git-Worktrees: eine ignorierte Datei existiert nur in dem Worktree, in dem Sie sie angelegt haben. Wer in mehreren Worktrees desselben Repositories arbeitet, importiert seine persönlichen Anweisungen stattdessen aus dem Home-Verzeichnis, etwa mit @~/.claude/mein-projekt.md in der CLAUDE.md.

Welche Datei wofür

Datei	Gilt für	Geteilt mit	Typischer Inhalt
~/.claude/CLAUDE.md	alle Ihre Projekte	nur Sie	Stilvorlieben, eigene Werkzeuge, Sprache der Commit-Nachrichten
./CLAUDE.md oder ./.claude/CLAUDE.md	dieses Projekt	Team, über Git	Build-Befehle, Architektur, Konventionen, Arbeitsabläufe
./CLAUDE.local.md	dieses Projekt	nur Sie	Sandbox-URLs, Testdaten, lokale Pfade
.claude/rules/*.md	dieses Projekt, optional nur bestimmte Pfade	Team, über Git	Regeln je Thema: Tests, API-Design, Sicherheit
~/.claude/rules/*.md	alle Ihre Projekte	nur Sie	persönliche Regeln je Thema

CLAUDE.md-Beispiele für verschiedene Projekttypen

Jetzt wird es konkret. Hier sind vollständige CLAUDE.md-Beispiele für gängige Projekttypen.

Next.js Frontend-Projekt

# CLAUDE.md: Next.js Frontend

## Build & Test
- Dev-Server: `pnpm dev`
- Build: `pnpm build`
- Tests: `pnpm test`
- Linting: `pnpm lint`
- Type-Check: `pnpm typecheck`

## Tech-Stack
- Next.js 15 mit App Router
- TypeScript strict mode
- Tailwind CSS für Styling
- Zustand für State Management
- React Query für Server State

## Code-Standards
- Funktionale Komponenten mit Hooks, keine Class-Components
- Props als Interface definieren, nicht als Type
- Server Components als Default, Client Components nur wo nötig
- `use client` Directive nur bei interaktiven Komponenten

## Dateistruktur
- app/ → Routen und Layouts (App Router)
- components/ → Wiederverwendbare UI-Komponenten
- lib/ → Utilities und Helper
- hooks/ → Custom React Hooks
- types/ → Globale TypeScript-Typen

## Gotchas
- Umgebungsvariablen: .env.local wird benötigt (siehe .env.example)
- Bilder immer über next/image einbinden
- API-Calls in Server Components bevorzugen

Python API-Projekt

# CLAUDE.md: Python FastAPI Backend

## Build & Test
- Virtuelle Umgebung: `python -m venv .venv && source .venv/bin/activate`
- Abhängigkeiten: `pip install -r requirements.txt`
- Dev-Server: `uvicorn app.main:app --reload`
- Tests: `pytest -v`
- Einzelner Test: `pytest tests/test_auth.py -v`
- Type-Check: `mypy app/`
- Linting: `ruff check app/`

## Tech-Stack
- Python 3.12+
- FastAPI mit Pydantic v2
- SQLAlchemy 2.0 (async)
- PostgreSQL als Datenbank
- Alembic für Migrationen
- Redis für Caching

## Code-Standards
- Type Hints für alle Funktionen und Parameter
- Pydantic Models für Request/Response Validierung
- Async/Await für alle Datenbankoperationen
- Docstrings im Google-Style

## Dateistruktur
- app/main.py → FastAPI App und Router
- app/api/ → Endpoint-Handler
- app/models/ → SQLAlchemy Models
- app/schemas/ → Pydantic Schemas
- app/services/ → Business Logic
- app/core/ → Konfiguration und Dependencies

## Gotchas
- .env Datei nötig (siehe .env.example)
- Datenbank-Migrationen: `alembic upgrade head`
- Redis muss lokal laufen für Tests
- WICHTIG: Keine raw SQL Queries, immer SQLAlchemy ORM nutzen

Monorepo mit Turborepo

# CLAUDE.md: Monorepo (Root)

## Build & Test
- Alle Packages bauen: `pnpm build`
- Alle Tests: `pnpm test`
- Nur geänderte Packages: `pnpm build --filter=...[HEAD~1]`
- Einzelnes Package: `pnpm --filter @acme/web dev`

## Monorepo-Struktur
- apps/web → Next.js Frontend
- apps/api → Express Backend
- packages/ui → Shared UI-Komponenten
- packages/config → Shared Konfiguration (ESLint, TSConfig)
- packages/types → Geteilte TypeScript-Typen

## Regeln
- WICHTIG: Änderungen an packages/ erfordern Tests in ALLEN abhängigen apps/
- Neue Dependencies immer im richtigen Package installieren, nicht im Root
- Shared Types gehören nach packages/types/, nicht in die Apps
- Workspace-Protokoll nutzen: `"@acme/ui": "workspace:*"`

## Git
- Conventional Commits mit Scope: feat(web): ..., fix(api): ...
- PRs brauchen mindestens einen Review
- CI muss grün sein vor Merge

@apps/web/CLAUDE.md
@apps/api/CLAUDE.md

WordPress Plugin

# CLAUDE.md: WordPress Plugin

## Setup
- Lokale Entwicklung: `wp-env start`
- Plugin-Assets bauen: `npm run build`
- Watch-Modus: `npm run start`
- PHP Linting: `composer run lint`
- JS Linting: `npm run lint`

## Tech-Stack
- PHP 8.1+ mit WordPress Coding Standards
- Gutenberg Blocks mit @wordpress/scripts
- React für Block-Editor-UI
- REST API für AJAX-Kommunikation

## Code-Standards
- WordPress Coding Standards (PHPCS)
- Alle Strings i18n-ready: `__('Text', 'mein-plugin')`
- Prefix für alle Funktionen: `meinplugin_`
- Nonces für alle Formulare und AJAX-Calls
- WICHTIG: Alle Datenbankabfragen mit `$wpdb->prepare()`

## Dateistruktur
- includes/ → PHP-Klassen und Funktionen
- src/ → JavaScript/React Quellcode
- build/ → Kompilierte Assets (nicht bearbeiten)
- languages/ → Übersetzungsdateien
- templates/ → PHP-Templates

## Gotchas
- `wp-env` braucht Docker
- Block-Registrierung in block.json, nicht in PHP
- Enqueue nur auf relevanten Admin-Seiten, nicht global

Auto Memory: Claude lernt automatisch dazu

Neben der CLAUDE.md gibt es ein zweites Gedächtnis-System: Auto Memory. Claude schreibt sich automatisch Notizen, wenn es etwas für künftige Sessions Nützliches entdeckt: Ihre Rolle und Vorlieben, Korrekturen, die Sie geben, laufende Vorhaben und Verweise nach außen. Was Claude aus dem Code selbst ablesen kann, etwa Architektur oder Dateipfade, wird bewusst nicht gespeichert. Sie müssen dafür nichts tun.

# Auto Memory wird hier gespeichert:
~/.claude/projects/<projekt>/memory/
├── MEMORY.md         # Index-Datei, wird bei jedem Session-Start geladen
├── feedback_tests.md  # eine Korrektur, die Sie gegeben haben
├── api-conventions.md # API-Design-Entscheidungen
└── ...               # Weitere Themen-Dateien

# Auto Memory verwalten
/memory              # Öffnet den Memory-Manager in der Session

# Claude aktiv etwas merken lassen
"Bitte merken: Wir nutzen immer pnpm, nicht npm"
"Zur Erinnerung: Die API-Tests brauchen eine lokale Redis-Instanz"

# Auto Memory deaktivieren (falls gewünscht)
# In .claude/settings.json:
{
  "autoMemoryEnabled": false
}

# Oder per Umgebungsvariable:
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Die ersten 200 Zeilen (oder 25 KB) der MEMORY.md werden bei jedem Session-Start geladen. Claude hält die Datei kompakt, indem es detaillierte Notizen in separate Themen-Dateien auslagert. Diese werden nur bei Bedarf gelesen. Alles ist normales Markdown, das Sie jederzeit bearbeiten oder löschen können.

Skills: Workflows auf Abruf

Während die CLAUDE.md bei jeder Session geladen wird, sind Skills Anweisungen, die nur bei Bedarf aktiviert werden. Perfekt für Domain-Wissen oder wiederholbare Workflows, die nicht bei jeder Konversation nötig sind.

# Skills leben in .claude/skills/ als Verzeichnisse mit SKILL.md

# Projekt-Skills (nur für dieses Projekt)
.claude/skills/deploy/SKILL.md
.claude/skills/review-pr/SKILL.md

# Persönliche Skills (für alle Projekte)
~/.claude/skills/fix-issue/SKILL.md

# Beispiel: .claude/skills/deploy/SKILL.md
---
name: deploy
description: Deployment in die Produktionsumgebung
disable-model-invocation: true    # Nur manuell auslösbar
---

Deployment durchführen:
1. Test-Suite ausführen
2. Build erstellen
3. Auf Deployment-Ziel pushen
4. Deployment verifizieren

# Aufruf in der Session:
/deploy production

Der Unterschied zur CLAUDE.md: Skills verbrauchen nur dann Context-Tokens, wenn sie tatsächlich aktiviert werden. Das spart Platz und hält das Context Window sauber. Nutzen Sie die CLAUDE.md für Dinge, die immer gelten, und Skills für spezifische Workflows.

Ausschlüsse in Monorepos

In großen Monorepos kann es passieren, dass CLAUDE.md-Dateien anderer Teams mitgeladen werden, die für Ihre Arbeit irrelevant sind. Mit claudeMdExcludes können Sie bestimmte Dateien ausschließen.

# In .claude/settings.local.json (bleibt lokal, nicht im Git)
{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/anderes-team/.claude/rules/**"
  ]
}

# Patterns werden gegen absolute Pfade gematcht (Glob-Syntax)
# Kann auf jeder Settings-Ebene konfiguriert werden:
# user, project, local oder managed policy
# Arrays werden über die Ebenen hinweg gemergt

# WICHTIG: Die Organisations-CLAUDE.md (managed policy)
# kann NICHT ausgeschlossen werden

Troubleshooting

Hier die häufigsten Probleme und wie Sie sie lösen.

Claude ignoriert meine CLAUDE.md

# 1. Prüfen Sie, ob die Dateien geladen werden
/context
# Zeigt unter "Memory files", welche CLAUDE.md- und Rules-Dateien
# in dieser Session wirklich geladen sind. /memory öffnet sie zum Bearbeiten.

# 2. Prüfen Sie den Speicherort
# Die CLAUDE.md muss im aktuellen oder einem übergeordneten Verzeichnis liegen

# 3. Machen Sie Anweisungen spezifischer
# Vage: "Formatiere Code ordentlich"
# Konkret: "Verwende 2-Space-Indentation, keine Tabs"

# 4. Suchen Sie nach widersprüchlichen Regeln
# Wenn zwei Dateien unterschiedliche Anweisungen geben,
# wählt Claude willkürlich

# 5. Betonen Sie wichtige Regeln
# "WICHTIG: Immer Tests ausführen vor dem Commit"
# "PFLICHT: pnpm verwenden, nicht npm"

CLAUDE.md ist zu groß

# Dateien über 200 Zeilen verbrauchen zu viel Context
# und Anweisungen werden schlechter befolgt

# Lösung 1: Detaillierte Inhalte in separate Dateien auslagern
@docs/api-reference.md     # per Import referenzieren

# Lösung 2: Nutzen Sie .claude/rules/ für modulare Regeln
# Pfad-spezifische Regeln laden nur wenn nötig

# Lösung 3: Verschieben Sie Workflows in Skills
# .claude/skills/ laden nur bei explizitem Aufruf

# Lösung 4: Überflüssiges streichen
# Alles entfernen, was Claude auch ohne Anweisung richtig macht

Anweisungen verschwinden nach /compact

# Die CLAUDE.md im Projektstamm überlebt Compaction.
# Nach /compact liest Claude sie neu von der Festplatte ein.
# Verschachtelte CLAUDE.md-Dateien und pfadgebundene Regeln laden
# erst wieder, wenn Claude eine passende Datei liest.

# Wenn eine Anweisung nach Compaction weg ist,
# wurde sie nur in der Konversation gegeben,
# nicht in die CLAUDE.md geschrieben.

# Lösung: Wichtige Anweisungen in die CLAUDE.md aufnehmen,
# damit sie über Sessions hinweg bestehen bleiben.

# Tipp für Compaction-Anweisungen in der CLAUDE.md:
# "Beim Komprimieren: Immer die vollständige Liste
#  geänderter Dateien und Test-Befehle beibehalten"

CLAUDE.md als Team-Ressource

Checken Sie die CLAUDE.md in Git ein. Sie gewinnt über die Zeit an Wert, wenn das ganze Team daran mitarbeitet. Behandeln Sie sie wie Code: Reviewen Sie sie, wenn etwas schiefläuft, und räumen Sie sie regelmäßig auf.

# Die CLAUDE.md ins Repo einchecken
git add CLAUDE.md .claude/rules/
git commit -m "docs: CLAUDE.md und Rules hinzufügen"

# Persönliche Overrides NICHT einchecken
# Stattdessen in CLAUDE.local.md (steht in .gitignore), oder bei
# mehreren Worktrees per Import aus dem Home-Verzeichnis:
# @~/.claude/meine-projekt-prefs.md

# .claude/settings.local.json in .gitignore
echo ".claude/settings.local.json" >> .gitignore

Fazit

Die CLAUDE.md ist der stärkste Hebel, den Sie haben, um Claude Code an Ihr Projekt anzupassen. Investieren Sie die Zeit, sie richtig aufzusetzen, und Sie werden bei jeder Session davon profitieren. Starten Sie mit /init, halten Sie die Datei schlank und spezifisch, nutzen Sie .claude/rules/ für modulare Regeln und Skills für Workflows, die nicht permanent im Kontext liegen müssen.

Denken Sie daran: Weniger ist mehr. Eine CLAUDE.md mit 50 präzisen Zeilen schlägt eine mit 500 vagen Zeilen. Und wenn Claude trotz Anweisung etwas falsch macht, ist die Lösung selten, noch mehr Regeln hinzuzufügen, sondern die bestehenden zu überarbeiten.

Weiterführend

• KI-Glossar: Fachbegriffe rund um KI verständlich erklärt
• Claude Code Cheat Sheet
• Claude Code Hooks: Praxisguide