CLAUDE.md meistern

Die meisten Ratschläge zu CLAUDE.md missverstehen den Zweck der Datei. Du liest, sie soll Claude auf deine Codebasis einarbeiten. Den Tech-Stack auflisten. Die wichtigsten Befehle reinschreiben. Die Ordnerstruktur skizzieren. Manche Guides drängen die Datei dabei auf unter 60 Zeilen.

Das ist die falsche Perspektive.

Stell dir CLAUDE.md als Steuerdatei vor, die das Verhalten von Claude regelt. Sie legt fest, wie das Modell läuft, wie eine Konversation verwaltet wird, und wie Arbeit zwischen dem zentralen Agenten und seinen Helfern aufgeteilt wird. Die Fakten zu deinem Stack gehören woanders hin. Skills sind der richtige Ort. Sie laden bei Bedarf, bringen genau das mit, was gebraucht wird, und treten zurück, wenn der Job erledigt ist.

Zwei Paradigmen: Onboarding vs. Orchestrierung

Der schlechtere Ansatz: Projekt-Onboarding

Die übliche Lesart ist, dass CLAUDE.md Claude auf deine Codebasis einarbeiten soll. Du beantwortest drei Fragen für das Modell: WAS der Tech-Stack ist, WARUM das Projekt existiert, und WIE man es startet. Ein paar Guides drücken die ganze Datei auf unter 60 Zeilen.

Dabei gehen mehrere Dinge schief:

Prioritätssättigung: Alles in CLAUDE.md hat hohe Priorität im Kontextfenster. Das Modell behandelt die ganze Datei als autoritativ. Stopfst du jede Regel rein, kämpft jede Zeile mit jeder anderen um diesen Top-Platz. Deine React-Notizen kollidieren mit deinen API-Konventionen, während du gerade an einer Datenbank-Migration arbeitest. Wenn alles hohe Priorität hat, hat nichts hohe Priorität.

Kontext-Verschwendung: Eine CLAUDE.md voller React-Patterns für deine React-App lädt trotzdem bei jeder einzelnen Session. Auch bei denen, bei denen die Arbeit ein Deployment-Skript oder eine Schema-Änderung ist.

Keine Verhaltenssteuerung: Den Tech-Stack aufzulisten sagt nichts darüber aus, wie Claude ein Problem angehen soll. Nichts über das Übergeben von Arbeit. Nichts über das Tempo bei einem mehrstufigen Job.

Wiederholung über Projekte hinweg: Jedes neue Repo bekommt eine neue CLAUDE.md, und jede neue CLAUDE.md weicht von der letzten ab. Das KI-Verhalten unterscheidet sich von Projekt zu Projekt.

Statisches Wissen: Projektdokumentation veraltet. Ein API-Pattern, das du vor einem halben Jahr geschrieben hast, hat vielleicht nichts mehr mit dem heutigen Code zu tun.

Onboarding behandelt Claude wie einen Auftragnehmer, der morgens kurz eingewiesen wird. Orchestrierung behandelt Claude wie ein laufendes System, das seine Parameter gesetzt braucht.

Der bessere Ansatz: Orchestrierungsschicht

CLAUDE.md sollte Folgendes definieren:

1. Operative Workflows - Die Abfolge, die Claude bei jeder Anfrage durchläuft
2. Kontext-Management-Strategie - Wie man Kontext effektiv spart und einsetzt
3. Delegationsmuster - Wann Sub-Agenten einsetzen vs. direkt handeln
4. Qualitätsstandards - Programmierpraktiken, Fehlerbehandlung, Sicherheitsanforderungen
5. Koordinationsprotokolle - Wie parallele vs. sequenzielle Arbeit gesteuert wird

Dein Stack, deine Muster, deine Konventionen leben in Skills, die dynamisch geladen werden, wenn sie relevant sind. Diese Aufteilung bringt dir:

• Konsistentes KI-Verhalten über alle Projekte hinweg
• Effizienter Kontextverbrauch - Domain-Wissen lädt nur, wenn es gebraucht wird
• Portables Know-how - Skills lassen sich zwischen Projekten übertragen
• Wartbares Wissen - einen Skill einmal updaten, überall davon profitieren

Deine CLAUDE.md strukturieren

Abschnitt für Kernprinzipien

Fang mit den grundlegenden Verhaltensweisen an, die du von deiner KI erwartest. Die sollen universell gelten, egal an welchem Projekt oder Task du gerade arbeitest.

## Core Principles
 
