Ich nutze Claude Code täglich seit Anfang 2025 und kann dir sagen, dass der wichtigste Faktor für nützliche Ergebnisse nicht Prompt Engineering oder clevere Tricks sind. Es ist Kontext. Genauer gesagt ist es eine gut geschriebene CLAUDE.md-Datei im Stammverzeichnis deines Projekts. Diese eine Datei ist der Unterschied zwischen einem KI-Assistenten, der mit deiner Codebasis kämpft, und einem, der sich wie ein Senior Dev anfühlt, der seit Monaten in deinem Team ist.

Wenn du bereits Prompts an Claude Code geworfen hast und generische, falsche oder frustrierende Ergebnisse bekommen hast, ist dieser Leitfaden für dich. Ich werde dir genau zeigen, wie du deine CLAUDE.md strukturierst, was du einbeziehst, was du weglässt, und ich teile echte Beispiele aus Production-Projekten, die wir bei Social Animal ausgeliefert haben.

Inhaltsverzeichnis

Was ist CLAUDE.md und warum ist es wichtig

CLAUDE.md ist eine Markdown-Datei, die du im Stammverzeichnis deines Repositories platzierst und die Claude Code automatisch bei jeder Sitzung liest. Stell dir vor, es wäre Onboarding-Dokumentation für deinen KI-Pair-Programmer. Wenn ein neuer Entwickler zu deinem Team stößt, gibst du ihm nicht einfach einen Laptop und sagst "figure it out". Du führst ihn durch die Architektur, erklärst die seltsamen Teile, zeigst ihm die Fallstricke. CLAUDE.md macht dasselbe für Claude.

Ohne sie muss Claude Code alles aus deiner Dateistruktur, package.json und den zufälligen Dateien, die es liest, ableiten. Das ist, als würde man einen neuen Mitarbeiter bitten, dein ganzes System zu verstehen, indem er zufällige Quelldateien liest. Er wird einige Dinge richtig machen, aber er wird auch Annahmen treffen, die alle Zeit verschwenden.

Mit einer soliden CLAUDE.md habe ich gesehen, dass die Aufgabenabschlussgenauigkeit von ungefähr 60% auf über 90% beim ersten Versuch sprang. Das ist keine kleine Verbesserung — es ist der Unterschied zwischen KI-unterstützter Entwicklung, die ein Produktivitätsverstärker ist, und einer frustrierenden Zeitverschwendung.

Wie Claude Code deinen Projektkontext liest

Claude Code hat eine spezifische Hierarchie zum Laden von Kontext. Es ist wichtig zu verstehen, wie das funktioniert, denn es beeinflusst, wie du dein Projekt-Memory organisierst.

Die Kontext-Ladreihenfolge

  1. ~/.claude/CLAUDE.md — Deine globalen Einstellungen (gelten für alle Projekte)
  2. ./CLAUDE.md — Die Projekt-Datei im Stammverzeichnis deines Repositorys
  3. ./subdirectory/CLAUDE.md — Spezifische Überschreibungen für Verzeichnisse
  4. .claude/settings.json — Projekt-spezifische Toolberechtigungen und Einstellungen
  5. Session-Kontext — Was du Claude in der aktuellen Unterhaltung erzählst

Die Projekt-CLAUDE.md ist, wo du die meiste Zeit verbringst. Die globale Datei ist gut für persönliche Vorlieben ("Ich bevorzuge funktionale Komponenten" oder "immer TypeScript strict mode verwenden"), aber der echte Wert liegt im projektweiten Kontext.

Hier ist das Wichtige: Claude Code liest die CLAUDE.md zu Beginn jeder Sitzung, aber es hat auch begrenzte Kontextfensterplatz. Wenn deine CLAUDE.md 5.000 Wörter durcheinander Dokumentation ist, verschleißt du Token, die für echte Code-Überlegungen verwendet werden könnten. Sei prägnant. Sei spezifisch. Jede Zeile sollte ihren Platz rechtfertigen.

Die Anatomie einer großartigen CLAUDE.md-Datei

Nach dem Schreiben und Verfeinern von CLAUDE.md-Dateien über dutzende Projekte — Next.js-Apps, Astro-Sites, Headless-CMS-Integrationen, API-Services — bin ich auf eine konsistente Struktur gestoßen, die funktioniert.

