CLAUDE.md Best Practices – Der umfassende Leitfaden 2026

Wie du deine CLAUDE.md so aufsetzt, dass Claude bei jeder Sitzung mit maximalem Kontext startet, ohne Token zu verschwenden. Basierend auf offiziellen Anthropic-Richtlinien, dem Karpathy-Framework und Erfahrungen aus dem produktiven Einsatz.

1. Warum CLAUDE.md alles verändert

Wenn du KI-Assistenten wie Claude regelmäßig für ernsthafte Arbeit nutzt, kennst du das Muster: Jeder neue Chat startet mit einer Aufwärmphase. Du erklärst, was das Projekt ist, welche Konventionen gelten, was auf keinen Fall passieren darf. Fünf Minuten Kontext-Setup, jedes einzelne Mal. Und trotzdem erwischst du den Assistenten dabei, wie er die Konvention verletzt, die du beim dritten Chat vergessen hast zu erwähnen. Genau dieses Problem löst die CLAUDE.md.

Die CLAUDE.md ist keine Nice-to-have-Datei. Sie ist der Unterschied zwischen einem Assistenten, der bei jeder Sitzung wieder bei Null anfängt, und einem, der bereits weiß, wie dein Projekt tickt, welche Konventionen gelten und was auf keinen Fall passieren darf. Anthropic beschreibt sie als „besondere Datei, die Claude zu Beginn jeder Konversation liest“ und die persistenten Kontext liefert, den Claude aus dem Code allein nicht ableiten kann.

In der Praxis heißt das: Statt jeden Chat mit einem Absatz zu starten wie „Wir arbeiten in TypeScript, benutzen Vitest, halten uns an Conventional Commits, die API läuft auf Port 3001…“, schreibst du das einmal in die CLAUDE.md und Claude hat es ab jetzt jedes Mal parat. Der Effekt ist messbar. Eine viel zitierte Auswertung eines Karpathy-inspirierten Regelwerks berichtet einen Rückgang von Fehlerraten von 41 Prozent auf 11 Prozent, allein durch eine gut kuratierte CLAUDE.md.

Die Kennzahlen im Überblick:

• 200 Zeilen Zielgröße
• 6 Memory-Ebenen in Claude Code
• 150–200 Instruktionen, die zuverlässig befolgt werden

Die entscheidende Einsicht: Diese Datei landet bei jeder Anfrage im Kontextfenster. Jede Zeile kostet Tokens, die dann nicht mehr für deinen eigentlichen Code oder Text zur Verfügung stehen. Deshalb geht es nicht darum, so viel wie möglich reinzupacken, sondern so wenig wie nötig – aber genau das Richtige.

Der zweite Punkt, den viele unterschätzen: Eine gute CLAUDE.md ist nicht nur ein Werkzeug, um Claude zu instruieren. Sie ist ein Werkzeug, um dich selbst zu zwingen, deine eigenen Regeln explizit zu machen. Vieles, was du im Kopf hast – „wir committen keine .env-Dateien“, „wir nutzen Vitest statt Jest, weil…“, „die API-Auth läuft immer über diese eine Middleware“ – ist implizites Wissen. Sobald du es aufschreibst, wird es prüfbar. Neue Team-Mitglieder profitieren. Du selbst profitierst, weil du in zwei Monaten nicht mehr rekonstruieren musst, warum ihr euch damals so entschieden habt. Die CLAUDE.md ist zwei Werkzeuge in einem: KI-Instruktion und Team-Dokumentation, gleichzeitig.

Die Datei-Hierarchie verstehen

Claude Code liest nicht nur eine einzige CLAUDE.md. Es gibt eine ganze Hierarchie von Speicher-Ebenen, und wer sie kennt, kann sauber zwischen persönlichen, projektspezifischen und teamweiten Regeln trennen. Diese Trennung ist keine Formalie, sondern die Grundlage dafür, dass mehrere Menschen an derselben Codebasis mit demselben Assistenten arbeiten können, ohne sich in die Quere zu kommen.

Die Regel: Global ist für Dinge, die für dich in jedem Projekt gelten (z. B. „antworte auf Deutsch“, „erkläre Änderungen kurz“). Projekt ist für alles, was das Team teilen muss (Build-Commands, Architektur, Konventionen). Projekt-lokal ist für deine persönlichen Eigenheiten in genau diesem Projekt.

Wichtig zur Reihenfolge: Innerhalb eines Verzeichnisses wird CLAUDE.local.md nach CLAUDE.md geladen. Bei Konflikten gewinnt also das Letzte, was Claude gelesen hat. Nutze das bewusst: Projekt-Regeln sind der Konsens, deine lokale Datei überschreibt gezielt.

3. Die goldene 200-Zeilen-Grenze

Die vielleicht wichtigste Zahl in diesem ganzen Leitfaden: Halte deine CLAUDE.md unter 200 Zeilen. Anthropic empfiehlt das explizit, und der Grund ist nicht Ästhetik, sondern ein Phänomen namens Context Rot. Der Begriff beschreibt einen unangenehmen Effekt in großen Sprachmodellen: Je mehr Text im Kontextfenster liegt, desto schlechter werden einzelne Details befolgt. Regeln am Anfang gewinnen an Gewicht; Regeln in der Mitte werden verwaschen; Regeln, die mit vielen anderen zusammen auftauchen, verlieren an Durchschlagskraft.

Ein Chroma-Benchmark aus 2025 hat gezeigt, dass alle 18 getesteten Frontier-Modelle – inklusive Claude Opus 4 – bei wachsender Kontextlänge an Präzision verlieren. Einige fielen von 95 Prozent Trefferquote auf 60 Prozent, sobald ein bestimmter Schwellenwert überschritten wurde. Übersetzt: Je mehr Regeln du reinschreibst, desto weniger davon werden zuverlässig befolgt. Das ist paradox, aber messbar: Die 201. Regel senkt die Wahrscheinlichkeit, dass die 12. Regel eingehalten wird.

Dazu kommt: Claude Code selbst verbrennt bereits rund 50 der zuverlässig befolgbaren 150 bis 200 Instruktionen für seinen eigenen System-Prompt. Was übrig bleibt, ist wertvoll. Nutze es für Dinge, die nirgends sonst stehen.

Ja, das gehört rein:

• Build- und Test-Kommandos
• Harte Einschränkungen („niemals X“)
• Architektur in drei Sätzen
• „Wir nutzen X, nicht Y“-Entscheidungen
• Bekannte Stolperfallen

Nein, das gehört raus:

• Standard-Best-Practices für die Sprache
• Alles, was aus dem Code offensichtlich ist
• Detaillierte Feature-Beschreibungen
• Lange Prosa-Erklärungen
• Aspirations-Floskeln („schreibe schönen Code“)