### Skills-First Workflow
 
**EVERY user request follows this sequence:**
 
Request → Load Skills → Gather Context → Execute
 
Skills contain critical workflows and protocols not in base context.
Loading them first prevents missing key instructions.
 
### Context Management Strategy
 
**Central AI should conserve context to extend pre-compaction capacity**:
 
- Delegate file explorations and low-lift tasks to sub-agents
- Reserve context for coordination, user communication, and strategic decisions
- For straightforward tasks with clear scope: skip heavy orchestration, execute directly
 
**Sub-agents should maximize context collection**:
 
- Sub-agent context windows are temporary
- After execution, unused capacity = wasted opportunity
- Instruct sub-agents to read all relevant files, load skills, and gather examples

Das sind die Verhaltensweisen, die bei jeder Interaktion greifen. Keine Projektdetails, die heute vielleicht relevant sind oder nicht.

Routing- und Delegationslogik

Definiere, wann Claude direkt handeln soll und wann an Spezialisten delegiert wird:

### Routing Decision
 
**Direct Execution**:
 
- Simple/bounded task with clear scope
- Single-component changes
- Quick fixes and trivial modifications
 
**Sub-Agent Delegation**:
 
- Complex/multi-phase implementations
- Tasks requiring specialized domain expertise
- Work that benefits from isolated context
 
**Lead Orchestrator**:
 
- Ambiguous requirements needing research
- Architectural decisions with wide impact
- Multi-day features requiring session management

Mit niedergeschriebenem Routing trifft Claude echte Entscheidungen, wer was macht. Kein ewiges Alleinarbeiten mehr. Kein sinnloses Delegieren des halben Projekte.

Operative Protokolle

Definiere, wie Claude Arbeit koordiniert, besonders wenn Parallelisierung möglich ist:

## Operational Protocols
 
### Agent Coordination
 
**Parallel** (REQUIRED when applicable):
 
- Multiple Task tool invocations in single message
- Independent tasks execute simultaneously
- Bash commands run in parallel
 
**Sequential** (ENFORCE for dependencies):
 
- Database → API → Frontend
- Research → Planning → Implementation
- Implementation → Testing → Security
 
### Quality Self-Checks
 
Before finalizing code, verify:
 
- All inputs have validation
- Authentication/authorization checks exist
- All external calls have error handling
- Import paths verified against existing codebase examples

Coding-Standards und Praktiken

Füge universelle Programmierprinzipien ein, die alle Arbeiten regeln sollen:

## Coding Best Practices
 
**Priority Order** (when trade-offs arise):
Correctness > Maintainability > Performance > Brevity
 
### Task Complexity Assessment
 
Before starting, classify:
 
- **Trivial** (single file, obvious fix) → execute directly
- **Moderate** (2-5 files, clear scope) → brief planning then execute
- **Complex** (architectural impact, ambiguous requirements) → full research first
 
Match effort to complexity. Don't over-engineer trivial tasks or under-plan complex ones.
 
### Integration Safety
 
Before modifying any feature:
 
- Identify all downstream consumers using codebase search
- Validate changes against all consumers
- Test integration points to prevent breakage

Das Rules-Verzeichnis: Modulare Anweisungen

Ab Claude Code v2.0.64 gibt es eine weitere Option zur Organisation von Anweisungen: das .claude/rules/-Verzeichnis. Rules lösen das Sättigungsproblem, indem du Top-Prioritäts-Anweisungen über Dateien mit engem Geltungsbereich verteilen kannst.

Kernaussage von Anthropic: Eine Rules-Datei hat dieselbe hohe Priorität wie eine CLAUDE.md-Datei. Was sich ändert, ist, dass du diese Priorität mit einem Pfadmuster gezielt einsetzen kannst. Die Regel aktiviert sich nur, wenn passende Dateien im Scope sind.

Wann Rules besser sind als CLAUDE.md

Rules zahlen sich aus, sobald deine Anweisungen Domain-Grenzen haben:

.claude/rules/
├── api-guidelines.md     # Only relevant for API work
├── react-patterns.md     # Only relevant for frontend
├── testing-rules.md      # Only relevant for test files
└── security-rules.md     # Only relevant for auth/payment code

Jede Datei lebt im Projekt-Speicher. Der Unterschied: Du kannst eine Regel an ein Dateimuster pinnen:

---
paths: src/api/**/*.ts
---
 
# API Development Rules
 
- All endpoints must validate input with Zod
- Return consistent error shapes

