CLAUDE.md ist das neue .env — Aber die meisten Entwickler behandeln es wie eine README
Dann habe ich mir angeschaut, was Boris Cherny — der Typ, der Claude Code gebaut hat — in seine Datei reinschreibt. Und was Trail of Bits in ihren Security-Audit-Repos verwendet. Und was die Teams nutzen, die bei Anthropics Hackathons echte Senior-Entwickler ausstechen.
Meine CLAUDE.md hat jetzt über 200 Zeilen. Die Qualität meiner Outputs ist durch die Decke gegangen. Im positiven Sinne.
TL;DR: Deine CLAUDE.md ist wahrscheinlich eine aufgeblähte README. Sie sollte behandelt werden wie deine .env — heilig, projektspezifisch und niemals nebensächlich. Hier zeige ich, wie ich meine in 4 Produktions-Repos umstrukturiert habe, welche Patterns Claudes Verhalten tatsächlich verändert haben, und warum die meisten "CLAUDE.md-Tipps"-Threads auf X dich zu schlechteren Outputs führen.
Dein Anweisungsbudget ist kleiner als du denkst
Vergiss für einen Moment, was in CLAUDE.md gehört. Reden wir darüber, was passiert, wenn du zu viel reinsteckst.
HumanLayers Analyse (die sich auf ein arxiv-Paper über Grenzen beim Befolgen von Anweisungen bezieht) legt nahe, dass fortgeschrittene Denkmodelle zuverlässig etwa 150–200 Anweisungen befolgen können. Ihre Aufschlüsselung von Claude Codes System-Prompt zählte ~50 Anweisungen, die bereits eingebacken sind, bevor deine CLAUDE.md überhaupt lädt.
Die genauen Zahlen sind diskutabel — aber die Richtung nicht. Ab einem bestimmten Punkt macht das Hinzufügen von mehr Regeln Claude schlechter darin, alle zu befolgen, nicht nur die neuen.
Die Befolgung sinkt gleichmäßig.
Die Befolgung sinkt gleichmäßig. Die Regeln, die dir am wichtigsten sind, werden genauso ignoriert wie der Füllstoff, den du vergessen hast zu löschen.
Deshalb zählt jede Zeile. Und deshalb sind die viralen Tweets mit 400-Zeilen-CLAUDE.md-Dateien, die "Claude zu einem 10x-Engineer machen", aktiv kontraproduktiv. Die Autoren meinen es gut — aber ihre Follower stopfen Dateien mit Regeln voll, die Claude nach den ersten hundert stillschweigend ignoriert.
Kontext ist ein Budget. Gib es aus wie Miete, nicht wie Casino-Chips.
Das Schlimmste? Die Hälfte dessen, was die meisten Leute in CLAUDE.md packen, kann Claude bereits ableiten. Dein Tech-Stack steht in package.json. TypeScript-Config ist in tsconfig.json. Linter-Regeln sind in .eslintrc. Claude liest all das. Es zu wiederholen verbrennt Anweisungsslots für Dinge, die nichts ändern.
Ein Test für jede Zeile: "Würde das Entfernen dieser Zeile Claude einen Fehler machen lassen, von dem er sich nicht erholen kann?" Wenn du "verwende TypeScript" löschst und dein Projekt hat eine tsconfig.json — passiert nichts. Wenn du löschst "Convex queries können keine mutations aufrufen, verwende actions" — generiert Claude Code, der den Type-Checker passiert und zur Laufzeit explodiert.
Nimm nur auf, was Claude nicht allein herausfinden kann.
Was tatsächlich falsch war mit meiner 47-Zeilen-Datei
Meine alte CLAUDE.md, paraphrasiert (weil ich mir nicht die Peinlichkeit der echten Version antue):
# Mein SaaS-Projekt
Stack: Next.js, Convex, Clerk, Supabase, Tailwind
Node-Version: 20
Package-Manager: pnpm
## Regeln
- Verwende TypeScript
- Schreibe Tests
- Lösche nicht die .env-Datei
Elf Zeilen "Information", die Claude in 3 Sekunden aus meinem Repo extrahieren könnte. Der Rest waren Phrasen. "Schreibe sauberen Code." "Folge Best Practices." "Halte Komponenten klein." Wie klein? Klein wie eine React-Komponente oder klein wie ein Microservice? Claude weiß es nicht, also rät es, und seine Vermutung ist etwa 40% der Zeit falsch.
Ich verbrannte mein Anweisungsbudget, um Claude Dinge zu sagen, die es bereits wusste, und sagte ihm nichts über die Dinge, die es nicht wissen konnte — Workflow-Sequenzen, Verifikationsschritte, die Convex-Deploy-vor-Build-Falle, die mich einen ganzen Sonntag im Februar kostete beim Debuggen eines Produktionsausfalls, der nicht hätte passieren sollen.
An diesem Sonntag habe ich die Datei von Grund auf neu aufgebaut.
Die Umstrukturierung: Was tatsächlich reingehört
Ich durchforstete Boris Chernys Threads (er baute Claude Code — seine Tipps haben Gewicht), Trail of Bits' öffentliches Config-Repo, den Dometrain-Guide und etwa 40 echte CLAUDE.md-Dateien auf GitHub.
Das Muster war konsistent: die besten Dateien sind nicht die längsten. Sie sind am spezifischsten bei Fehlermodi.
1. Befehle die einschließen, wie sie kaputtgehen
## Befehle
Führe ALLE Befehle vom Projekt-Root aus, außer anders angegeben.
### Dev
- `pnpm dev` — startet Next.js auf :3000. Convex-Dev-Server muss separat laufen.
- `npx convex dev` — in einem ZWEITEN Terminal ausführen. Wird stillschweigend fehlschlagen, wenn CONVEX_DEPLOY_KEY in .env.local fehlt
### Test
- `pnpm vitest run src/path/to/file.test.ts` — führe eine EINZELNE Testdatei aus. Niemals die komplette Suite, außer explizit gefragt.
- Integrationstests benötigen eine laufende Convex-Dev-Instanz.
### Deploy
- `pnpm build && npx convex deploy` — immer ZUERST builden. Convex deploy allein wird veraltete Funktionen verwenden.
- Wenn Deploy >30s hängt, kill es. Prüfe `npx convex logs` für Schema-Validierungsfehler.
Nicht nur was zu tippen ist. Was schiefgeht und wie man sich erholt. Boris' Kern-Tipp: gib Claude immer einen Weg, seine eigene Arbeit zu verifizieren. Tests, Diffs, Logs. Ohne Verifikation bekommst du Bauchgefühl.
2. Architektur-Entscheidungen, nicht Architektur-Beschreibungen
Früher listete ich meine Dateistruktur auf. Verschwendung von Tokens — Claude liest deinen Dateibaum sowieso.
Jetzt dokumentiere ich das Warum hinter Entscheidungen, die Claude nicht ableiten kann:
## Architektur-Entscheidungen
- Auth: Clerk übernimmt alle Auth. NIEMALS eigene Auth-Logik implementieren.
- Database: Convex für Echtzeit-Daten. Supabase NUR für Blob-Storage. Verwende Supabase NICHT für strukturierte Daten.
- State: Keine Client-State-Library. Convex reactive queries ersetzen useState für alle Server-Daten.
- Styling: Nur Tailwind. Keine CSS-Module, keine styled-components.
Jede Zeile eliminiert eine ganze Kategorie von Fehlern.
Bevor dieser Abschnitt existierte, erstellte Claude periodisch Supabase-Tabellen für Benutzerdaten, obwohl Convex direkt da war. Kleine Entscheidungen, die sich zu Refactoring-Sessions summierten, die ich nicht eingeplant hatte.
3. Die Selbstverbesserungs-Schleife
Das könnte das einzelne Pattern mit dem höchsten Hebel in der ganzen Datei sein.
Nachdem Claude einen Fehler macht, fixst du ihn nicht nur. Du sagst Claude, es soll eine neue Regel zu CLAUDE.md hinzufügen, damit es diesen Fehler nie wieder macht:
"Fixe den Bug, wo du von @clerk/nextjs/server in einer Client-Komponente importiert hast.
Dann aktualisiere CLAUDE.md mit einer Regel, damit du das nie wieder machst."
Meine CLAUDE.md hat jetzt einen ## Gelernte Regeln-Abschnitt am Ende, der vollständig von Claude verfasst ist:
## Gelernte Regeln (auto-generiert, regelmäßig überprüfen)
- NIEMALS von `@clerk/nextjs/server` in Dateien unter `src/app/(dashboard)/` importieren
- Convex `query`-Funktionen können keine `mutation`-Funktionen aufrufen. Verwende `action` für Side Effects.
- `useQuery` von convex/react gibt während des Ladens `undefined` zurück, nicht `null`. Handle beides.
- Neue API-Routes gehören in `src/app/api/` NICHT `src/pages/api/` (nur App Router)
Mit der Zeit wird dieser Abschnitt zum wertvollsten Teil der Datei. Ein lebendiges Changelog jedes Fehlers, den Claude in deinem spezifischen Projekt gemacht hat. Sich aufbauendes Wissen, nicht sich aufbauende Fehler. Falls das bekannt vorkommt — es ist dieselbe Philosophie hinter Prompt Contracts: strukturierte Beschränkungen, die sich aufbauen statt zu verfallen.
Der Haken: editiere gnadenlos. Boris warnt auch davor.
Aufgeblähte Dateien bringen Claude dazu, alles zu ignorieren — einschließlich der Regeln, die am wichtigsten sind. Ich bereinige alle zwei Wochen. Redundante Regeln werden zusammengeführt. Offensichtliche werden gestrichen.
4. Sicherheitsvorkehrungen
OK dieser Abschnitt existiert, weil mir eines Morgens klar wurde, dass ich null Schutz gegen rm -rf in meiner CLAUDE.md hatte und ich Claude Code monatelang in meinen Produktions-Repos laufen ließ. Cool. Cool cool cool. 😐
## Sicherheit
- NIEMALS `rm -rf` oder `rm -fr` ausführen. Verwende stattdessen `trash`-Befehl.
- NIEMALS .env, .env.local oder .env.production ohne explizite Erlaubnis modifizieren.
- NIEMALS direkt zu `main` pushen. Immer einen Feature-Branch erstellen.
- NIEMALS `npx convex deploy --prod` ausführen, außer ich sage explizit "deploy to production."
Claude ist ein probabilistisches Modell, trainiert auf dem Internet. rm -rf node_modules erscheint in zehn Milliarden Stack Overflow-Antworten. Ein falsch gelesener Kontext und dein src/-Verzeichnis wird zu einer schönen Erinnerung.
Deine .env schützt deine Geheimnisse. Deine CLAUDE.md schützt deinen Quellcode. Gleiche Energie. Gleiche Disziplin.
5. Das Router-Pattern
Für alles größer als ein Wochenendprojekt reicht eine Datei nicht. Aber eine aufgeblähte Datei ist schlimmer als keine. Die Lösung: verwende die Root-CLAUDE.md als Inhaltsverzeichnis.
# Projekt Root
Siehe @docs/convex-conventions.md für Datenbank-Patterns
Siehe @docs/api-patterns.md für API-Route-Konventionen
Siehe @docs/testing-guide.md für Teststruktur und Befehle
Claude Code löst @path/to/import nativ auf. Root-CLAUDE.md lädt jede Session. Importierte Dateien laden bei Bedarf. Dein Root bleibt unter 100 Zeilen. Gesamtanweisungen beim Arbeiten in einer beliebigen Zone: komfortabel unter der 150–200-Obergrenze. (Und falls du dich fragst, ob einige dieser Tool-Definitionen CLIs statt MCPs sein sollten — weniger Tools im Kontext bedeutet weniger verbrannte Anweisungen.)
Trail of Bits geht weiter mit .claude/rules/ — bereichsspezifische Markdown-Dateien, die automatisch basierend auf dem Dateipfad laden:
---
paths: src/api/**/*.ts
---
# API-Regeln
- Alle Endpoints müssen Input-Validierung enthalten
- Verwende Standard-Error-Response-Format
API-Regeln für dein API-Verzeichnis. Test-Regeln für dein Test-Verzeichnis. Claude lädt nur, was relevant ist. Mein SaaS hat 3 Zonen — Marketing-Site, Dashboard, API — jede mit ihrer eigenen Regel-Datei. Die Root-CLAUDE.md überschreitet nie 100 Zeilen.
Mein echtes Template
Keine bereinigte Version. Das ist das echte Skelett, Kommentare inklusive:
# [Projektname]
## Kritischer Kontext
[Max 2-3 Zeilen. Was das IST und die eine Sache, die Claude niemals falsch machen darf]
## Befehle
[Exakte Befehle mit Fehlermodi. Keine Man-Page - ein Überlebensguide]
## Architektur-Entscheidungen
[Nur das WARUM hinter Entscheidungen, die Claude nicht aus Code ableiten kann]
## Sicherheit
[Harte Grenzen. Ja, ich habe einen Sicherheits-Abschnitt. Ja, ich habe es auf die harte Tour gelernt.]
## Stil
[NUR was Linter nicht durchsetzen. Wenn eslint es fängt, lösche es hier]
## Gelernte Regeln
[Claude-verfasst. Der beste Abschnitt in der Datei. Bereinige ihn oder er frisst alles andere]
@docs/[bereich]-conventions.md
Sieben Abschnitte. Keine "Projektübersicht", die die README nachplappert. Kein Tech-Stack, der package.json dupliziert.
Claude Code unterstützt auch Skills (.claude/skills/ — On-Demand-Workflows, die nicht jede Session laden) und Auto Memory (~/.claude/projects/*/memory/ — Notizen, die Claude für sich selbst zwischen Sessions schreibt, opt-in mit CLAUDE_CODE_DISABLE_AUTO_MEMORY=0). Beides reduziert, was du in der Root-Datei brauchst. Aber CLAUDE.md ist das Fundament — mach es zuerst richtig.
Der echte Durchbruch
Die echte Veränderung war nicht zu lernen, was in CLAUDE.md gehört. Es war zu lernen, was zu entfernen ist.
Ich löschte den Tech-Stack-Abschnitt.
Löschte die "Code-Stil"-Regeln, die mein Linter bereits durchsetzt. Löschte die vagen Phrasen, die exakt nichts bewirkten. Was übrig blieb, waren die Dinge, die Claude davon abhalten, Fehler zu machen, die nur ein Mensch, der monatelang an diesem Projekt gearbeitet hat, zu vermeiden weiß.
Das institutionelle Wissen deines Projekts, komprimiert auf die kleinstmögliche Oberfläche. Jede Session gelesen. Jeden Sprint bereinigt.
Behandle es wie deine .env. Jede Zeile verdient ihren Platz oder wird gestrichen.
Hast du ein CLAUDE.md-Pattern, das deinen Workflow verändert hat? Oder eine Kriegsgeschichte über eine Regel, die du dir gewünscht hättest, früher geschrieben zu haben? Ich sammle diese für einen Follow-up. Hit subscribe — der nächste handelt davon, die Selbstverbesserungs-Schleife in ein System zu verwandeln, das sich über deinen gesamten Stack aufbaut.
Medium emailt Abonnenten nur, wenn ich publiziere — kein Spam, kein Digest. Ein Artikel landet in deinem Postfach, du liest ihn oder nicht. Besser als den Feed zu refreshen.
CLAUDE.md ist dein neuer Produktions-Schlüssel — nicht nur eine Notiz. In der Wochennewsletter teile ich, wie ich meine KI-Konfigurationen von 'nett' zu 'präzise' transformiert habe.