Die ideale Struktur

# Projektname

## Übersicht
Ein Absatz, der erklärt, was dieses Projekt tut und für wen es ist.

## Tech Stack
Genaue Versionen und Frameworks.

## Architektur
Wie die Teile zusammenpassen.

## Wichtige Konventionen
Coding-Standards, Benennungsmuster, Dateiorganisationsregeln.

## Häufige Befehle
Build-, Test-, Deploy- und Dev-Befehle.

## Wichtiger Kontext
Dinge, die nicht offensichtlich aus dem Code hervorgehen.

## Bekannte Probleme / Fallstricke
Fallstricke, die zu vermeiden sind.

## NICHT TUN
Dinge, die die KI niemals tun sollte.

Lasst uns in jeden Abschnitt tiefer eintauchen.

Abschnitt-für-Abschnitt-Aufschlüsselung

Übersicht

Halte dies auf maximal 2-3 Sätze. Claude braucht deine Produkt-Roadmap nicht — er muss die Domain verstehen, um kontextuell angemessene Entscheidungen zu treffen.

## Übersicht
Dies ist die Marketing-Website für Acme Corp, eine B2B-SaaS-Plattform für Supply-Chain-Management. Die Website wird statisch mit dynamischen API-Routes für Formularverarbeitung und Lead-Erfassung generiert. Der Inhalt wird von der Marketing-Abteilung über Sanity CMS verwaltet.

Tech Stack

Sei genau. Sag nicht einfach "React" — gib die Version, das Framework, die Rendering-Strategie an. Das verhindert, dass Claude Muster vorschlägt, die in React 18 funktionieren, aber in React 19 brechen, oder Pages Router empfiehlt, wenn du App Router verwendest.

## Tech Stack
- **Framework**: Next.js 15.1 (App Router, RSC standardmäßig)
- **Sprache**: TypeScript 5.7 (strict mode)
- **Styling**: Tailwind CSS v4 mit CSS-First-Konfiguration
- **CMS**: Sanity v3 mit Live Preview
- **Deployment**: Vercel (Produktion + Preview-Umgebungen)
- **Package Manager**: pnpm 9.x
- **Node**: v22 LTS
- **Testing**: Vitest + Playwright
- **State Management**: Zustand (minimal, nur für clientseitiger UI-State)

Architektur

Das ist, wo die meisten Leute entweder viel zu wenig oder viel zu viel schreiben. Du schreibst kein System-Design-Dokument. Du gibst Claude ein mentales Modell.

## Architektur
- `app/` — Next.js App Router Seiten und Layouts
- `app/api/` — API-Routes (Formularübermittlungen, Webhooks)
- `components/` — Gemeinsame UI-Komponenten (atomares Design: atoms/, molecules/, organisms/)
- `lib/` — Utility-Funktionen, API-Clients, Typdefinitionen
- `lib/sanity/` — Sanity-Client, Queries (GROQ) und Typ-Generierung
- `content/` — MDX-Dateien für Blog-Beiträge (Co-located mit Frontmatter)
- `public/` — Statische Assets (bevorzugen next/image für alle Bilder)

Datenfluss: Sanity CMS → GROQ Queries in lib/sanity/queries.ts → Server Components → Client Components (nur wenn Interaktivität erforderlich ist)

Alle Seiten werden zur Build-Zeit statisch generiert außer /blog/[slug]/preview, die Draft Mode verwendet.

Wichtige Konventionen

Dieser Abschnitt spart die meiste Zeit. Ohne ihn folgt Claude allgemeinen Best Practices, die mit deinen Team-Entscheidungen in Konflikt stehen können.

## Wichtige Konventionen
- Komponenten sind PascalCase, eine Komponente pro Datei
- Benannte Exporte verwenden, nie Standardexporte (außer pages/layouts)
- Alles Datenabrufen geschieht in Server Components — verwende niemals useEffect zum Datenabrufen
- API-Antworttypen leben in lib/types/ und werden automatisch aus dem Sanity-Schema generiert
- Verwende `cn()`-Utility (lib/utils.ts) für bedingte Klassenzusammenführung, nicht Template Literals
- Error Boundaries umhüllen jede Hauptseiten-Sektion, nicht die ganze Seite
- Alle Formularverarbeitung verwendet react-hook-form + zod Validierungsschemas
- Commit-Nachrichten folgen Conventional Commits (feat:, fix:, chore:)