Diese Regel greift nur, wenn Claude eine API-Datei anfasst. Im Frontend bleiben deine API-Konventionen still.

Die Anweisungs-Prioritätshierarchie

Stell sie dir als Schichten vor. Jede Schicht kombiniert ein Prioritätsniveau mit einer Laderegel:

CLAUDE.md enthält das universelle Verhalten, das du konstant mit hoher Priorität willst. Rules enthalten das Domain-spezifische Zeug, das diese Priorität nur bekommt, wenn die richtigen Dateien offen sind. Skills enthalten portables Know-how mit mittlerer Priorität, geladen bei Bedarf.

Du willst die Tiefenversion mit Pfad-Targeting und Migrations-Taktiken? Lies den Rules-Directory-Guide.

CLAUDE.md aus zusätzlichen Verzeichnissen laden

Seit Claude Code v2.1.20 kann Claude CLAUDE.md-Dateien aus Verzeichnissen außerhalb deines aktiven Projekts einlesen. Nützlich für Monorepos, gemeinsame Team-Konventionen und Multi-Projekt-Setups.

So funktioniert es:

# Enable the feature and specify additional directories
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-standards
 
# Multiple directories work too
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config ../team-rules

Mit aktiviertem Flag lädt Claude diese Dateien aus jedem zusätzlichen Verzeichnis:

• CLAUDE.md-Dateien
• .claude/CLAUDE.md-Dateien
• .claude/rules/*.md-Dateien

Warum das besser ist als Claude verbal auf eine Datei hinzuweisen:

Durch --add-dir werden externe CLAUDE.md-Dateien zu echtem System-Speicher statt zu Konversations-Füller. Sie laden selbstständig, überleben Session-Neustarts, und sitzen in der Prioritätshierarchie.

Praktische Anwendungsfälle:

Monorepo mit gemeinsamen Standards:

company/
├── shared-standards/
│   └── CLAUDE.md          # Company coding guidelines
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Web-specific rules
│   └── api/
│       └── CLAUDE.md      # API-specific rules

Aus dem web/-Verzeichnis:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../../shared-standards

Projektübergreifende Konsistenz: Leg deine persönlichen Entwicklungsstandards in einen zentralen Ordner und zieh sie in jedes Projekt. Keine kopierten Dateien.

Team-Onboarding: Neue Teammitglieder zeigen auf ein geteiltes Verzeichnis mit Team-Konventionen. Das löst das Problem "jedes Projekt hat eine leicht andere CLAUDE.md".

Aktualisierte Prioritätshierarchie:

Hinweis: Das Feature greift nur, wenn CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 gesetzt ist. Der --add-dir-Flag allein gewährt nur Dateizugriff auf diese Verzeichnisse. Er lädt die CLAUDE.md-Dateien darin nicht.

@import-Syntax: Eine einfachere Alternative

--add-dir gibt dir ein ganzes externes Verzeichnis. Für das Einlesen einzelner Dateien gibt es eine leichtere Option. CLAUDE.md-Dateien unterstützen die @path/to/import-Syntax für zusammensetzbaren Speicher:

See @README for project overview and @package.json for available npm commands.
 
# Standards
 
- coding guidelines @docs/coding-standards.md
- git workflow @docs/git-instructions.md

Relative und absolute Pfade funktionieren beide. Ein relativer Pfad wird von der importierenden Datei aus aufgelöst, nicht von deinem Arbeitsverzeichnis.

Der Unterschied zu --add-dir:

Erste Genehmigung: Das erste Mal, wenn Claude Code auf Imports in einem Projekt trifft, erscheint ein Genehmigungsdialog mit einer Liste jeder Datei. Einmalig pro Projekt. Lehnst du ab, kommt der Dialog nie wieder. Diese Imports bleiben deaktiviert.

Rekursive Imports: Eine importierte Datei kann weitere Dateien importieren, mit einer maximalen Tiefe von 5 Stufen. So baust du geschichtete Anweisungssets:

# CLAUDE.md imports standards.md
 
@.claude/standards.md
 
# standards.md imports sub-files
 
@.claude/standards/api.md
@.claude/standards/testing.md

Imports werden innerhalb von Markdown-Code-Spans und abgezäunten Code-Blöcken übersprungen. Ein Code-Beispiel, das @path erwähnt, löst keinen versehentlichen Load aus.

CLAUDE.local.md: Persönliche Projekteinstellungen

Für Einstellungen, die nicht im geteilten Team-Tree landen sollen, nutze CLAUDE.local.md. Die Datei wird automatisch zu .gitignore hinzugefügt und lädt direkt neben CLAUDE.md mit derselben Priorität.

Gute Kandidaten:

• Deine lokalen Dev-Server-URLs und Sandbox-Endpoints
• Persönliche Testdaten-Präferenzen
• Branch-Naming-Konventionen, die du bevorzugst
• Editor- und Tool-Konfigurationen, die zu deinem Setup gehören

Git-Worktree-Tipp: CLAUDE.local.md lebt nur in einem einzigen Worktree. Zieh einen Import aus deinem Home-Verzeichnis rein, und dieselben persönlichen Anweisungen gelten in jedem Worktree, den du startest:

# CLAUDE.local.md
 
@~/.claude/my-project-instructions.md

Geladenen Speicher mit /memory anzeigen

Führe /memory aus, um die Dateien aufzulisten, die gerade in Claudes Kontext sind, oder um eine geladene Speicherdatei im Editor zu öffnen. Das ist nützlich, wenn eine Anweisung im Modellverhalten zu fehlen scheint. Und nochmal, wenn du beweisen willst, dass eine Import-Kette und deine Rules korrekt ankommen.

Skills: Wo Domain-Wissen lebt

Skills sind die andere Hälfte des Bildes. CLAUDE.md definiert wie Claude arbeitet. Skills liefern was Claude über eine bestimmte Domain weiß.

Die Skills-Architektur

Anthropic beschreibt den Unterschied direkt: "Projects say 'here's what you need to know.' Skills say 'here's how to do things.'"

Skills nutzen progressive Offenlegung:

1. Metadaten laden zuerst (~100 Tokens) - genug, um zu wissen, wann der Skill relevant ist
2. Vollständige Anweisungen laden bei Bedarf (<5k Tokens)
3. Gebündelte Dateien/Skripte laden nur wenn nötig

Wegen dieses Designs kannst du Dutzende von Skills vorhalten, ohne das Kontextfenster zu sprengen. Claude greift genau nach dem Stück, das es braucht, zum Zeitpunkt, an dem es es braucht.

Was in Skills gehört

Technologie-Muster:

• Framework-Konventionen (React-Patterns, API-Design)
• Datenbankoperationen und Migrationen
• Testing-Strategien und Utilities

Domain-Workflows:

• Zahlungsabwicklungs-Integrationen
• Authentifizierungs-Implementierungen
• Deployment-Prozeduren

Projektspezifischer Kontext:

• Codebasis-Navigationsguides
• Architekturdokumentation
• Team-Konventionen

Beispiel: Zuständigkeiten trennen

Statt das hier in CLAUDE.md zu schreiben:

## About This Project
 
FastAPI REST API for user authentication.
Uses SQLAlchemy for database operations.
 
## Commands
 
uvicorn app.main:app --reload
pytest tests/ -v

Erstell einen backend-api-Skill:

# Backend API Development Skill
 
## Framework
 
FastAPI with SQLAlchemy ORM, Pydantic validation.
 
## Development Commands
 
- `uvicorn app.main:app --reload` - Start dev server
- `pytest tests/ -v` - Run test suite
- `alembic upgrade head` - Apply migrations
 
## Patterns
 
[Detailed patterns, examples, conventions...]

Deine CLAUDE.md verweist auf das Skill-System:

### Key Skills
 
`backend-api`, `frontend-react`, `database-ops`, `deployment`
 
Load relevant skills before beginning domain-specific work.

Jetzt tauchen die Backend-Details nur bei Backend-Arbeit auf. Der Kontext bleibt frei für den Rest des Jobs.

Die Zeilenzahl-Debatte

Eine verbreitete Meinung sagt, CLAUDE.md sollte unter 60 Zeilen bleiben, weil Claude angeblich alles Längere "ignoriert". Diese Einschätzung, wie Claude mit Kontext umgeht, ist falsch.

Die Realität: Anthropic empfiehlt, Skill-Dateien unter 500 Zeilen zu halten. Wenn ein Skill, der nur bei Bedarf lädt, 500 Zeilen gut nutzen kann, kann eine immer geladene CLAUDE.md sicher 200 bis 400 Zeilen operative Details aufnehmen.

Kürze ist nicht das, was optimiert werden soll. Relevanz ist es. Sechzig Zeilen Projekt-Trivia, die für den heutigen Task nicht zutreffen, fressen mehr effektiven Kontext als 300 Zeilen universelle operative Regeln.

Der Sweet Spot ist 200-400 Zeilen mit:

• Operativen Workflows (immer relevant)
• Routing-Logik (immer relevant)
• Qualitätsstandards (immer relevant)
• Koordinationsprotokollen (immer relevant)

Sechzig Zeilen Projektspezifika, von denen die Hälfte bei jeder Anfrage tote Last ist, ist das Schlechteste aus beiden Welten.

Framework-Evolution

Bake Anweisungen zur Selbstverbesserung in die Datei ein:

### Framework Improvement
 
**Recognize patterns that warrant updates:**
 
**Update existing skill when**:
 
- A workaround was needed for something the skill should have covered
- New library version changes established patterns
- A better approach was discovered during implementation
 
**Create new skill when**:
 
- Same domain-specific context needed across 2+ sessions
- A payment processor, API, or tool integration was figured out
- Reusable patterns emerged that will apply to future projects
 
**Action**: Prompt user with: "This [pattern/workaround/integration] seems
reusable. Should I update [skill] or create a new skill to capture this?"

Das Ergebnis ist ein sich selbst verbesserndes System. Claude markiert die Momente, die es wert sind, in einen neuen Skill oder ein Upgrade eines bestehenden umgewandelt zu werden.

Warum dieser Ansatz funktioniert

Multi-Agenten-Orchestrierung

Moderne Claude Code-Arbeit setzt immer mehr auf Sub-Agenten: spezialisierte Instanzen, die diskrete Jobs erledigen. Deine CLAUDE.md ist das, was dem zentralen Modell sagt, wie es dieses Team führen soll.

Laut Anthropic wurde Opus 4.5 speziell darauf trainiert, ein Team von Sub-Agenten zu leiten. Nutz dieses Training in deiner CLAUDE.md, indem du festlegst:

• Wann delegieren vs. direkt handeln
• Wie Sub-Agenten-Prompts konstruiert werden
• Wie Sub-Agenten-Ergebnisse zurück in die Hauptkonversation fließen

Kontext-Ökonomie

Dein Kontextfenster hat eine Obergrenze. Jedes Byte Projektdokumentation, das du in CLAUDE.md reinpackst, ist ein Byte, das nicht für die eigentliche Arbeit ausgegeben werden kann. Orchestrierung ist, wie du dieses Budget sinnvoll einsetzt:

• CLAUDE.md: Operative Anweisungen (immer gebraucht)
• Skills: Domain-Wissen (bei Bedarf geladen)
• Sub-Agenten: Frischer Kontext für spezialisierte Arbeit

Konsistenz über Projekte hinweg

Wenn die Datei Verhalten statt Projekt-Trivia kodiert, verhält sich die KI bei jedem Job gleich. Routing, Qualitätsstandards und Koordinationsgewohnheiten übertragen sich. Eine React-App bekommt dieselbe Behandlung wie ein Python-CLI-Tool.

Kurzreferenz

Request → Load Skills → Route Decision → Execute

Routing:

• Einfacher/begrenzter Task → Direkte Ausführung
• Komplex/mehrphasig → Sub-Agenten-Delegation oder Session-Management

CLAUDE.md enthält:

• Operative Workflows
• Kontext-Management-Strategie
• Routing- und Delegationslogik
• Qualitätsstandards
• Koordinationsprotokolle

Skills enthalten:

• Tech-Stack-Spezifika
• Framework-Muster
• Projektkonventionen
• Domain-Workflows

Nächste Schritte

1. Prüfe deine aktuelle CLAUDE.md: Ist es Projektdokumentation oder operative Anweisungen?

2. Extrahiere Domain-Wissen in Skills: Verschiebe Tech-Stack, Muster und Konventionen raus aus CLAUDE.md

3. Definiere deine operativen Workflows: Wie soll Claude jede Anfrage angehen?

4. Lege Routing-Logik fest: Wann soll Claude delegieren vs. direkt handeln?

5. Setze Qualitätsstandards: Welche Praktiken sollen alle Arbeiten regeln?

Merke: CLAUDE.md ist kein Dokument, das Claude liest. Es ist das System, auf dem Claude läuft. Definiere das Verhalten, lagere das Wissen in Skills aus, und lass das Ganze sich mit der Zeit selbst verbessern.

Du willst das vollständige Playbook zu diesen Prinzipien? Lies unsere 5 Claude Code-Best-Practices, die Top-Entwickler auszeichnen.