Ich habe viele schlechte CLAUDE.md-Dateien gelesen. Die meisten haben dasselbe Problem: Sie sind eine Wunschliste, kein Briefing. Seite um Seite "Bitte schreib sauberen Code" und "Befolge Best Practices" — Anweisungen, so generisch, dass sie nichts ändern. Wenn deine CLAUDE.md zu jedem Projekt auf der Welt gehören könnte, ist sie toter Ballast.
Eine CLAUDE.md-Datei ist die Notiz, die Claude Code zu Beginn jeder Sitzung in deinem Repository liest. Sie wird automatisch geladen. Sie ist persistenter Kontext. Und hier ist das, was die Leute verpassen: Jedes Wort darin kostet Token bei jeder Anfrage. Die Frage ist also nicht "Was könnte ich Claude erzählen?" Die Frage ist "Was macht Claude falsch ohne das, was ich müde bin zu korrigieren?"
Diese Umdeutung ändert alles. Lass mich zeigen, was in deine CLAUDE.md gehört.
Fang mit dem an, was Claude nicht erraten kann
Claude kann deinen Code lesen. Nicht deine Gedanken. Die wertvollsten Zeilen in jeder CLAUDE.md sind Fakten, die in den Dateien selbst nicht sichtbar sind.
## Projekt
Dies ist eine Next.js-14-App, die den App Router verwendet. Wir deployen auf Cloudflare Pages.
Paketmanager ist pnpm — niemals npm oder yarn.
## Befehle
- `pnpm dev` — lokaler Server auf :3000
- `pnpm test` — führt Vitest aus, muss vor jedem Commit bestehen
- `pnpm typecheck` — nach dem Bearbeiten jeder .ts-Datei ausführen
Dieser Befehlsblock allein spart dir ein Dutzend Korrekturen pro Woche. Ohne ihn wird Claude fröhlich npm test ausführen und zusehen wie es fehlschlägt, oder den Typecheck überspringen, den du immer ausführst. Mit ihm macht der Agent das Richtige ohne Aufforderung.
Beachte, ich habe "niemals npm oder yarn" gesagt. Spezifisches schlägt Vibes. "Verwende pnpm" ist ein Vorschlag. "Niemals npm oder yarn" ist eine Regel, und Claude behandelt es wie eine.
Kodiere die Konventionen, die du immer wieder erklärst
Denk an deine letzte Arbeitswoche. Was hast du mehr als einmal korrigiert? Diese Korrekturen sind deine CLAUDE.md.
## Konventionen
- Komponenten kommen in src/components, ein Ordner pro Komponente.
- Wir verwenden Tailwind. Keine CSS-Module, kein styled-components.
- API-Routen geben { data } oder { error } zurück, niemals bloße Werte.
- Daten werden immer als UTC-ISO-Strings gespeichert.
Jede davon ist eine echte Entscheidung, die deine Codebasis bereits getroffen hat. Sie einmal aufzuschreiben bedeutet, dass du aufhörst, sie in jeder Sitzung zu tippen. Das ist das ganze Spiel — die wiederkehrende Korrektur aus deinem Kopf in die Datei verschieben.
Eine Anmerkung zu Ton-Anweisungen
Du kannst wie Claude arbeitet gestalten, nicht nur was er weiß:
## Arbeitsstil
- Mach nur die angeforderte Änderung. Refaktoriere keinen benachbarten Code ohne Aufforderung.
- Bei kleinen Entscheidungen (Variablennamen, Dateispeicherort): einfach eine wählen und vermerken.
Nicht stoppen, um zu fragen.
- Nach dem Bearbeiten: Typecheck und Tests ausführen, bevor du mir sagst, dass du fertig bist.
Die mittlere Zeile ist Gold, wenn du ein aktuelles Claude-Modell verwendest. Die neueren Modelle sind standardmäßig bedachter — sie pausieren und fragen bei kleinen Entscheidungen viel. Eine kurze "Wähl einfach eine"-Anweisung holt diese Zeit zurück, ohne den Agenten bei wichtigen Dingen unvorsichtig zu machen.
Was wegfällt
Jetzt die Streichungen, die genauso wichtig sind.
Alles Generische streichen. "Schreibe sicheren, wartbaren Code" tut nichts. Claude versucht das bereits. Du gibst Token aus, um das Standardverhalten zu bekräftigen.
Was im Code steht streichen. Füge nicht deine ganze package.json ein oder liste jede Abhängigkeit auf. Claude kann die Datei öffnen. Beschreibe, was beim Lesen nicht offensichtlich ist — wie warum du eine Bibliothek gewählt hast, oder welche bevorzugt wird, wenn zwei infrage kommen.
Den Roman streichen. Ich habe CLAUDE.md-Dateien mit 600 Zeilen gesehen. Ab Zeile 200 ist das Signal-Rausch-Verhältnis so schlecht, dass wichtige Regeln untergehen. Eine knappe 40-Zeilen-Datei, die Claude wirklich befolgt, schlägt eine aufgeblähte, die er halb ignoriert. Sei unbarmherzig. Wenn eine Zeile ihren Platz nicht durch Verhindern eines echten Fehlers verdient hat, lösch sie.
Wo die Datei hinkommt
Leg CLAUDE.md in dein Repository-Root, und Claude Code findet sie automatisch. Du kannst auch eine in einem Unterverzeichnis verschachteln — zum Beispiel frontend/CLAUDE.md — und Claude legt sie oben drauf, wenn du in diesem Ordner arbeitest. Praktisch für Monorepos, wo Backend und Frontend wirklich unterschiedliche Regeln haben.
Es gibt auch eine globale im Home-Konfigurationsverzeichnis, die für alle Projekte gilt. Meine halte ich fast leer: nur ein paar persönliche Präferenzen, die überall gelten. Projektspezifisches Wissen gehört ins Projekt, nicht in deine globale Datei.
Eine Vorlage, die du stehlen kannst
# CLAUDE.md
## Projekt
[Ein oder zwei Sätze: was das ist, der Stack, wo es deployed wird.]
## Befehle
- [Entwicklungsbefehl]
- [Testbefehl — vermerken ob er vor Commits bestehen muss]
- [jeder Check, den du immer ausführst]
## Konventionen
- [eine Entscheidung, die im Code nicht offensichtlich ist]
- [eine Bibliothekspräferenz]
- [ein Muster das du durchsetzt]
## Arbeitsstil
- [wie gründlich/konservativ zu sein]
- [wann fragen vs. wann entscheiden]
Füll das aus, dann leb eine Woche damit. Wenn du dich dabei ertappst, Claude zum dritten Mal etwas zu korrigieren, ist das eine fehlende Zeile — füge sie hinzu. Wenn du eine Zeile bemerkst, die nie wirklich wichtig war, lösch sie.
Eine CLAUDE.md-Datei ist kein Dokument, das du einmal schreibst. Es ist etwas, das du feinstimmst. Die guten sind kurz, spezifisch, und eine Korrektur nach der anderen erarbeitet. Klein anfangen. Nur dort wachsen lassen, wo es nötig ist.