4. Spezifisch statt vage: warum „schöner Code“ nichts bringt

Die vielleicht häufigste Falle: Regeln, die wie Ratschläge aus einem Coaching-Buch klingen. „Sei konsistent.“ „Schreibe sauberen Code.“ „Denke an die Wartbarkeit.“ Solche Anweisungen sind für ein Sprachmodell wertlos, weil sie keine überprüfbare Aussage machen. Der Assistent hat keinen internen Kompass für „sauber“ – er hat statistische Muster aus Millionen Beispielen, in denen unterschiedlichste Codestile „sauber“ genannt wurden. Wenn du willst, dass Claude einen bestimmten Stil erzeugt, musst du diesen Stil operational beschreiben.

Vage (unwirksam): „Schreibe schönen, konsistenten Code.“ Claude weiß nicht, was du mit „schön“ meinst. Jede Sitzung interpretiert es anders.

Spezifisch (wirksam): „Nutze 2-Space-Einrückung. Single Quotes für Strings. Trailing Commas in Multiline-Objekten. Server Components als Default; ‚use client‘ nur wenn nötig.“ Testbar. Reproduzierbar. Kein Interpretationsspielraum.

Die Faustregel: Wenn du eine Regel nicht mit einem einzelnen Test oder einem Grep-Befehl verifizieren könntest, ist sie zu vage. Formuliere sie so, dass sie in einem PR-Review-Kommentar landen könnte.

Beispiele für konkrete Formulierungen:

# Statt "gute Fehlerbehandlung":
- Werfe niemals nackte Error-Instanzen. Nutze AppError mit code-Feld.
- Fange Exceptions nur, wenn du sie sinnvoll behandeln kannst.
- Logge Fehler mit logger.error(), niemals console.log().

# Statt "sauberer Test-Code":
- Jeder Test folgt Arrange/Act/Assert, getrennt durch Leerzeilen.
- Test-Namen im Format "sollte X, wenn Y".
- Keine Mocks, wo ein echter Fake ausreicht.

# Statt "gute Commits":
- Conventional Commits: feat:, fix:, chore:, docs:.
- Betreff unter 60 Zeichen, Imperativ.
- Body erklärt warum, nicht was.

5. Das Karpathy-Framework: vier Regeln, die alles verändern

Andrej Karpathy hat mit einer minimalistischen CLAUDE.md aus vier Regeln eine Bewegung ausgelöst. Das zugehörige Repository sammelte innerhalb weniger Wochen über 100.000 GitHub-Sterne. Der Grund: Die vier Regeln zielen nicht auf Formatierung, sondern auf die eigentlichen Fehlermodi von Coding-Agenten. Karpathy hatte über Monate beobachtet, wie moderne KI-Assistenten dieselben Fehler in immer neuen Verkleidungen wiederholen, und daraus vier Grundprinzipien destilliert, die diese Fehler an der Wurzel packen.

1. Think Before Coding – Kläre Annahmen, bevor du losschreibst. Wenn etwas unklar ist, frag nach oder markiere die Unsicherheit explizit.
2. Simplicity First – Wähle die einfachste Lösung, die funktioniert. Kein Overengineering, keine spekulative Abstraktion.
3. Surgical Changes – Ändere nur, was für die Aufgabe nötig ist. Kein Umformatieren nicht betroffener Dateien.
4. Goal-Driven Execution – Definiere konkrete Erfolgskriterien, bevor du anfängst. Was muss am Ende wahr sein?

Diese vier adressieren exakt die vier Failure Modes, die Karpathy dokumentiert: Modelle machen stille Annahmen, bauen zu komplex, fassen zu viel an, und arbeiten ohne klares Erfolgskriterium.

# Grundregeln

## 1. Denken vor Coden
Bevor du Code schreibst, formuliere in 3–5 Sätzen:
- Was ist die Aufgabe konkret?
- Welche Annahmen mache ich?
- Wo bin ich unsicher?
Stelle Rückfragen, statt zu raten.

## 2. Einfachheit zuerst
Wähle die kleinste Lösung, die den Test besteht.
Keine Klassen, wo Funktionen reichen.
Keine Abstraktionen für hypothetische Zukunftsfälle.

## 3. Chirurgische Änderungen
Fasse nur an, was für die Aufgabe nötig ist.
Kein Umformatieren, kein "opportunistisches" Refactoring.
Wenn du Nachbarcode anfassen willst, frag vorher.

## 4. Ziel-gesteuerte Ausführung
Vor dem Start: liste die Erfolgskriterien.
Am Ende: prüfe jedes einzelne ab.
Kein "sieht fertig aus" – nur "Test grün, Kriterium erfüllt".

Karpathy hat sein Framework 2026 auf zehn Regeln erweitert, mit sechs zusätzlichen Selbstprüfungs-Protokollen für Runtime-Fehler:

1. Reproduce before fix – Jeder Bug bekommt zuerst einen Test, der ihn zuverlässig reproduziert, dann erst die Korrektur.
2. Token-Budgets – Jeder KI-Schritt läuft unter einer Obergrenze pro Schritt, pro Pipeline und pro Tag.
3. No silent overruns – Fehler werden geloggt und dem Operator gemeldet, nie stumm ausgesessen.
4. Destructive only with consent – Löschungen, Migrationen, Deployments brauchen explizite Bestätigung.
5. Prompt-Injection-Guardrails – Nutzer-Input, der als Instruktion verstanden werden könnte, wird gekennzeichnet.
6. Trust but verify – Jede wichtige KI-Ausgabe wird gegen eine zweite Instanz (Test, Regel, Review) geprüft.

Diese sechs sind für produktive Pipelines gedacht, in denen Claude autonom Aktionen ausführt. Für die klassische „ich schreibe mit Claude Code an einem Projekt“-Nutzung reichen meistens die ersten vier. Die Erweiterung wird relevant, sobald Claude über CI/CD, Deploy-Bots oder Scheduled Tasks in echte Systeme eingreift.

6. IMPORTANT und YOU MUST: wie du Adherence erzwingst

Anthropic dokumentiert in seinen eigenen Guidelines, dass Instruktionen mit IMPORTANT oder YOU MUST verstärkt werden können. Das ist kein Marketing-Trick, sondern reflektiert, wie das Modell trainiert wurde: Diese Signalwörter erhöhen die Wahrscheinlichkeit, dass eine Regel auch unter Druck eingehalten wird.

Nutze das sparsam. Wenn alles IMPORTANT ist, ist nichts mehr IMPORTANT. Reserviere die Verstärkung für Regeln, deren Verletzung echten Schaden anrichtet.

## Harte Grenzen