Häufige Befehle

Das scheint grundlegend zu sein, aber Claude Code führt diese Befehle tatsächlich aus. Wenn es nicht die richtigen kennt, wird es raten, und es wird oft falsch raten.

## Häufige Befehle
- `pnpm dev` — Entwicklungsserver starten (Port 3000)
- `pnpm build` — Produktions-Build
- `pnpm lint` — ESLint + Prettier Check
- `pnpm test` — Vitest Unit-Tests ausführen
- `pnpm test:e2e` — Playwright E2E-Tests ausführen
- `pnpm sanity:typegen` — Sanity-Typen nach Schema-Änderungen neu generieren
- `pnpm db:migrate` — Drizzle ORM-Migrationen ausführen

Wichtiger Kontext

Das ist für die Sachen, die Claude nicht durch Lesen deines Codes verstehen kann. Geschäftslogik, externe Einschränkungen, Dinge, die 30 Minuten Erklärung eines menschlichen Reviewers erfordern würden.

## Wichtiger Kontext
- Wir verwenden ISR (revalidate: 3600) für alle CMS-Seiten. Verwende niemals `force-dynamic` außer wenn absolut notwendig.
- Der Sanity-Webhook bei /api/revalidate verarbeitet On-Demand-Revalidierung — füge keine manuelle Revalidierungslogik hinzu.
- Bild-Optimierung erfolgt über Sanity's CDN (cdn.sanity.io), nicht next/image für CMS-Inhalte.
- Auth wird von Clerk verarbeitet — baue niemals benutzerdefinierte Auth-Flows.
- Der /api/leads-Endpoint hat Rate Limiting via Upstash Redis. Entferne das Rate-Limit-Middleware nicht.

Bekannte Fallstricke

Jedes Projekt hat komisches Zeug. Füge es hier ein, damit Claude nicht darüber stolpert.

