CLAUDE.md Best Practices – mit kommentiertem Beispiel

CLAUDE.md ist die teuerste Datei in deinem Repository. Nicht in Bytes. In Wiederholung. Was du dort hineinschreibst, wird zu Beginn jeder Session in Claudes Kontext geladen und reist danach mit jeder einzelnen Nachricht mit, die du schickst. Eine aufgeblähte CLAUDE.md ist eine Steuer, die du hundertmal am Tag zahlst, ohne es zu merken.

Wir testen bei SkillProof beruflich Claude-Setups und haben inzwischen mehr CLAUDE.md-Dateien gelesen, als uns lieb ist. Die meisten machen denselben Fehler: Sie behandeln die Datei als Abladeplatz für alles, was der Autor Claude jemals mitteilen wollte. Coding-Philosophie, Tonalitätswünsche, ein kompletter Styleguide, drei Absätze über Sorgfalt. Alles geladen, immer, bei jeder Anfrage — auch bei der, in der du Claude gebeten hast, eine Variable umzubenennen.

Dieser Guide ist unser Versuch, das zu reparieren. Wofür CLAUDE.md wirklich da ist, ein vollständiges kommentiertes Beispiel zum Adaptieren, was in Skills ausgelagert gehört — und die Rechnung, die erklärt, warum das alles überhaupt eine Rolle spielt.

Was CLAUDE.md ist und wann sie geladen wird

CLAUDE.md ist die Projekt-Gedächtnisdatei von Claude Code. Startest du eine Session in einem Verzeichnis, läuft Claude Code von deinem Arbeitsverzeichnis aus nach oben, sucht CLAUDE.md-Dateien und lädt die Funde in den System-Kontext. Deine globale Datei unter ~/.claude/CLAUDE.md wird ebenfalls geladen, in jedem Projekt. Dateien in Unterverzeichnissen laden, sobald Claude mit Dateien dort arbeitet.

Der Teil, den die meisten übersehen: Das ist kein einmaliges Einlesen. Sprachmodelle sind zustandslos, also wird der komplette Kontext — inklusive deiner CLAUDE.md — mit jeder Anfrage der Unterhaltung mitgeschickt. Stellst du in einer Session vierzig Fragen, wird die Datei vierzigmal übertragen. Prompt-Caching dämpft die Dollarkosten, zu den konkreten Zahlen kommen wir noch, aber nichts dämpft die Aufmerksamkeitskosten. Jedes Token in der CLAUDE.md konkurriert mit deinem eigentlichen Code um den Fokus des Modells.

Das ist der Preis. Dafür bekommst du etwas Echtes: Claude startet jede Session und kennt bereits deine Build-Befehle, deine Architektur-Eigenheiten und die Tretminen in deiner Codebasis. Niemand muss zum neunten Mal „wir benutzen pnpm, nicht npm" einfügen. Die Frage ist nie, ob du eine CLAUDE.md haben solltest. Sondern was sich einen Platz darin verdient.

Die goldene Regel: Fakten in CLAUDE.md, Verhalten in Skills

Hier ist die These dieses ganzen Artikels — und der eine Filter, der die meisten schlechten Dateien repariert:

CLAUDE.md ist für Fakten über dieses Projekt. Skills sind für wiederverwendbares Verhalten.

Ein Fakt über dieses Projekt: „Preise werden als ganzzahlige Cents gespeichert." Das kann Claude nicht erraten. Keine noch so große allgemeine Intelligenz holt das aus dem Nichts, und ein Fehler dabei korrumpiert Daten. Das gehört in die CLAUDE.md, dauerhaft geladen, weil es für fast jede Änderung relevant ist, die Geld berührt.

Wiederverwendbares Verhalten: „Prüfe bei Code-Reviews zuerst das Error-Handling, dann Security, dann Namensgebung." Das ist kein Fakt über dein Projekt. Es ist eine Prozedur, sie gilt für jedes Projekt, das du je anfassen wirst, und sie ist nur relevant, wenn du tatsächlich Code reviewst. Steht sie in der CLAUDE.md, zahlst du dafür bei jeder Commit-Message, jedem CSS-Tweak, jedem „Was macht diese Funktion". Steckt sie in einem Skill, kostet sie dich eine Zeile Metadaten — bis zu dem Moment, in dem ein Review wirklich stattfindet und die vollen Anweisungen on demand laden.