IMPORTANT: Schreibe niemals in die Produktions-Datenbank aus Tests.
IMPORTANT: Committe nie .env-Dateien oder Dateien in secrets/.
YOU MUST jeden neuen API-Endpunkt durch requireAuth schleusen.
YOU MUST destruktive DB-Migrationen explizit bestätigen lassen.

## Weiche Präferenzen

Bevorzuge async/await über .then()-Chains.
Nutze Tailwind-Utilities statt eigener CSS-Klassen.
Halte Funktionen unter 50 Zeilen, wo sinnvoll.

Beachte den Unterschied im Ton: Die harten Grenzen sind Verbote, die Präferenzen sind Empfehlungen. Claude wird beides berücksichtigen, aber bei den harten Grenzen deutlich strikter sein.

7. Progressive Disclosure: modular arbeiten mit @-Imports

Was tun, wenn du eigentlich mehr als 200 Zeilen an Regeln hast? Antwort: Du packst sie nicht in die CLAUDE.md, sondern in getrennte Dateien, die Claude bei Bedarf nachlädt. Das ist die Idee hinter Progressive Disclosure – ein Prinzip aus dem UX-Design, das sich hier hervorragend auf Prompting anwenden lässt.

Die Grundidee: Zeige immer nur das, was gerade relevant ist. Details bleiben zugänglich, aber verstecken sich hinter einem Trigger. In der CLAUDE.md heißt das: Der Kern enthält, was in jeder Sitzung gilt. Alles, was nur in bestimmten Kontexten relevant ist – die genauen Test-Konventionen, die Regeln für Datenbank-Migrationen, das API-Design-Handbuch – wandert in eigene Dateien.

Claude Code unterstützt Datei-Imports mit dem @-Syntax. Wenn du in deiner CLAUDE.md schreibst @docs/testing.md, wird der Inhalt dieser Datei nachgeladen, sobald der Kontext es nahelegt. So bleibt der Kern schlank, während spezialisierte Regeln griffbereit sind.

Wichtige Nuance: Imports reduzieren die Kontext-Nutzung nicht automatisch – der importierte Inhalt wird inline expandiert und zählt weiter gegen das Fenster. Der eigentliche Gewinn liegt in Organisation und Wartbarkeit: Du kannst einen Teil ändern, ohne den Rest anfassen zu müssen, und andere Tools können auf denselben Kern verweisen.

# CLAUDE.md (der Kern, unter 200 Zeilen)

## Kommandos
- Install: pnpm install
- Test: pnpm test
- Dev: pnpm dev

## Architektur
- apps/web – Next.js App Router
- packages/db – Prisma + PostgreSQL
- packages/ui – shadcn/ui Components

## Detailregeln bei Bedarf laden
@docs/testing-conventions.md
@docs/api-design.md
@docs/db-migrations.md

8. Sicherheits-Leitplanken: der Filler-Killer und Anti-Höflichkeit

Ein oft übersehener Vorteil einer guten CLAUDE.md: Sie kann Claudes Standard-Verhalten so justieren, dass es besser zu deinem Arbeitsstil passt. Der bekannteste Trick aus der Community ist der Filler-Killer – eine Sammlung von Regeln, die Höflichkeitsfloskeln, Überentschuldigungen und redundante Bestätigungen unterdrücken.

Warum das relevant ist: Standardmäßig antwortet Claude in einem freundlich-höflichen Ton, der für Consumer-Anwendungen sinnvoll ist. In produktiver Arbeit an einem Projekt fühlt sich das schnell wie Overhead an. „Klar, gerne! Ich verstehe, dass du eine Funktion für die Datenbank-Verbindung brauchst. Hier ist der Code…“ – zwei Sätze, in denen kein Bit neuer Information steckt. Über hunderte Interaktionen summiert sich das zu spürbar mehr gelesenen Zeilen bei gleichem Nutzen.

Vorsicht mit dieser Kategorie: Regeln wie „Erkläre nie, was du tust“ oder „Frage nie nach“ können nach hinten losgehen. Sie ringen Tokens ab, um Claudes Kernverhalten zu unterdrücken, und machen den Assistenten oft schlechter, nicht besser. Kürzere Antworten sind gut, blinder Gehorsam ist es nicht.

## Kommunikationsstil

- Antworte auf Deutsch.
- Keine Einleitungssätze wie "Klar, gerne!" oder "Natürlich!".
- Keine abschließenden Zusammenfassungen der eigenen Aktion.
- Bei Code-Änderungen: nenne die Datei und die Zeilen, keine Prosa drumherum.
- Frag nach, wenn eine Annahme das Ergebnis stark verändert.
- Bei Unsicherheit: sag es explizit, statt zu raten.

Beachte die letzten beiden Punkte: Sie sind das Gegengift zu naiven „Sei still“-Regeln. Du willst nicht, dass Claude schweigend eine falsche Annahme trifft.

9. Das Plan-First-Prinzip: erst denken, dann handeln

Bei komplexeren Aufgaben – Refactorings, Feature-Implementierungen, Migrationen – lohnt es sich, Claude in einen erzwungenen Planungsschritt zu zwingen, bevor Code entsteht. Das reduziert Ausrutscher massiv, weil du den Plan noch korrigieren kannst, bevor Zeilen produziert werden.

## Plan-First für nicht-triviale Aufgaben

YOU MUST bei jeder Aufgabe, die mehr als eine Datei berührt
oder mehr als 50 Zeilen Code produziert, zuerst einen Plan liefern.

Der Plan enthält:
1. Ziel: was ist der Endzustand?
2. Schritte: nummerierte Liste, jeder Schritt eine überprüfbare Aktion.
3. Betroffene Dateien: vollständige Liste mit begründeter Änderung.
4. Risiken: was könnte kaputtgehen? Wie fangen wir es ab?
5. Erfolgskriterien: welcher Test/welche Beobachtung zeigt Erfolg?

Erst nach meiner ausdrücklichen Freigabe ("go", "los", "machen")
beginnst du mit der Implementierung.

Diese eine Regel ist oft der größte Hebel, den du in einer CLAUDE.md ziehen kannst. Sie verhindert nicht nur Fehler, sie zwingt dich als Nutzer auch dazu, deine eigenen Anforderungen präziser zu formulieren.

In der Praxis bedeutet Plan-First einen Bruch mit dem Reflex, sofort „schreib mir die Funktion“ zu tippen. Stattdessen: „Refactor das Auth-System, damit Magic-Links funktionieren.“ Claude antwortet mit einem strukturierten Plan. Du liest ihn und merkst in Zeile drei: „Halt, den Sessions-Store wollen wir nicht anfassen.“ Ein Wort Korrektur, neuer Plan, dann grünes Licht. Was du vermeidest, ist der klassische Fall, in dem 200 Zeilen Code entstehen und du beim Review feststellst, dass die Architektur-Annahme im dritten Absatz schon falsch war. Der Plan kostet dich 30 Sekunden, spart dir 30 Minuten Reparatur.

