Eine CLAUDE.md, an die sich Claude in jeder Sitzung tatsächlich hält

Wenn du jede Claude-Sitzung damit beginnst, dieselbe Notiz zu Befehlen, Codestil und Tests einzufügen, erledigst du von Hand, was eine Datei für dich tun kann. Eine CLAUDE.md im Projekt enthält diese wiederkehrenden Anweisungen, und Claude liest sie in jeder neuen Sitzung ein. Hier steht, wie man sie aufbaut, was hineingehört und was draußen bleiben sollte, mit Beispielen zum Anpassen.

Wohin die Datei gehört

Leg sie in den Stammordner des Projekts, direkt neben die README:

my-project/
 - CLAUDE.md
 - README.md
 - package.json
 - src/
 - tests/

Committe sie in Git, damit deine Teamkollegen dieselben Vorgaben bekommen. Ein weiterer gültiger Ort ist .claude/CLAUDE.md.

Wächst das Projekt, brauchen verschiedene Bereiche vielleicht verschiedene Regeln. Dafür legst du zusätzliche CLAUDE.md-Dateien in Unterverzeichnisse, etwa eine für einen Frontend-Ordner und eine für einen Backend-Ordner:

my-project/
 - CLAUDE.md
 - src/
   - frontend/
     - CLAUDE.md
   - backend/
     - CLAUDE.md

Fang mit einer einzigen Datei im Stammverzeichnis an. Füge weitere erst hinzu, wenn ein Teil der Codebasis wirklich eigene Anweisungen braucht.

Gute Vorsätze gegen Konkretes tauschen

Eine Anweisung, die dir offensichtlich vorkommt, kann für einen Agenten vage sein. Zeilen wie diese klingen vernünftig:

• Schreib sauberen Code
• Halte dich an Best Practices
• Teste gründlich
• Halte die Architektur einheitlich

Sieh sie aber einmal aus Sicht des Agenten an. Was heißt „gründlich“ in diesem Repository? Welche Best Practices gelten? Du weißt, was du gemeint hast, aber der Agent muss raten, solange du es nicht sagst.

So liest sich dieselbe Absicht für eine TypeScript-API:

• Route-Handler liegen in src/routes/.
• Datenbankabfragen gehören nach src/repositories.
• Request-Bodys werden mit den vorhandenen Zod-Schemas validiert.
• Fehler laufen über src/lib/api-error.ts.
• Beim Beheben eines Bugs einen Regressionstest hinzufügen, der den gemeldeten Fehler reproduziert.

Das sind Entscheidungen, keine Wünsche, und ein Agent kann ihnen folgen.

Die echten Befehle auflisten

Ein Projekt kann Unit-, Integrations- und Browsertests haben und mehrere Wege, die App zu starten. „Führ nach jeder Änderung die Tests aus“ sagt einem Agenten nicht, welche davon. Nimm ein Setup mit pnpm und Vitest. Du könntest einen Abschnitt mit Befehlen schreiben und dazusagen, dass sie im Stammverzeichnis des Repositorys laufen:

• Abhängigkeiten installieren mit pnpm install.
• Den Dev-Server starten mit pnpm dev.
• Typen prüfen mit pnpm typecheck.
• Die Unit-Tests einmal durchlaufen lassen mit pnpm exec vitest run.
• Nur eine Datei testen mit pnpm exec vitest run <test-file>.

Das Verzeichnis, aus dem du startest, und alle Voraussetzungen zählen genauso viel wie der Befehl selbst. Führ jeden Befehl selbst aus, bevor du ihn einträgst. Ein kopierter Befehl, der in den Watch-Modus springt oder einen nirgends dokumentierten Dienst braucht, beschert dir nur ein neues Problem.

Lass außerdem nicht jede kleine Änderung jede teure Prüfung auslösen. Beschreib die Prüfungen, die im Alltag sinnvoll sind, und überlass die Pflicht-Gates der CI.

Eigenheiten festhalten, die wie Fehler aussehen

Hier verdient sich die Datei ihren Platz. Angenommen, deine API speichert Geldbeträge als ganzzahlige Cent, sodass 19,99 $ als 1999 durch das System wandern. Ohne dieses Wissen kann eine harmlos wirkende Änderung inkonsistente Werte einschleppen. Eine bessere Notiz nennt die Regel und die Stelle zur Wiederverwendung:

• Beträge in API und Datenbank sind ganzzahlige Cent.
• Nur die UI rechnet in eine Anzeigewährung um, und zwar über das vorhandene formatMoney() in src/lib/money.ts.

Oder ein älterer mobiler Client verlässt sich auf merkwürdiges Verhalten. Ein Kompatibilitätseintrag könnte sagen, dass POST /subscriptions bei doppelten Anfragen HTTP 200 zurückgibt, dass alte mobile Clients davon abhängen und dass das so bleiben soll, solange die Aufgabe nicht ausdrücklich den API-Vertrag ändert. Dieser letzte Halbsatz ist wichtig. Er lässt Raum für gewollte Änderungen, damit eine historische Notiz nicht zu einer unerklärten Regel wird, die niemand mehr hinterfragen kann.

Ein einzeiliger Grund, warum etwas existiert, kann einen unnötigen „Fix“ verhindern.

Wiederholte Korrekturen in Vorgaben verwandeln

Stell dir vor, Claude holt eine neue Datumsbibliothek ins Projekt, obwohl es schon einen gemeinsamen Formatter gibt. Du könntest sagen: „Füg keine unnötigen Abhängigkeiten hinzu.“ Das Problem: Beim nächsten Mal streitet ihr darüber, was „unnötig“ heißt.

Eine stärkere Fassung nennt die Prüfung, zeigt auf den Code und erklärt den Weg für Ausnahmen:

• Bevor du eine Laufzeitabhängigkeit hinzufügst, such in package.json und src/lib/ nach etwas, das die Aufgabe schon erledigt.
• Für Datumswerte src/lib/date.ts wiederverwenden.
• Wenn ein neues Paket wirklich nötig ist, begründen, was die vorhandenen Werkzeuge nicht können.

Sei aber wählerisch. Eine einzelne merkwürdige Aufgabe rechtfertigt nicht immer eine dauerhafte Regel. Ein brauchbarer Test ist die Frage, ob die Korrektur in einem Monat noch eine Rolle spielt.

Kurzlebige Arbeit draußen lassen

Manche Notizen verfallen an dem Tag, an dem sie geschrieben werden:

Denk an eine Notiz wie „Heute geht es um den Checkout-Bug, das kaputte Konto ist test-user-42, erhöh zuerst das Timeout“.

Bleibt so etwas in der CLAUDE.md, wenn der Bug längst behoben ist, verwirrt es eine spätere Sitzung. Halte aufgabenspezifische Anweisungen stattdessen in separaten Dateien. Claude Code unterstützt außerdem pfadbezogene Regeln in .claude/rules/, die sich für Vorgaben eignen, die nur für bestimmte Teile des Baums gelten.

Eine Vorlage für den Anfang

Beginne mit den Grundlagen, die ein Assistent braucht, bevor er deinen Code anfasst: Zweck des Projekts, Befehle zum Starten, Konventionen im Team und eine Möglichkeit, Ergebnisse zu überprüfen. Dieses Gerüst deckt all das ab, die Details lieferst du:

Project overview
 - Briefly explain what this project does and its main technologies.

Useful commands
 - Set up the project: [command]
 - Run locally: [command]
 - Run tests: [command]
 - Check formatting and linting: [command]

Mention where to run these commands and any required setup.

Where things live
 - Point to the main source code, tests, and important documentation.
 - Include locations that may be difficult to find or easy to confuse.

Project conventions
 - Describe the patterns to follow and existing helpers to reuse.
 - Focus on decisions that aren't obvious from reading the code.

Things to watch out for
 - Explain unusual behavior that must be preserved.
 - Identify generated files and how they should be updated.
 - Give a short reason for each restriction.

Checking changes
 - Explain how to choose and run the relevant checks.
 - Ask Claude to report what it checked and anything it couldn't verify.

Nicht jeder Abschnitt muss gefüllt sein. Hat einer nichts Nützliches zu sagen, lösch ihn. Ersetze die Platzhalter durch echte Befehle und Pfade, bevor du dich auf die Datei verlässt.

Wenn du eine weitere Gewohnheit gefunden hast, die eine CLAUDE.md besser funktionieren lässt, probier sie aus und behalte sie nur, wenn sie ein paar echte Sitzungen übersteht.