## Bekannte Fallstricke
- Sanity's Portable-Text-Renderer hat einen Bug mit verschachtelten Listen in v3.2. Wir verwenden einen Custom Serializer in components/portable-text/list-fix.tsx
- Tailwind v4 unterstützt die `@apply`-Direktive nicht in Modul-CSS-Dateien — verwende stattdessen Inline-Klassen
- Die vercel.json Rewrites für /docs/* sind Proxy zu unserer Mintlify-Dokumentation. Ändere diese nicht ohne Absprache mit dem Team.
- Umgebungsvariablen mit Präfix NEXT_PUBLIC_ sind die einzigen, die auf der Client-Seite verfügbar sind. Belege API-Geheimnisse niemals auf diese Weise.

Der "NICHT TUN"-Abschnitt

Dieser ist wohl der wichtigste Abschnitt. Negative Anweisungen sind unglaublich effektiv bei KI-Modellen.

## NICHT TUN
- Installiere neue Dependencies nicht ohne zu fragen
- Verwende keinen `any` Type — finde oder erstelle korrekte Typen
- Erstelle neue API-Routes für Dinge, die in Server Components erledigt werden können
- Ändere die Sanity-Schema-Dateien nicht ohne Bestätigung des Migrationsplans
- Verwende `"use client"` nur wenn die Komponente wirklich Browser-APIs oder Event Handler braucht
- Schreibe keine CSS-Dateien — alles ist Tailwind Utility-Klassen
- Hardcode keine Strings, die vom CMS kommen sollten

Echte CLAUDE.md-Beispiele

Beispiel: Next.js Marketing-Website

Dies ist eine vereinfachte Version einer CLAUDE.md, die wir auf Client-Projekten verwenden, besonders beim Bauen von Next.js-Sites mit Headless-CMS-Backends.

# Acme Marketing-Website

## Übersicht
Marketing-Website für Acme (acme.com). Gebaut mit Next.js 15, gestylt mit Tailwind v4, Inhalt von Sanity CMS. Ziel: sub-2s LCP auf allen Seiten.

## Tech Stack
Next.js 15.1 | TypeScript 5.7 strict | Tailwind v4 | Sanity v3 | Vercel | pnpm

## Architektur
App Router mit RSC. Alles Datenabrufen in Server Components via GROQ Queries in lib/sanity/queries.ts. Client Components nur für interaktive Elemente (Modals, Formulare, Karusselle).

Seiten: / (Home), /about, /pricing, /blog, /blog/[slug], /contact

## Konventionen
- Nur benannte Exports (außer page.tsx/layout.tsx)
- Komponenten: PascalCase, eine pro Datei
- cn() für Klassenzusammenführung
- Zod Schemas für alle Formularvalidierung
- Kein useEffect zum Datenabrufen. Je.

## Befehle
pnpm dev | pnpm build | pnpm lint | pnpm test

## NICHT TUN
- Füge "use client" ohne Begründung hinzu
- Installiere Packages nicht ohne zu fragen
- Verwende keine Standardexporte für Komponenten
- Ändere sanity/schema/ Dateien nicht ohne Migrationsbestätigung
- Verwende keinen any Type

Beispiel: Astro Content-Website

Bei Astro-Projekten sieht die CLAUDE.md etwas anders aus, weil das Architektur-Paradigma unterschiedlich ist.

# Tech Blog — Astro

## Übersicht
Developer-Blog mit 500+ Artikeln. Statisch-First, standardmäßig null JS. MDX für Inhalte mit Custom Components.

## Tech Stack
Astro 5.x | MDX | Tailwind v4 | Bereitgestellt auf Cloudflare Pages | Content Collections v2

## Architektur
src/content/ — MDX Artikel mit Zod-validiertem Frontmatter
src/components/ — Astro Components (null JS) und React Islands (interaktiv)
src/layouts/ — Basis-Layouts
src/pages/ — Datei-basiertes Routing

## Wichtigste Regeln
- Standardmäßig auf Astro Components (.astro) setzen. Verwende React nur für Islands, die Interaktivität benötigen.
- client:visible für unterhalb des Falz interaktive Komponenten
- client:idle für nicht-kritische interaktive Komponenten
- Verwende client:load nicht, es sei denn absolut notwendig
- Alle Bilder verwenden Astro's Image Component mit korrekter width/height
- RSS-Feed wird automatisch aus Content Collection generiert — baue keine manuelle Feed-Logik

## NICHT TUN
- Füge React Components hinzu, wenn eine Astro Component funktionieren würde
- Verwende client:load Direktive
- Überspringe Bildabmessungen (verursacht CLS)
- Ändere nicht das Content Collection Schema ohne bestehende Frontmatter zu aktualisieren

Häufige Fehler, die deinen KI-Kontext ruinieren

Ich habe inzwischen viele CLAUDE.md-Dateien überprüft. Hier sind die Muster, die konsistent zu schlechten Ergebnissen führen.

Fehler Warum es wehtut Lösung
Zu lang (2000+ Wörter) Verbrennt Kontext-Fenster Tokens, wichtige Info geht verloren Halte unter 800 Wörter. Link zu externen Docs für tiefere Dives.
Zu vage ("wir verwenden React") Claude füllt Lücken mit Annahmen Sei spezifisch: Versionen, Muster, genaue Tools
Keine negativen Anweisungen Claude macht "angemessene" Dinge, die deine Konventionen brechen Füge immer einen "NICHT TUN"-Abschnitt hinzu
Copy-Paste von README.md READMEs sind für Menschen, nicht für KI-Kontext Schreibe CLAUDE.md von Grund auf mit KI-spezifischer Framing
Sensible Daten einbeziehen API Keys, Secrets in Kontextdateien Füge niemals Secrets in CLAUDE.md ein. Referenziere .env.example stattdessen
Nie aktualisieren Projekt entwickelt sich weiter, Kontextdatei nicht Review CLAUDE.md jeden Sprint oder großen Refactor
Widersprechende Anweisungen "Verwende Server Components" + Beispiele mit useEffect Fetching Eine Person sollte die Datei besitzen, überprüfe auf Konsistenz

CLAUDE.md vs. andere KI-Kontextdateien

Claude Code ist nicht das einzige KI-Tool, das Projekt-Kontextdateien liest. Hier ist der Stand der Landschaft in 2025:

Datei Tool Auto-Lesen Bereich
CLAUDE.md Claude Code Ja, beim Session-Start Projekt-weit
.cursorrules Cursor Ja, beim Datei-Öffnen Projekt-weit
.github/copilot-instructions.md GitHub Copilot Ja, in Copilot Chat Repo-weit
.windsurfrules Windsurf (Codeium) Ja Projekt-weit
AGENTS.md OpenAI Codex CLI Ja Projekt-weit
.ai/context.md Custom Konvention Nein (manuelle Referenz) Variiert

Die gute Nachricht: Der meiste Inhalt ist übertragbar. Wenn du eine solide CLAUDE.md schreibst, dauert die Umwandlung zu .cursorrules oder copilot-instructions.md etwa 5 Minuten. Die Struktur und Informationen sind gleich — nur der Dateiname und minimale Formatierung unterscheiden sich.

Wenn dein Team mehrere KI-Tools verwendet (und viele tun das in 2025), solltest du eine einzige Informationsquelle pflegen und die Tool-spezifischen Dateien aus ihr generieren. Ein einfaches Build-Script kann deine Master-Kontextdatei an alle richtigen Orte kopieren.

Erweiterte Muster für große Projekte

Verschachtelte CLAUDE.md-Dateien

Für Monorepos oder große Codebases kannst du CLAUDE.md-Dateien in Unterverzeichnissen platzieren. Claude Code wird die spezifischste für das Verzeichnis, in dem du arbeitest, lesen.

project/
├── CLAUDE.md              # Globaler Projekt-Kontext
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Web App spezifischer Kontext
│   └── api/
│       └── CLAUDE.md      # API spezifischer Kontext
├── packages/
│   └── ui/
│       └── CLAUDE.md      # Design-System-Kontext

Die Wurzel CLAUDE.md deckt gemeinsame Architektur und Konventionen ab. Jede verschachtelte Datei fügt Spezifiken für dieses Package hinzu.

Dynamischer Kontext mit /compact

Claude Code's /compact Befehl komprimiert die aktuelle Unterhaltung und gibt Kontext-Platz frei. Für lange Sessions habe ich ein Muster gefunden, das funktioniert:

  1. Beginne mit CLAUDE.md, das automatisch geladen wird
  2. Arbeite an einem Feature
  3. Führe /compact aus, wenn Kontext schwer wird
  4. Fortfahrt — Claude behält CLAUDE.md-Kontext plus komprimierte Zusammenfassung

Team-Gemeinsam vs. Persönlicher Kontext

Wir halten CLAUDE.md in der Versionskontrolle (es sollte committed werden). Aber einzelne Entwickler verwenden auch ~/.claude/CLAUDE.md für persönliche Vorlieben:

# Persönliche Vorlieben
- Ich bevorzuge ausführliche Variablennamen gegenüber Abkürzungen
- Zeige mir das Reasoning vor dem Schreiben von Code
- Wenn du Änderungen vorschlägst, zeige mir den vollständigen File-Diff
- Ich verwende VS Code mit Vim-Keybindings (schlage keine IDE-spezifischen Shortcuts vor)

Diese Trennung hält die Team-Datei sauber und fokussiert auf Projekt-Fakten, während Individuen ihre Erfahrung anpassen können.

Die Auswirkungen messen

Woher weißt du, dass deine CLAUDE.md funktioniert? Hier sind Metriken, die wir intern verfolgen:

  • Genauigkeit beim ersten Versuch: Wie oft benötigt Claudes erste Antwort null Korrektionen? Eine gute CLAUDE.md bekommt dies über 80%.
  • Konventionsverletzungen: Zähle, wie oft Claude deine Coding-Standards bricht. Sollte gegen null tendieren.
  • Kontext-Fragen: Wenn Claude ständig fragt "welches Framework ist das?" oder "sollte ich App Router verwenden?", fehlt deiner CLAUDE.md Information.
  • Häufigkeit rückgängig machen: Wie oft du Claudes Änderungen ablehnen oder rückgängig machen musst. Niedriger ist besser.

Ein Team bei einem mittelgroßen Startup berichtete, dass sie ihre durchschnittliche KI-unterstützte Task-Zeit von 12 Minuten auf 4 Minuten reduzierten, nachdem sie eine Stunde in ihre CLAUDE.md investierten. Das ist eine 3x Verbesserung von einer Datei.

Wenn du ein Projekt mit uns durch unsere Headless-CMS-Entwicklungsservices aufbaust, inkludieren wir eine maßgeschneiderte CLAUDE.md als Teil jeder Projekt-Übergabe. Das ist so wichtig für die laufende Entwicklungsgeschwindigkeit.

Häufig gestellte Fragen

Was ist CLAUDE.md und wo kommt es hin? CLAUDE.md ist eine Markdown-Datei, die im Stammverzeichnis deines Projekt-Repositorys platziert wird. Claude Code liest sie automatisch zu Beginn jeder Sitzung, um die Architektur, Konventionen, den Tech Stack und die Einschränkungen deines Projekts zu verstehen. Stell dir vor, es wäre ein Onboarding-Dokument speziell für deinen KI-Codierassistenten geschrieben.

Wie lang sollte eine CLAUDE.md-Datei sein? Ziele auf 300-800 Wörter ab. Kürzere Dateien vermissen kritischen Kontext, aber alles über 1.000 Wörter beginnt dein Kontextfenster aufzuzehren — Raum, der besser für echte Code-Überlegungen verwendet wird. Sei prägnant und spezifisch. Jeder Satz sollte seinen Platz rechtfertigen. Wenn du mehr Tiefe brauchst, link zu externen Dokumentationen, anstatt es einzubetten.

Sollte ich CLAUDE.md in die Versionskontrolle committen? Absolut. CLAUDE.md sollte wie jede andere Projekt-Dokumentation behandelt werden — versioniert, überprüft und auf dem neuesten Stand gehalten. Dein ganzes Team profitiert vom konsistenten KI-Verhalten. Persönliche Vorlieben gehen stattdessen in ~/.claude/CLAUDE.md, die auf der Maschine jedes Entwicklers lokal bleibt.

Wie unterscheidet sich CLAUDE.md von .cursorrules? Der Inhalt ist fast identisch — beide liefern Projekt-Kontext zu einem KI-Codierungs-Tool. Der Unterschied liegt darin, welches Tool sie liest. CLAUDE.md ist für Claude Code (Anthropic's CLI-Tool), während .cursorrules für Cursor IDE ist. Wenn du beide Tools verwendest, pflege eine einzige Informationsquelle und kopiere sie zu beiden Dateien, wobei du für Tool-spezifisches Formatting anpasst.

Welcher ist der wichtigste Abschnitt einer CLAUDE.md? Der "NICHT TUN"-Abschnitt. Negative Anweisungen sind überproportional effektiv bei KI-Modellen. Claude zu sagen, was zu vermeiden ist — verwende any Typen nicht, füge "use client" nicht unnötig hinzu, installiere neue Packages nicht ohne zu fragen — verhindert die häufigsten und frustrierendsten Fehler. Eine gute Ban-Liste spart mehr Zeit als Seiten positiver Anweisungen.

Kann ich CLAUDE.md für Nicht-Code-Projekte verwenden? Ja. CLAUDE.md funktioniert für jedes Projekt, bei dem du mit Claude Code interagierst. Ich habe effektive Versionen für Dokumentations-Repos, Infrastructure-as-Code-Projekte und sogar Data-Analysis-Pipelines gesehen. Das Prinzip ist gleich: gib Claude den Kontext, den er braucht, um gute Entscheidungen über dein spezifisches Projekt zu treffen.

Wie oft sollte ich meine CLAUDE.md aktualisieren? Überprüfe sie bei jedem großen Refactor und mindestens einmal pro Sprint. Wenn du eine Framework-Version upgradest, eine Key-Dependency änderst oder eine neue Konvention adoptierst, update die Datei sofort. Veralteter Kontext ist schlimmer als kein Kontext, denn er täuscht die KI aktiv. Einige Teams fügen einen CLAUDE.md-Review zu ihrer PR-Checkliste für Infrastruktur-Änderungen hinzu.

Funktioniert CLAUDE.md mit Claude im Web (claude.ai)? Nein. CLAUDE.md wird speziell von Claude Code, dem CLI-basierten Codierungs-Tool, gelesen. Wenn du Claude durch die Web-Schnittstelle oder API verwendest, müsstest du den Kontext manuell einfügen oder die Projects-Funktion verwenden, um ihn als Wissensdatei anzufügen. Das automatische Laden von Claude Code ist das, was die Datei so mächtig macht — null Reibung, jede Sitzung.