10. Der Compounding Learning Loop mit MEMORY.md und ERRORS.md

Der wahrscheinlich wirkungsvollste Setup, um Claude über Zeit besser zu machen: der Learning Loop. Die Idee ist einfach – jede Sitzung produziert Lernstoff. Sackst du diesen strukturiert in Dateien, wird jede folgende Sitzung besser als die davor. Das ist der „Compounding-Effekt“: Kleine Erkenntnisse addieren sich zu einer wachsenden Wissensbasis.

Das Setup nutzt zwei Zusatzdateien:

• MEMORY.md – Ein strukturiertes Protokoll dessen, was gelernt wurde. Entscheidungen, Muster, „das haben wir versucht und verworfen“-Notizen.
• ERRORS.md – Eine Sammlung realer Fehler mit Ursache und Fix. Damit derselbe Fehler nicht dreimal auftritt.

Die Kopplung zur CLAUDE.md:

## Learning Loop

Zu Beginn jeder Sitzung: lies @MEMORY.md und @ERRORS.md.

Wenn ich dich um "session end", "log lernen" oder "protokoll" bitte:

1. Aktualisiere MEMORY.md:
   - Datum + kurze Session-Zusammenfassung
   - Getroffene Entscheidungen (Was, Warum)
   - Neu gelernte Konventionen oder Codebase-Fakten
   - Offene Fragen für nächste Sitzung

2. Aktualisiere ERRORS.md für jeden aufgetretenen Fehler:
   - Symptom (was war die Fehlermeldung/das Verhalten?)
   - Ursache (was war der eigentliche Grund?)
   - Fix (was hat es behoben?)
   - Präventionsregel (wie vermeiden wir das künftig?)

IMPORTANT: Erfinde keine Einträge. Nur echte Vorkommnisse dieser Sitzung.

MEMORY.md – Template:

# Projekt-Gedächtnis

## Kernentscheidungen (dauerhaft)

- Datenbank: PostgreSQL 16, verwaltet via Prisma. Grund: Team-Erfahrung.
- Auth: NextAuth mit Google + E-Mail-Magic-Link.
- Deployment: Vercel für Web, Fly.io für Worker.

## Konventionen (im Team abgestimmt)