Die meisten stopfen alles in die CLAUDE.md, weil es die Datei ist, die sie kennen. Sie liegt direkt da, sie funktioniert offensichtlich, und die Kosten sind unsichtbar, weil auf keiner Rechnung je steht: „Du hast diesen Monat 4.000-mal für deinen Styleguide bezahlt." Aber die Kosten sind real, und die Aufteilung ist fast mechanisch, sobald du zu jeder Anweisung zwei Fragen stellst. Gilt sie nur für dieses Projekt? Ist sie für die meisten Anfragen relevant? Zweimal Ja: CLAUDE.md. Alles andere: ein Skill — oder der Papierkorb.

Es gibt einen zweiten Grund für die Trennung, der nichts mit Tokens zu tun hat. Anweisungen in einer immer geladenen Datei konkurrieren miteinander. Wir haben eine 2.000-Wörter-CLAUDE.md gesehen, in der die wirklich wichtige Regel („niemals db:push gegen Staging laufen lassen") in Absatz elf stand, unter einem Vortrag über Clean Code. Claude folgt langen Anweisungslisten so, wie Menschen es tun: Die scharfen Punkte werden vom Füllmaterial drumherum verwässert. Kurze Dateien werden befolgt. Lange Dateien werden überflogen.

Ein kommentiertes CLAUDE.md-Beispiel für eine mittelgroße Web-App

Hier ein vollständiges Beispiel für einen fiktiven, aber realistischen Next.js-Storefront. Die Kommentare erklären, warum sich jede Sektion ihren Dauerplatz im Kontext verdient. Das Ganze kommt auf etwa 350 Wörter, grob 500 Tokens — und wir würden behaupten, nichts davon ist streichbar.

# Acme Storefront

Next.js 14 (App Router) + TypeScript. Postgres via Prisma. Deployed on Vercel.
<!-- One line of stack. Claude infers most of this from package.json anyway;
     this just saves it the lookup. Do not write paragraphs here. -->

## Commands
- `pnpm dev` — local server on :3000 (needs `docker compose up db` first)
- `pnpm test` — unit tests (Vitest). Integration: `pnpm test:int` (slow, needs db)
- `pnpm lint && pnpm typecheck` — run both before calling any task done
- Migrations go through `pnpm db:migrate`. NEVER `db:push` outside local.
<!-- Commands earn their place because Claude runs them dozens of times per
     session, and a wrong guess (npm vs pnpm) wastes a round-trip every time.
     The db:push line is here because the failure is irreversible. -->

## Architecture facts you can't guess
- `src/app` is routes only. All logic lives in `src/modules/<domain>`.
- API routes are thin wrappers over `src/modules/*/service.ts`. No logic in routes.
- Auth is Clerk, but `userId` in services is OUR internal id, not Clerk's.
  Map with `getInternalUser()`.
- Prices are integer cents everywhere. Formatting lives in `lib/money.ts`.
- Feature flags come from `flags.ts`, not env vars.
<!-- The test for this section: would a skilled new hire get it wrong on
     day one? The Clerk id mismatch has caused real bugs; that is exactly
     the kind of fact worth paying for on every request. -->

## Conventions that differ from defaults
- Named exports only. Legacy violations exist in `src/legacy`; don't add new ones.
- Server components by default. `"use client"` needs a comment saying why.
- Zod schemas live next to services; infer types from them, never hand-write both.
<!-- Only conventions that DIFFER from what Claude would do anyway.
     "Use TypeScript strict mode" when tsconfig already says so is a wasted line. -->

## Gotchas
- `src/legacy/*` is frozen. Don't refactor it or import from it in new code.
- CI runs Node 20. `pnpm test:int` fails on 22; use `nvm use` first.
<!-- Each line here represents an hour someone actually lost. -->

## Definition of done
Lint, typecheck, and unit tests pass, and you state which of them you ran.
<!-- One sentence. Not a philosophy of quality. -->

Beachte, was fehlt. Kein „write clean, maintainable code". Keine Tonalitätsanweisungen. Keine Erklärung, was Next.js ist. Keine Lint-Regeln, die der Linter ohnehin maschinell durchsetzt. Jede Zeile ist entweder ein Befehl, den Claude ausführen wird, ein Fakt, den es nicht ableiten kann, oder eine Grenze, deren Überschreiten echtes Geld oder echte Stunden kostet.

Was du in Skills auslagern solltest

Wenn deine aktuelle CLAUDE.md 1.500 Wörter hat, fällt der Überschuss meist in ein paar wiedererkennbare Kategorien — und jede davon hat ein skillförmiges Zuhause. Ein paar Beispiele aus unserem eigenen Katalog, alle vor der Listung auf sauberen Maschinen installiert und getestet:

Git-Zeremonie. Branch-Namen, Commit-Message-Format, PR-Beschreibungs-Templates, wann gesquasht wird. Das ist Verhalten, es ist über deine Projekte hinweg identisch, und es ist nur relevant, wenn du tatsächlich committest. Der von uns getestete git-workflow-Skill deckt genau diesen Umfang ab, und ihn aus der CLAUDE.md zu ziehen spart typischerweise 200 bis 400 Wörter dauerhaft geladenen Text.

Review-Checklisten. „Wenn ich ein Review anfrage, prüfe X, dann Y"-Anweisungen sind der klassische CLAUDE.md-Hausbesetzer. Sie sind lang, sie sind prozedural, und sie schlafen 95 % der Zeit. code-review-checklist lädt seine Checkliste nur, wenn gerade ein Review läuft — genau das ist der Sinn des Skill-Formats.

Debugging-Disziplin. Anweisungen wie „erst reproduzieren, dann fixen, Hypothese nennen, danach verifizieren" beschreiben eine Methodik, nicht dein Projekt. systematic-debugging verpackt diese Methodik und hält sich aus dem Kontext heraus, solange du nichts anderes tust, als einem Bug hinterherzujagen.

Die Faustregel: Könntest du den Absatz unverändert in die CLAUDE.md eines anderen Projekts kopieren, ist er kein Fakt über dein Projekt und hat dort nichts verloren. Extrahiere ihn. Einen eigenen Skill zu schreiben dauert mit unserem Guide etwa zwanzig Minuten — und es sind die zwanzig Minuten mit dem größten Hebel für alle, deren CLAUDE.md länger als ein Bildschirm geworden ist.

Anti-Patterns, die uns immer wieder begegnen

Wir reviewen viele Setups, und dieselben fünf Fehler tauchen in Dauerschleife auf.

Der Roman. Eine 3.000-Wörter-CLAUDE.md, die sich liest wie ein Engineering-Handbuch. Jemand hatte eine schlechte Erfahrung, ergänzte einen Absatz, hatte die nächste, ergänzte den nächsten — und löschte nie etwas. Die Datei wächst nur. Über die Token-Kosten hinaus begraben solche Dateien die zwei Regeln, die wirklich zählen, unter zwanzig, die es nicht tun, und Claudes Befolgung sinkt für alle gemeinsam.

Veraltete Befehle. In der Datei steht npm run test:unit, das Script wurde vor acht Monaten in pnpm test umbenannt, und jetzt führt Claude selbstbewusst einen Befehl aus, der fehlschlägt, liest den Fehler, stochert in der package.json und rettet sich. Jede Session. Du zahlst für die falsche Dokumentation und dann noch einmal dafür, dass Claude sie umschifft. Eine falsche CLAUDE.md ist schlimmer als keine, denn Claude vertraut ihr.

Duplizierte Lint-Regeln. „Single Quotes. Keine unbenutzten Variablen. Maximale Zeilenlänge 100." Deine ESLint-Konfiguration erzwingt das bereits maschinell, mit besserer Abdeckung, als die Aufmerksamkeit eines LLM je haben wird. Maschinell erzwungene Regeln in Prosa zu wiederholen ist reine Verschwendung. Die eine Ausnahme: Regeln, die das Tooling nicht fangen kann, etwa „nicht aus src/legacy importieren" — die müssen wirklich aufgeschrieben werden.

Die „Sei hilfreich"-Sektion. „Schreib sauberen Code. Denk sorgfältig nach, bevor du etwas änderst. Sei gründlich, aber prägnant." Irgendeine Variante davon sehen wir in etwa der Hälfte der Dateien, die wir reviewen, und sie bewirkt nichts. Claude versucht es ohnehin schon. Anweisungen auf Vibes-Basis ohne prüfbaren Inhalt sind das Erste, was du löschen solltest — ihr einziger messbarer Effekt sind die Tokens, die sie verbrennen.

Die Autobiografie. Lange Beschreibungen, was das Produkt tut, wer die Nutzer sind, die Firmenmission. Gelegentlich ist ein Produktfakt für Code-Entscheidungen relevant („unsere Nutzer hängen an langsamen Verbindungen auf dem Land, Bundle-Größe ist ein echtes Limit"). Behalte diesen einen Satz. Streich das Pitch-Deck.

Die Token-Rechnung

Machen wir die Rechnung, die alle überspringen — denn die Zahlen sind es, die uns zu Minimalisten gemacht haben.

Eine 3.000-Wörter-CLAUDE.md sind grob 4.000 Tokens. Sie reist mit jeder Anfrage mit; eine Arbeitssession mit 40 Nachrichten überträgt sie also 40-mal: 160.000 Input-Tokens in einer Session, die deine Gedächtnisdatei sind — nicht dein Code, nicht deine Unterhaltung. Bei fünf Sessions am Tag bewegst du täglich 800.000 CLAUDE.md-Tokens. Über einen Monat mit 22 Arbeitstagen: etwa 17,6 Millionen.

Prompt-Caching rettet den Großteil der Dollarkosten, und da sollten wir ehrlich sein. Gecachter Input kostet auf Sonnet ein Zehntel des Basispreises; diese 17,6 Mio. Tokens kosten also ein paar Dollar im Monat, wenn der Cache warm bleibt — eher 50 $, wenn nicht. Ärgerlich, nicht ruinös.

Was Caching nicht rettet, ist der Kontext. Das Kontextfenster von Claude Code ist endlich, und lange Sessions enden ohnehin in der Compaction, bei der die Unterhaltung zusammengefasst wird und Details verloren gehen. Ein 4.000-Token-Dauerbewohner heißt: Du erreichst die Compaction früher, in jeder Session, für immer. Und er schwächt die Aufmerksamkeit schon vor jedem harten Limit: Modelle folgen Anweisungen nachweislich besser, wenn weniger davon konkurrieren. Der Unterschied zwischen einer 500-Token-Datei und einer 4.000-Token-Datei sind nicht 3.500 Tokens. Es ist die Frage, ob dem Modell deine „Niemals Staging anfassen"-Regel bei Nachricht 35 noch wichtig ist.

Rechne dieselben Zahlen mit dem gekürzten Beispiel oben durch: 500 Tokens, 40 Nachrichten, fünf Sessions, 22 Tage. Etwa 2,2 Mio. Tokens im Monat, ein Achtel der aufgeblähten Version — und die wichtigen Regeln stehen in einem unverstellten Raum. Das größere Kostensenkungs-Playbook haben wir in unserem Token-Kosten-Guide aufgeschrieben, und das Trimmen der CLAUDE.md ist darin durchgehend der billigste Gewinn.

Projekt vs. global: der ~/.claude/CLAUDE.md-Split

Du hast zwei Dateien, und Ärger entsteht, wenn Inhalte in der falschen landen.

~/.claude/CLAUDE.md ist global. Sie lädt in jedem Projekt, darf also nur Dinge enthalten, die überall stimmen: „Ich nutze pnpm in allen privaten Projekten", „antworte auf Englisch, auch wenn meine Prompts manchmal Russisch sind", „niemals ungefragt committen". Halte sie unter zehn Zeilen. Jede Zeile hier multipliziert sich über deine gesamte Arbeit, ihr Budget sollte also das strengste sein.

<project>/CLAUDE.md ist die Projektdatei, in Git eingecheckt, geteilt mit Teamkollegen und CI. Fakten über diese Codebasis, im Zuschnitt des Beispiels oben. Weil sie geteilt wird, gehören persönliche Vorlieben nicht hinein; dafür gibt es CLAUDE.local.md oder die globale Datei.

CLAUDE.md-Dateien in Unterverzeichnissen sind die unterschätzte Mittelebene. Eine packages/api/CLAUDE.md mit API-spezifischen Fakten lädt nur, wenn Claude dieses Package anfasst. Enthält die Root-Datei deines Monorepos Sektionen, die nur einen Workspace betreffen, ist das Herunterschieben um eine Ebene gratis Token-Ersparnis ohne jeden Informationsverlust.

Ein Irrglaube, den es zu beerdigen gilt: Etwas in mehr als eine dieser Dateien zu schreiben bringt Claude nicht dazu, es strenger zu befolgen. Es macht nur die Datei länger. Ein Zuhause pro Fakt.

Frisch halten

CLAUDE.md verrottet schneller als normale Dokumentation, weil nichts sichtbar kaputtgeht, wenn sie falsch ist. Tests schlagen laut fehl. Eine veraltete Gedächtnisdatei führt das Modell nur leise in die Irre, das Modell rettet sich leise, und du zahlst leise für beides.

Unser Ritual ist langweilig und dauert zehn Minuten im Monat. Datei öffnen. Jeden Befehl tatsächlich ausführen. Bei jedem behaupteten Fakt fragen, ob er noch stimmt und ob Claude diesen Monat seinetwegen etwas falsch gemacht hat. Mindestens eine Zeile löschen; es gibt immer eine Zeile, und wenn du keine findest, sind deine Maßstäbe für „verdient sich einen Platz" verrutscht. Dann die Länge prüfen: Ein Bildschirm ist das Ziel, zwei Bildschirme die Obergrenze — darüber hinaus editierst du nicht mehr, du extrahierst in Skills.

Der beste Auslöser für Updates ist aber nicht der Kalender. Es ist der Moment, in dem Claude etwas falsch macht, weil die Datei es in die Irre geführt hat. Reparier die Datei im selben Atemzug wie den Code. Behandle CLAUDE.md-Bugs wie Bugs, denn sie haben dasselbe Rückfallverhalten: Ungefixt passieren sie nächste Session wieder.

FAQ

Wie lang sollte eine CLAUDE.md sein?

Unter 500 Wörtern für die meisten Projekte, unter 1.000 für ein wirklich kompliziertes Monorepo. Unser Praxistest: Passt sie nicht auf einen Bildschirm, steckt darin Verhalten, das sich als Fakt tarnt — und das gehört in einen Skill. Das Beispiel in diesem Artikel hat etwa 350 Wörter und deckt eine echte mittelgroße App ab.

Was ist der Unterschied zwischen CLAUDE.md und einem Skill?

Das Ladeverhalten. CLAUDE.md wird vollständig geladen, immer, bei jeder Anfrage. Ein Skill zeigt nur eine einzeilige Description, bis eine Aufgabe passt — dann lädt er on demand. CLAUDE.md sollte also Fakten enthalten, die du ständig brauchst, Skills die Prozeduren, die du gelegentlich brauchst. Die Mechanik erklärt unser Skills-Guide.

Sollte ich CLAUDE.md in Git einchecken?

Ja. Sie ist geteilte Dokumentation, und die Claude-Sessions deiner Teamkollegen profitieren von denselben Fakten wie deine. Persönliche Vorlieben gehören in CLAUDE.local.md (gitignored) oder deine globale Datei, statt sie dem Team aufzudrücken.

Kann ich verschachtelte CLAUDE.md-Dateien in Unterverzeichnissen verwenden?

Ja, und in Monorepos solltest du. Claude Code lädt die Datei eines Unterverzeichnisses, wenn es dort mit Dateien arbeitet. Die Root-Datei bekommt repo-weite Fakten, packages/api/CLAUDE.md die API-Fakten, und Ein-Package-Projekte können sich das Verschachteln komplett sparen.

Ändert das Trimmen der CLAUDE.md wirklich Claudes Verhalten — oder nur die Kosten?

Beides, und das Verhalten ist der größere Gewinn. Das Befolgen von Anweisungen verschlechtert sich mit wachsender Anweisungszahl; eine kurze Datei mit fünf scharfen Regeln wird zuverlässiger befolgt als eine lange mit dreißig. Die Token-Ersparnis ist der messbare Teil — welche Skills dort am meisten helfen, verfolgt unser Effizienz-Ranking —, aber die bessere Befolgung ist das, was du zuerst bemerkst.

Eine letzte Meinung: Die besten CLAUDE.md-Dateien, die wir gesehen haben, wurden alle durch Löschen editiert. Niemand schreibt am ersten Tag eine großartige. Du schreibst eine mittelmäßige, beobachtest, wo Claude stolpert, ergänzt den Fakt, der es verhindert hätte — und streichst dafür eine Zeile Füllmaterial. Sechs Wochen davon schlagen jedes Template, auch unseres.