- Feature-Ordner statt Layer-Ordner.
- API-Routen in app/api/[...]/route.ts, immer mit requireAuth.
- Datenbank-Zugriffe nur über packages/db/queries/*.

## Session-Log

### 2026-07-14 – Refactor Auth-Flow
- Entscheidung: Magic-Link-Only, Passwort-Login entfernt.
- Grund: Support-Ticket-Volumen wg. vergessener Passwörter zu hoch.
- Neue Konvention: Alle Session-Tokens werden bei jedem Login rotiert.
- Offen: Rate-Limiting für Magic-Link-Anfragen fehlt noch.

### 2026-07-15 – Migration von SWR zu React Query
- Grund: Bessere Optimistic-Update-Story, Devtools reifer.
- Kompatibilitäts-Wrapper unter lib/data/* beibehalten (bis Q4).
- Offen: Cache-Invalidierung nach Mutations noch inkonsistent.

ERRORS.md – Template:

# Fehler-Kompendium

## 2026-07-15 · Hydration-Mismatch nach Date-Formatierung
Symptom: "Warning: Text content did not match" beim ersten Render.
Ursache: new Date().toLocaleString() erzeugt server- und clientseitig
unterschiedliche Strings, weil die Zeitzone abweicht.
Fix: Datum als ISO-String vom Server holen, im Client mit
useEffect + Intl.DateTimeFormat in User-Zeitzone konvertieren.
Regel für die Zukunft: Nie lokale Zeitformate im Server-Render.

## 2026-07-14 · Prisma-Query gab plötzlich undefined
Symptom: TypeError: Cannot read property 'id' of undefined.
Ursache: findFirst() statt findFirstOrThrow() genutzt, kein Null-Check.
Fix: Auf findFirstOrThrow() gewechselt, Error-Boundary hochgezogen.
Regel für die Zukunft: In Route-Handlern immer findFirstOrThrow(),
außer der Null-Fall ist explizit erwarteter Business-Case.

## 2026-07-10 · Test-Suite hängt bei CI, lokal grün
Symptom: CI-Run bricht nach 10 Minuten Timeout ab.
Ursache: Ein await auf ein Promise, das im Test-Mock nie resolved wurde.
Fix: Mock explizit auf Promise.resolve(null) gesetzt.
Regel für die Zukunft: Jeder Mock, der ein Promise zurückgibt, muss
in beforeEach explizit resolved/rejected sein.

Der eigentliche Trick: Wenn dieselbe Präventionsregel drei- oder viermal in ERRORS.md auftaucht, ist es Zeit, sie in die CLAUDE.md zu heben. So verdichtet sich Wissen automatisch: Der Fehler-Speicher ist die Werkbank, die CLAUDE.md ist das Regelwerk.

Der Compounding-Effekt ist real, aber er kommt nicht von allein. Er entsteht, wenn du am Ende jeder ernsthaften Sitzung tatsächlich das Kommando gibst, das Protokoll zu schreiben. Am Anfang wird sich das aufwendig anfühlen – zwei Minuten für ein paar Zeilen. Nach vier Wochen wirst du feststellen, dass Claude typische Fehler bereits vermeidet, bevor du sie ansprechen musst. Nach drei Monaten hat dein Projekt eine Wissensbasis, die den Schwund von Team-Wissen bei Weggängen abfedert. Nach einem Jahr bist du in einer anderen Liga als Teams ohne diesen Loop.

Ein häufiger Einwand: „Aber Claude Code hat doch schon Auto-Memory, das reicht doch.“ Nein. Auto-Memory ist eine sinnvolle Ergänzung, aber sie ist ein Nebenprodukt, kein Prozess. Die entscheidende Bewegung ist, dass du als Nutzer bewusst entscheidest, was Wissen wird und was nicht. Auto-Memory sammelt alles Mögliche – dein manuell gepflegtes MEMORY sammelt nur das, was du für kanonisch erklärt hast. Der Unterschied ist Signal versus Rauschen.

11. CLAUDE.md im Team: geteilter Kontext ohne Reibung

Bis hierher haben wir die CLAUDE.md hauptsächlich als persönliches Werkzeug betrachtet. In Teams wird sie noch mächtiger – und noch heikler. Denn was für eine Person eine nützliche Regel ist, kann für eine andere ein Ärgernis sein. Die Kunst liegt darin, den geteilten Kern von den persönlichen Vorlieben zu trennen.

Die Trennlinie verläuft klar entlang der Datei-Hierarchie: Was das Team teilt, gehört in ./CLAUDE.md, was jede Person für sich anpasst, in ./CLAUDE.local.md. In der Praxis heißt das: Build-Commands, Architektur, Konventionen, Sicherheitsregeln – geteilt. Kommunikationsstil, Ausführlichkeit der Erklärungen, bevorzugte Werkzeuge – lokal.

Ein pragmatischer Prozess für Teams, die neu einsteigen: Setze in einem einstündigen Workshop die erste Version der geteilten CLAUDE.md auf. Nimm die Basis-Vorlage aus Sektion 14, geh sie zu dritt oder zu viert durch. Streiche, was für euer Projekt nicht zutrifft. Ergänze die drei bis fünf Dinge, die euch als „so machen wir das hier“-Konsens einfallen. Committe das Ergebnis. Fertig. Jede Person ergänzt danach für sich eine CLAUDE.local.md.

Der eigentliche Team-Vorteil: Neue Teammitglieder werden dramatisch schneller produktiv. Statt eine Woche zu brauchen, um implizite Konventionen aus Code-Reviews zu extrahieren, lesen sie 200 Zeilen und wissen, wie das Projekt tickt. Der Assistent hilft ihnen dabei zusätzlich, weil er bereits nach denselben Regeln arbeitet.

Konfliktlösung: was tun, wenn zwei Regeln kollidieren?

Es wird passieren. Jemand fügt eine Regel hinzu, die einer bestehenden widerspricht. Der schnelle Reflex – die neue Regel dazu schreiben und weiterziehen – ist der Anfang der 400-Zeilen-Bibel. Besser: Wenn ein Konflikt auftaucht, führt ihn im Pull-Request-Kommentar bewusst aus. Welche Regel gewinnt? Warum? Was ist die konsolidierte Formulierung? Ein Konflikt-PR ist immer eine Gelegenheit, die Datei zu straffen statt zu verlängern.

Onboarding-Ritual mit CLAUDE.md

Nutze die Datei als offizielles Onboarding-Artefakt. Neue Kolleg*innen lesen sie am ersten Tag durch und schreiben in einer Pull-Request die Fragen auf, die dabei entstehen – „warum machen wir X, nicht Y?“, „steht Z hier drin, weil…?“ Diese Fragen sind Gold: Sie zeigen genau, welche Regeln unklar formuliert sind, und liefern damit die konkreten Verbesserungspunkte für die nächste Iteration. Nach ein paar Onboarding-Runden ist deine Datei so klar, dass Missverständnisse verschwinden.

12. AGENTS.md und andere Agenten: Interoperabilität

Ein Detail, das langsam Standard wird: Nicht nur Claude Code liest solche Instruktions-Dateien. Codex von OpenAI liest AGENTS.md, Cursor liest .cursorrules, Windsurf liest .windsurfrules, und die Liste wächst. Wenn du in einer Umgebung arbeitest, in der mehrere Assistenten dieselbe Codebasis anfassen, willst du keine drei Versionen derselben Regeln pflegen.

Die pragmatische Lösung: Halte den kanonischen Kern in einer neutralen Datei, z. B. AGENTS.md, und lasse alle tool-spezifischen Dateien darauf verweisen. In CLAUDE.md steht dann im Kern nichts als ein Import und ein paar Claude-spezifische Ergänzungen.

# CLAUDE.md

# Kanonische Projektregeln (geteilt mit allen Assistenten)
@AGENTS.md

## Claude-spezifische Ergänzungen

- Nutze den Karpathy-Vier-Regel-Modus (siehe unten).
- Bei größeren Aufgaben immer Plan-First mit Freigabe.
- Learning Loop: @MEMORY.md + @ERRORS.md am Session-Ende aktualisieren.

## Karpathy-Grundregeln

1. Denken vor Coden – Annahmen klären.
2. Einfachheit zuerst.
3. Chirurgische Änderungen.
4. Ziel-gesteuert – Erfolgskriterien vor Start.

Der Vorteil dieser Trennung: Wenn du morgen von Claude Code zu Codex wechselst oder parallel Cursor benutzt, ändert sich in AGENTS.md nichts. Die tool-spezifischen Dateien enthalten nur, was wirklich tool-spezifisch ist. Karpathy selbst hat diese Praxis mit dem Hinweis „die gleiche Intuition verallgemeinert sich auf jede Agenten-Laufzeit“ bereits empfohlen.

Gleichzeitig gilt: Übertreib es nicht. Wenn du nur mit Claude Code arbeitest, brauchst du keine AGENTS.md. Die Kernregel bleibt Sparsamkeit. Baue Interoperabilität erst ein, wenn du sie brauchst.

13. Anti-Patterns: die häufigsten Fallen

Aus Community-Beobachtungen kristallisieren sich immer wieder dieselben Fehler heraus. Prüfe deine CLAUDE.md gegen diese Liste.

Anti-Pattern 1: Die 400-Zeilen-Bibel. Teams sammeln über Monate Regeln an, ohne alte zu entfernen. Am Ende hat die Datei 400+ Zeilen, teils widersprüchlich, teils obsolet. Ergebnis: Jede Session verbrennt Tokens für nichts, und die wichtigen Regeln gehen im Rauschen unter. Fix: Quartalsweiser Review, konsequent kürzen.

Anti-Pattern 2: Widersprüchliche Regeln. „Nie Kommentare in Code“ oben, „Komplexe Logik immer mit Inline-Kommentaren dokumentieren“ unten. Claude wählt kontextabhängig – das Ergebnis ist inkonsistent. Fix: Formuliere Regeln mit klaren „wenn/dann“-Klauseln oder entscheide dich für eine Version.

Anti-Pattern 3: Kritische Regeln tief unten. Claude gewichtet frühen Kontext stärker als späten. Wenn deine wichtigste Sicherheitsregel auf Zeile 180 steht, wird sie eher ignoriert als eine Style-Präferenz auf Zeile 10. Fix: Harte Grenzen und Nicht-Verhandelbares oben.

Anti-Pattern 4: Regeln gegen Claudes Grundverhalten. „Erkläre nie deine Aktionen“, „Frag nie zurück“, „Schlage nie Alternativen vor“. Diese Regeln kämpfen gegen Claudes Training, verbrennen Tokens und machen den Assistenten dümmer. Fix: Formuliere positiv, was du willst, statt zu unterdrücken.

Anti-Pattern 5: Aspirations-Floskeln ohne Test. „Sei konsistent“, „denke an die Zukunft“, „schreibe wartbaren Code“. Wertloses Rauschen. Fix: Wenn du eine Regel nicht durch einen Test oder Grep überprüfen könntest, gehört sie nicht rein.

Anti-Pattern 6: Fehlende Begründung. Eine Regel ohne Warum wird beim ersten Konflikt ignoriert. „Nutze Vitest“ ist schwächer als „Nutze Vitest (nicht Jest) – wir haben ESM-Module und Jest scheitert an unseren Node16-Configs.“ Fix: Ein kurzer Grund hinter jeder Regel, die nicht selbsterklärend ist.

Anti-Pattern 7: Kopierte Docs. Ganze Abschnitte aus der Projekt-README oder aus API-Docs in die CLAUDE.md geschoben, statt darauf zu verweisen. Doppelte Wartung, veralte Redundanz. Fix: Verweise per @import oder als Link, aber halte die Wahrheit an einem Ort.

Anti-Pattern 8: „Copy-me-alles“-Attitüde. Manche Teams gehen mit dem Gedanken heran: „Wenn Claude bei uns arbeitet, muss er unser gesamtes Onboarding-Wiki kennen.“ Falsch. Die CLAUDE.md ist keine Wissensbasis, sie ist ein Regelwerk. Fix: Trenne Regeln (wenige, dauerhaft, streng) von Wissen (viel, veränderlich, referenzierbar).

Anti-Pattern 9: Regeln ohne Datum. Eine Regel, die auf einen Bug oder eine spezielle Situation reagiert, ist in sechs Monaten oft überholt – aber niemand weiß es, weil kein Datum dransteht. Fix: Bei taktischen Regeln ein Kommentar mit Datum und Grund: „seit 2026-03: nur JSONB in Postgres, weil Row-Level-Locking auf JSON kaputt war“. Das macht den quartalsweisen Review dramatisch leichter.

Anti-Pattern 10: Der einsame Autor. Eine Person schreibt die CLAUDE.md im Alleingang, das Team liest sie nicht mal. Ergebnis: Der Autor freut sich über perfektes Verhalten, alle anderen kämpfen mit einem Assistenten, der Dinge tut, die niemand erwartet. Fix: Änderungen an der CLAUDE.md laufen wie Code-Änderungen durch einen Pull-Request.

14. Templates zum direkten Kopieren

Hier sind zwei vollständige, kopierbare Templates: ein CLAUDE.md-Basisgerüst für ein Projekt und ein CLAUDE.local.md-Vorspann. Die MEMORY.md- und ERRORS.md-Templates findest du in Sektion 10.

CLAUDE.md – vollständiges Basis-Template

# Projekt-Kontext für Claude

Diese Datei wird bei jeder Sitzung geladen. Halte sie unter 200 Zeilen.
Detailregeln kommen in eigene Dateien und werden per @-Import geladen.

## Was dieses Projekt ist

Interne Analytics-Plattform für unser Sales-Team. Nutzer sind ca. 40 Account
Executives. Daten kommen aus Salesforce, HubSpot und dem eigenen Postgres.

## Harte Grenzen (nicht verhandelbar)

IMPORTANT: Niemals Zugriffe auf Prod-DB aus Tests oder Dev-Skripten.
IMPORTANT: Niemals Secrets in Code oder Logs. Alle Keys via env.
YOU MUST alle API-Routen durch requireAuth-Middleware schleusen.
YOU MUST destruktive Migrationen (DROP, TRUNCATE) explizit bestätigen lassen.

## Kommandos

- Install: pnpm install
- Dev-Server: pnpm dev
- Tests: pnpm test
- Lint: pnpm lint
- Typecheck: pnpm typecheck
- DB-Migration: pnpm db:migrate

## Architektur in drei Sätzen

1. Monorepo mit pnpm-Workspaces: apps/web (Next.js), apps/worker, packages/db.
2. Auth über NextAuth (Google + Magic Link), Sessions in Redis.
3. Datenfluss: Salesforce -> nightly ETL -> Postgres -> Next.js.

## Konventionen

- TypeScript strict, keine any. Bei Bedarf: unknown + Narrowing.
- Feature-Ordner statt Layer-Ordner.
- Datenzugriffe nur über packages/db/queries/*.
- Client-Komponenten explizit mit 'use client'. Default = Server Component.
- Errors nur als AppError-Instanzen. Nackte throw new Error() = Fehler.
- Commit-Nachrichten: Conventional Commits. Betreff unter 60 Zeichen, Imperativ.

## Kommunikationsstil

- Antworte auf Deutsch.
- Kein "Klar!", kein "Natürlich!" zu Beginn.
- Keine Zusammenfassung der eigenen Aktion am Ende.
- Bei Code-Änderung: Datei + Zeilen benennen, minimale Prosa.
- Bei Unsicherheit: sage es explizit, statt zu raten.

## Plan-First bei nicht-trivialen Aufgaben

YOU MUST bei Aufgaben mit mehr als einer Datei oder über 50 Zeilen Code:
1. Zuerst einen Plan liefern (Ziel, Schritte, Dateien, Risiken, Erfolg).
2. Auf meine Freigabe warten ("go", "los", "machen").
3. Dann implementieren.

## Karpathy-Grundprinzipien

1. Denken vor Coden – Annahmen klären, Rückfragen bei Unsicherheit.
2. Einfachheit zuerst – kleinste funktionierende Lösung.
3. Chirurgische Änderungen – nur anfassen, was für die Aufgabe nötig ist.
4. Ziel-gesteuert – Erfolgskriterien vor Start definieren und prüfen.

## Bekannte Stolperfallen

- Prisma-Client bei Hot-Reload doppelt initialisiert -> global-Cache nutzen.
- Turborepo-Cache invalidieren mit pnpm turbo run --force bei komischen Bugs.
- next/image braucht bei externen Bildern remotePatterns in next.config.ts.

## Detailregeln bei Bedarf

@docs/testing-conventions.md
@docs/db-migrations.md
@docs/api-design.md

## Learning Loop

Zu Beginn jeder Sitzung: lies @MEMORY.md und @ERRORS.md.
Am Ende einer Sitzung (auf "session end"): Beide aktualisieren.

## Was nicht in diese Datei gehört

- Was aus dem Code offensichtlich ist.
- Standard-Best-Practices von TS/React (Claude kennt sie).
- Feature-Beschreibungen (gehören in docs/features/*).
- Persönliche Präferenzen (gehören in CLAUDE.local.md).

CLAUDE.local.md – persönliche Ergänzung

## Meine lokale Umgebung

- OS: macOS 14 auf M2. Homebrew-Pfad ist /opt/homebrew.
- Node via mise gemanagt, aktuell v22.5.0.
- Postgres läuft in Docker unter localhost:5433 (nicht 5432 wegen Konflikt).
- Redis lokal unter localhost:6380.

## Meine Präferenzen

- Kurze Antworten. Wenn etwas in 3 Sätzen sagbar ist, keine 10.
- Bei Ambiguität lieber eine explizite Rückfrage als eine geratene Antwort.
- Zeige mir Diffs, keine ganzen Dateien, bei kleinen Änderungen.

## Meine typischen Aufgaben

- Ich arbeite meist an apps/web/features/reporting/.
- Für Prisma-Schema-Änderungen: erst mit mir abstimmen.
- Ich nutze just statt make lokal – siehe justfile.

15. Für Nicht-Code-Projekte: Marketing, Research, Writing

Alles bisher Gesagte gilt genauso für nicht-technische Projekte. Die Struktur ändert sich, die Prinzipien bleiben. Der Effekt ist teils sogar größer als bei Code: In kreativen oder redaktionellen Arbeiten sind Konsistenz und Stil-Treue oft das eigentliche Qualitätsmerkmal, und genau da liefert eine gut kuratierte CLAUDE.md enormen Wert.

Marketing-Pipeline

# Marketing-Kontext

## Marke
- Positionierung: "präzise, unaufgeregt, evidenzbasiert".
- Zielgruppe: Marketing-Ops-Leads in Mid-Market-SaaS (50–500 MA).
- Ton: sachlich, kein Gehype, keine Superlative ohne Zahl.

## Verbotswörter
IMPORTANT: Diese Wörter nie in kundenbezogenen Texten:
"revolutionär", "bahnbrechend", "cutting-edge", "world-class", "10x".

## Format-Regeln je Kanal
- LinkedIn-Post: max. 1300 Zeichen. Erste Zeile = Hook. Absätze durch Leerzeilen.
- Newsletter: max. 400 Wörter. Ein Thema. CTA nur im letzten Absatz.
- Blog: 800–1400 Wörter. H2 nach jeder ~200-Wörter-Sektion.

## Approval-Prozess
YOU MUST jede Behauptung mit Zahl auf Quelle prüfbar machen.
YOU MUST vor Publish-Vorschlag: Faktcheck + Ton-Check gegen die Marke.

Research-Projekt

# Research-Kontext

## Forschungsfrage
Wie wirken sich KI-Coding-Assistenten auf die Fehlerrate in Legacy-Codebasen aus?
Zielpublikum: Engineering Manager mittelständischer SaaS-Firmen.

## Quellenregeln (nicht verhandelbar)
IMPORTANT: Jede Zahl braucht eine Primärquelle mit direktem Link.
IMPORTANT: Keine synthetischen Statistiken erfinden, auch nicht plausibel.
YOU MUST Zweitquellen-Bestätigung für jede Behauptung außerhalb
persönlicher Anekdoten. Wenn nur eine Quelle: als solche markieren.

## Format
- Zitate im Fließtext mit Autor + Jahr, volle Quelle in Fußnote.
- Screenshots von Original-Quellen im Ordner quellen/screenshots/.
- Rohnotizen in notes/YYYY-MM-DD.md, gruppiert nach Interview-Partner.

## Ausschlüsse
- Keine Reddit-Threads als Primärquelle.
- Keine Marketing-Blogs von Anbietern ohne Peer-Review.
- Keine anekdotischen Behauptungen aus Twitter/X ohne Verifikation.

## Register
@quellen/verifiziert.md
@quellen/vorlaeufig.md
@interviews/transkripte-index.md

Beachte, dass die Muster identisch sind: harte Regeln oben, Konventionen mit Grund, Ausschluss-Listen, Arbeitsablauf, modulare Detail-Referenzen per Import. Was sich ändert, ist der Inhalt, nicht die Form. Egal ob Code, Marketing, Prosa oder Research – das Muster funktioniert überall dort, wo ein Assistent wiederholt in denselben Kontext eintauchen soll.

16. Deine CLAUDE.md testen: der Drei-Prompt-Check

Ein oft übersehener Schritt: Wie weißt du eigentlich, ob deine CLAUDE.md funktioniert? Die naive Antwort lautet „wenn Claude gute Antworten gibt“. Das ist zu unspezifisch. Wer seine Datei ernst nimmt, testet sie mit definierten Prompts, die genau die Regeln herausfordern, die drinstehen.

Der einfachste Weg ist der Drei-Prompt-Check. Öffne eine komplett frische Session (kein History-Kontext) und stelle drei Prompts, die jeweils genau eine deiner wichtigen Regeln testen sollten. Nicht „kannst du bitte X tun“, sondern eine echte Aufgabe.

# Test 1 – prüft die "Plan-First"-Regel
Prompt: "Baue mir eine Login-Seite mit Magic-Link."
Erwartung: Claude liefert einen Plan, keinen Code. Wartet auf Freigabe.
Rot, wenn: sofort Code ohne Plan kommt.

# Test 2 – prüft die "Datenzugriff-nur-über-Queries"-Regel
Prompt: "Zeig mir, wie ich in der Route /api/reports/[id]
        den Report aus der DB holen würde."
Erwartung: Verweis auf packages/db/queries/*, keine Prisma-Calls in Route.
Rot, wenn: prisma.report.findFirst() direkt im Route-Handler steht.

# Test 3 – prüft den Kommunikationsstil
Prompt: "Wie ändere ich den Port des Dev-Servers?"
Erwartung: kurze Antwort, kein "Klar, gerne!", keine Zusammenfassung.
Rot, wenn: Prosa-Wolke mit Höflichkeitsfloskeln.

Nimm dir die Zeit, das nach jeder größeren Änderung an der Datei zu tun. Fünf Minuten Realtest schlägt eine Stunde Theorie. Wenn ein Prompt rot ist, weißt du sofort, welche Regel nicht durchdringt – und ob sie deutlicher formuliert, verschoben oder mit IMPORTANT verstärkt werden muss.

17. Wartung: der quartalsweise Review

Eine CLAUDE.md ist kein Set-and-forget. Sie ist ein lebendes Dokument, das mit dem Projekt atmet. Ohne Pflege verkommt sie zu einem Friedhof veralteter Regeln, der Claudes Antworten verschlechtert statt verbessert.

Blocke dir alle drei Monate eine Stunde für einen kurzen Review-Prozess:

1. Lies die Datei einmal komplett durch. Was hörst du dich selbst denken „das gilt nicht mehr“? Streichen.
2. Prüfe jede Regel auf Aktualität. Ist der Command noch korrekt? Existiert die Datei noch, auf die verwiesen wird?
3. Prüfe ERRORS.md. Welche Präventionsregel taucht mehrfach auf? Sie gehört in die CLAUDE.md.
4. Zähle die Zeilen. Bei 200+ – was kann in einen Import wandern?
5. Teste in einer frischen Sitzung. Öffne einen neuen Chat, stelle eine typische Frage. Werden die Regeln befolgt?

Faustregel für den Review: Wenn du am Ende einer Session mehr Regeln in der Datei hast als davor, hast du wahrscheinlich einen Fehler gemacht. Der gesunde Trend ist Verdichtung, nicht Wachstum.

Der 90-Tage-Rhythmus in der Praxis

Blocke dir im Kalender einen wiederkehrenden Termin: „CLAUDE.md-Review, 30 Minuten, alle 90 Tage“. Das klingt banal, ist aber der entscheidende Unterschied zwischen einer lebendigen Datei und einem verwaisten Regelwerk. Nutze den Termin, um mit einer der drei Auslöseformen einzusteigen: Erstens der Zeilenzahl-Check – wie viele Zeilen hat die Datei jetzt, wie viele hatte sie vor 90 Tagen? Zweitens der Frust-Check – wo hast du Claude in den letzten Wochen immer wieder korrigiert, obwohl es einer Regel entsprechen sollte? Drittens der Streich-Check – welche Regel hättest du seit langem nicht mehr angewandt?

Ein Anti-Muster hier: Man setzt den Review-Termin, aber niemand fühlt sich verantwortlich. In Teams sollte pro Quartal eine Person namentlich für den Review nominiert sein – rotierend. Diese Person führt ihn durch, öffnet einen PR mit den Änderungen, das Team reviewt in 15 Minuten. Fertig. Wer die Verantwortung diffundiert, hat in einem Jahr wieder 400 Zeilen.

18. Die finale Checkliste vor dem Deploy

Wenn du deine CLAUDE.md für ein neues oder überarbeitetes Projekt fertig hast, geh sie einmal gegen diese Liste durch, bevor du sie committest.

Fünf Fehler, die du in den ersten 30 Tagen machen wirst

Sei ehrlich zu dir selbst: Beim ersten Versuch wirst du diese Datei nicht optimal aufsetzen. Das ist okay. Die folgenden fünf Fehler machen alle, und du wirst sie auch machen. Wenn du sie kennst, korrigierst du sie schneller.

Erstens: Zu viel schreiben. Der Impuls, alles reinzupacken, was einem einfällt, ist übermächtig. Widerstehe. Wenn du unsicher bist, ob eine Regel reingehört, lass sie erstmal weg. Du kannst sie in einer Woche ergänzen, falls dir wirklich etwas fehlt. Aber du wirst überrascht sein, wie selten das passiert.

Zweitens: Zu abstrakt formulieren. „Halte den Code lesbar“ ist keine Regel, das ist ein Wunsch. Zwing dich, jede Regel so umzuformulieren, dass ein Junior-Entwickler in fünf Minuten prüfen könnte, ob sie eingehalten wurde.

Drittens: Auto-Memory überbewerten. Claude Code schreibt eigenständig Dinge in seine Auto-Memory, wenn du es zulässt. Praktisch, aber verführerisch. Wenn du diesen Autopiloten ohne Kuratierung laufen lässt, hast du in Wochen eine wilde Sammlung halb-relevanter Fakten. Auto-Memory ist ein Vorschlag, kein Ersatz.

Viertens: Regeln nicht begründen. „Nutze Postgres, nicht SQLite“ – warum? Ohne Begründung wird die Regel beim ersten Konflikt ignoriert, weil Claude nicht weiß, ob sie eine harte Anforderung ist oder eine Präferenz. Ein halber Satz Grund reicht meistens.

Fünftens: Den Learning Loop skippen. Die MEMORY- und ERRORS-Dateien fühlen sich nach mehr Arbeit an, als sie sind. Und sie fühlen sich am Anfang nach wenig Nutzen an. Der Payoff kommt nach Wochen. Halte durch. Nach 30 Tagen wirst du feststellen, dass typische Fehler nicht mehr auftauchen, weil deine Präventionsregeln sie schon abfangen.

Wenn du nur eine Sache mitnehmen sollst

Es ist diese: Deine CLAUDE.md ist die Antwort auf die Frage „Was würde ich einem neuen Kollegen am ersten Tag sagen?“ Nicht „was steht in unseren Docs“, nicht „was ist offensichtlich“, sondern die konzentrierten Regeln, die den Unterschied zwischen „so machen wir das nicht“ und „so machen wir das“ ausmachen. Alles andere gehört woanders hin.

Fang mit der Basis-Vorlage aus Sektion 14 an. Kürze sie auf das, was für dein Projekt zutrifft. Ergänze eine Woche später drei bis fünf Dinge, die du in der Woche vermisst hast. Setze dir einen Review in 90 Tagen. Das ist der Weg.

Der Aufwand für den Start ist minimal – die Basis-Vorlage in eine leere Datei kopieren, die Kommandos anpassen, die Architektur-Sätze umformulieren. In einer halben Stunde hast du eine funktionierende Version, die schon 80 Prozent des Effekts bringt. Die restlichen 20 Prozent kommen über die nächsten Wochen durch Beobachtung, was Claude falsch macht, und durch das MEMORY-Protokoll, das dir zeigt, welche Regel gefehlt hat. Wichtig ist nur, den Anfang zu machen. Eine mittelmäßige CLAUDE.md, die existiert, ist um Größenordnungen besser als eine perfekte, die du für nächste Woche geplant hast.

Und noch ein Gedanke, der oft untergeht: Diese Datei ist auch ein Signal an dein zukünftiges Ich. In sechs Monaten, wenn du das Projekt wieder anfasst, wird die CLAUDE.md das Erste sein, was dich abholt. Sie ist die einminütige Version deines eigenen Onboarding-Dokuments. Behandle sie mit der Sorgfalt, die du dir selbst schuldig bist.

Quellen und weiterführende Links

• Anthropic – Best practices for Claude Code
• Anthropic – How Claude remembers your project
• Anthropic Help Center – Give Claude context: CLAUDE.md and better prompts
• multica-ai/andrej-karpathy-skills auf GitHub
• Karpathy CLAUDE.md Rules: Cut Claude Errors 41% to 11%
• Karpathy CLAUDE.md Grows to Ten Rules (TechTimes)
• HumanLayer – Writing a good CLAUDE.md
• 7 CLAUDE.md Patterns That Stop Claude From Drifting Off-Script
• MindStudio – Compounding Knowledge Loop in Claude Code
• MindStudio – What Is Claude Code Auto-Memory
• Claude Code Memory Explained (Substack)
• CLAUDE.md Best Practices Guide 2026 (DEV)
• AGENTS.md Spezifikation